omnicaptions-LaiCut

LaiCut

LattifAI 的音频文本处理工具包。目前支持强制对齐，翻译和说话人分离功能即将推出。

需要 LattifAI API 密钥——可从 https://lattifai.com/dashboard/api-keys 获取

适用场景

• 需要准确／精确的时间信息——用户要求准确的时间戳或精确对齐时
• 同步错位的字幕——修复下载字幕中的时间漂移
• 对齐人工转录文本——将文本与语音精确匹配
• 转录后对齐——改善自动生成字幕的时间信息
• 支持多种格式——SRT、VTT、ASS、LRC、TXT、MD

不适用场景

• 需要完整转录（使用 /omnicaptions:transcribe）
• 没有现成的字幕／转录文本（无内容可供对齐）
• 非常短的片段（<5 秒）

设置

pip install "omni-captions-skills[laicut]" --extra-index-url https://lattifai.github.io/pypi/simple/

API 密钥

优先级：LATTIFAI_API_KEY 环境变量 → .env 文件 → ~/.config/omnicaptions/config.json

如果未设置，请询问用户：Please enter your LattifAI API key (get from https://lattifai.com/dashboard/api-keys):

然后使用 -k <key> 运行。密钥将自动保存到配置文件。

CLI 用法

# Basic alignment (default: JSON with word-level timing, RECOMMENDED)
omnicaptions LaiCut audio.mp3 caption.srt
# → caption_LaiCut.json

# Then convert to desired format (preserves word timing in JSON for future use)
omnicaptions convert caption_LaiCut.json -o caption_LaiCut.srt

# Smart sentence segmentation (for word-level captions like YouTube VTT)
omnicaptions LaiCut video.mp4 caption.vtt --split-sentence

选项	说明
-o, --output	输出文件（默认：<caption>_LaiCut.json）
-f, --format	输出格式（默认：json）
-k, --api-key	LattifAI API 密钥
--split-sentence	AI 驱动的语义句子分段
-v, --verbose	显示进度

JSON 输出（推荐）

JSON 输出会保留单词级时间信息，供后续任务使用：

[
  {
    "text": "Hello world",
    "start": 0.0,
    "end": 2.5,
    "words": [
      {"word": "Hello", "start": 0.0, "end": 0.5},
      {"word": "world", "start": 0.6, "end": 2.5}
    ]
  }
]

将 JSON 转换为其他格式：

# For playback/editing
omnicaptions convert video.en_LaiCut.json -o video.en_LaiCut.srt

# For bilingual ASS
omnicaptions convert video.en_LaiCut.json -o video.en_LaiCut.ass --style bilingual

# For karaoke
omnicaptions convert lyrics_LaiCut.json -o lyrics_LaiCut_karaoke.ass --karaoke

用于翻译：请先转换为 SRT（JSON 文件过大，Claude 无法读取）：

# 1. JSON → SRT
omnicaptions convert video.en_LaiCut.json -o video.en_LaiCut.srt

# 2. Claude 翻译 → video.en_LaiCut_Claude_zh.srt

# 3. 转换为带颜色 ASS
omnicaptions convert video.en_LaiCut_Claude_zh.srt -o video.en_LaiCut_Claude_zh_Color.ass \
  --line1-color "#00FF00" --line2-color "#FFFF00"

询问用户：是否启用智能句子分段？

当输入字幕为单词级或分段不佳时（例如 YouTube VTT），请询问用户是否启用 --split-sentence：

Is the caption word-level or poorly segmented (e.g., YouTube VTT)?
- Yes → Add --split-sentence (AI re-segments into natural sentences)
- No → Keep original segmentation

使用场景：YouTube VTT、单词对齐字幕、杂乱的自动生成字幕

LattifAI API 密钥错误处理

LaiCut 需要 LattifAI API 密钥（不是 Gemini API 密钥）

错误示例：

API KEY verification error: API KEY is invalid or expired.

正确处理方式：

1. 告知用户 LaiCut 需要有效的 LattifAI API 密钥
2. 询问用户是否要提供新密钥
3. 引导用户前往 https://lattifai.com/dashboard/api-keys
4. 绝不要以“时间信息已经足够准确”为由跳过对齐步骤

常见错误

错误	修复方法
API 密钥无效／已过期	向用户索要新密钥，不要跳过
没有 API 密钥	设置 LATTIFAI_API_KEY 或使用 -k
音频格式错误	先转换为 WAV/MP3/M4A
输出为空	检查字幕是否包含文本内容

相关技能

技能	使用场景
/omnicaptions:transcribe	先生成转录文本
/omnicaptions:convert	转换字幕格式
/omnicaptions:translate	对齐后翻译

工作流示例

重要提示：

• LaiCut 默认输出 JSON（保留单词级时间信息）
• 在需要播放或翻译时转换为 SRT/ASS
• 对齐后再生成双语字幕

# No caption: transcribe → align (JSON) → convert → translate
omnicaptions transcribe video.mp4
# → video_GeminiUnd.md
omnicaptions LaiCut video.mp4 video_GeminiUnd.md
# → video_GeminiUnd_LaiCut.json
omnicaptions convert video_GeminiUnd_LaiCut.json -o video_GeminiUnd_LaiCut.srt
# → video_GeminiUnd_LaiCut_Claude_zh.srt (after translate)

# Has caption: download → align (JSON) → convert → translate
omnicaptions download "https://youtu.be/xxx"
# → xxx.en.vtt
omnicaptions LaiCut xxx.mp4 xxx.en.vtt
# → xxx.en_LaiCut.json
omnicaptions convert xxx.en_LaiCut.json -o xxx.en_LaiCut.srt
# → xxx.en_LaiCut_Claude_zh.srt (after translate)
# → xxx.en_LaiCut_Claude_zh_Color.ass (after convert with --style)