Script Director 是一个将音频文件与台本（文本）自动对齐，生成带时间戳字幕的工具。它利用 Faster Whisper / Stable Whisper 进行语音识别，并通过 Needleman-Wunsch 风格的动态规划算法将识别结果与台本句子精确匹配，即使识别结果与台本不完全一致也能智能插值，确保每一句台本都有准确的时间码。
- 🎙️ 基于 Stable Whisper 的高质量语音识别，支持单词级时间戳
- 📄 支持日语（
ja）、中文（zh）、英文（en）等多语言台本分割（使用pysbd或标点符号） - 🔗 智能句子对齐：采用增强的 Needleman-Wunsch 算法，预计算相似度矩阵，使用 NumPy 优化内存，允许一个台本句子匹配连续多个单词片段
- ✂️ 短句模式：按标点符号（句号、问号、感叹号等）将长句拆分为更短的句子，生成更精确的字幕（适合台词密集场景）
- 🔄 只对齐模式：可直接将已有字幕文件（SRT/LRC）与台本重新对齐，无需再次语音识别，节省时间
- ⚙️ 命令行界面（CLI） 和配置文件支持，方便重复使用
- 🖥️ 图形化界面（GUI）（基于 customtkinter），提供实时进度条、日志显示和帮助提示
- 🎛️ 高级参数可配置：通过配置文件调整对齐惩罚、相似度偏移、默认时长、束搜索宽度、VAD（语音活动检测）等，适应不同场景
- 📊 实时进度反馈：听写阶段和对齐阶段均有进度显示，CLI 使用 tqdm，GUI 使用进度条
- 🧩 模块化设计：
director.py为核心，only_align.py处理只对齐，just_utils.py提供公共工具，main_logger.py统一管理多进程日志 - 🎬 视频输入支持：直接输入视频文件（MP4、MKV、AVI、MOV 等），自动提取音频后继续处理
- Python 3.9+, 3.12.10-
- NVIDIA CUDA Toolkit 12.9 （若使用 CUDA 计算）
- ffmpeg（处理视频文件时需要，见下方注意事项）
- 第三方 Python 库（见
requirements.txt）
- 克隆或下载本项目。
- 安装依赖：
pip install -r requirements.txt
- 下载 Faster Whisper 模型并解压到本地目录。
- 快上加快
- 极致精度
- 性能取舍
以上超链接均指向 Huggingface，若你身处中国大陆无法访问，可尝试使用 HF-Mirror 此镜像网站。
Script Director 提供两种使用方式：命令行工具 cli.py 和 图形界面 gui.py。
若你使用打包好的 Release 版本，以下内容的 python cli.py 均可替换为 .\cli.exe。
CLI 支持子命令，便于配置和处理。
首次使用需通过 init 命令创建配置文件 config.ini：
python cli.py init按照提示输入：
- Faster Whisper 本地模型路径：模型文件夹的路径（如
./faster-whisper-large-v3） - 台本与音频所使用的语言代码：例如
ja（日语）、zh（中文）、en（英文） - 设备类型：
cuda或cpu - 计算类型：
float16（GPU）、int8（CPU）等
高级参数（可选）：在初始化过程中，还可以设置以下高级参数（直接回车跳过则使用默认值）：
gap_penalty：对齐惩罚值，默认-10similarity_offset：相似度偏移，默认50default_duration：默认字幕时长（秒），默认5.0max_combine：最大合并片段数，默认20beam_size：束搜索宽度，默认5vad_filter：启用语音活动检测，默认Falsevad_parameters：VAD 参数（JSON 格式），默认{}
这些参数会自动写入配置文件的 [advanced] 节，便于后续调优。
如需修改配置项，可使用 config 命令：
python cli.py config model=/new/model/path
python cli.py config lang=en支持修改的键（包括高级参数）：model, lang, device, compute, gap_penalty, similarity_offset, default_duration, max_combine, beam_size, vad_filter, vad_parameters。
使用 process 命令生成字幕：
python cli.py process "音频文件路径,台本文件路径" [-t srt|lrc] [-n 自定义名称] [-p] [-s]- 参数
INPUT_STR必须用英文逗号分隔两个文件路径，程序会自动识别音频/视频文件和台本文件（台本文件扩展名需为.txt，音频/视频文件支持常见格式，视频将自动提取音频轨）。 -t, --type：输出格式，可选srt或lrc，默认为srt。-n, --name：自定义输出文件名（不含扩展名），默认与音频文件同名。-p, --preprocess：启用台本预处理，自动删除空行和方括号内容。-s, --shorter：启用短句模式（按标点分割长句，生成更精确的字幕）。
进度反馈：
- 听写阶段（0-80%）：由 Stable Whisper 内部进度回调驱动，无额外进度条（避免干扰）。
- 对齐阶段（80-99%）：使用
tqdm显示进度条，实时反映动态规划进度。 - 收尾阶段（99-100%）：将字幕保存到文件，完成台本转字幕工作。
示例：
# 基本用法
python cli.py process "meeting.wav,transcript.txt" -t lrc -n meeting_lyrics
# 启用预处理和短句模式
python cli.py process "audio.mp3,script.txt" -t srt -p -s输出文件将保存在音频文件所在目录，名为 meeting_lyrics.lrc 或 audio.srt。
如果你已经有一份字幕文件（SRT/LRC），只想用它和台本重新对齐（例如修正时间轴或格式转换），可以直接将字幕文件作为第二个输入：
python cli.py process "台本文件.txt,已有字幕.srt" [-t srt|lrc] [-n 自定义名称] [-p]此时程序不会启动语音识别，而是将已有字幕的每句时间戳与台本句子进行动态规划对齐，生成新字幕。注意：只对齐模式下 -s/--shorter 选项无效（因为已有字幕通常没有单词级时间戳），程序会自动忽略并给出警告。
典型应用场景：
- 修正自动生成字幕的时间轴（使用更精确的台本）
- 将 SRT 格式转换为 LRC 格式，同时重新对齐
- 合并多个字幕文件或调整台词分段
示例：
# 将现有 SRT 字幕与台本重新对齐，输出 LRC
python cli.py process "script.txt,old_subtitle.srt" -t lrc -n aligned如果你更喜欢可视化操作，可以直接运行图形界面：
python gui.py界面采用左右分屏布局：
- 左侧：配置与输入区域，包括模型路径、语言代码、设备类型、计算类型、音频/台本文件选择、可选的已有字幕文件（带有 ❔ 帮助提示）、输出名称、输出格式、预处理选项、短句模式选项以及开始按钮。
- 右侧：上方为进度条（实时显示处理进度），下方为运行日志区域（实时显示所有日志输出）。
操作步骤：
- 选择本地 Faster Whisper 模型文件夹（听写模式需要；只对齐模式不需要模型，但可以留空）
- 选择音频文件（支持 .wav, .mp3, .flac, .m4a 等）—— 如果提供了已有字幕文件，则音频文件可留空
- 选择台本文件（UTF-8 编码的 .txt 文件）
- （可选）选择已有字幕文件（.srt 或 .lrc），此时程序将进入只对齐模式
- （可选）指定输出文件名（不含扩展名）
- 选择输出格式（SRT 或 LRC）
- 勾选“预处理台本”可自动清理空行和方括号标识
- 勾选“短句模式”可按标点将长句拆分为短句（注意：只对齐模式下此选项会自动禁用并灰显）
- 点击“开始处理”，实时查看进度和日志，处理完成后弹出提示
关闭窗口时会弹出确认框，若正在处理则询问是否强制退出，确保子进程被终止。
config.ini 文件包含两个节：[common] 和 [advanced]。
[common]
model = D:/models/faster-whisper-large-v3
lang = ja
device = cuda
compute = float16model：Faster Whisper 模型文件夹路径lang：语言代码（支持ja,zh,en,ko,fr,de等）device：计算设备cuda或cpucompute：计算精度，常用float16（GPU）或int8（CPU）
[advanced]
gap_penalty = -10
similarity_offset = 50
default_duration = 5.0
max_combine = 20
beam_size = 5
vad_filter = False
vad_parameters = {}gap_penalty：序列对齐时的插入/删除惩罚值，负值，绝对值越大惩罚越重，影响匹配粒度。similarity_offset：相似度得分偏移量（原始相似度减去该值），用于将相似度得分映射到 DP 表的匹配得分，值越大匹配门槛越高。default_duration：当无法从 Whisper 结果中获取时间时，为未匹配句子分配的默认时长（秒）。max_combine：限制一句台本最多合并的 Whisper 片段数（包括单词或字幕段）。beam_size：束搜索宽度，影响识别速度和准确度，值越大越慢但越准。vad_filter：启用语音活动检测（Voice Activity Detection），可过滤非语音段，提高识别效率。vad_parameters：VAD 参数，JSON 格式，可自定义阈值等（默认为空，使用 Faster Whisper 内置参数）。
如果配置文件中缺少 [advanced] 节或某项参数，程序会使用默认值，不会报错。
director.py：核心模块，包含语音识别、增强版句子对齐（NumPy 优化、预计算相似度矩阵）、时间戳映射、字幕保存等功能。cli.py：命令行入口，处理参数、配置文件并调用director.direct_it或only_align.align_it。gui.py：图形化界面入口，基于 customtkinter 实现，包含进度条、日志显示和帮助提示。only_align.py：只对齐模式专用模块，负责解析已有字幕文件并与台本重新对齐。just_utils.py：公共工具模块，提供配置加载、日志映射、时间格式化、字幕保存、进程管理、台本清洗、时间轴插值等功能。main_logger.py：日志管理模块，提供全局单例 logger，支持主进程输出到控制台/文件/队列，子进程仅发送队列（避免多进程冲突）。
- 音频格式支持取决于 Faster Whisper（常见格式如
wav,mp3,m4a等）。 - 视频输入：支持 MP4、MKV、AVI、MOV 等常见视频格式。处理视频文件时需要 ffmpeg，程序按以下顺序查找：项目
ffmpeg/目录 → 系统 PATH。如未找到会提示安装。可将 ffmpeg 放入项目根目录的ffmpeg/文件夹下（详见ffmpeg/README.md，若为打包版本，则为_internal/ffmpeg/）。 - 台本文件需为 UTF-8 编码的纯文本。
- 预处理功能会删除行首的方括号标识（如
[人名]或【动作】），但保留句子内部的方括号（如他说[笑]）。 - 短句模式：启用后会按标点符号（句号、问号、感叹号、顿号等）将长句切分为短句，适合台词间隔明显的场景；但注意这会增加字幕条数，且需要 Whisper 提供单词级时间戳才能获得较好的效果。只对齐模式下因缺少单词级时间戳，短句模式自动禁用。
- 只对齐模式：当提供已有字幕文件（.srt 或 .lrc）时，程序自动跳过语音识别，直接对齐台本和字幕文本。此模式下短句模式无效，程序会自动禁用并给出警告。只对齐模式同样支持预处理和自定义输出格式。
- 日志系统：主进程可同时输出到控制台、文件和队列（用于 GUI）；子进程仅将日志发送到队列，由主进程统一处理，避免文件写入冲突和无限循环。
- 如果 Whisper 识别结果与台本差异较大，可尝试调整
[advanced]中的gap_penalty和similarity_offset参数，以获得更佳的对齐效果。 - 关闭 GUI 窗口时会强制终止所有子进程（包括 Faster Whisper 识别进程），确保程序完全退出。
- 多进程隔离机制可防止 Faster Whisper 底层崩溃导致主程序异常退出。
- 本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。
Happy Subtitling! 🎬