feat(voice): 提取视频配音接口 + 素材来源标识 #1654

Merged

xiaoxia merged 2 commits from feat/extract-video-voice-and-source-label into develop 2026-09-03 18:34:04 +08:00

Conversation 3 Commits 2 Files Changed 2

+263 -3

xiaoxia commented 2026-09-03 18:23:56 +08:00

Owner

Copy Link

Copy Source

功能 1：提取视频配音接口

POST /voices/extract-voice

接收视频文件，用 ffmpeg 提取人声并降噪，保存到配音素材库。

接口规格

• 输入：视频文件（mp4/mov/webm/avi）+ project_id，最大 500MB
• 处理：
  1. 保存视频到临时文件
  2. ffmpeg 提取音频 + 降噪滤镜链：highpass=f=80 → afftdn=nf=-25 → lowpass=f=8000
  3. 编码为 mp3 192kbps 单声道 44.1kHz
  4. 上传到 OSS uploads/voice/extracted/{uuid}.mp3
  5. 创建 Asset 记录到用户配音素材库
  6. 清理临时文件
• 输出：{id, name, audio_url, duration, file_size, status, source}
• metadata：source: "video_extract", original_video: 原文件名

错误处理

• 非视频文件 → 400
• 文件过大 → 413
• ffmpeg 失败（无音轨等） → 422
• 超时（>5分钟） → 504

功能 2：素材来源标识

在 Asset 的 metadata.source 字段标识来源：

来源	source 值	写入位置
TTS 保存	tts_job	tts.py save_tts_job_to_library()（已有）
用户上传	upload	ingest.py worker（本次新增）
视频提取	video_extract	voices.py extract_voice_from_video()（本次新增）

AssetResponse.metadata 已包含此字段，前端可直接通过 asset.metadata.source 判断来源，区分 AI 生成配音和用户上传配音。

文件变更

• apps/api/app/api/routes/voices.py — 新增 extract-voice 端点 + 辅助函数
• apps/worker/worker_app/tasks/ingest.py — 上传素材写入 source=upload 标识

## 功能 1：提取视频配音接口 **POST /voices/extract-voice** 接收视频文件，用 ffmpeg 提取人声并降噪，保存到配音素材库。 ### 接口规格 - **输入**：视频文件（mp4/mov/webm/avi）+ project_id，最大 500MB - **处理**： 1. 保存视频到临时文件 2. ffmpeg 提取音频 + 降噪滤镜链：`highpass=f=80 → afftdn=nf=-25 → lowpass=f=8000` 3. 编码为 mp3 192kbps 单声道 44.1kHz 4. 上传到 OSS `uploads/voice/extracted/{uuid}.mp3` 5. 创建 Asset 记录到用户配音素材库 6. 清理临时文件 - **输出**：`{id, name, audio_url, duration, file_size, status, source}` - **metadata**：`source: "video_extract"`, `original_video: 原文件名` ### 错误处理 - 非视频文件 → 400 - 文件过大 → 413 - ffmpeg 失败（无音轨等） → 422 - 超时（>5分钟） → 504 ## 功能 2：素材来源标识 在 Asset 的 `metadata.source` 字段标识来源： | 来源 | source 值 | 写入位置 | |------|-----------|----------| | TTS 保存 | `tts_job` | `tts.py` save_tts_job_to_library()（已有） | | 用户上传 | `upload` | `ingest.py` worker（本次新增） | | 视频提取 | `video_extract` | `voices.py` extract_voice_from_video()（本次新增） | `AssetResponse.metadata` 已包含此字段，前端可直接通过 `asset.metadata.source` 判断来源，区分 AI 生成配音和用户上传配音。 ## 文件变更 - `apps/api/app/api/routes/voices.py` — 新增 extract-voice 端点 + 辅助函数 - `apps/worker/worker_app/tasks/ingest.py` — 上传素材写入 source=upload 标识

xiaoxia added 1 commit 2026-09-03 18:23:56 +08:00

feat(voice): 提取视频配音接口 + 素材来源标识 ... 5478be5c09

1. 新增 POST /voices/extract-voice 接口：
   - 接收视频文件（mp4/mov/webm/avi，最大 500MB）
   - ffmpeg 提取音频 + 人声降噪（highpass→afftdn→lowpass 滤镜链）
   - 编码为 mp3 192kbps 保存到配音素材库
   - 原视频不保留（临时文件处理后即清理）
   - 返回素材信息（id、时长、文件大小、URL）
   - metadata.source = 'video_extract'

2. 素材来源标识（metadata.source 字段）：
   - TTS 保存：source='tts_job'（已有）
   - 用户上传：source='upload'（本次新增，写入 ingest worker）
   - 视频提取：source='video_extract'（本次新增）
   - metadata 已在 AssetResponse 中返回，前端可直接读取

gitea-actions bot commented 2026-09-03 18:25:05 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1654
预览链接	https://pr-1654.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1654 | | 预览链接 | [https://pr-1654.preview.xiaoxiajianji.com](https://pr-1654.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot added 1 commit 2026-09-03 18:28:40 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] fe0ceceeb6

auto-approve-bot commented 2026-09-03 18:33:06 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：3 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [apps/api/app/api/routes/voices.py: 535] 参数 project_id 未被使用

   • 问题类型：逻辑bug
   • 问题描述：函数 extract_voice_from_video 接收了 project_id 表单参数，但在函数体内部完全未使用。代码逻辑是调用 _find_or_create_voice_library_for_extract，该函数会遍历用户的所有可访问项目并选取第一个匹配项。这导致用户无法指定将提取的配音存放到特定项目，违背了接口设计意图。
   • 修改建议：将 project_id 传递给 _find_or_create_voice_library_for_extract 函数，并修改该函数逻辑以优先使用指定的 project_id，而非遍历查找。

2. [apps/worker/worker_app/tasks/ingest.py: 688] Metadata 覆盖导致数据丢失

   • 问题类型：数据损坏风险
   • 问题描述：在更新已存在的 Asset 记录时，使用了 asset.metadata = metadata 进行直接赋值。metadata 变量在当前上下文中仅包含 source: "upload" 等字段。如果该 Asset 是由 voices.py 创建的（包含 source: "video_extract" 和 original_video 等元数据），此操作会清空原有的业务元数据，导致数据丢失。
   • 修改建议：使用字典合并（如 asset.metadata.update(metadata)）或仅更新特定字段，避免全量覆盖。

3. [apps/api/app/api/routes/voices.py: 564] 文件名处理存在路径遍历风险

   • 问题类型：安全漏洞
   • 问题描述：构造 video_path 时直接使用了 file.filename：tmp_dir / f"...{file.filename}"。如果攻击者上传的文件名包含 ../（如 ../../evil.mp4），pathlib 解析后可能会将文件写入临时目录之外（如 /tmp/evil.mp4），虽然受限于系统权限，但仍存在污染系统临时目录或覆盖其他文件的风险。此外，特殊字符可能导致 ffmpeg 调用失败。
   • 修改建议：不要直接使用用户提供的文件名作为磁盘文件名。应使用 uuid 生成安全的临时文件名，原始文件名仅用于元数据记录或返回值。

💡 改进建议（不阻塞合并）

1. [apps/worker/worker_app/tasks/ingest.py: 633, 669, 688] 重复的 Metadata 赋值

   • 具体内容：代码在 ingest_error 分支、新建 Asset 分支和更新 Asset 分支均设置了 metadata["source"] = "upload"。建议在函数入口处统一处理 metadata 的初始化或默认值，减少重复代码。

2. [apps/api/app/api/routes/voices.py: 589] 依赖外部命令未做存在性检查

   • 具体内容：代码直接调用 subprocess.run(["ffmpeg", ...])。如果运行环境未安装 ffmpeg 或不在 PATH 中，会导致运行时错误。虽然这是环境配置问题，但在关键路径上增加预检查或捕获更具体的 FileNotFoundError 会更健壮。

✅ 良好实践

• 使用了 subprocess.run 的列表参数形式调用外部命令，有效避免了 Shell 注入风险。
• 在 voices.py 中设置了 timeout=300，防止长时间处理阻塞服务。
• 使用了 tempfile.mkdtemp 和 try...finally 确保临时文件被清理，资源管理良好。
• 对上传文件大小进行了流式检查（1MB chunk），防止内存溢出。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-09-03 10:33:05 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：3 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[apps/api/app/api/routes/voices.py: 535] 参数 `project_id` 未被使用** - 问题类型：逻辑bug - 问题描述：函数 `extract_voice_from_video` 接收了 `project_id` 表单参数，但在函数体内部完全未使用。代码逻辑是调用 `_find_or_create_voice_library_for_extract`，该函数会遍历用户的所有可访问项目并选取第一个匹配项。这导致用户无法指定将提取的配音存放到特定项目，违背了接口设计意图。 - 修改建议：将 `project_id` 传递给 `_find_or_create_voice_library_for_extract` 函数，并修改该函数逻辑以优先使用指定的 `project_id`，而非遍历查找。 2. **[apps/worker/worker_app/tasks/ingest.py: 688] Metadata 覆盖导致数据丢失** - 问题类型：数据损坏风险 - 问题描述：在更新已存在的 Asset 记录时，使用了 `asset.metadata = metadata` 进行直接赋值。`metadata` 变量在当前上下文中仅包含 `source: "upload"` 等字段。如果该 Asset 是由 `voices.py` 创建的（包含 `source: "video_extract"` 和 `original_video` 等元数据），此操作会清空原有的业务元数据，导致数据丢失。 - 修改建议：使用字典合并（如 `asset.metadata.update(metadata)`）或仅更新特定字段，避免全量覆盖。 3. **[apps/api/app/api/routes/voices.py: 564] 文件名处理存在路径遍历风险** - 问题类型：安全漏洞 - 问题描述：构造 `video_path` 时直接使用了 `file.filename`：`tmp_dir / f"...{file.filename}"`。如果攻击者上传的文件名包含 `../`（如 `../../evil.mp4`），`pathlib` 解析后可能会将文件写入临时目录之外（如 `/tmp/evil.mp4`），虽然受限于系统权限，但仍存在污染系统临时目录或覆盖其他文件的风险。此外，特殊字符可能导致 `ffmpeg` 调用失败。 - 修改建议：不要直接使用用户提供的文件名作为磁盘文件名。应使用 `uuid` 生成安全的临时文件名，原始文件名仅用于元数据记录或返回值。 ### 💡 改进建议（不阻塞合并） 1. **[apps/worker/worker_app/tasks/ingest.py: 633, 669, 688] 重复的 Metadata 赋值** - 具体内容：代码在 `ingest_error` 分支、新建 Asset 分支和更新 Asset 分支均设置了 `metadata["source"] = "upload"`。建议在函数入口处统一处理 `metadata` 的初始化或默认值，减少重复代码。 2. **[apps/api/app/api/routes/voices.py: 589] 依赖外部命令未做存在性检查** - 具体内容：代码直接调用 `subprocess.run(["ffmpeg", ...])`。如果运行环境未安装 ffmpeg 或不在 PATH 中，会导致运行时错误。虽然这是环境配置问题，但在关键路径上增加预检查或捕获更具体的 `FileNotFoundError` 会更健壮。 ### ✅ 良好实践 - 使用了 `subprocess.run` 的列表参数形式调用外部命令，有效避免了 Shell 注入风险。 - 在 `voices.py` 中设置了 `timeout=300`，防止长时间处理阻塞服务。 - 使用了 `tempfile.mkdtemp` 和 `try...finally` 确保临时文件被清理，资源管理良好。 - 对上传文件大小进行了流式检查（1MB chunk），防止内存溢出。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-09-03 10:33:05 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit e6e4090f3c into develop 2026-09-03 18:34:04 +08:00

gitea-actions bot commented 2026-09-03 18:38:00 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1654 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1654 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this pull request 2026-09-03 19:53:08 +08:00

fix: 修复 voices.py 中 3 处 ruff B904 错误，解除 CI Validate-Style 阻塞 #1667

xiaoxia referenced this pull request 2026-09-04 23:31:28 +08:00

Release: 同步 develop 到 main（PR #1654~#1698 全量同步） #1699

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1654