Stooland Docs

Appearance

智能体分镜闭环与 FFmpeg 后备合成 ​

> 视频合成与 AI 处理服务采用 Muse Engine（缪斯引擎） 品牌名，内部实现代码仍使用 pybridge。

核心目标 ​

  • 将分镜能力升级为“智能体应用”，形成从想法→分镜→素材/配音→合成→发布的闭环。
  • 保留现有 REST，用独立 MCP 接口（对外/AI 客户端）进行编排，新增 FFmpeg 后备合成。

已落地 ​

  • 接口与数据
    • 新建智能体数据表与迁移：agent/agent_app/agent_app_run/...，含索引、外键与 TEXT 优化。
    • 后端 REST：/agent/admin/app、/agent/admin/run 模型与控制器接入，运行记录落表与更新。
    • 新增 MCP 服务入口与路由：/mcp/tools、/mcp/tools/call、/mcp/resources、/mcp/prompts、/mcp/jobs/:id。
    • 修复 MCP 路由变量支持 UUID：jobs/<id> 并设置正则。
  • 智能体 UI
    • Gallery：/aigc/agents/gallery，卡片管理与入口。
    • 详情与调试：/aigc/agents/detail，选择分镜→读取预签名→触发 MCP FFmpeg→查看状态与结果。
    • 分镜页工具条：保留“ICE合成视频”，新增“FFmpeg合成视频（调试）”。
  • 前端生成编排
    • agent-controller.js：生成→标准化→确保项目→批量保存。
    • llm-provider-adapter.js：Ark/Qwen/统一接口适配与标准化输出。
    • StoryBoard.vue：agentIdeaToVideo() 走 ICE 合成闭环；composeWithFFmpeg() 走 MCP。
  • FFmpeg 后备与桥接
    • pybridge（根目录）：FastAPI 服务与 FFmpeg Runner（最小实现）。
    • MCP→pybridge：触发合成并在 getJob 成功时自动上传 OSS，更新 agent_app_run.media_url。
    • 修复预签名 URL 被转义导致 403：MCP 禁用过滤读取 JSON，后端与 Python 均反转义 &amp;。

主要接口 ​

  • REST（后端）
    • POST /agent/admin/run 创建运行记录
    • PUT /agent/admin/run/{id} 更新状态/结果（ICE 闭环已接入）
  • MCP（后端）
    • GET /mcp/tools、POST /mcp/tools/call、GET /mcp/jobs/:id
    • 工具：compose_timeline_ffmpeg、generate_storyboard、batch_dubbing 等
  • pybridge（Python）
    • POST /compose-timeline-ffmpeg、GET /jobs/{job_id}

环境与配置 ​

  • 需在 api/.env 配置：
    • PYBRIDGE_URL（例：http://127.0.0.1:8787）
    • OSS 相关：OSS_ACCESSKEY_ID/OSS_ACCESSKEY_SECRET/OSS_BUCKET_NAME/OSS_REGION/OSS_DOMAIN
  • Python 服务启动：
    • python3 -m venv pybridge/.venv && source pybridge/.venv/bin/activate
    • pip install -r pybridge/requirements.txt
    • python -m uvicorn src.service.fastapi_app:app --host 0.0.0.0 --port 8787

调试与验证 ​

  • ICE 路径：分镜页点击“ICE合成视频”，沿用现有闭环（项目已稳定）。
  • FFmpeg 路径：
    • 详情页或分镜页点击“FFmpeg合成视频”，返回 job_id
    • 查询 GET /mcp/jobs/{job_id}，完成后返回 status=success 与 media_url（自动上传 OSS）

常见问题与修复 ​

  • 404 controller not exists: app\mcp\controller\Mcp 属于路由层，已通过 jobs/<id> + 正则修复。
  • 403 Forbidden（OSS）：预签名 URL 被 htmlspecialchars 转义，已在 MCP 禁用过滤读取 JSON，并在 MCP/Python 层反转义。
  • JSON 全局过滤绕过：api/app/Request.php 在 Content-Type: application/json 时自动禁用 param/post 的全局过滤（保障签名 URL 精确透传）。

候选成熟项目对比 ​

  • moviepy（https://github.com/Zulko/moviepy）
    • 优点：高层抽象，剪辑/拼接/文本/合成功能丰富；跨平台；生态文档完善；快速表达复杂效果。
    • 缺点：v2.0 有重大变更需适配；整体性能较直接 FFmpeg 慢（大量数据导入/导出与 numpy 操作）。
    • 适用：快速实现合成逻辑、字幕叠加、简单特效；对性能不苛刻的批处理。
  • ffmpeg-python（https://github.com/kkroening/ffmpeg-python）
    • 优点：对 FFmpeg 复杂滤镜图支持好；以 Python DSL 构建命令，更可维护；保留 FFmpeg 性能与能力边界。
    • 缺点：本质仍是命令封装，需理解 FFmpeg 滤镜与映射；遇到少见参数时需回退手写。
    • 适用：需要稳定、可维护的复杂 filter_complex 组合（拼接、字幕、对齐）。
  • PyAV（https://github.com/PyAV-Org/PyAV）
    • 优点：直接绑定 FFmpeg 库；帧级精确控制、容器与编解码细粒度操作；性能与可控性强。
    • 缺点：学习曲线陡峭；复杂度高；与底层版本兼容性需谨慎管理。
    • 适用：需要精确的时序控制、音视频对齐、复杂轨道操作的高性能场景。
  • vidgear（https://github.com/abhiTronix/vidgear）
    • 优点：高性能跨平台视频处理框架，提供多种“Gear”（采集、写入、流式、网络传输、WebRTC 等）；多线程+Asyncio，封装健壮。
    • 缺点：更偏向流媒体/实时处理；学习与集成范围较广，超出现阶段离线合成的最小需求。
    • 适用：后续若需实时预览、网络分发、WebRTC 流式推送。

选型建议 ​

  • 第一阶段：在现有最小实现基础上引入 ffmpeg-python，以 DSL 替换手写命令的组装，提升可维护性与可测试性。
  • 第二阶段：如需帧级对齐与复杂轨道，在局部能力上引入 PyAV；保持 MCP 协议不变，通过适配层切换实现。
  • 补充：在若干高层合成需求上可引入 moviepy 以加速开发；实时/流式场景再考虑 vidgear。

引入策略与路径 ​

  • 以 Git 子模块方式放置到 pybridge/vendor/submodules/<project>。
  • 在 pybridge/src/bridge/ 增加适配器层（如 moviepy_adapter.py、ffmpeg_python_adapter.py、pyav_adapter.py）。
  • 保持 POST /compose-timeline-ffmpeg 与 GET /jobs/{job_id} 协议不变，内部选择实现路径。
  • 按目标增强合成能力：
    • 分段精确对齐音频主轨
    • 素材不足自动补帧与统一帧率
    • 字幕样式参数化与轨道化
  • 继续由 pybridge 完成 OSS 上传与 agent_app_run.media_url 更新。

维护与版本化 ​

  • 在文档中记录：项目名、版本、仓库链接、许可协议、引入方式（子模块/打包）、适配层文件路径与测试用例位置。
  • 加入最小集成测试，覆盖：时间线解析、合成成功/失败、字幕轨道、音频映射、OSS 上传回写。

当前选型执行 ​

  • 已引入 ffmpeg-python 依赖（pybridge/requirements.txt）并新增适配器 pybridge/src/bridge/ffmpeg_python_adapter.py。
  • pybridge/src/bridge/ffmpeg_runner.py 支持通过 options.impl = "ffmpeg-python" 使用适配器，异常时回退到原始命令。
  • 文档与 README 已更新选型与使用说明。