Transmute 开发者完整指南:如何编写自定义转换器,让 Registry 自动发现你的新格式

原创2026-10-11 15:29:061,915 阅读

Transmute 开发者完整指南:如何编写自定义转换器,让 Registry 自动发现你的新格式

Transmute 是一款自托管(self hosted)的文件转换与压缩工具,支持图片、视频、音频、JSON、Excel 等 3,000 多种格式转换。本指南面向开发者,手把手教你在 Transmute 中编写自定义转换器:只需继承 ConverterInterface、声明支持的格式、在包中导出,Registry 就会在启动时自动发现并注册你的新格式——无需任何额外配置。

Transmute 转换工作台,上传文件后可选择目标格式,扩展自定义转换器后新格式会出现在这里

一、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 拿到匹配的转换器后执行转换并落库

发现流程分四步,全部在启动时自动完成:

  1. 应用启动时创建全局单例 registry = ConverterRegistry()(见 registry.py#L303-L304)。
  2. _auto_register() 用 inspect.getmembers() 扫描 converters 包中所有导出的类(见 registry.py#L57-L69)。
  3. 对每个 ConverterInterface 子类调用类方法 can_register()——若返回 False(如缺少 FFmpeg 二进制文件),则静默跳过,不会报错。
  4. 通过检查的类被登记进 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() 的判断一致,才会计入总数。

Transmute 转换完成后的结果列表,自定义转换器的产物会以新的 FORMAT 标签展示

三、类属性速查表: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 Jobs 任务列表页,自定义转换任务完成后显示格式、质量、大小与状态

总结:扩展 Transmute 支持新格式只需 3 个文件

回顾整个流程,让 Registry 自动发现你的自定义转换器,实际只需要改动 3 处:

  1. 新建 backend/converters/xxx_convert.py——继承接口、声明格式、实现转换逻辑
  2. 修改 backend/converters/__init__.py——一行导入 + 一行 __all__
  3. (可选)新增测试文件 backend/tests/converters/test_xxx_convert.py

格式映射表、API 查询、界面下拉框、后台任务调度全部由 backend/registry/registry.py 自动推导完成。这正是 Transmute 的设计哲学:让转换器"自我描述",让 Registry 负责发现——这也是它能在 20 多个转换器上支撑 3,000 多种转换路径、并轻松持续扩展的关键。

登录后查看全文
transmute