音视频音频处理视频处理CLI【免费下载链接】ffsubsyncAutomagically synchronize subtitles with video.项目地址https://gitcode.com/gh_mirrors/ff/ffsubsync点击查看免费下载FFsubsync 是一款语言无关language-agnostic的字幕自动同步工具它不需要理解字幕或语音的内容只需把视频中的语音与字幕的时间轴抽象成两串二进制信号用卷积与 FFT 找到最佳对齐偏移即可自动把字幕校正到视频的正确起始位置。本文以项目根目录 README.md 为主线结合 ffsubsync/ffsubsync.py 等源码与测试系统讲解安装、命令行用法、远程参考、Docker 部署、库式调用、编码处理、疑难排查、算法原理与边界限制读完你将能够独立完成一键同步、批量同步、远程流同步与分段同步并理解其底层为何能在几十秒内完成全片对齐。项目概述要解决的问题与典型场景字幕与视频不同步是常见的观影痛点视频文件从不同渠道下载、片头片尾被裁剪、帧率不一致如 24.000 与 23.976 fps 混用都会导致字幕整体偏移甚至逐渐漂移。FFsubsync 的核心能力是自动把字幕对齐到视频中的正确起始点其独特之处在于全程不依赖任何语言模型对视频它用**语音活动检测VAD**找出什么时候有人在说话对字幕它直接从字幕时间戳推导出什么时候字幕在屏幕上两者被抽象为二进制序列后用FFT 卷积在 O(n log n) 时间内找出最佳偏移。由于不涉及语音识别与文本匹配它对任何语言的字幕都有效——这正是 README 开篇强调的 Language-agnostic automatic synchronization 的含义。项目同时提供三种等价命令行入口ffs、subsync、ffsubsync参数解析器由 make_parser() 统一构建完整参数清单见 docs/cli.rst。浏览器版无需安装即可试用README 特别介绍了一个浏览器版本完全在浏览器内完成同步不需要 Python、不需要ffmpeg、无需安装任何东西文件也不会被上传始终留在本机。它既可以针对一个已正确同步的参考字幕同步也可以针对视频 / 音频文件同步——音频在浏览器内通过 ffmpeg.wasm 解码大文件按需惰性读取。浏览器端实现位于仓库的 web/ 目录含 web/src/ffsubsync_engine.mjs、web/src/ffmpeg_decode.mjs 等模块适合一次性应急批量或脚本化使用仍推荐下面的命令行工具。安装ffmpeg 依赖与 pip 安装FFsubsync 依赖ffmpeg完成音频提取与转码因此安装分两步第一步确保 ffmpeg 已安装。macOS 上brew install ffmpegWindows 用户需要确保ffmpeg在 PATH 中、可从命令行直接引用即能执行ffmpeg命令。ffmpeg 的可执行路径也可在运行时用--ffmpeg-path显式指定。第二步安装 Python 包README 声明兼容 Python 3.6最新发布版本号以 PyPI 为准pip install ffsubsync如果想使用开发分支的最新代码live dangerously 模式pip install githttps://github.com/smacke/ffsubsynclatest需要说明的是ffmpeg二进制本体不会随 pip 包一起安装pip 包只含 Python 代码请务必先完成第一步。仓库根目录的 requirements.txt 列出了运行时依赖其中音频提取经由 ffmpeg-python 包装层完成。快速上手三种核心用法以视频为参考最常见把视频当作时间基准让 FFsubsync 提取其音频、运行 VAD 找出语音区间再求解与字幕的最佳对齐ffs video.mp4 -i unsynchronized.srt -o synchronized.srt以已正确同步的字幕为参考极快有时你手上有一个已经正确同步但语种看不懂的字幕文件同时还有一份未同步的母语字幕。此时无需视频直接以正确字幕为参考ffsubsync reference.srt -i unsynchronized.srt -o synchronized.srtFFsubsync 通过参考文件的扩展名决定走哪条处理路径见 make_reference_pipe()扩展名属于字幕类型.srt、.ass、.ssa、.sub常量定义在 constants.py 的SUBTITLE_EXTENSIONS时完全跳过音频提取直接由参考字幕的开关时间戳构造语音信号。因为无需解码音频整个同步通常不到 1 秒。参考类型全集见 docs/reference_types.rst。省略 -i兄弟字幕自动检测若省略-iFFsubsync 会在参考文件所在目录中自动查找与参考文件同名的字幕并逐一同步ffs video.mp4对名为video.mp4的参考它会捡起同目录下的video.srt、video.en.srt等文件为每个生成name.synced.srt如video.synced.srt原文件保持不动。该逻辑由 _detect_srtin_from_reference() 实现它按参考文件的所在目录而非当前工作目录扫描匹配参考主名.srt与参考主名.后缀.srt两种形态且跳过已生成的*.synced.srt——因此重复运行是安全的幂等。需要原地覆盖时加--overwrite-input。自动检测在字幕通过 stdin 管道输入时会被跳过且仅对本地参考生效远程参考无法枚举远端目录。标准输入输出与管道-i默认为 stdin、-o默认为 stdout因此 FFsubsync 可以干净地嵌入 Unix 管道cat unsynchronized.srt | ffs video.mp4 synchronized.srt进度与日志信息全部写到stderr不会污染管道中的字幕数据。注意当 stdin 正在接收字幕时兄弟字幕自动检测会被禁用见 validate_args() 对sys.stdin.isatty()的判断避免劫持管道输入。远程参考直接用 URL 同步参考可以是远程 URL 而非本地文件。凡是 ffmpeg 能直接读取的地址都能作为视频 / 音频参考远程字幕文件同样可以作为参考ffs https://example.com/video.mp4 -i unsynchronized.srt -o synchronized.srt ffs https://example.com/reference.srt -i unsynchronized.srt -o synchronized.srt支持的协议为http(s)://、rtmp://、rtsp://、ftp://与 constants.py 中的REMOTE_URL_PROTOCOLS常量一一对应is_remote_url()也据此跳过本地文件的读权限检查见 validate_file_permissions()。处理时 FFsubsync 会流式读取参考因此可靠性依赖网络连接的稳定性对大文件或不稳定源先下载到本地再同步通常更可靠。另外兄弟字幕自动检测无-i形式是本地专属能力对远程参考会被跳过。长参考与不稳定连接的三板斧针对参考很长与网络不稳两类痛点README 给出了三个专门选项参数定义见 add_cli_only_args()--max-duration-seconds N只处理前 N 秒ffs https://example.com/video.mp4 -i unsynchronized.srt -o synchronized.srt --max-duration-seconds 600只处理从--start-seconds默认 0见 constants.py起的前 N 秒。对远程参考尤其有用——ffmpeg 一旦读到该时长就会停止下载从而大幅减少网络流量。--extract-audio-first先落地音频再检测网络不稳时可以先把远程音频轨道拷贝到本地临时文件不重新编码再在本地做语音检测而不是在整个检测期间一直挂着网络流ffs https://example.com/video.mp4 -i unsynchronized.srt -o synchronized.srt --extract-audio-first该选项对本地参考会被忽略且可与--max-duration-seconds组合使用先按最大时长截取音频再本地检测。--multi-segment-sync跨全片采样多段同步如果失步只出现在影片后半段--max-duration-seconds会漏掉它。此时改用--multi-segment-sync在参考全片范围内采样若干个短片段只对这些片段做语音检测ffs https://example.com/video.mp4 -i unsynchronized.srt -o synchronized.srt --multi-segment-sync由于每个采样段都保留其在时间轴上的真实位置常规的帧率比与偏移搜索完全不受影响——帧率不匹配依然能被检测并修正实现于 MultiSegmentVideoSpeechTransformer 对应的 speech_transformers 模块。只提取对远程参考也只下载采样音频速度提升显著。配套调优参数参数默认值作用--segment-count N8采样的片段数量--skip-intro-outro关跳过开头 30 秒与结尾 60 秒片头片尾常无对白再布点--parallel-workers N4并行提取片段数可重叠下载远程片段该模式仅适用于视频 / 音频参考字幕参考本身无需提取音频。用 Docker 运行仓库提供了多阶段 Dockerfile并发布预构建镜像到 GitHub Container Registrydocker pull ghcr.io/smacke/ffsubsync:latest运行方式是把视频与字幕所在目录挂载到容器的/videodocker run --rm -v $PWD:/video ghcr.io/smacke/ffsubsync:latest \ video.mp4 -i unsynchronized.srt -o synchronized.srt也可以自行构建。默认从当前工作树安装docker build -t ffsubsync .若要改为从 PyPI 安装指定版本传入构建参数FFSUBSYNC_VERSIONdocker build -t ffsubsync --build-arg FFSUBSYNC_VERSION0.4.31 .作为 Python 库使用ffsubsync.run 与进度回调命令行所做的一切都可以通过ffsubsync.run以编程方式驱动。它接受一个argparse.Namespace——最省事的方式是用 CLI 同一个make_parser()解析参数列表import ffsubsync from ffsubsync.ffsubsync import make_parser def on_progress(info: ffsubsync.ProgressInfo) - None: # info.processed_seconds / info.total_secondstotal 可能为 None # info.fraction 是 0.0-1.0 的比例总时长未知时为 None。 if info.fraction is not None: print(f{info.fraction:.0%}) args make_parser().parse_args([ref.mkv, -i, in.srt, -o, out.srt]) result ffsubsync.run(args, progress_handleron_progress)run()返回一个描述结果的字典见 run() 的实现retval进程式退出码0 成功1 失败sync_was_successful同步是否成功offset_seconds计算出的偏移秒数framerate_scale_factor若做了帧率校正给出缩放系数。进度回调progress_handler只在视频 / 音频参考路径上被调用——这正是同步的主要耗时环节音频解码字幕参考路径近乎瞬时。回调抛出的异常会被记录日志并吞掉任何有 bug 的回调都不会中断同步。更完整的库式用法示例见 docs/library.rst。字符编码legacy 编码的自动识别现实中的字幕文件携带五花八门的遗留编码西里尔文常用 Windows-1251、中文常遇 GBK / Big5、还有 Latin-1、Shift-JIS、带 BOM 的 UTF-16……README 明确表示健壮处理这些编码是 FFsubsync 优于同类工具的地方且全程自动--encoding默认infer把输入按原始字节读取并自动检测编码底层按顺序尝试最多三个检测器取第一个能作答的结果cchardet→charset_normalizer→chardet解码时使用errorsreplace即使检测稍有偏差也能优雅降级而不是崩溃BOM 天然被处理检测器看到的就是原始字节。若自动检测猜错了可强制指定例如--encoding windows-1251。输出默认写为 UTF-8传--output-encoding same则保留输入编码也可以显式命名任意 codec见 --output-encoding 参数定义。当参考本身是字幕文件时用--reference-encoding控制默认同样是infer。一个跨版本注意事项最快 / 常常最准确的cchardet由持续维护的faust-cchardet分支提供它取代了不再维护的原版cchardet但仍以cchardet模块名安装。它只在Python 3.13下被声明为依赖requirements.txt 中的faust-cchardet;python_version3.13。在Python 3.13上不会安装它import cchardet会静默失败检测自动回退到纯 Python 的charset_normalizer与chardet。实践中通常难以察觉差异但在某些模糊的遗留编码上猜测结果可能不同——此时显式传--encoding或在 Python 3.12 及更早版本上运行即可。完整讨论见 docs/encoding.rst。同步失败时的排查清单Sync IssuesREADME 为同步失败场景提供了一套递进的排查路线每一条都有对应的源码佐证1. 假设帧率一致传--no-fix-framerate跳过帧率比搜索对应 get_framerate_ratios_to_try() 中返回空列表的分支。2. 用黄金分割搜索找最优帧率比默认只评估少数常见帧率比24/23.976、25/23.976、25/24及其倒数见 constants.py 的FRAMERATE_RATIOS。传--gss则启用黄金分割搜索在 [0.9, 1.1] 区间内连续求解最优比例边界常量在 aligners.py实现见 golden_section_search.py。3. 增大最大偏移默认--max-offset-seconds为 60 秒constants.py。如果字幕偏差超过 60 秒实践中罕见但可能调大该值偏移搜索窗口本身在 FFTAligner._eliminate_extreme_offsets_from_solutions() 中把超出窗口的偏移置为 -inf 排除。4. 中部断裂用--split-penalty如果字幕开头对齐、中途开始漂移——如商业广告被剪掉、插入 / 删除了场景导演剪辑版、或两张碟拼接成一个文件——单个全局偏移无法同时修正两侧。--split-penalty启用 alass 风格的分段对齐piecewise alignment允许偏移沿时间轴变化只在确实能改善对齐的位置引入断点ffs video.mp4 -i unsynchronized.srt -o synchronized.srt --split-penalty不带值使用合理默认DEFAULT_SPLIT_PENALTY 5.0秒的重叠成本见 constants.py也可传一个数字作为每引入一个断点需付出多少秒重叠代价约 4–20 为典型区间值越低越倾向积极切分值越高越接近单一偏移。配套参数--split-length-penalty默认 0.25加权标准评分的边界 / 长度项与--split-subsample默认 1偏移搜索的子采样分辨率可在 constants.py 查看默认值。分段搜索还会在多个候选帧率缩放中选取分段得分最高者而不是沿用单偏移 FFT 搜索的选择见 try_sync()。完整介绍见 docs/advanced.rst。5. 换用 auditok 检测--vadauditok在低质量音频上有时比 WebRTC 的 VAD 更有效。注意 auditok 检测的是所有声音而非专门语音当真正的 VAD 能良好工作时它可能表现次优但在某些场景下很有效。所有可选的 VAD 名称集中在VAD_CHOICESconstants.py。6. 融合神经 VAD--vadfused将 WebRTC 与神经网络的 silero VAD 结合对嘈杂音频更鲁棒。策略可调--vadfused:intersection保守——只有两者一致才算语音--vadfused:union激进——任一触发即算语音--vadfused:weighted默认。这些选项需要可选依赖 silero而 silero 依赖 PyTorch两者都通过pip install ffsubsync[torch]安装或单独pip install torch。torch 默认不会随ffsubsync一起安装。7. 无字幕可借时用 whisper 转录对完全没有可用字幕的视频可用 whisper.cpp 转录音频、以转录稿为参考ffs video.mp4 -i in.srt -o out.srt --whisper-weights ~/whisper.cpp/models/ggml-base.en.bin这要求ffmpeg 8.0 且以--enable-whisper构建。FFsubsync 会替你展开路径中的~、推断语言*.en.bin模型视为英语否则自动检测可用--language覆盖并在视频已含内嵌字幕时给出提示。额外的 whisper 过滤参数可通过--whisper-args传递如--whisper-args queue12增大音频窗口以换取更准的时间戳代价是更高 CPU 占用。model、format、destination三个参数由 FFsubsync 托管不允许覆盖见 make_reference_pipe() 与参数定义 --whisper-weights。注意在转录模式下--vad被复用以携带 whisper 的 ggml VAD 模型路径而不是命名的检测器——这也是--vad不使用 argparsechoices而在 validate_args() 中手工校验的原因。批量同步的质量门控批量同步时一次错误的同步比不同步更糟。传--skip-sync-on-low-quality后当对齐结果不可信时保留字幕原样不动原样输出判定规则由 assess_alignment_quality() 实现含三条阈值参数默认值含义--min-score0.0得分低于此值即拒绝。得分符号有意义而绝对值未归一化因此默认 0.0 只拒绝反相关明显错误的对齐--quality-max-offset-seconds30.0偏移超过此秒数即视为可疑匹配--max-framerate-deviation0.1帧率缩放偏离 1.0 超过此值即拒绝。默认值放行 FFsubsync 能做出的全部真实校正离散比最大约 0.0427只在确定帧率不该变时才收紧工作原理把字幕同步化为信号对齐问题README 与 docs/how_it_works.rst 把算法归纳为三步每一步都能在源码中找到对应实现第一步离散化把参考视频的音频流或已有字幕的时间轴与输入字幕都切成10 ms窗口。10 ms 粒度对应常量SAMPLE_RATE 100每秒 100 个窗口见 constants.py所有偏移计算都以样本数为单位、最后再除以采样率换算成秒见 try_sync()。第二步标记语音对每个 10 ms 窗口判断是否含语音对字幕是平凡的只要该窗口内有任何字幕处于显示状态就标记为语音对音频使用现成的语音活动检测器如 WebRTC 内置的 VAD可切换 auditok、silero、fused 等见上文排查清单。注意--frame-rate默认 48000指的是用于 VAD 的音频采样率而不是视频的帧率帧率校正由--gss/ 帧率比搜索处理。第三步对齐两条二进制串现在得到两条二进制串——一条来自参考视频语音或参考字幕一条来自待同步字幕。对齐得分定义为(视频 1 与字幕 1 匹配数) − (视频 1 与字幕 0 匹配数)然后搜索使该得分最大化的偏移。由于二进制串很长超过 1 小时的视频可达数百万位朴素的 O(n²) 全偏移评分不可接受关键观察是对所有偏移评分本质上是卷积运算可用**快速傅里叶变换FFT**在 O(n log n) 内完成——这正是 FFTAligner.fit() 做的事把两串映射为 ±1 序列、补零到 2 的幂长度、FFT 相乘再逆变换最后取卷积峰值对应的偏移由 MaxScoreAligner 在多个候选帧率比与--gss候选上挑选全局最优。底层 FFT 由 numpy间接来自 FFTPACK提供。测试 tests/test_alignment.py 用(111001, 11001, -1)等微型二进制串验证了 FFT 对齐、MaxScoreAligner 封装与空语音输入报错FailedToFindAlignmentException等行为是理解该算法的绝佳最小示例。关于参考类型的一个补充--reference-stream可以从多音轨 / 多字幕轨的视频中选定特定流ffmpeg 约定格式如0:s:0是第一字幕轨、0:a:3是第四音轨可省略前导0:写作s:0或a:3见 --reference-stream 参数。此外还有 PGS 图像字幕参考--pgs-ref-stream无需 OCR 直接从图像字幕显示时间构造语音信号、序列化语音参考.npy/.npz配合--serialize-speech一次提取多次复用以及无参考的--apply-offset-seconds纯偏移模式详见 docs/reference_types.rst。性能与限制性能README 给出经验值——针对视频同步通常 2030 秒完成最昂贵的步骤是原始音频提取如果已有正确同步的参考字幕可跳过音频提取通常不到 1 秒。这与 docs/how_it_works.rst 的主要成本在音频提取而非对齐本身一致。限制大多数视频与字幕的不一致源于开头或结尾段落的增减如字幕中的剧情回顾被视频剪掉FFsubsync 在这些场景下表现良好README 称实践中覆盖 95% 的使用场景。真正的难点是中间段落的断裂——中段广告被剪、场景被增删、两碟拼接——因为单一全局偏移无法同时修正两侧这正是实验性的--split-penalty模式要处理的情况。该项目在 README 的 Future Work 一节中明确表示会继续加固该模式目前仍视为实验特性。此外空语音输入参考或字幕完全检测不到语音会被明确拒绝并抛出FailedToFindAlignmentException见 tests/test_alignment.py 中的空数组用例。小结与延伸阅读FFsubsync 把字幕同步这一看似需要 NLP 的问题优雅地转化为信号处理问题10 ms 离散化、VAD 标记、FFT 卷积对齐配合帧率比搜索与可选的分段对齐实现了语言无关、无需训练、秒级到数十秒级的自动同步。从命令行一键同步到批量质量门控、远程流式参考、Docker 部署、Python 库式集成README 覆盖了完整的实战链路。想继续深入仓库内的官方文档都是很好的下一站docs/usage.rst更多用法示例、docs/cli.rst由参数解析器直接生成的完整 CLI 参考、docs/how_it_works.rst算法详解、docs/reference_types.rst全部参考类型、docs/advanced.rst分段同步等高级选项、docs/encoding.rst编码处理全史以及 docs/library.rst库式 API。项目遵循 MIT 许可证其核心依赖包括 ffmpeg 与 ffmpeg-python音频提取、WebRTC VAD 与 py-webrtcvad语音检测、srtSRT 解析、numpy/FFTPACKFFT 对齐以及 argparse、rich、tqdm 等开发体验库。赞分享音视频音频处理视频处理CLI【免费下载链接】ffsubsyncAutomagically synchronize subtitles with video.项目地址https://gitcode.com/gh_mirrors/ff/ffsubsync点击查看免费下载相关推荐ansi库函数详解如何将ANSI功能集成到你的Bash脚本中ansi库函数详解如何将ANSI功能集成到你的Bash脚本中 在Bash脚本开发中通过ANSI转义码可以实现文本颜色变化、光标定位等高级终端效果。 ansi开发工具pyvideotrans字幕语言检测自动识别字幕语言的终极指南pyvideotrans字幕语言检测自动识别字幕语言的终极指南 想要轻松处理多语言视频字幕pyvideotrans的字幕语言检测功能正是你需要的解决方案?音视频AI 应用语音本地部署ffsubsync自动字幕同步的终极解决方案ffsubsync自动字幕同步的终极解决方案 ffsubsync 是一款强大的字幕同步工具能够自动将字幕与视频完美对齐让你告别手动调整字幕时间轴的繁琐过程音视频音频处理视频处理CLI上一篇极速迁移TensorRT插件从IPluginV2到IPluginV3的实战指南下一篇YOLOv5性能优化内存管理最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考