Skip to content

利用 AI 大模型和自动化工作流,根据主题或关键词一键生成高清短视频。Generate HD short videos from a topic or keyword with an automated AI workflow.

feat(webui): upload custom background music from the UI

Paulo C. Benettia4ee0e21d29b
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 09a3b745..c28c9b6b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,4 +32,4 @@ jobs:
run: uv run python -m compileall app cli.py main.py webui test
- name: Run deterministic unit tests
- run: uv run python -X utf8 -m unittest test.services.test_state test.services.test_task test.services.test_schema test.services.test_video_effects test.services.test_clip_speed test.services.test_webui_i18n
+ run: uv run python -X utf8 -m unittest test.services.test_state test.services.test_task test.services.test_schema test.services.test_video_effects test.services.test_bgm test.services.test_webui_bgm test.services.test_clip_speed test.services.test_webui_i18n
diff --git a/app/controllers/v1/video.py b/app/controllers/v1/video.py
index 8d561c63..0302dcdd 100644
--- a/app/controllers/v1/video.py
+++ b/app/controllers/v1/video.py
@@ -29,6 +29,7 @@ from app.models.schema import (
VideoMaterialUploadResponse,
VideoMaterialRetrieveResponse
)
+from app.services import bgm as bgm_service
from app.services import state as sm
from app.services import task as tm
from app.utils import file_security, utils
@@ -236,18 +237,15 @@ def delete_video(request: Request, task_id: str = Path(..., description="Task ID
"/musics", response_model=BgmRetrieveResponse, summary="Retrieve local BGM files"
)
def get_bgm_list(request: Request):
- suffix = "*.mp3"
- song_dir = utils.song_dir()
- files = glob.glob(os.path.join(song_dir, suffix))
bgm_list = []
- for file in files:
+ for file in bgm_service.list_bgm_files():
filename = os.path.basename(file)
bgm_list.append(
{
"name": filename,
"size": os.path.getsize(file),
- # 只返回文件名,避免把服务器绝对路径暴露给调用方。
- # 服务端后续会把该文件名解析回 songs 白名单目录。
+ # 只返回文件名,避免把服务器绝对路径暴露给调用方。服务端会
+ # 在 storage/bgm 和 resource/songs 两个白名单目录中重新解析。
"file": filename,
}
)
@@ -258,26 +256,45 @@ def get_bgm_list(request: Request):
@router.post(
"/musics",
response_model=BgmUploadResponse,
- summary="Upload the BGM file to the songs directory",
+ summary="Upload a background music file",
+ description=(
+ "Validate an MP3, M4A, AAC, WAV, FLAC, OGG, OPUS, or WMA file up to "
+ "30 MB and store it under an immutable UUID filename in storage/bgm."
+ ),
+ responses={
+ 400: {"description": "The filename, format, size, or audio stream is invalid"},
+ 500: {"description": "FFmpeg validation or persistent storage is unavailable"},
+ },
)
def upload_bgm_file(request: Request, file: UploadFile = File(...)):
request_id = base.get_task_id(request)
- safe_filename = _sanitize_upload_filename(file.filename, request_id)
- # check file ext
- if safe_filename.lower().endswith("mp3"):
- song_dir = utils.song_dir()
- save_path = os.path.join(song_dir, safe_filename)
- # save file
- with open(save_path, "wb+") as buffer:
- # If the file already exists, it will be overwritten
- file.file.seek(0)
- buffer.write(file.file.read())
- response = {"file": safe_filename}
- return utils.get_response(200, response)
+ try:
+ safe_filename = bgm_service.save_bgm_upload(file.filename, file.file)
+ except bgm_service.BgmUploadError as exc:
+ # 上传失败通常可以由用户更换文件后恢复,因此记录 request_id 和明确原因,
+ # 但不输出文件内容或绝对路径,避免日志泄露用户数据。
+ logger.warning(
+ f"background music upload rejected: request_id={request_id}, error={str(exc)}"
+ )
+ raise HttpException(
+ task_id=request_id,
+ status_code=400,
+ message=f"{request_id}: {str(exc)}",
+ )
+ except bgm_service.BgmServiceError as exc:
+ # 工具链或存储故障属于服务端问题,不能伪装成用户文件错误。日志保留
+ # request_id 和内部原因,HTTP 响应只返回稳定文案,避免暴露服务器路径。
+ logger.error(
+ f"background music upload failed: request_id={request_id}, error={str(exc)}"
+ )
+ raise HttpException(
+ task_id=request_id,
+ status_code=500,
+ message=f"{request_id}: background music validation is unavailable",
+ )
- raise HttpException(
- "", status_code=400, message=f"{request_id}: Only *.mp3 files can be uploaded"
- )
+ response = {"file": safe_filename}
+ return utils.get_response(200, response)
@router.get(
"/video_materials", response_model=VideoMaterialRetrieveResponse, summary="Retrieve local video materials"
diff --git a/app/models/schema.py b/app/models/schema.py
index ab46c2bd..08da480b 100644
--- a/app/models/schema.py
+++ b/app/models/schema.py
@@ -334,9 +334,9 @@ class BgmRetrieveResponse(BaseResponse):
"data": {
"files": [
{
- "name": "output013.mp3",
+ "name": "4fca18fce7344f3aa824777a40d45c8c.mp3",
"size": 1891269,
- "file": "/MoneyPrinterTurbo/resource/songs/output013.mp3",
+ "file": "4fca18fce7344f3aa824777a40d45c8c.mp3",
}
]
},
@@ -350,7 +350,7 @@ class BgmUploadResponse(BaseResponse):
"example": {
"status": 200,
"message": "success",
- "data": {"file": "/MoneyPrinterTurbo/resource/songs/example.mp3"},
+ "data": {"file": "4fca18fce7344f3aa824777a40d45c8c.mp3"},
},
}
diff --git a/app/services/bgm.py b/app/services/bgm.py
new file mode 100644
index 00000000..c7fb669b
--- /dev/null
+++ b/app/services/bgm.py
@@ -0,0 +1,298 @@
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import BinaryIO
+from uuid import uuid4
+
+from loguru import logger
+
+from app.utils import file_security, utils
+
+
+# Streamlit 默认允许较大的上传文件,但背景音乐通常只有几 MB。这里设置明确的
+# 服务端上限,避免 API 或 WebUI 把超大文件完整写入磁盘,影响同一进程中的视频任务。
+MAX_BGM_UPLOAD_BYTES = 30 * 1024 * 1024
+_COPY_CHUNK_BYTES = 1024 * 1024
+_INTERNAL_UPLOAD_PREFIX = ".bgm-upload-"
+_WINDOWS_INVALID_FILENAME_CHARS = frozenset('<>:"|?*')
+_WINDOWS_RESERVED_FILENAMES = frozenset(
+ {"CON", "PRN", "AUX", "NUL"}
+ | {f"COM{index}" for index in range(1, 10)}
+ | {f"LPT{index}" for index in range(1, 10)}
+)
+# MoviePy 最终通过 FFmpeg 解码背景音乐,因此不需要人为限制为 MP3。这里仅开放
+# 主流且语义明确的音频扩展名,避免把 MP4 等带视频容器误当作背景音乐上传。
+# 元组同时作为 WebUI 上传控件的单一数据源,后续增删格式时不会出现前后端不一致。
+SUPPORTED_BGM_EXTENSIONS = (
+ ".mp3",
+ ".m4a",
+ ".aac",
+ ".wav",
+ ".flac",
+ ".ogg",
+ ".opus",
+ ".wma",
+)
+
+
+class BgmUploadError(ValueError):
+ """表示上传文件不满足背景音乐的安全或格式要求。"""
+
+
+class BgmServiceError(RuntimeError):
+ """表示 FFmpeg 或文件系统不可用等服务端执行故障。"""
+
+
+def uploaded_bgm_dir(create: bool = True) -> str:
+ """
+ 返回用户背景音乐的持久化目录。
+
+ 内置歌曲属于代码资源,继续放在 resource/songs;用户上传内容属于运行时数据,
+ 必须放在 Docker 已挂载的 storage 下,容器重建后才能保留,也不会污染 Git 工作区。
+ """
+ return utils.storage_dir("bgm", create=create)
+
+
+def _remove_staged_file(file_path: str) -> None:
+ """尽力清理上传临时文件,且不覆盖调用方正在处理的原始异常。"""
+ if not file_path or not os.path.exists(file_path):
+ return
+ try:
+ os.remove(file_path)
+ except OSError as exc:
+ # 临时文件使用保留前缀,不会进入 BGM 列表;清理失败不应把“音频非法”
+ # 等更准确的原始异常覆盖掉,但必须留下路径和系统错误供运维定位。
+ logger.warning(
+ f"failed to remove staged background music: path={file_path}, "
+ f"error={str(exc)}"
+ )
+
+
+def sanitize_upload_filename(filename: str) -> str:
+ """提取可跨平台展示的音频文件名,并拒绝非法名称与不支持的扩展名。"""
+ safe_name = (filename or "").replace("\\", "/").split("/")[-1].strip()
+ if (
+ not safe_name
+ or safe_name in {".", ".."}
+ or len(safe_name) > 255
+ or any(ord(character) < 32 for character in safe_name)
+ or any(character in _WINDOWS_INVALID_FILENAME_CHARS for character in safe_name)
+ or safe_name.lower().startswith(_INTERNAL_UPLOAD_PREFIX)
+ ):
+ raise BgmUploadError("invalid background music filename")
+
+ # Windows 会把扩展名前的首段识别为设备名,例如 CON.mp3、LPT1.wav 都
+ # 不能作为普通文件创建。即使服务端最终使用 UUID,提前拒绝这类名称也能
+ # 保证 API 在不同平台上的输入行为一致。
+ windows_basename = safe_name.split(".", 1)[0].rstrip(" .").upper()
+ if windows_basename in _WINDOWS_RESERVED_FILENAMES:
+ raise BgmUploadError("invalid background music filename")
+ if Path(safe_name).suffix.lower() not in SUPPORTED_BGM_EXTENSIONS:
+ supported_formats = ", ".join(
+ extension.removeprefix(".").upper()
+ for extension in SUPPORTED_BGM_EXTENSIONS
+ )
+ raise BgmUploadError(
+ f"unsupported background music format; supported formats: {supported_formats}"
+ )
+ return safe_name
+
+
+def _validate_audio(file_path: str) -> None:
+ """
+ 仅使用项目当前配置的 FFmpeg 验证文件包含可完整解码的音频流。
+
+ 项目允许 imageio-ffmpeg 提供便携 FFmpeg,该安装方式不保证同时存在
+ FFprobe,因此不能新增独立二进制依赖。`-map 0:a:0` 会在没有音频流时失败,
+ `-xerror` 会把解码错误提升为失败;完整解码还能拦截加密文件或随机数据偶然
+ 命中音频帧头的误判。文件可以包含专辑封面等附加流,但只校验第一条音频流。
+ """
+ try:
+ decoded = subprocess.run(
+ [
+ utils.get_ffmpeg_binary(),
+ "-nostdin",
+ "-v",
+ "error",
+ "-xerror",
+ "-i",
+ file_path,
+ "-map",
+ "0:a:0",
+ "-f",
+ "null",
+ "-",
+ ],
+ capture_output=True,
+ timeout=30,
+ check=False,
+ )
+ except subprocess.TimeoutExpired as exc:
+ raise BgmServiceError("FFmpeg background music validation timed out") from exc
+ except OSError as exc:
+ raise BgmServiceError("failed to run FFmpeg for background music validation") from exc
+ if decoded.returncode != 0:
+ raise BgmUploadError("uploaded file must contain a decodable audio stream")
+
+
+def _stage_bgm_upload(filename: str, source: BinaryIO) -> tuple[str, str, int]:
+ """
+ 将上传流写入同目录临时文件,并返回安全文件名、临时路径和字节数。
+
+ WebUI 的上传预检和最终持久化必须使用完全相同的分块读取、大小限制与文件名
+ 规则,否则可能出现界面显示可用、点击生成后却被服务端拒绝的状态分裂。
+ 临时文件由调用方在完成音频探测后删除或原子替换。
+ """
+ safe_name = sanitize_upload_filename(filename)
+ try:
+ target_dir = uploaded_bgm_dir(create=True)
+ except OSError as exc:
+ raise BgmServiceError("failed to prepare background music storage") from exc
+ temp_path = ""
+ total_bytes = 0
+
+ try:
+ try:
+ source.seek(0)
+ except (AttributeError, OSError) as exc:
+ raise BgmUploadError("background music upload is not seekable") from exc
+
+ # 保留原始扩展名便于 FFmpeg 针对无容器头的 AAC 等格式选择正确的
+ # demuxer;临时文件仍放在目标目录,以保证最终 os.replace 是原子操作。
+ descriptor, temp_path = tempfile.mkstemp(
+ prefix=_INTERNAL_UPLOAD_PREFIX,
+ suffix=Path(safe_name).suffix.lower(),
+ dir=target_dir,
+ )
+ with os.fdopen(descriptor, "wb") as output:
+ while True:
+ chunk = source.read(_COPY_CHUNK_BYTES)
+ if not chunk:
+ break
+ if not isinstance(chunk, (bytes, bytearray, memoryview)):
+ raise BgmUploadError("background music upload must be binary")
+ total_bytes += len(chunk)
+ if total_bytes > MAX_BGM_UPLOAD_BYTES:
+ raise BgmUploadError("background music file exceeds the 30 MB limit")
+ output.write(chunk)
+ output.flush()
+ os.fsync(output.fileno())
+
+ if total_bytes == 0:
+ raise BgmUploadError("background music file is empty")
+ return safe_name, temp_path, total_bytes
+ except Exception as exc:
+ _remove_staged_file(temp_path)
+ if isinstance(exc, BgmUploadError):
+ raise
+ if isinstance(exc, OSError):
+ raise BgmServiceError("failed to stage background music upload") from exc
+ raise
+ finally:
+ # Streamlit 还需要使用同一个 UploadedFile 做浏览器试听;恢复文件指针可
+ # 避免校验后播放器或最终保存读取到空内容。
+ try:
+ source.seek(0)
+ except (AttributeError, OSError):
+ pass
+
+
+def validate_bgm_upload(filename: str, source: BinaryIO) -> str:
+ """完整校验上传音频但不持久化,用于 WebUI 在显示“已就绪”前预检。"""
+ safe_name, temp_path, total_bytes = _stage_bgm_upload(filename, source)
+ try:
+ _validate_audio(temp_path)
+ logger.debug(
+ f"background music upload validated: name={safe_name}, "
+ f"size={total_bytes} bytes"
+ )
+ return safe_name
+ finally:
+ _remove_staged_file(temp_path)
+
+
+def save_bgm_upload(filename: str, source: BinaryIO) -> str:
+ """
+ 以分块、限量和原子替换的方式保存用户背景音乐。
+
+ 使用场景包括 FastAPI UploadFile 和 Streamlit UploadedFile,两者都提供二进制
+ 文件接口。先写同目录临时文件并验证,再通过 os.replace 原子落盘,既能避免
+ 并发上传或进程中断留下半个音频文件,也会让同名上传获得不同的 UUID 存储键,
+ 已排队或运行中的任务因此始终引用原来的不可变文件。
+ """
+ safe_name, temp_path, total_bytes = _stage_bgm_upload(filename, source)
+ stored_name = f"{uuid4().hex}{Path(safe_name).suffix.lower()}"
+ target_path = os.path.join(os.path.dirname(temp_path), stored_name)
+
+ try:
+ _validate_audio(temp_path)
+ try:
+ os.replace(temp_path, target_path)
+ except OSError as exc:
+ raise BgmServiceError("failed to persist background music upload") from exc
+ temp_path = ""
+ logger.info(
+ f"background music uploaded: original_name={safe_name}, "
+ f"stored_name={stored_name}, size={total_bytes} bytes"
+ )
+ return stored_name
+ finally:
+ _remove_staged_file(temp_path)
+
+
+def list_bgm_files() -> list[str]:
+ """列出用户上传和内置的可用背景音乐。"""
+ files_by_name: dict[str, str] = {}
+ for directory in (utils.song_dir(), uploaded_bgm_dir(create=True)):
+ if not os.path.isdir(directory):
+ continue
+ for name in sorted(os.listdir(directory), key=str.lower):
+ # 上传预检和最终保存都会短暂创建同目录文件。临时文件虽然带有合法
+ # 音频扩展名,但尚未完成校验,不能被随机 BGM 列表提前选中。
+ if name.startswith(_INTERNAL_UPLOAD_PREFIX):
+ continue
+ if Path(name).suffix.lower() not in SUPPORTED_BGM_EXTENSIONS:
+ continue
+ file_path = os.path.join(directory, name)
+ try:
+ # 枚举结果同样需要真实路径校验。否则攻击者可在允许目录中放置
+ # 指向外部文件的音频符号链接,再借随机 BGM 路径交给 MoviePy。
+ resolved_path = file_security.resolve_path_within_directory(
+ directory, file_path
+ )
+ except ValueError as exc:
+ logger.warning(
+ f"skip unsafe background music file: name={name}, error={str(exc)}"
+ )
+ continue
+ files_by_name[name] = resolved_path
+ return [files_by_name[name] for name in sorted(files_by_name, key=str.lower)]
+
+
+def resolve_bgm_file(unsafe_path: str) -> str:
+ """
+ 在用户上传目录和内置歌曲目录中解析 BGM,并拒绝两个白名单之外的路径。
+
+ 文件名优先命中用户目录,同时保留 `output000.mp3`、绝对白名单路径和
+ `./resource/songs/output000.mp3` 等旧用法。新上传文件使用 UUID,正常情况下
+ 不会与内置歌曲或历史上传发生重名。
+ """
+ if (
+ not unsafe_path
+ or Path(unsafe_path).suffix.lower() not in SUPPORTED_BGM_EXTENSIONS
+ ):
+ raise ValueError("unsupported background music path")
+
+ candidates = [unsafe_path]
+ if not os.path.isabs(unsafe_path):
+ candidates.append(os.path.join(utils.root_dir(), unsafe_path))
+
+ last_error = ValueError("background music file does not exist")
+ for directory in (uploaded_bgm_dir(create=True), utils.song_dir()):
+ for candidate in candidates:
+ try:
+ return file_security.resolve_path_within_directory(directory, candidate)
+ except ValueError as exc:
+ last_error = exc
+ raise ValueError(str(last_error)) from last_error
diff --git a/app/services/video.py b/app/services/video.py
index 538a5435..0e9cbc97 100644
--- a/app/services/video.py
+++ b/app/services/video.py
@@ -35,6 +35,7 @@ from app.models.schema import (
VideoParams,
VideoTransitionMode,
)
+from app.services import bgm as bgm_service
from app.services.utils import video_effects
from app.utils import file_security, utils
@@ -79,7 +80,6 @@ _MIN_MATERIAL_DIMENSION = 480
# 丢弃,最终以 "no valid materials found" 整体失败。这里留一个很小的容差,
# 既能放行仅仅因为取整而略低于阈值的素材,也仍然能挡住真正的低清素材。
_MIN_DIMENSION_TOLERANCE = 10
-_BGM_EXTENSIONS = (".mp3",)
_DEFAULT_VIDEO_CODEC = "libx264"
_SUPPORTED_VIDEO_CODECS = (
"libx264",
@@ -499,57 +499,27 @@ def delete_files(files: List[str] | str):
logger.debug(f"failed to delete file {file}: {str(e)}")
-def _resolve_bgm_file_path(song_dir: str, bgm_file: str) -> str:
- # 背景音乐只允许读取 resource/songs 目录内的文件,避免用户输入任意路径后
- # 被 MoviePy 打开。这里兼容两种常见输入:
- # 1. output000.mp3:来自 BGM 列表或用户只填写文件名
- # 2. ./resource/songs/output000.mp3:用户按项目目录结构填写的相对路径
- # 两种写法最终都会再次通过 resource/songs 白名单校验,不能绕过目录限制。
- try:
- return file_security.resolve_path_within_directory(song_dir, bgm_file)
- except ValueError as song_dir_exc:
- if os.path.isabs(bgm_file):
- raise song_dir_exc
-
- project_relative_file = os.path.join(utils.root_dir(), bgm_file)
- try:
- return file_security.resolve_path_within_directory(
- song_dir, project_relative_file
- )
- except ValueError as root_dir_exc:
- raise ValueError(str(root_dir_exc)) from song_dir_exc
-
-
def get_bgm_file(bgm_type: str = "random", bgm_file: str = ""):
if not bgm_type:
return ""
if bgm_file:
- song_dir = utils.song_dir()
try:
- resolved_bgm_file = _resolve_bgm_file_path(song_dir, bgm_file)
+ resolved_bgm_file = bgm_service.resolve_bgm_file(bgm_file)
except ValueError as exc:
- # API 请求里的 bgm_file 来自用户输入,不能直接把任意绝对路径交给
- # MoviePy 打开。这里强制限制到 resource/songs 目录,阻止读取
- # /etc/passwd、配置文件、密钥等非背景音乐文件。
+ # API 请求里的 bgm_file 来自用户输入,只允许解析到用户 BGM 或内置
+ # 歌曲目录,阻止 MoviePy 读取配置、密钥等任意服务器文件。
logger.warning(
- f"reject unsafe bgm file: {bgm_file}, song_dir: {song_dir}, error: {str(exc)}"
+ f"reject unsafe bgm file: {bgm_file}, error: {str(exc)}"
)
return ""
-
- if not resolved_bgm_file.lower().endswith(_BGM_EXTENSIONS):
- logger.warning(f"reject unsupported bgm file extension: {resolved_bgm_file}")
- return ""
-
return resolved_bgm_file
if bgm_type == "random":
- suffix = "*.mp3"
- song_dir = utils.song_dir()
- files = glob.glob(os.path.join(song_dir, suffix))
+ files = bgm_service.list_bgm_files()
# 当背景音乐目录为空时,直接回退为“不使用 BGM”,避免 random.choice([]) 抛异常。
if not files:
- logger.warning(f"no bgm files found in song directory: {song_dir}")
+ logger.warning("no background music files found")
return ""
return random.choice(files)
diff --git a/test/services/test_bgm.py b/test/services/test_bgm.py
new file mode 100644
index 00000000..30a1dfe2
--- /dev/null
+++ b/test/services/test_bgm.py
@@ -0,0 +1,329 @@
+import io
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+from uuid import UUID
+
+from fastapi import UploadFile
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from app.services import bgm
+from app.controllers.v1 import video as video_controller
+from app.models.exception import HttpException
+
+
+class _FakeRequest:
+ def __init__(self):
+ self.headers = {"x-task-id": "bgm-upload-test"}
+
+
+class _UnseekableUpload(io.BytesIO):
+ def seek(self, *args, **kwargs):
+ raise OSError("stream is not seekable")
+
+
+class _TextUpload(io.BytesIO):
+ def read(self, *args, **kwargs):
+ return "not binary"
+
+
+class TestBackgroundMusicService(unittest.TestCase):
+ def test_sanitize_upload_filename_strips_directory_components(self):
+ self.assertEqual(
+ bgm.sanitize_upload_filename("../../用户音乐.mp3"), "用户音乐.mp3"
+ )
+ self.assertEqual(
+ bgm.sanitize_upload_filename("windows\\path\\song.MP3"), "song.MP3"
+ )
+
+ def test_sanitize_upload_filename_accepts_common_audio_formats(self):
+ # WebUI 与 API 共用同一格式白名单;这里覆盖大小写和常见容器,避免未来
+ # 修改上传控件时只支持界面展示、服务层却拒绝文件。
+ for extension in bgm.SUPPORTED_BGM_EXTENSIONS:
+ filename = f"background{extension.upper()}"
+ with self.subTest(filename=filename):
+ self.assertEqual(bgm.sanitize_upload_filename(filename), filename)
+
+ def test_sanitize_upload_filename_rejects_invalid_names_and_extensions(self):
+ for filename in (
+ "",
+ " ",
+ ".",
+ "..",
+ "song.mp4",
+ "song.mp3\x00",
+ "CON.mp3",
+ "lpt1.wav",
+ "bad:name.mp3",
+ "bad?.flac",
+ ".bgm-upload-user.m4a",
+ "song.mp3.",
+ "aux.extra.ogg",
+ ):
+ with self.subTest(filename=filename):
+ with self.assertRaises(bgm.BgmUploadError):
+ bgm.sanitize_upload_filename(filename)
+
+ def test_save_bgm_upload_uses_atomic_storage_directory_write(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ source = io.BytesIO(b"valid-mp3-placeholder")
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "_validate_audio", return_value=None),
+ patch.object(
+ bgm,
+ "uuid4",
+ return_value=UUID("4fca18fc-e734-4f3a-a824-777a40d45c8c"),
+ ),
+ ):
+ saved_name = bgm.save_bgm_upload("music.mp3", source)
+
+ self.assertEqual(saved_name, "4fca18fce7344f3aa824777a40d45c8c.mp3")
+ self.assertEqual(
+ Path(temp_dir, saved_name).read_bytes(), b"valid-mp3-placeholder"
+ )
+ self.assertEqual(
+ [name for name in os.listdir(temp_dir) if name.startswith(".bgm-upload-")],
+ [],
+ )
+ # 服务会把文件指针恢复到开头,同一个 UploadedFile 仍可供 Streamlit
+ # 试听或后续 rerun 使用,不会因为保存操作变成空文件。
+ self.assertEqual(source.tell(), 0)
+
+ def test_validate_bgm_upload_checks_audio_without_persisting_file(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ source = io.BytesIO(b"valid-audio-placeholder")
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "_validate_audio", return_value=None),
+ ):
+ validated_name = bgm.validate_bgm_upload("preview.m4a", source)
+
+ self.assertEqual(validated_name, "preview.m4a")
+ # WebUI 预检只允许短暂使用临时文件,用户尚未点击生成时不能把文件
+ # 留在持久化 BGM 目录,也不能改变后续试听所需的文件指针。
+ self.assertEqual(os.listdir(temp_dir), [])
+
+ def test_staging_rejects_empty_unseekable_and_non_binary_uploads(self):
+ invalid_sources = (
+ (io.BytesIO(b""), "background music file is empty"),
+ (_UnseekableUpload(b"audio"), "not seekable"),
+ (_TextUpload(b"audio"), "must be binary"),
+ )
+ for source, expected_error in invalid_sources:
+ with self.subTest(expected_error=expected_error):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ with patch.object(
+ bgm, "uploaded_bgm_dir", return_value=temp_dir
+ ):
+ with self.assertRaisesRegex(
+ bgm.BgmUploadError, expected_error
+ ):
+ bgm.save_bgm_upload("invalid.mp3", source)
+ self.assertEqual(os.listdir(temp_dir), [])
+ self.assertEqual(source.tell(), 0)
+
+ def test_validate_bgm_upload_rejects_invalid_audio_and_cleans_temp_file(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(
+ bgm,
+ "_validate_audio",
+ side_effect=bgm.BgmUploadError("invalid audio"),
+ ),
+ ):
+ with self.assertRaises(bgm.BgmUploadError):
+ bgm.validate_bgm_upload("invalid.m4a", io.BytesIO(b"invalid"))
+
+ # 失败的预检同样不能在持久化目录留下临时音频,避免随后被随机 BGM
+ # 枚举逻辑选中,也避免长期运行时逐步堆积无效文件。
+ self.assertEqual(os.listdir(temp_dir), [])
+
+ def test_save_bgm_upload_rejects_oversized_file_and_cleans_temp_file(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "MAX_BGM_UPLOAD_BYTES", 4),
+ ):
+ with self.assertRaises(bgm.BgmUploadError):
+ bgm.save_bgm_upload("large.mp3", io.BytesIO(b"12345"))
+
+ self.assertEqual(os.listdir(temp_dir), [])
+
+ def test_save_bgm_upload_rejects_invalid_audio_before_replacing_target(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ target = Path(temp_dir, "music.mp3")
+ target.write_bytes(b"existing-valid-file")
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(
+ bgm,
+ "_validate_audio",
+ side_effect=bgm.BgmUploadError("invalid audio"),
+ ),
+ ):
+ with self.assertRaises(bgm.BgmUploadError):
+ bgm.save_bgm_upload("music.mp3", io.BytesIO(b"broken-file"))
+
+ # 校验失败发生在原子替换之前,已有用户文件不能被损坏。
+ self.assertEqual(target.read_bytes(), b"existing-valid-file")
+ self.assertEqual(os.listdir(temp_dir), ["music.mp3"])
+
+ def test_same_original_filename_creates_immutable_storage_keys(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ generated_uuids = [
+ UUID("11111111-1111-4111-8111-111111111111"),
+ UUID("22222222-2222-4222-8222-222222222222"),
+ ]
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "_validate_audio", return_value=None),
+ patch.object(bgm, "uuid4", side_effect=generated_uuids),
+ ):
+ first_name = bgm.save_bgm_upload(
+ "shared.mp3", io.BytesIO(b"first-user-audio")
+ )
+ second_name = bgm.save_bgm_upload(
+ "shared.mp3", io.BytesIO(b"second-user-audio")
+ )
+
+ self.assertNotEqual(first_name, second_name)
+ self.assertEqual(Path(temp_dir, first_name).read_bytes(), b"first-user-audio")
+ self.assertEqual(
+ Path(temp_dir, second_name).read_bytes(), b"second-user-audio"
+ )
+
+ def test_audio_validation_uses_only_configured_ffmpeg(self):
+ completed = SimpleNamespace(returncode=0)
+ with (
+ patch.object(
+ bgm.utils,
+ "get_ffmpeg_binary",
+ return_value="/portable/imageio/ffmpeg",
+ ),
+ patch.object(bgm.subprocess, "run", return_value=completed) as run,
+ ):
+ bgm._validate_audio("/tmp/background.m4a")
+
+ command = run.call_args.args[0]
+ self.assertEqual(command[0], "/portable/imageio/ffmpeg")
+ self.assertNotIn("ffprobe", " ".join(command).lower())
+ self.assertIn("0:a:0", command)
+
+ def test_audio_validation_distinguishes_service_failure_from_invalid_audio(self):
+ with patch.object(
+ bgm.subprocess,
+ "run",
+ side_effect=OSError("ffmpeg missing"),
+ ):
+ with self.assertRaises(bgm.BgmServiceError):
+ bgm._validate_audio("/tmp/background.mp3")
+
+ with patch.object(
+ bgm.subprocess,
+ "run",
+ return_value=SimpleNamespace(returncode=1),
+ ):
+ with self.assertRaises(bgm.BgmUploadError):
+ bgm._validate_audio("/tmp/background.mp3")
+
+ with patch.object(
+ bgm.subprocess,
+ "run",
+ side_effect=bgm.subprocess.TimeoutExpired("ffmpeg", 30),
+ ):
+ with self.assertRaises(bgm.BgmServiceError):
+ bgm._validate_audio("/tmp/background.mp3")
+
+ def test_save_normalizes_extension_and_maps_storage_failure(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "_validate_audio", return_value=None),
+ patch.object(
+ bgm,
+ "uuid4",
+ return_value=UUID("4fca18fc-e734-4f3a-a824-777a40d45c8c"),
+ ),
+ ):
+ saved_name = bgm.save_bgm_upload(
+ "UPPER.FLAC", io.BytesIO(b"valid-audio")
+ )
+ self.assertTrue(saved_name.endswith(".flac"))
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=temp_dir),
+ patch.object(bgm, "_validate_audio", return_value=None),
+ patch.object(bgm.os, "replace", side_effect=OSError("disk full")),
+ ):
+ with self.assertRaises(bgm.BgmServiceError):
+ bgm.save_bgm_upload("music.mp3", io.BytesIO(b"valid-audio"))
+ self.assertEqual(os.listdir(temp_dir), [])
+
+ def test_upload_controller_returns_uuid_and_maps_errors(self):
+ request = _FakeRequest()
+ upload = UploadFile(filename="music.mp3", file=io.BytesIO(b"audio"))
+ with patch.object(
+ bgm,
+ "save_bgm_upload",
+ return_value="4fca18fce7344f3aa824777a40d45c8c.mp3",
+ ):
+ response = video_controller.upload_bgm_file(request, upload)
+ self.assertEqual(response["status"], 200)
+ self.assertEqual(
+ response["data"]["file"],
+ "4fca18fce7344f3aa824777a40d45c8c.mp3",
+ )
+
+ for service_error, expected_status in (
+ (bgm.BgmUploadError("invalid audio"), 400),
+ (bgm.BgmServiceError("FFmpeg unavailable"), 500),
+ ):
+ with self.subTest(expected_status=expected_status):
+ with patch.object(
+ bgm, "save_bgm_upload", side_effect=service_error
+ ):
+ with self.assertRaises(HttpException) as context:
+ video_controller.upload_bgm_file(request, upload)
+ self.assertEqual(context.exception.status_code, expected_status)
+
+ def test_resolve_and_list_prefer_uploaded_file_with_same_name(self):
+ with (
+ tempfile.TemporaryDirectory() as builtin_dir,
+ tempfile.TemporaryDirectory() as uploaded_dir,
+ ):
+ Path(builtin_dir, "same.mp3").write_bytes(b"builtin")
+ Path(builtin_dir, "builtin.mp3").write_bytes(b"builtin")
+ Path(uploaded_dir, "same.mp3").write_bytes(b"uploaded")
+ Path(uploaded_dir, "user.flac").write_bytes(b"uploaded")
+ Path(uploaded_dir, ".bgm-upload-pending.m4a").write_bytes(b"pending")
+
+ with (
+ patch.object(bgm, "uploaded_bgm_dir", return_value=uploaded_dir),
+ patch.object(bgm.utils, "song_dir", return_value=builtin_dir),
+ ):
+ resolved = bgm.resolve_bgm_file("same.mp3")
+ listed = bgm.list_bgm_files()
+
+ self.assertEqual(
+ resolved, os.path.realpath(os.path.join(uploaded_dir, "same.mp3"))
+ )
+ self.assertEqual(
+ [os.path.basename(file_path) for file_path in listed],
+ ["builtin.mp3", "same.mp3", "user.flac"],
+ )
+ same_file = next(path for path in listed if path.endswith("same.mp3"))
+ self.assertEqual(
+ same_file, os.path.realpath(os.path.join(uploaded_dir, "same.mp3"))
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test/services/test_webui_bgm.py b/test/services/test_webui_bgm.py
new file mode 100644
index 00000000..4d49cfae
--- /dev/null
+++ b/test/services/test_webui_bgm.py
@@ -0,0 +1,112 @@
+import io
+import sys
+import unittest
+import wave
+from pathlib import Path
+from unittest.mock import patch
+
+from loguru import logger
+from streamlit.testing.v1 import AppTest
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from app.services import bgm
+
+
+ROOT_DIR = Path(__file__).parent.parent.parent
+WEBUI_MAIN = ROOT_DIR / "webui" / "Main.py"
+
+
+def _valid_wav_bytes() -> bytes:
+ """生成一个很短的标准 WAV,避免测试依赖仓库外部音频或系统录音文件。"""
+ output = io.BytesIO()
+ with wave.open(output, "wb") as wav_file:
+ wav_file.setnchannels(1)
+ wav_file.setsampwidth(2)
+ wav_file.setframerate(8000)
+ wav_file.writeframes(b"\x00\x00" * 800)
+ return output.getvalue()
+
+
+class TestWebuiBackgroundMusic(unittest.TestCase):
+ def _open_custom_bgm_panel(self):
+ app = AppTest.from_file(str(WEBUI_MAIN), default_timeout=30).run()
+ source_select = next(
+ item for item in app.selectbox if item.label == "背景音乐来源"
+ )
+ source_select.set_value("自定义背景音乐").run()
+ return app
+
+ @staticmethod
+ def _uploader(app):
+ return next(item for item in app.file_uploader if item.label == "上传背景音乐")
+
+ def test_invalid_audio_shows_error_without_ready_state_or_player(self):
+ app = self._open_custom_bgm_panel()
+ with patch.object(logger, "warning") as warning:
+ self._uploader(app).set_value(
+ ("invalid.m4a", b"not-a-decodable-audio-file", "audio/mp4")
+ ).run()
+ # 非法文件留在上传控件时,音量调整会触发 Streamlit rerun。缓存命中
+ # 只能重绘错误,不能重复执行校验或重复记录 warning。
+ next(
+ item for item in app.selectbox if item.label == "背景音乐音量"
+ ).set_value(0.4).run()
+
+ rejection_logs = [
+ call
+ for call in warning.call_args_list
+ if "WebUI background music validation rejected" in str(call)
+ ]
+ self.assertEqual([str(item.value) for item in app.exception], [])
+ self.assertTrue(any("有效" in item.value for item in app.error))
+ self.assertEqual(
+ [item.value for item in app.info if "背景音乐已就绪" in item.value],
+ [],
+ )
+ self.assertEqual(len(app.get("audio")), 0)
+ self.assertEqual(len(rejection_logs), 1)
+
+ def test_valid_audio_shows_ready_state_and_reuses_validation_cache(self):
+ app = self._open_custom_bgm_panel()
+ self._uploader(app).set_value(
+ ("valid.wav", _valid_wav_bytes(), "audio/wav")
+ ).run()
+
+ # 首次校验通过后,把服务函数改成显式失败;如果音量 rerun 错误地再次
+ # 调用 FFmpeg,AppTest 会收到 AssertionError,从而稳定保护缓存行为。
+ with patch.object(
+ bgm,
+ "validate_bgm_upload",
+ side_effect=AssertionError("validation repeated during rerun"),
+ ):
+ next(
+ item for item in app.selectbox if item.label == "背景音乐音量"
+ ).set_value(0.4).run()
+
+ self.assertEqual([str(item.value) for item in app.exception], [])
+ self.assertEqual([item.value for item in app.error], [])
+ self.assertEqual(
+ [item.value for item in app.info if "背景音乐已就绪" in item.value],
+ ["背景音乐已就绪: valid.wav"],
+ )
+ self.assertEqual(len(app.get("audio")), 1)
+
+ def test_service_failure_is_not_reported_as_invalid_user_audio(self):
+ app = self._open_custom_bgm_panel()
+ with patch.object(
+ bgm,
+ "validate_bgm_upload",
+ side_effect=bgm.BgmServiceError("FFmpeg unavailable"),
+ ):
+ self._uploader(app).set_value(
+ ("valid.wav", _valid_wav_bytes(), "audio/wav")
+ ).run()
+
+ self.assertEqual([str(item.value) for item in app.exception], [])
+ self.assertTrue(any("无法校验" in item.value for item in app.error))
+ self.assertEqual(len(app.get("audio")), 0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/webui/Main.py b/webui/Main.py
index acaf76be..6c14ab9f 100644
--- a/webui/Main.py
+++ b/webui/Main.py
@@ -1,5 +1,7 @@
+import hashlib
import html
import json
+import mimetypes
import os
import re
import shutil
@@ -36,6 +38,7 @@ from app.models.schema import (
VideoParams,
VideoTransitionMode,
)
+from app.services import bgm as bgm_service
from app.services import cache_manager, llm, video, voice
from app.services import state as sm
from app.services import task as tm
@@ -970,6 +973,8 @@ def _apply_pending_task_restore():
# 同时清空当前页面已缓存的上传素材,避免恢复后误用另一个任务的文件。
st.session_state["local_video_materials"] = []
st.session_state.pop("custom_audio_file_uploader", None)
+ st.session_state.pop("custom_bgm_uploader", None)
+ st.session_state.pop("custom_bgm_validation", None)
st.session_state["task_restore_upload_requirements"] = (
_build_restore_upload_requirements(params)
)
@@ -2324,7 +2329,8 @@ def _render_voice_preview(params, friendly_names, selected_tts_server, voice_nam
def _render_background_music_settings(params):
- """渲染背景音乐来源与音量设置。"""
+ """渲染背景音乐来源与音量设置,并返回本次待保存的上传文件。"""
+ uploaded_bgm_file = None
st.divider()
bgm_options = [
(tr("No Background Music"), ""),
@@ -2341,12 +2347,109 @@ def _render_background_music_settings(params):
params.bgm_type = selected_bgm_type
if params.bgm_type == "custom":
+ uploaded_bgm_file = st.file_uploader(
+ tr("Upload Background Music"),
+ type=[
+ extension.removeprefix(".")
+ for extension in bgm_service.SUPPORTED_BGM_EXTENSIONS
+ ],
+ accept_multiple_files=False,
+ key="custom_bgm_uploader",
+ help=tr("Upload Background Music Help"),
+ # Streamlit 默认会在控件上展示全局 200MB 上限。这里必须与服务层
+ # 30MB 硬限制保持一致,避免界面允许选择、提交时才被服务端拒绝。
+ max_upload_size=bgm_service.MAX_BGM_UPLOAD_BYTES // (1024 * 1024),
+ )
+ if uploaded_bgm_file is not None:
+ try:
+ safe_name = bgm_service.sanitize_upload_filename(
+ uploaded_bgm_file.name
+ )
+ # Streamlit 在调整音量等任意控件后都会重新执行页面。使用内容哈希
+ # 区分上传文件,并在当前会话内缓存完整解码结果,既不能只凭同名、
+ # 同大小文件误用旧结果,也避免每次 rerun 都重复调用 FFmpeg。
+ validation_key = (
+ safe_name,
+ uploaded_bgm_file.size,
+ hashlib.sha256(uploaded_bgm_file.getbuffer()).hexdigest(),
+ )
+ cached_validation = st.session_state.get("custom_bgm_validation")
+ if (
+ not cached_validation
+ or cached_validation.get("key") != validation_key
+ ):
+ try:
+ bgm_service.validate_bgm_upload(
+ uploaded_bgm_file.name, uploaded_bgm_file
+ )
+ except bgm_service.BgmUploadError as exc:
+ cached_validation = {
+ "key": validation_key,
+ "error": str(exc),
+ "error_type": "upload",
+ }
+ # 同一个文件指纹的失败结果会进入会话缓存,因此这里只在
+ # 首次真实执行校验时记录一次,避免普通控件 rerun 刷屏。
+ logger.warning(
+ "WebUI background music validation rejected: "
+ f"name={safe_name}, error={str(exc)}"
+ )
+ except bgm_service.BgmServiceError as exc:
+ cached_validation = {
+ "key": validation_key,
+ "error": str(exc),
+ "error_type": "service",
+ }
+ logger.error(
+ "WebUI background music validation failed: "
+ f"name={safe_name}, error={str(exc)}"
+ )
+ else:
+ cached_validation = {
+ "key": validation_key,
+ "error": "",
+ "error_type": "",
+ }
+ st.session_state["custom_bgm_validation"] = cached_validation
+
+ if cached_validation.get("error"):
+ if cached_validation.get("error_type") == "service":
+ raise bgm_service.BgmServiceError(
+ cached_validation["error"]
+ )
+ raise bgm_service.BgmUploadError(cached_validation["error"])
+ except bgm_service.BgmUploadError as exc:
+ # 非法文件不能沿用上一次有效上传的名称,否则任务参数可能仍指向
+ # 历史 BGM。保留 UploadedFile 返回值,让用户点击生成时仍会被最终
+ # 服务端校验拦截,而不是静默生成一条没有背景音乐的视频。
+ params.bgm_file = ""
+ st.error(tr("Invalid Background Music"))
+ except bgm_service.BgmServiceError:
+ params.bgm_file = ""
+ st.error(tr("Background Music Validation Failed"))
+ else:
+ # 完整解码校验通过后才展示播放器和“已就绪”。文件仍只在点击
+ # 生成时持久化,用户仅预览或随后移除文件不会污染 storage/bgm。
+ uploaded_mime_type = str(
+ getattr(uploaded_bgm_file, "type", "") or ""
+ )
+ preview_mime_type = (
+ uploaded_mime_type
+ if uploaded_mime_type.startswith("audio/")
+ else mimetypes.guess_type(safe_name)[0] or "audio/mpeg"
+ )
+ st.audio(uploaded_bgm_file, format=preview_mime_type)
+ st.info(f"{tr('Background Music Ready')}: {safe_name}")
+ params.bgm_file = safe_name
+
custom_bgm_file = st.text_input(
tr("Custom Background Music File"),
key="custom_bgm_file_input",
+ disabled=uploaded_bgm_file is not None,
)
- if custom_bgm_file:
- # 文件名由服务层映射到 resource/songs 后校验,UI 不接受任意路径。
+ if uploaded_bgm_file is None and custom_bgm_file:
+ # 文件名由服务层映射到 storage/bgm 或 resource/songs 后校验,
+ # UI 不接受两个白名单目录之外的任意路径。
params.bgm_file = custom_bgm_file.strip()
params.bgm_volume = stable_selectbox(
tr("Background Music Volume"),
@@ -2356,6 +2459,7 @@ def _render_background_music_settings(params):
format_func=lambda value: f"{int(value * 100)}%",
disabled=not params.bgm_type,
)
+ return uploaded_bgm_file
def _render_audio_settings(panel, params):
@@ -2766,8 +2870,8 @@ def _render_audio_settings(panel, params):
"Custom audio will be used directly. TTS synthesis will be skipped for this task."
)
)
- _render_background_music_settings(params)
- return uploaded_audio_file, voice_mode
+ uploaded_bgm_file = _render_background_music_settings(params)
+ return uploaded_audio_file, uploaded_bgm_file, voice_mode
def _render_subtitle_settings(panel, params):
@@ -2999,7 +3103,7 @@ def _render_subtitle_settings(panel, params):
def _render_generation_controls(
- params, uploaded_files, uploaded_audio_file, voice_mode
+ params, uploaded_files, uploaded_audio_file, uploaded_bgm_file, voice_mode
):
"""校验生成依赖、执行任务,并渲染日志与成片结果。"""
restore_upload_requirements = st.session_state.get(
@@ -3095,6 +3199,25 @@ def _render_generation_controls(
st.error(tr("Task Restore Custom Audio Warning"))
st.stop()
+ if uploaded_bgm_file:
+ try:
+ saved_bgm_name = bgm_service.save_bgm_upload(
+ uploaded_bgm_file.name, uploaded_bgm_file
+ )
+ except bgm_service.BgmUploadError as exc:
+ _remove_active_generation_task(task_id)
+ logger.warning(f"WebUI background music upload rejected: {str(exc)}")
+ st.error(tr("Invalid Background Music"))
+ st.stop()
+ except bgm_service.BgmServiceError as exc:
+ _remove_active_generation_task(task_id)
+ logger.error(f"WebUI background music upload failed: {str(exc)}")
+ st.error(tr("Background Music Validation Failed"))
+ st.stop()
+ # 保存成功后只把文件名写入任务参数。视频服务会在两个 BGM 白名单
+ # 目录中重新解析,避免把服务器绝对路径持久化或展示给用户。
+ params.bgm_file = saved_bgm_name
+
if uploaded_audio_file:
task_dir = utils.task_dir(task_id)
try:
@@ -3232,11 +3355,19 @@ def _render_application():
_render_script_settings(left_panel, params)
uploaded_files = _render_video_settings(middle_panel, params)
- uploaded_audio_file, voice_mode = _render_audio_settings(audio_panel, params)
+ uploaded_audio_file, uploaded_bgm_file, voice_mode = _render_audio_settings(
+ audio_panel, params
+ )
_render_subtitle_settings(right_panel, params)
- _render_generation_controls(params, uploaded_files, uploaded_audio_file, voice_mode)
+ _render_generation_controls(
+ params,
+ uploaded_files,
+ uploaded_audio_file,
+ uploaded_bgm_file,
+ voice_mode,
+ )
config.save_config()
diff --git a/webui/i18n/en.json b/webui/i18n/en.json
index 9833e903..59f01d1b 100644
--- a/webui/i18n/en.json
+++ b/webui/i18n/en.json
@@ -110,6 +110,11 @@
"Random Background Music": "Random Background Music",
"Custom Background Music": "Custom Background Music",
"Custom Background Music File": "Custom Music Path",
+ "Upload Background Music": "Upload Background Music",
+ "Upload Background Music Help": "Upload an MP3, M4A, AAC, WAV, FLAC, OGG, OPUS, or WMA file up to 30 MB. It will be stored persistently when video generation starts.",
+ "Background Music Ready": "Background music ready",
+ "Invalid Background Music": "Please upload a valid supported background music file up to 30 MB.",
+ "Background Music Validation Failed": "Background music could not be validated because FFmpeg or storage is unavailable. Please check the server logs.",
"Background Music Volume": "Background Music Volume",
"Subtitle Settings": "**Subtitle Settings**",
"Enable Subtitles": "Enable Subtitles",
diff --git a/webui/i18n/ru.json b/webui/i18n/ru.json
index 770be311..c91e8970 100644
--- a/webui/i18n/ru.json
+++ b/webui/i18n/ru.json
@@ -110,6 +110,11 @@
"Random Background Music": "Случайная фоновая музыка",
"Custom Background Music": "Своя фоновая музыка",
"Custom Background Music File": "Введите путь к файлу фоновой музыки:",
+ "Upload Background Music": "Загрузить фоновую музыку",
+ "Upload Background Music Help": "Загрузите файл MP3, M4A, AAC, WAV, FLAC, OGG, OPUS или WMA размером до 30 МБ. Он будет сохранён при запуске создания видео.",
+ "Background Music Ready": "Фоновая музыка готова",
+ "Invalid Background Music": "Загрузите корректный файл фоновой музыки поддерживаемого формата размером до 30 МБ.",
+ "Background Music Validation Failed": "Не удалось проверить фоновую музыку: FFmpeg или хранилище недоступны. Проверьте журналы сервера.",
"Background Music Volume": "Громкость фоновой музыки",
"Subtitle Settings": "**Настройки субтитров**",
"Enable Subtitles": "Показывать субтитры",
diff --git a/webui/i18n/zh.json b/webui/i18n/zh.json
index 5afe74bc..2d46147a 100644
--- a/webui/i18n/zh.json
+++ b/webui/i18n/zh.json
@@ -110,6 +110,11 @@
"Random Background Music": "随机背景音乐",
"Custom Background Music": "自定义背景音乐",
"Custom Background Music File": "请输入自定义背景音乐的文件路径",
+ "Upload Background Music": "上传背景音乐",
+ "Upload Background Music Help": "请上传不超过 30 MB 的 MP3、M4A、AAC、WAV、FLAC、OGG、OPUS 或 WMA 文件,点击生成视频时会持久化保存。",
+ "Background Music Ready": "背景音乐已就绪",
+ "Invalid Background Music": "请上传不超过 30 MB 的有效且受支持的背景音乐文件。",
+ "Background Music Validation Failed": "无法校验背景音乐,请检查 FFmpeg、存储目录和服务端日志。",
"Background Music Volume": "背景音乐音量",
"Subtitle Settings": "**字幕设置**",
"Enable Subtitles": "启用字幕",