omnicaptions-transcribe

Gemini 转录

使用 Google Gemini API 转录音频/视频，并输出结构化 Markdown。

YouTube 视频工作流

重要：转录前先检查是否已有字幕：

1. Check captions: yt-dlp --list-subs "URL"
2. Has caption → Use /omnicaptions:download to get existing captions (better quality)
3. No caption → Transcribe directly with URL (don't download first!)

向用户确认：转录前，询问他们是否想先检查是否已有字幕。

URL 和本地文件支持

Gemini 原生支持 YouTube URL——无需下载，直接传入 URL 即可：

# YouTube URL (recommended, no download needed)
omnicaptions transcribe "https://www.youtube.com/watch?v=VIDEO_ID"

# Local files
omnicaptions transcribe video.mp4

注意：除非用户指定 -o，否则输出默认保存到当前目录。

适用场景

• 视频 URL——YouTube、直接视频链接（Gemini 原生支持）
• 转录播客、访谈、讲座
• 需要包含时间戳和说话人标签的逐字转录
• 希望根据内容自动生成章节
• 混合语言音频（保留语码切换）

不适用场景

• 视频已有字幕——先使用 /omnicaptions:download 获取现有字幕
• 需要实时流式转录（使用 Whisper）
• 音频超过 2 小时（Gemini 上传时长限制）
• 需要翻译而非转录

快速参考

方法	说明
transcribe(path)	转录文件或 URL（同步）
translate(in, out, lang)	翻译字幕
write(text, path)	将文本保存到文件

设置

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

API 密钥

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

如果未设置，请询问用户：Please enter your Gemini API key (get from https://aistudio.google.com/apikey):

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

CLI 用法

重要：CLI 需要子命令（transcribe、translate、convert）

# Transcribe (auto-output to same directory)
omnicaptions transcribe video.mp4              # → ./video_GeminiUnd.md
omnicaptions transcribe "https://youtu.be/abc" # → ./abc_GeminiUnd.md

# Specify output file or directory
omnicaptions transcribe video.mp4 -o output/   # → output/video_GeminiUnd.md
omnicaptions transcribe video.mp4 -o my.md     # → my.md

# Options
omnicaptions transcribe -m gemini-3-pro-preview video.mp4
omnicaptions transcribe -l zh video.mp4  # Force Chinese

选项	说明
-k, --api-key	Gemini API 密钥（缺失时会自动提示输入）
-o, --output	输出文件或目录（默认：自动）
-m, --model	模型（默认：gemini-3-flash-preview）
-l, --language	强制指定语言（zh、en、ja）
-t, --translate LANG	翻译成指定语言（一步完成）
--bilingual	双语输出（与 -t 配合使用）
-v, --verbose	详细输出

双语字幕（可选）

如果用户需要双语输出，请添加 -t <lang> --bilingual：

omnicaptions transcribe video.mp4 -t zh --bilingual

如需精确控制时间，请使用单独的工作流：转录 → LaiCut → 翻译（参见相关技能）。

输出格式

## Table of Contents
* [00:00:00] Introduction
* [00:02:15] Main Topic

## [00:00:00] Introduction

**Host:** Welcome to the show. [00:00:01]

**Guest:** Thanks for having me. [00:00:05]

[Applause] [00:00:08]

主要特性：

• ## [HH:MM:SS] Title 章节标题
• **Speaker:** 说话人标签（自动检测）
• 段落末尾的 [HH:MM:SS] 时间戳
• 用于非语音内容（大笑、音乐）的 [Event]

常见错误

错误	解决方法
API 密钥错误	使用 -k YOUR_KEY 或按照提示操作
响应为空	检查文件格式（支持 mp3/mp4/wav/m4a）
上传超时	文件过大（超过 2GB）；请先拆分
语言错误	使用 -l en 强制指定语言

相关技能

技能	使用场景
/omnicaptions:convert	将输出转换为 SRT/VTT/ASS
/omnicaptions:translate	翻译（Gemini API 或 Claude 原生功能）
/omnicaptions:download	先下载视频/音频

工作流示例

# Basic transcription
omnicaptions transcribe video.mp4
# → video_GeminiUnd.md

# Precise timing needed: transcribe → LaiCut align → convert
omnicaptions transcribe video.mp4
omnicaptions LaiCut video.mp4 video_GeminiUnd.md
# → video_GeminiUnd_LaiCut.json
omnicaptions convert video_GeminiUnd_LaiCut.json -o video_GeminiUnd_LaiCut.srt

注意：翻译请使用 /omnicaptions:translate（默认：Claude，可选：Gemini API）