audify

audify

読みやすいリソースをナレーション向けの文章に整え、Gemini 3.1 Flash TTS で音声を合成し、MP3、整形済みの文字起こし、マニフェストを含むタイムスタンプ付きの出力フォルダーを書き出します。

2026年4月15日更新の Gemini API 音声生成ドキュメントと、2026年4月16日公開の Google Cloud ブログ記事に照らして検証済みです。

判断フロー

どのような種類の入力を扱っていますか？

• 聞き取りたい URL、Markdown ファイル、HTML ファイル、DOCX、プレーンテキストファイル、または生テキスト

  • python3 scripts/audify.py ... を実行します。

• 主にコード、ログ、表、圧縮された JSON、その他ナレーションを想定していないコンテンツで構成されるリソース

  • TTS を無理に適用せず、処理を中止します。ナレーションに適さない理由を説明します。

• 声やニュアンスに実質的な曖昧さがある依頼

  • 合成する前に、短い質問を 1 つします。
  • 次の文を使います。「どの声と話し方にしますか？ 特に希望がなければ、Kore を使って、明瞭でニュートラルなナレーションにします。」

• スタイルの詳細にこだわらない依頼

  • Kore と、明瞭でニュートラルなニュアンスをデフォルトにします。

• 複数のチャンクに分かれる、または整形済みの文字起こしが大量にある長時間の処理

  • 複数チャンクの TTS には数分かかることがあり、処理中に何も起きていないように見える時間があることを、あらかじめユーザーに伝えます。
  • 短いポーリングのたびに説明を繰り返さないでください。先に見通しを 1 回伝えたら、チャンクの進捗または完了を待ちます。

• GEMINI_API_KEY がない、gemini-3.1-flash-tts-preview が利用できない、ffmpeg がない、または読み込み試行が上限に達した場合

  • 前提条件のうち、具体的に満たされていないものを示して処理を中止します。

クイックリファレンス

タスク	コマンド	参照先
URL から MP3 バンドルを作成	python3 scripts/audify.py "https://example.com/"	references/patterns.md
ローカルファイルから MP3 バンドルを作成	python3 scripts/audify.py --file templates/sample-input.md --voice Kore --nuance "Warm documentary narrator"	references/patterns.md
標準入力から生テキストを読み込む	cat templates/sample-input.md | python3 scripts/audify.py --stdin	references/patterns.md
整形のみの適性チェック	python3 scripts/audify.py --url "https://example.com/" --check-only	references/patterns.md
モデルと合成のライブプローブ	python3 scripts/probe_gemini_tts.py --mode all	references/api.md

参照ガイド

ユーザーが必要としている情報	参照先
Gemini REST の基本形式、対応モデル、音声、エラーコード	references/api.md
環境変数、キーの設定、ffmpeg、前提条件のチェック	references/configuration.md
URL／ファイル／テキストのワークフロー、出力バンドルの構成、質問のルール	references/patterns.md
エラー処理、再試行、audify が処理を中止する理由	references/gotchas.md

運用ルール

1. SKILL.mdをエントリーポイントとして扱い、使用するツールを絞ります。本番実行にはscripts/audify.py、ライブ検証にはscripts/probe_gemini_tts.pyを使用します。
2. まずクリーンアップし、その後に音声を合成します。TTS の前にマークアップ、HTML、コードフェンス、URL のみの行を取り除き、読み上げるテキストが転送形式ではなく、読みやすいテキストにできるだけ近くなるようにします。
3. 可能な限り、人が書いたテキストを保持します。表示されるアンカーテキスト、見出し、段落の内容、インラインの文章は残し、読み上げるものではなく構造上のものにすぎない定型文は削除します。
4. ソースが読み上げに適していない場合は中止します。コードの羅列、ログ、スタックトレース、生の表、バイナリデータは、テキストとしてデコードできたというだけで読み上げないでください。
5. 読み取りを試みても取得できない場合は中止します。取得失敗やデコードできないファイルから、幻覚による要約を作って黙って代用しないでください。
6. 長時間の実行前に、所要時間の目安を伝えます。複数チャンクの TTS では、「通常は2～6分ほどかかります」など現実的な範囲と、チャンクの完了通知の間に無音状態が続くのは正常であることをユーザーに伝えてください。
7. ポーリングによる進捗報告でユーザーに何度も通知しないでください。最初に所要時間の目安を伝えた後は、チャンクの進捗、再試行、最終完了など、意味のある状態変化のみを報告してください。
8. 一時的に失敗する大きなチャンクは、諦める前に自動的に分割します。チャンク境界を小さくして再試行する際も、同じ音声、ニュアンス、モデル、出力形式を維持してください。

出力仕様

デフォルトでは、scripts/audify.pyは現在の作業ディレクトリの下にaudify-output/<timestamp>-<slug>/を作成します。

フォルダーには次のものが含まれます。

• デフォルトのaudio.mp3
• 最終的に読み上げるテキストを含むcleaned.txt
• ソース、音声、ニュアンス、チャンク分割、再試行のメタデータを含むmanifest.json
• ラッパーの出力 JSON とステータスストリームの両方に含まれる実行時間の目安
• 大きなチャンクを小さく分割して再試行した場合の、代替チャンク分割メタデータ

MP3 への変換が不要な場合は、--format wavを使用します。

注意事項

1. Gemini TTS が返すのは MP3 ではなく PCM です：Gemini API は base64 エンコードされた PCM 音声を返します。このスキルではffmpegを使ってローカルで変換するため、デフォルトの MP3 出力ではffmpegがないと処理を続行できません。
2. Gemini 3.1 Flash TTS で一時的な500エラーが発生することがあります：Google のドキュメントによると、まれにモデルが音声トークンではなくテキストトークンを出力することがあります。ラッパーはバックオフを行い、一時的な失敗を再試行します。
3. 曖昧なプロンプトは拒否されたり、そのまま読み上げられたりすることがあります：ラッパーでは「音声のみを合成する」という明示的な前置きと、ラベル付きのTRANSCRIPTセクションを使用し、指示がナレーションにならないようにしています。
4. 音声とプロンプトが食い違うことがあります：Google は、話者の特徴が大きく食い違うと不自然に聞こえる可能性があると警告しています。ユーザーが非常に具体的なペルソナを求める場合は、選択した音声とニュアンスが同じ方向性になるようにしてください。
5. HTML の抽出は可能な範囲で行います：ページが雑然としていると、ブログの装飾部分、ナビゲーションのテキスト、法的事項のフッターテキストなどが残る場合があります。クリーンアップ後のプレビューに問題がある場合は中止し、対象を絞ったソースを依頼してください。
6. 長い無音状態は必ずしも失敗ではありません：複数チャンクの実行では、Gemini の呼び出しとローカルでの MP3 変換に数分かかることがあります。30秒間静かな状態が続くたびに問題と判断しないでください。
7. 大きなチャンク1つでも、一時的に失敗することがあります：その場合、ラッパーは失敗したチャンクだけを小さく分割し、同じ音声、ニュアンス、モデル、形式のまま処理を続け、最初から手動で再実行する必要がないようにします。

ヘルパースクリプト

• scripts/audify.pyは、URL、ファイル、標準入力、生テキストを入力として扱う本番用ラッパーです。
• scripts/probe_gemini_tts.pyは、モデルの検出と短い音声合成に対して安全なライブプローブを実行します。
• scripts/test_audify_unit.pyは、クリーナー、チャンク分割、DOCX 抽出、中止ヒューリスティクスをテストします。
• scripts/validate.pyは、構造、相互参照、残存するテンプレートのプレースホルダーをチェックします。
• scripts/test_skill.pyは、構造チェック、ユニットテスト、およびGEMINI_API_KEYが設定されている場合のライブスモークプローブを実行します。