harry0703/MoneyPrinterTurbo · warning · ValueError

--bgm-file is required when --bgm-type is custom

Error message

--bgm-file is required when --bgm-type is custom

What it means

Validation in prepare_cli_files: with --bgm-type custom and BGM effectively enabled (volume > 0 per should_use_bgm), the --bgm-file argument is mandatory. The 0-volume case intentionally skips the requirement and blanks the file param, keeping CLI behavior consistent with WebUI/service layers.

Source

Thrown at cli.py:687

        )
        audio_extension = os.path.splitext(params.custom_audio_file)[1].lower()
        if audio_extension not in _CUSTOM_AUDIO_EXTENSIONS:
            allowed = ", ".join(sorted(_CUSTOM_AUDIO_EXTENSIONS))
            raise ValueError(
                f"unsupported custom audio type {audio_extension or '<none>'}; "
                f"allowed extensions: {allowed}"
            )

    if params.bgm_type == "custom":
        if not bgm_service.should_use_bgm(params.bgm_type, params.bgm_volume):
            # 0 音量时下游会统一跳过所有 BGM。这里同时清空文件参数，避免
            # CLI 为一个不会被读取的文件执行路径解析、存在性检查或格式
            # 校验。
            params.bgm_file = ""
        elif not params.bgm_file:
            # 缺少文件是否构成错误取决于通用 BGM 开关，不能在 argparse 阶段
            # 无条件拦截，否则 ``custom + 0%`` 会和 WebUI、服务层行为不一致。
            raise ValueError("--bgm-file is required when --bgm-type is custom")
        else:
            try:
                # CLI、WebUI 和任务服务必须共用同一个 BGM 文件边界。这里直接
                # 复用服务层解析，既支持用户上传目录和内置歌曲目录，也
                # 自动继承新增音频格式及路径安全规则，避免多个入口分别
                # 维护白名单。
                params.bgm_file = bgm_service.resolve_bgm_file(params.bgm_file)
            except ValueError as exc:
                supported_extensions = ", ".join(
                    bgm_service.SUPPORTED_BGM_EXTENSIONS
                )
                raise ValueError(
                    "background music must be a supported audio file inside "
                    f"storage/bgm or resource/songs ({supported_extensions}): "
                    f"{params.bgm_file}"
                ) from exc

    if params.subtitle_enabled and params.font_name and stop_at == "video":

View on GitHub (pinned to 1f9f19c202)

Solutions

1. Add --bgm-file <path> pointing at an existing supported audio file.
2. If you actually want no BGM, drop --bgm-type custom instead of leaving the file empty.
3. If you want custom type but silence, set the BGM volume to 0 — the CLI then deliberately skips this check.

Example fix

# before
python cli.py --bgm-type custom

# after
python cli.py --bgm-type custom --bgm-file ./music/lofi.mp3

if params.bgm_type == "custom" and bgm_service.should_use_bgm(params.bgm_type, params.bgm_volume) and not params.bgm_file:
    raise ValueError("provide --bgm-file, or set --bgm-volume 0 to disable BGM")

def has_required_bgm_config(bgm_type: str, bgm_file: str, bgm_volume: float) -> bool:
    if bgm_type != "custom":
        return True
    return bool(bgm_file) or not bgm_service.should_use_bgm(bgm_type, bgm_volume)

When it happens

Trigger: Running with --bgm-type custom without --bgm-file while bgm volume is non-zero; a script template that sets bgm type but not the file; assuming a default BGM file is implied by 'custom'.

Common situations: User selects 'custom' background music in a wrapper but forgets the file field; migrating an old command that used a different BGM flag name; env-driven invocations dropping the flag.

Related errors

• {description} path cannot be empty
• background music must be a supported audio file inside stora
• uploaded file must contain a decodable audio stream
• background music file is empty or missing
• background music file exceeds the 30 MB limit

AI-assisted analysis of harry0703/MoneyPrinterTurbo@1f9f19c202 (2026-08-14). Data as JSON: /api/errors/13c934e83b69b547. Report an issue: GitHub.