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	言語に翻訳します（1 ステップ）
--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）