Griller | 烤肉架

Griller 是一个用于辅助视频搬运的命令行工具。 给定视频的源 URL，它能自动完成视频/封面下载、生成元信息、听译字幕+打轴等流水线化工序。

安装

Griller 实现于 Python3 上，需要本地安装了 ffmpeg 以运行。

在 bash 中执行下面的命令以安装 Griller：

pip install git+https://github.com/WangNianyi2001/Griller.git

使用

通用

python -m griller [程序] [{-h,--help}]
	[-s 输入源]...
	[-o 输出路径]
	[-l 语言]
	[-m 模型路径]
	[-f | --force]

输入与输出采用“按资源类型判别”的语义：

• 输入资源可为 URL、TOML 文件、工作区目录、媒体文件、字幕文件。

  • 凡是原本接受 URL 的位置，也接受本地媒体文件路径。

• 对于支持工作区输入的命令，若省略 -s，默认输入为当前目录 .。

• 输出路径会自动判别为“文件”或“目录”：

  • 以文件后缀结尾（如 .toml、.mp4）时按文件处理。
  • 其余情况按目录处理。

程序

• sniff：从 URL 嗅探媒体元信息。

  参数：

  • 输入源：媒体 URL 或本地媒体文件路径。
  • 输出：
    • 缺省：创建工作区并写入 media.toml。
    • 以 .toml 结尾：直接写单 TOML 文件。
    • 否则：视为工作区根目录，在其中创建工作区并写 media.toml。

  说明：

  • 若输入是本地媒体文件，sniff 只记录引用路径，不复制文件。
  • 若输入是本地媒体文件且输出是目录，则该目录本身就是工作区（默认 .），不会再自动创建一层同名子目录。

• fetch：下载媒体源文件。

  参数：

  • 输入源：URL、本地媒体文件、TOML 文件、工作区目录（缺省为 .）。
  • 输出：文件或目录。

  行为：

  • 输入 URL 时会隐式 sniff，但不会额外落盘 TOML。
  • 输入本地媒体文件时，fetch 行为为复制。
  • 输入 TOML 时直接读取元信息。
  • 输入工作区时读取 media.toml。
  • 输出为文件时直接写到该文件路径。
  • 输出为目录时写到该目录（工作区输入下默认文件名为 <stem>.<ext>，并更新 media.toml）。
  • 默认文件名中的 stem 使用“转义媒体名”（通常来源于 [origin].title 或媒体文件名），media.toml 文件名本身保持不变。
  • 远程下载会尝试同时下载封面图；若成功且在工作区模式下，会写入 [cover].path / [cover].filename。
  • 若封面下载失败，不会中断 fetch，会留给后续 extract 再尝试从媒体容器中提取封面轨。

• extract：抽取音轨与封面。

  参数：

  • 输入源：媒体文件或工作区目录（缺省为 .）。
  • 输出：仅目录（缺省为输入工作区或 .）。

  说明：

  • 不会自动执行 sniff/fetch；若源媒体不存在会直接报错。
  • 工作区中的媒体、音频、字幕等路径由 media.toml 指针字段决定；固定文件名仅作兼容兜底。
  • 默认音频文件名为 <stem>.wav。
  • 若工作区里已存在可用封面（[cover] 指向本地文件），extract 不会重复提取封面。
  • 若封面缺失，extract 只尝试从 attached_pic 视频流提取封面，默认封面文件名为 <stem>.<ext>。
  • 若既无已下载封面、又无 attached_pic，会在命令行打印提示，不会 fallback 到抽取首帧。

• convert：转码媒体。

  参数：

  • 输入源：媒体文件或工作区目录（缺省为 .）。
  • -c / --codec：目标编码。若输入含视频，则作用于视频编码；若输入为纯音频，则作用于音频编码。
  • 输出：
    • 单文件模式下只能是目录；输出文件名默认为 <源文件名>-converted.<ext>。
    • 工作区模式下默认写到工作区，并记录转码元信息到 media.toml。
  • --replace：原地覆写源媒体；不能与 -o 同时使用。

  说明：

  • 若工作区中存在转码版本，则依赖源媒体的命令会优先使用转码版本。
  • 默认编码配置项为 convert.codec.video = libx264、convert.codec.audio = aac。

• transcribe：将音轨转写为 SRT。

  参数：

  • 输入源：媒体文件、TOML 文件、工作区目录（不支持 URL；缺省为 .）。
  • 输出：文件或目录。
  • 输出为目录时默认文件名为 <stem>.transcribed.srt。
  • 模型：-m 指定模型名或路径；若省略则优先读取工作区 media.toml 中 [transcribe].model。
  • 全局配置：若工作区里没有模型覆盖，则回退到全局 config.toml。

• prepare：一条龙执行 sniff metadata -> fetch -> optional convert -> extract -> transcribe。

  参数：

  • 输入源：URL、本地媒体文件、TOML 文件、工作区目录（缺省为 .）。
  • 输出：工作区目录。
  • --convert：在本次 prepare 中强制启用 convert（不改写配置）。

  说明：

  • 当输入是本地媒体引用时，prepare 采用“引用优先”语义，不强制复制；仅在需要远程抓取时才执行 fetch 下载。
  • 若 convert.enabled = true，或传入 --convert，或传入 -c/--codec，prepare 会在 fetch 后、extract 前执行 convert。
  • prepare 在本次命令执行期间会在目标工作区语境下运行后续步骤（fetch/extract/transcribe），命令结束后恢复原目录语境。

• 工作区创建日志：

  说明：

  • 命令在创建工作区目录时会打印创建提示；不同命令可能使用不同文案（如 Workspace created: <path> 或 created workspace folder at <path>）。

• burn：烧录字幕。

  参数：

  • 输入源：
    • 必须提供一个 ASS 字幕文件。
    • 另可提供一个媒体文件或工作区目录。
    • 输入顺序无关，由类型匹配。
    • 若仅提供 ASS，且当前目录是工作区，则自动使用当前工作区媒体。
  • 输出：文件或目录（目录下默认输出 <视频名>.burnt.mp4）。

• download：fetch 的兼容别名（建议迁移到 fetch）。

• 冲突处理：

  说明：

  • 当默认输出路径已存在且未传 -f/--force 时，命令会警告并中止，不再静默跳过。

• config：设置或读取工作区/全局配置。

  参数：

  • 输入源：工作区目录（缺省为 .，非工作区会报错）。
  • -g：操作全局配置，使用 config.toml。
  • --get：读取当前生效的模型配置。
  • --delete：移除当前作用域下的模型覆盖。
  • 配置项路径：transcribe.model，对应 TOML 中的键路径。
  • 设置示例：griller config transcribe.model /path/to/model
  • 读取示例：griller config --get transcribe.model
  • 删除示例：griller config --delete transcribe.model
  • convert 示例：
    • griller config convert.codec.video libx265
    • griller config convert.codec.audio libopus
    • griller config convert.enabled true

  全局配置文件位置：

  • Windows：%APPDATA%\griller\config.toml
  • macOS：~/Library/Application Support/griller/config.toml
  • Linux：$XDG_CONFIG_HOME/griller/config.toml，否则 ~/.config/griller/config.toml

  配置优先级：

  • 命令行 -m 仅用于 transcribe，优先于一切。
  • 工作区 media.toml 中的 [transcribe].model 优先于全局配置。
  • 全局配置优先于内置默认值。
  • convert.codec.video 默认值为 libx264，convert.codec.audio 默认值为 aac，convert.enabled 默认值为 false。

  模型缓存位置：

  • Windows：%LOCALAPPDATA%\griller\whisper 与 %LOCALAPPDATA%\griller\huggingface\hub
  • macOS：~/Library/Caches/griller/whisper 与 ~/Library/Caches/griller/huggingface/hub
  • Linux：$XDG_CACHE_HOME/griller/whisper 与 $XDG_CACHE_HOME/griller/huggingface/hub，否则 ~/.cache/griller/...

致谢

• 字幕烧录部分逻辑借鉴自 july-lyan/subtitle-burner。