wholetrans/sub-cli
1
0
Fork 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions
sub-cli/docs/zh-Hans/commands.md
CDN 6d730fa69b
docs: add ass docs
2025-04-23 19:33:02 +08:00

10 KiB
Raw Permalink Blame History

title description
命令参考 所有Sub-CLI命令的详细文档

命令参考

本页面提供了所有可用Sub-CLI命令的详细文档、选项和用法。

全局选项

这些选项在所有Sub-CLI命令中都可用：

help      显示命令的帮助信息

convert

convert 命令将字幕文件在不同格式之间转换，尽可能保留信息，同时适应目标格式的功能。

用法

sub-cli convert <源文件> <目标文件>

参数

参数 描述
<源文件> 源字幕文件的路径
<目标文件> 要创建的目标字幕文件的路径

支持的格式转换

源格式 目标格式 注意
SRT (.srt) SRT, VTT, LRC, TXT, ASS -
VTT (.vtt) SRT, VTT, LRC, TXT, ASS -
LRC (.lrc) SRT, VTT, LRC, TXT, ASS -
ASS (.ass) SRT, VTT, LRC, TXT, ASS -
TXT (.txt) — TXT只能作为目标格式，不能作为源格式

功能保留

转换过程旨在尽可能保留更多功能，但某些特定于格式的功能可能会丢失或适应：

SRT功能

  • 保留: 文本内容、时间线（开始和结束时间）、基本样式（粗体、斜体、下划线）
  • 在某些格式中丢失: 转换为LRC或TXT等格式时的HTML样式标签

VTT功能

  • 保留: 文本内容、时间线、标题、CSS样式（当目标格式支持时）
  • 在某些格式中丢失: 转换为SRT或LRC时的定位、对齐和高级样式

LRC功能

  • 保留: 文本内容、时间线、元数据（标题、艺术家、专辑）
  • 结构限制: LRC只支持开始时间戳（没有结束时间戳），不像SRT和VTT
  • 从LRC转换时的适应: 当转换为SRT/VTT时，LRC中每行的单一时间戳会转换为开始+结束时间对。结束时间的计算方式为:
    • 使用下一个条目的开始时间作为当前条目的结束时间
    • 对于最后一个条目，添加默认时长（通常3-5秒）来创建结束时间
  • 转换为LRC时丢失: 当其他格式转换为LRC时，任何结束时间戳信息都会被丢弃

ASS功能

  • 保留: 文本内容、时间线（开始和结束时间）、基本样式信息
  • 仅有基本支持: 转换创建一个具有基本结构的"最小"ASS文件
  • 转换为ASS时:
    • 基本样式（粗体、斜体、下划线）会转换为具有默认设置的ASS样式
    • 默认字体为Arial，大小20pt，具有标准颜色和边距
    • 只创建"Dialogue"（对话）类型的事件（不创建"Comment"或其他事件类型）
  • 从ASS转换时:
    • 只转换类型为"Dialogue"的事件，忽略"Comment"事件
    • 在目标格式支持的情况下保留样式信息
    • ASS特有的属性（如Layer、MarginL/R/V等）在可能的情况下存储为元数据

TXT功能

  • 仅输出: 纯文本格式只包含没有任何时间或样式的文本内容

技术细节

转换器使用中间表示法，尽可能保留特定格式的数据。转换分两步进行：

  1. 将源格式转换为中间表示
  2. 将中间表示转换为目标格式

这种方法最大限度地减少信息丢失，确保尽可能准确的转换。

示例

# 从SRT转换为WebVTT
sub-cli convert subtitles.srt subtitles.vtt

# 从LRC转换为纯文本（去除时间信息）
sub-cli convert lyrics.lrc transcript.txt

# 从WebVTT转换为SRT
sub-cli convert subtitles.vtt subtitles.srt

# 从SRT转换为ASS
sub-cli convert subtitles.srt subtitles.ass

# 从ASS转换为SRT
sub-cli convert subtitles.ass subtitles.srt

sync

sync 命令将源字幕文件的时间/时间戳应用到目标字幕文件，同时保留目标文件的内容。

用法

sub-cli sync <源文件> <目标文件>

参数

参数 描述
<源文件> 带有参考时间线的源字幕文件的路径
<目标文件> 要同步的目标字幕文件的路径

支持的格式

目前，同步仅适用于相同格式的文件之间：

  • SRT到SRT
  • LRC到LRC
  • VTT到VTT
  • ASS到ASS

行为详情

对于LRC文件：

  • 当条目数匹配时: 源时间线直接应用于目标内容。
  • 当条目数不同时: 源时间线使用线性插值进行缩放以匹配目标内容：
    • 对于每个目标条目位置，计算源时间线中的对应位置
    • 在最近的源条目之间进行线性插值计算时间
    • 这确保了在不同数量的条目间实现平滑和比例化的时间分布
  • 从目标保留: 所有内容文本和元数据（艺术家、标题等）。
  • 在目标中修改: 只更新时间戳。

对于SRT文件：

  • 当条目数匹配时: 源的开始和结束时间直接应用于目标条目。
  • 当条目数不同时: 使用基于线性插值的缩放方法：
    • 开始时间使用源条目之间的线性插值计算
    • 结束时间根据源条目时长计算
    • 保持条目之间的时间关系
  • 从目标保留: 所有内容文本。
  • 在目标中修改: 更新时间戳并标准化条目编号（从1开始顺序编号）。

对于VTT文件：

  • 当条目数匹配时: 源的开始和结束时间直接应用于目标条目。
  • 当条目数不同时: 使用基于线性插值的缩放方法：
    • 开始时间使用源条目之间的线性插值计算
    • 结束时间根据源条目时长计算
    • 保持条目之间的时间关系
  • 从目标保留: 所有字幕文本内容和样式信息。
  • 在目标中修改: 更新时间戳并标准化提示标识符。

对于ASS文件：

  • 当条目数匹配时: 源时间线（开始和结束时间）直接应用于目标事件。
  • 当条目数不同时: 使用基于线性插值的缩放方法：
    • 开始时间使用源事件之间的线性插值计算
    • 结束时间根据源事件时长计算
    • 保持事件之间的时间关系
  • 从目标保留: 所有事件文本内容、样式引用和其他属性（如Layer、MarginL/R/V）。
  • 在目标中修改: 只更新时间戳（Start和End）。

时间线插值详情

同步命令使用线性插值来处理源文件和目标文件之间不同的条目数量：

  • 什么是线性插值？ 这是一种估计两个已知点之间值的数学技术。对于时间线同步，它在应用于不同数量的目标条目时，可以在源时间戳之间创建平滑过渡。

  • 工作原理：

    1. 算法将每个目标条目位置映射到源时间线中的对应位置
    2. 对于每个目标位置，通过插值计算最近的源时间戳之间的时间戳
    3. 计算确保按比例分布的时间戳，保持原始节奏

  • 示例： 如果源文件在1秒、5秒和9秒有条目（共3个条目），而目标有5个条目，插值后的时间戳将大约为1秒、3秒、5秒、7秒和9秒，保持均匀间隔。

  • 线性插值的好处：

    • 当条目数相差很大时，提供更准确的时间
    • 保持源时间线的节奏和韵律
    • 既能处理扩展（目标条目更多）也能处理收缩（目标条目更少）的情况

边缘情况

  • 如果源文件没有时间信息，目标保持不变。
  • 如果源时长计算导致负值，会应用默认的零秒时长（改进自之前的3秒默认值）。
  • 当条目数不同时，命令会显示警告但会继续进行缩放同步。
  • 目标文件中的特定格式功能（如样式、对齐方式、元数据）会被保留。同步操作只替换时间戳，不会更改任何其他格式或内容功能。

示例

# 使用另一个SRT文件作为参考来同步SRT文件
sub-cli sync reference.srt target.srt

# 使用另一个LRC文件作为参考来同步LRC文件
sub-cli sync reference.lrc target.lrc

# 使用另一个VTT文件作为参考来同步VTT文件
sub-cli sync reference.vtt target.vtt

# 使用另一个ASS文件作为参考来同步ASS文件
sub-cli sync reference.ass target.ass

fmt

fmt 命令根据其特定格式的约定标准化和格式化字幕文件。

用法

sub-cli fmt <文件>

参数

参数 描述
<文件> 要格式化的字幕文件的路径

支持的格式

格式 扩展名 格式化操作
SRT .srt 标准化条目编号（从1开始顺序）
格式化时间戳为00:00:00,000格式
确保条目之间适当的间距
LRC .lrc 组织元数据标签
标准化时间戳格式[mm:ss.xx]
确保正确的内容对齐
VTT .vtt 验证WEBVTT头
标准化提示标识符
格式化时间戳为00:00:00.000格式
组织样式信息
ASS .ass 标准化部分顺序（[Script Info], [V4+ Styles], [Events]）
格式化时间戳为h:mm:ss.cc格式
保留所有脚本信息、样式和事件数据

格式特定详情

SRT格式化

格式化器解析SRT文件，提取所有条目，确保从1开始的顺序编号，并以一致的格式将文件写回。这保留了所有内容和时间信息，同时标准化结构。

LRC格式化

对于LRC文件，格式化器保留所有元数据和内容，但标准化时间戳的格式并确保正确对齐。这使文件更易于阅读，并与不同的LRC解析器更兼容。

VTT格式化

格式化WebVTT文件时，命令确保适当的头格式、顺序提示标识符和标准时间戳格式。所有VTT特定功能（如样式、定位和注释）都被保留。

ASS格式化

格式化器读取并解析ASS文件，然后以标准化结构重新生成它。它保持所有原始内容，包括脚本信息、样式和事件。强制执行标准部分顺序（[Script Info], [V4+ Styles], [Events]），并以标准的h:mm:ss.cc格式格式化时间戳。

示例

# 格式化SRT文件
sub-cli fmt subtitles.srt

# 格式化LRC文件
sub-cli fmt lyrics.lrc

# 格式化VTT文件
sub-cli fmt subtitles.vtt

# 格式化ASS文件
sub-cli fmt subtitles.ass

version

显示Sub-CLI的当前版本。

用法

sub-cli version

help

显示一般帮助信息或特定命令的帮助。

用法

sub-cli help [命令]

参数

参数 描述
[命令] （可选）要获取帮助的特定命令

示例

# 显示一般帮助
sub-cli help

# 显示convert命令的帮助
sub-cli help convert