Transmute 开发者完整指南:如何编写自定义转换器,让 Registry 自动发现你的新格式
Transmute 开发者完整指南:如何编写自定义转换器,让 Registry 自动发现你的新格式
Transmute 是一款自托管(self hosted)的文件转换与压缩工具,支持图片、视频、音频、JSON、Excel 等 3,000 多种格式转换。本指南面向开发者,手把手教你在 Transmute 中编写自定义转换器:只需继承 ConverterInterface、声明支持的格式、在包中导出,Registry 就会在启动时自动发现并注册你的新格式——无需任何额外配置。
一、Registry 自动发现:Transmute 转换器扩展的核心机制
在动手写代码前,先理解 Transmute 的架构分层,这决定了"为什么新转换器不需要手动注册":
| 层次 | 文件 | 职责 |
|---|---|---|
| 转换器接口 | backend/converters/converter_interface.py | 定义所有转换器必须遵守的契约 |
| 具体转换器 | backend/converters/*_convert.py |
每个文件封装一个工具链(FFmpeg、Pillow、pandas 等) |
| 包导出 | backend/converters/init.py | 把转换器类 re-export,供 Registry 扫描 |
| 注册中心 | backend/registry/registry.py | 自动发现类、维护"格式 → 转换器"映射表 |
| 调度执行 | backend/services/conversion_service.py | 拿到匹配的转换器后执行转换并落库 |
发现流程分四步,全部在启动时自动完成:
- 应用启动时创建全局单例
registry = ConverterRegistry()(见 registry.py#L303-L304)。 _auto_register()用inspect.getmembers()扫描converters包中所有导出的类(见 registry.py#L57-L69)。- 对每个
ConverterInterface子类调用类方法can_register()——若返回False(如缺少 FFmpeg 二进制文件),则静默跳过,不会报错。 - 通过检查的类被登记进
converters字典,并按类属性supported_input_formats/supported_output_formats构建输入/输出格式两张映射表。
之后前端界面展示"某文件能转成哪些格式"时,API 层直接查询 Registry(见 backend/api/routes/files.py#L96 的 get_compatible_formats_and_qualities);用户提交转换任务时,registry.get_converter_for_conversion() 从映射表中选出合适的转换器类执行转换(见 backend/api/routes/conversions.py#L117)。
💡 关键结论:"导出即注册"。你的工作只是写好类并放入导出列表,映射表、路由、界面下拉框全部由 Registry 自动生成。
二、5 分钟上手:编写一个最简自定义转换器
下面以"把自定义的 foo 格式转成 txt"为例,走一遍完整流程。代码刻意保持最小化,方便你对照官方 README 中的 Typical Workflow 逐步实现。
第 1 步:新建模块文件。 在 backend/converters/ 下创建 foo_convert.py,遵循项目"*_convert.py"命名约定:
from pathlib import Path
from typing import Optional
from .converter_interface import ConverterInterface
class FooConverter(ConverterInterface):
"""把 foo 文件转成 txt 的示例转换器。"""
supported_input_formats = {'foo'}
supported_output_formats = {'txt'}
def can_convert(self) -> bool:
# 只有 foo -> txt 这一条路径有效
return (
self.input_type in self.supported_input_formats
and self.output_type in self.supported_output_formats
)
def convert(self, overwrite: bool = True, quality: Optional[str] = None) -> list[str]:
input_path = Path(self.input_file)
output_path = Path(self.output_dir) / f"{input_path.stem}.txt"
if not overwrite and output_path.exists():
return [str(output_path)]
text = input_path.read_text().upper()
output_path.write_text(text)
return [str(output_path)]
第 2 步:在包中导出。 编辑 backend/converters/init.py,仿照现有条目追加两行:
from .foo_convert import FooConverter
# 并把 "FooConverter" 加入 __all__ 列表
这一步就是触发自动发现的开关——inspect.getmembers(converters, ...) 只能看到 __init__.py 中导入的类。
第 3 步:重启后端。 运行 make dev(定义于 Makefile#L47)重新启动服务。此时 _auto_register 已完成扫描,Registry 的映射表里已经存在 foo → FooConverter 和 txt 的入口。
第 4 步:验证发现成功。 两个快速验证手段:
# 交互式确认:新格式应出现在全部格式集合中
from registry import registry
assert 'foo' in registry.get_formats()
# 命令行确认:支持的转换对总数增加了
make conv-count
转换总数由 backend/export_supported_conversions.py 统计——它遍历 Registry 中每个转换器的输入/输出格式组合,并调用 can_convert() 逐对验证,所以你声明的格式对必须与 can_convert() 的判断一致,才会计入总数。
三、类属性速查表:Registry 靠什么"认识"你的转换器
Registry 只读取类级别的属性(不实例化),因此格式声明必须写在类体上。对照 converter_interface.py#L15-L25 的基类定义:
| 属性 / 方法 | 类型 | 是否必需 | Registry 如何使用 |
|---|---|---|---|
supported_input_formats |
set |
✅ 必需 | 构建输入格式映射,get_formats() 的并集来源 |
supported_output_formats |
set |
✅ 必需 | 构建输出格式映射 |
qualities |
set |
可选 | 提供 low / medium / high 质量选项 |
formats_with_qualities |
set |
可选 | 声明哪些输出格式支持质量参数 |
can_register() |
类方法 | 有外部依赖时必需 | 注册前检查运行环境,失败则跳过 |
can_convert() |
实例方法 | ✅ 必须实现 | 任务提交时逐对校验方向有效性 |
get_formats_compatible_with() |
类方法 | 可选 | 控制前端格式下拉框展示;默认返回"输出格式 − 当前格式" |
convert() |
实例方法 | ✅ 必须实现 | 实际执行转换,必须返回输出文件路径列表 |
三个容易踩坑的细节:
- 格式名要走别名表。用户在界面可能选
jpg,而你的类里写的是jpeg。接口构造时会自动用 core/media_types.py 中的media_type_aliases归一化(jpg → jpeg、yml → yaml),Registry 查询侧同样归一化,所以你只需声明规范格式名,别名由框架兜底。 convert()返回的是列表。即使通常只产出一个文件,也返回<a href="https://link.gitcode.com/i/c6719e81169de62363d13734b13021e5" target="_blank">path]——这是官方 [Converters README 明确要求的约定,多文件产物(如拆分转换)也能自然支持。- 不要在转换器模块中 import registry。
registry.py反过来要扫描converters包,循环导入会导致启动失败;需要格式别名时直接从core导入即可。
四、依赖外部二进制时:用 can_register() 优雅降级
如果你的自定义转换器依赖 Python 之外的工具(例如需要系统安装 FFmpeg、LibreOffice),一定要覆写 can_register()。参考最典型的 FFmpegConverter:
@classmethod
def can_register(cls) -> bool:
try:
subprocess.run([cls.ffmpeg_path, '-version'], check=True,
stdout=subprocess.PIPE, stderr=subprocess.PIPE)
return True
except (subprocess.CalledProcessError, FileNotFoundError):
return False
效果是"环境不具备时安静缺席":_auto_register 发现 can_register() 返回 False 就跳过注册(registry.py#L67-L68),对应格式在界面上自动消失,而不会因为缺失依赖让整个服务启动失败。纯 Python 实现的转换器(如基于 pysubs2 的字幕转换,见 backend/converters/pysubs2_convert.py)无需覆写,基类默认返回 True。
五、上线前检查清单
对照这份清单自检,确保你的自定义转换器与 Transmute 的既有规范一致:
- ☑️ 类继承
ConverterInterface,格式声明为类属性,写在类体顶层 - ☑️
backend/converters/__init__.py中已导入并加入__all__ - ☑️
can_convert()与convert()均已实现;convert()返回输出路径列表 - ☑️ 有外部依赖时实现了
can_register()环境探测 - ☑️ 有格式限制时覆写了
get_formats_compatible_with(),避免界面出现"转了却失败"的选项 - ☑️ 未从转换器模块反向 import registry(防循环依赖)
- ☑️ 通过
make conv-count确认转换对数量按预期增加 - ☑️ 参照 backend/tests/converters/test_pysubs2_convert.py 为新格式补一条测试用例
任务提交后,后台队列会再次通过 Registry 解析转换器并交给 ConversionService 执行,转换结果最终出现在用户的任务列表中:
总结:扩展 Transmute 支持新格式只需 3 个文件
回顾整个流程,让 Registry 自动发现你的自定义转换器,实际只需要改动 3 处:
- 新建
backend/converters/xxx_convert.py——继承接口、声明格式、实现转换逻辑 - 修改
backend/converters/__init__.py——一行导入 + 一行__all__ - (可选)新增测试文件
backend/tests/converters/test_xxx_convert.py
格式映射表、API 查询、界面下拉框、后台任务调度全部由 backend/registry/registry.py 自动推导完成。这正是 Transmute 的设计哲学:让转换器"自我描述",让 Registry 负责发现——这也是它能在 20 多个转换器上支撑 3,000 多种转换路径、并轻松持续扩展的关键。


