Movie Narrator 插件开发指南:10分钟为视频流水线注入自定义步骤与新TTS后端
Movie Narrator 插件开发指南:10分钟为视频流水线注入自定义步骤与新TTS后端
Movie Narrator(movie-narrator)是一款只需用一句提示词就能生成带解说旁白的电影回顾视频的开源工具。它的强大之处在于内置插件系统:你可以在不修改任何核心源码的前提下,为视频流水线注入自定义步骤,或接入全新的 TTS 语音合成后端。本指南面向新手,带你用 10 分钟完成一次完整的插件开发。
一、先看懂插件架构:注册表模式
Movie Narrator 的插件系统基于统一的注册表(Registry)模式——"导入时注册,运行时发现"。通过插件,你可以扩展五类能力:
| 扩展类型 | 用途 |
|---|---|
| 流水线步骤 | 在任何环节注入自定义处理逻辑 |
| TTS 提供商 | 接入新的语音合成后端 |
| Vision 说明生成器 | 新的画面描述后端 |
| LLM / Research 提供商 | 替换推理与资料检索后端 |
| 远程提供商 | 将 LLM/TTS 调用代理到远程 worker(v0.6+) |
一个插件本质上就是实现了 name 属性和 register(ctx) 方法的对象,契约定义见 contracts.py:
class WatermarkPlugin:
name = "watermark"
def register(self, ctx: PluginContext) -> None:
ctx.steps.register("add_watermark", add_watermark, after="render_video")
PluginContext 向插件暴露 steps、tts、vision、llm、research 五个全局注册表,拿到后想往哪个注册什么就往哪个注册。
二、给视频流水线加一个自定义步骤
Movie Narrator 内置 16 个按固定顺序执行的步骤(如 resolve_video → generate_script → generate_voice → … → render_video → validate_deliverable)。插件步骤必须声明插入点:
after="render_video":紧跟在指定步骤之后执行before="validate_deliverable":紧跟在指定步骤之前执行
还有一个关键概念是 Soft(软)步骤 vs Hard(硬)步骤:
- 软步骤(
soft=True):出错时被捕获并降级为警告,流水线继续输出(需配status_field和consequence) - 硬步骤(默认):出错直接中止流水线
参考仓库自带的水印插件示例——它在 render_video 之后用 ffmpeg 把水印图片合成到成片右下角:
参考实现:plugin.py,完整插件包见 examples/plugins/watermark/
步骤函数接收并返回 Context,其中可读写 ctx.video_path、ctx.output_dir、ctx.metadata 等全部流水线状态。
三、打包插件:entry point 配置
插件通过 Python 的 entry point 机制被发现。在 pyproject.toml 中声明即可:
[project.entry-points."movie_narrator.plugins"]
my-plugin = "my_package:MyPlugin"
仓库里提供了一个开箱即用的插件模板,目录结构、占位符都帮你准备好了:
my-plugin/
├── pyproject.toml # 声明 entry point
└── my_package/
└── __init__.py # 实现 MyPlugin 类
模板说明见 template/README.md 和 pyproject.toml。
四、安装、发现与验证插件
安装并验证只需三条命令:
pip install -e . # 开发模式安装插件
mn plugin list # 列出已安装的插件
mn plugin registries # 查看所有已注册的步骤与提供商
也可以在代码里显式触发发现与加载:
from movie_narrator import discover_plugins, load_plugin
discover_plugins() # 自动加载所有已安装插件
💡 建议插件在导入时调用 check_version((0, 8, 0)) 声明最低契约版本——引擎版本过低时会快速失败并给出清晰报错,避免用户踩坑。兼容性策略详见 PLUGIN_DEVELOPMENT.md。
五、10分钟接入一个全新 TTS 后端
Movie Narrator 内置 edge、openai、mimo 三种 TTS 后端,但它们都走同一个抽象协议:实现 synthesize(text, voice, output_path) 异步方法,在指定路径产出 mp3 音频即可(时长探测由流水线负责,后端不用管)。
第 1 步:注册 TTS 工厂
from movie_narrator import register_tts
@register_tts("elevenlabs")
def make_elevenlabs(settings: Settings) -> TTSProvider:
from .elevenlabs import ElevenLabsProvider
return ElevenLabsProvider(settings)
第 2 步:实现协议
你的 Provider 只需实现 protocol.py 中的 synthesize 方法。可以参考内置的 OpenAI 实现:它用 asyncio.to_thread 包装同步 SDK,写法非常简洁。
第 3 步:切换配置
工厂会收到项目的 Settings 对象(含 API Key 等配置)。内置后端的注册与分发逻辑在 factory.py 中,插件注册的名字会汇入同一个注册表。之后在环境变量中将 MN_TTS_PROVIDER 设为你的 provider 名称即可生效。
⚠️ 注册表对 TTS 启用了协议校验:工厂若返回不符合 TTSProvider 的对象,create() 会抛出 TypeError,帮你尽早发现问题。
六、常见坑与最佳实践
- 重名冲突:注册已存在的名字会抛
ValueError(如tts provider 'edge' is already registered),插件取名务必避开内置名。 - 优先用软步骤:非必要步骤建议
soft=True,出错时降级而非让整个视频任务失败。 - 别持有 PluginContext 引用:它只在注册阶段存在,用完即弃。
- 声明契约版本:导入时调用
check_version(),版本不匹配时快速失败。 - 签名保持稳定:
Context -> Context的步骤函数签名和register(name, func, *, soft, ...)签名承诺不会变更,可放心依赖。
七、延伸阅读
| 资源 | 路径 |
|---|---|
| 插件开发完整文档 | docs/PLUGIN_DEVELOPMENT.md |
| 插件模板 | examples/plugins/template/ |
| 水印步骤示例 | examples/plugins/watermark/ |
| TTS 协议说明 | docs/sdk/tts.md |
| SDK 注册表说明 | docs/sdk/registries.md |
| 步骤注册源码 | src/movie_narrator/pipeline/registry.py |
从一句提示词到一支带解说的电影回顾视频,Movie Narrator 已经帮你跑通了全程;而插件系统,正是让它"长"出更多可能的入口。现在,打开模板,写第一个 register 吧!🚀