视频转文字

功能概览

识别视频语音并保存字幕

适合采访、课程、活动记录、幕后花絮和需要快速定位对白的长视频。所有识别在本机运行，插件不会因为识别任务自动上传视频或字幕。

安装运行时

安装视频转文字插件

1. 1
   下载视频转文字 ZIP

   获取与当前照片流和系统架构匹配的 PhotoFlow-video-transcription-*.zip。

2. 2
   放入组件根目录

   在“设置 → 插件管理”打开组件根目录，将 ZIP 原样复制进去。

3. 3
   刷新并安装

   确认清单、运行时和必需文件完整后点击安装。

4. 4
   打开组件设置

   进入“设置 → 视频转文字”，运行诊断并查看模型根目录。

安装识别模型

选择 Whisper 或 Kimi-Audio，按需配置

两种识别引擎都可选，配置其中一种即可开始识别，也可以都安装后按任务切换。选择 Kimi 不需要先安装用于 Faster-Whisper 的模型；两套环境和模型分别存放。

模型文件不随插件自动下载。运行环境、模型和设备全部就绪后，再在“设置 → 视频转文字”选择引擎并测试。切换设置只影响新任务。

可选方案一

配置 Faster-Whisper 和识别模型

1. 准备运行环境并选择模型

在“设置 → 视频转文字”选择 Faster-Whisper，先运行诊断。正式插件包自带运行环境，不需要另装 Python；CPU 可选 int8，NVIDIA GPU 可选 CUDA/float16。是否可用以诊断结果为准。

只需下载一个适合设备的模型，无需把下面所有模型都装上。小模型占用较少，较大模型需要更多内存或显存；用同一段素材比较速度和效果后再决定。

方法一：使用 Hugging Face hf 命令下载

1. 1
   在插件设置中打开模型目录

   进入“设置 → 视频转文字”，点击模型根目录旁的“打开”，复制资源管理器地址栏中的完整路径。

2. 2
   安装 Hugging Face CLI

   按照 Hugging Face 官方 Windows 安装说明安装 hf 命令；安装完成后在 PowerShell 运行 hf --help 检查。

将下面的占位路径替换为设置页显示的模型根目录。只下载一个模型时执行对应的一条命令：

$ModelRoot = 'C:\请替换为设置页显示的模型根目录'

# 推荐：Large V3 Turbo
hf download dropbox-dash/faster-whisper-large-v3-turbo --local-dir "$ModelRoot\large-v3-turbo"

# 另一种选择：Large V3
hf download Systran/faster-whisper-large-v3 --local-dir "$ModelRoot\large-v3"

下载完成后，可以保留或删除模型目录中的 .cache\huggingface 元数据目录；删除它不会删除模型，但再次更新模型时会重新检查文件。

方法二：在浏览器中手动下载

1. 1
   打开上方模型仓库

   进入模型页面的“Files and versions”，确认仓库说明写明 CTranslate2 / faster-whisper。

2. 2
   下载仓库中的全部模型文件

   至少必须取得 config.json、model.bin、tokenizer.json，并保留仓库中的其他 JSON、词表和子目录。不要只下载 model.bin。

3. 3
   按模型 ID 建立目录

   Turbo 使用 large-v3-turbo，Large V3 使用 large-v3。把下载文件直接放入对应目录，不要多套一层仓库名文件夹。

2. 检查模型目录和必需文件

模型根目录/
  large-v3-turbo/
    config.json
    model.bin
    tokenizer.json
    preprocessor_config.json
    ...仓库中的其他文件

  large-v3/
    config.json
    model.bin
    tokenizer.json
    preprocessor_config.json
    ...仓库中的其他文件

1. 1
   重新打开或刷新设置页

   只有名称在允许列表、目录没有越界链接且文件完整的模型会显示为已安装。

2. 2
   选择模型并运行诊断

   诊断成功后再用一个短视频测试；模型切换只影响之后新建的任务。

还可安装 tiny、base、small、medium、large-v1/v2、large-v3、large-v3-turbo 及对应英语/Distil 变体。模型切换只影响之后新建的任务，已有任务保留创建时的设置快照。

3. 选择设备并完成第一次识别

1. 1
   刷新模型列表

   回到“设置 → 视频转文字”，确认引擎为 Faster-Whisper，并选择已下载的模型。

2. 2
   设置计算设备

   CPU 选择 int8；CUDA 通常使用 float16。GPU 加载失败时，可开启 CPU 回退，或直接选择 CPU。大型模型在 CPU 上可能较慢。

3. 3
   运行诊断并测试

   先确认模型和设备可用，再选一段短视频开始识别。完成后检查同目录 SRT 的文字与时间轴。

模型不显示时，检查文件夹名、目录层级以及 config.json、model.bin、tokenizer.json 是否完整；不要使用 PyTorch 的 .pt 权重代替 CTranslate2 模型。显存不足时可选较小模型或改用 CPU。

可选方案二

配置 Kimi-Audio 的运行环境和模型

以下步骤适用于 Windows x64。Kimi 使用独立环境，不需要先完成 Whisper 配置。安装依赖和下载模型时需要联网，识别时在本机运行。

1. 检查电脑和准备安装目录

• 安装 Python 3.12 x64 和 Git；依赖安装会从官方源码仓库读取指定版本。
• 需要 NVIDIA GPU、支持 CUDA 12.8 的 Windows 驱动，以及 BF16 计算能力。Kimi 不支持 CPU 识别。
• 在“设置 → 插件管理”打开视频转文字插件目录。确认里面有 requirements-kimi.txt，再从该目录打开 PowerShell。
• 下面使用固定的 PyTorch、CUDA 和 FlashAttention 组合。不要单独升级其中一个包；其他组合需要单独验证。

py -3.12 --version
git --version
nvidia-smi
Test-Path .\requirements-kimi.txt

前三条应正常显示版本或显卡信息，最后一条应返回 True。缺少命令时，先完成对应软件安装并重新打开终端。

2. 创建独立环境并安装依赖

在插件目录中依次执行下面的命令，每条成功后再执行下一条。这会创建 .venv-kimi，不需要激活环境，也不会使用 Whisper 自带的 Python。

py -3.12 -m venv .venv-kimi
.\.venv-kimi\Scripts\python.exe -m pip install --upgrade pip
.\.venv-kimi\Scripts\python.exe -m pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128
.\.venv-kimi\Scripts\python.exe -m pip install --no-deps "https://github.com/kingbri1/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1%2Bcu128torch2.7.0cxx11abiFALSE-cp312-cp312-win_amd64.whl"
.\.venv-kimi\Scripts\python.exe -m pip install packaging wheel setuptools ninja
.\.venv-kimi\Scripts\python.exe -m pip install --no-build-isolation -r requirements-kimi.txt

FlashAttention 的 wheel 来自 kingbri1 维护的 Windows 预编译包，是插件安装说明所用的第三方构建，并非 PyTorch 官方发布。它只适用于上述 Windows x64、Python 3.12 和 CUDA/PyTorch 组合。安装失败时保留报错，核对版本后再继续。

安装完成后，可检查 GPU 是否能被环境识别：

.\.venv-kimi\Scripts\python.exe -c "import torch; print('CUDA:', torch.cuda.is_available()); print('BF16:', torch.cuda.is_bf16_supported())"

CUDA 和 BF16 都应为 True。此检查仅说明基础计算能力可用，模型是否能装入显存，还需要后面的真实识别测试。

3. 下载 Kimi 主模型和语音 tokenizer

在插件设置中打开模型根目录并复制地址。准备好 Hugging Face 的 hf 下载工具后，替换下面的占位路径，依次下载两组文件：

$ModelRoot = 'C:\请替换为设置页显示的模型根目录'
hf download moonshotai/Kimi-Audio-7B-Instruct --local-dir "$ModelRoot\kimi-audio-7b-instruct" --exclude "audio_detokenizer/*" "vocoder/*"
hf download zai-org/glm-4-voice-tokenizer --local-dir "$ModelRoot\kimi-audio-7b-instruct\glm-4-voice-tokenizer"

tokenizer 用于把语音转换成模型需要的数据，也是必需文件。命令只排除了语音生成用的 audio_detokenizer 和 vocoder；其他文件要完整保留，包括模型仓库自带的 Python 代码。Kimi 目录中的 whisper-large-v3 是它自己的音频编码器，不是另一套需要单独配置的 Faster-Whisper 模型。

也可以在这两个模型页面的 Files and versions 中手动下载，放入同样的目录。不要只下载一个权重分片，也不要多套一层仓库名文件夹。

模型根目录/
  kimi-audio-7b-instruct/
    config.json
    tokenizer_config.json
    special_tokens_map.json
    tiktoken.model
    configuration_moonshot_kimia.py
    modeling_moonshot_kimia.py
    tokenization_kimia.py
    model.safetensors.index.json
    model-*.safetensors       # 索引中列出的全部分片
    whisper-large-v3/
      config.json
      model.safetensors
    glm-4-voice-tokenizer/
      config.json
      preprocessor_config.json
      model.safetensors
    ...仓库中的其他必需文件

4. 在插件中选择 Kimi 并运行诊断

1. 1
   刷新设置页

   打开“设置 → 视频转文字”，将“识别引擎”设为 Kimi-Audio，刷新模型列表并选择 Kimi-Audio 7B Instruct。

2. 2
   运行诊断

   确认独立环境、CUDA、BF16、FlashAttention 和模型文件可用。模型未显示时，检查目录层级和下载是否完整。

3. 3
   选择权重精度

   自动模式在 20 GB 及以下显卡使用 NF4 量化以减少显存占用；也可明确选择 NF4 或原始 BF16。量化可能影响效果，16 GB 显存不保证一定能运行。

4. 4
   测试短视频

   回到文件页选择一段短视频，开始识别。检查文字、分段时间和同名 SRT，再处理长视频。

如果电脑另外装有 Node.js，还可在插件目录运行 node scripts/diagnose-kimi.cjs 查看诊断；普通使用也可以直接通过设置页诊断。

5. 调整字幕分段并处理常见问题

Kimi 按语音片段生成时间戳，不是逐字对齐。VAD（语音活动检测）分段默认最长 12 秒，可设为 3–30 秒；关闭 VAD 时按固定长度切分。需要更精确时间轴时，可以选择 Whisper。

• 环境不可用：检查 .venv-kimi 是否直接位于插件目录，以及依赖是否全部安装成功。
• 模型未安装：检查主模型、全部权重分片、whisper-large-v3 和 glm-4-voice-tokenizer 子目录。
• 显存不足：尝试 NF4 并关闭占用 GPU 的其他程序；仍不足时换用可运行的设备或选择 Whisper。Kimi 不会自动切换为 CPU。
• Beam、CTranslate2 计算类型和 CPU 回退仅适用于 Whisper，不用于 Kimi。
• 自动语言保留原文；明确选择中文后才执行简体转换。

已有独立 Python 环境时，可在启动照片流前设置 PHOTOFLOW_KIMI_PYTHON 为它的完整路径。该 Python 必须能被当前系统直接运行；Windows 不能填写 WSL 中的 Linux 路径。

识别设置

选择识别语言、模型和计算设备

开始识别

选择视频并开始识别

1. 选择来源在项目文件页选择视频、文件夹或两者组合，从“视频工具 → 视频转文字”打开。
2. 检查预览树左侧列出将处理的视频；图片、独立音频和无关文件会被忽略。
3. 确认设置检查识别引擎、语言、模型、设备和语音分段设置。
4. 开始识别点击按钮后才开始识别和准备视频副本；刷新页面或切换文件不会自动开始。
5. 查看进度同一批次只加载一次模型，逐文件识别并保存 SRT；某个文件失败不影响其他文件继续。
6. 恢复任务本次运行中可继续取消、失败或部分失败的任务；重启后请查看已保存的 SRT，再选择未完成的视频重新开始。

字幕浏览与搜索

浏览字幕并搜索关键词

播放与字幕

一边播放视频，一边查看和搜索字幕

1. 打开字幕面板在文件夹页面右上角的“面板”菜单中勾选“字幕”，再打开视频预览。
2. 读取同名字幕面板读取视频同目录、同名的 SRT。找不到时，先生成字幕或把 SRT 放到对应位置。
3. 跟随或自由浏览播放时自动高亮并滚动到当前字幕；关闭“跟随播放”后可以自由滚动。
4. 点击字幕跳转点击一条字幕，视频跳到对应时间；也可以先搜索关键词再定位。
5. 刷新和调整布局字幕生成或被外部修改后点击刷新。面板可固定、排序，并通过拖动边界调整宽度。

此面板只读取同名 SRT，不会启动识别或修改字幕，也不读取视频内嵌字幕轨。支持每文件最多 4 MiB、20,000 条有效字幕；超限时请先拆分或精简字幕文件。

SRT 保存

识别成功后，字幕直接保存到视频旁边

每个成功结果立即写入同目录、同名的 UTF-8 BOM .srt。字幕保存在 SRT 文件里，任务记录只在本次运行期间保留。

• 每个视频的字幕保存后，即可浏览、搜索或打开对应的 SRT。
• 重新识别会检查已有字幕内容，再替换同名 SRT；如需保留人工修改的字幕，请先另存副本。
• 取消会停止识别并清理尚未保存的临时文件；之前已保存的 SRT 保留。
• 成功保存后安全回收完整视频副本；应用重启后仍可直接读取和搜索已落盘的 SRT。

限制与排查

识别失败或速度慢时怎么办

• 单次选择最多解析 2,000 个视频；超大目录应拆成多批。
• 大型模型需要更多显存、内存和磁盘空间；先用短视频测试速度与质量。
• 长静音段可能较久不产生字幕；VAD 可减少等待，但不保证所有录音环境都准确。
• 显示“运行时不可用”时先运行诊断；显示“模型未安装”时，按所选引擎检查模型目录和必需文件。Whisper 和 Kimi 的文件要求不同。
• 素材、模型和字幕都在本机处理；第三方同步盘仍遵循其自己的上传规则。