/srt
このスキルは、Perso AI STT API を介して、動画・音声のソース言語の字幕を抽出し、その後、あなた(エージェント)が リクエストされた言語に翻訳します。
核となるルール(必ず従うこと)
- ワーカーだけが生のキーを見ることができます。
Readでキーを開いたり、エコーしたり、コマンドライン引数として渡したりしないでください。ワーカーはXP-API-KEYヘッダーでのみキーを送信します。 - 1つのコマンド = 抽出全体。
scripts/srt.mjsが、アップロード・文字起こし・SRTダウンロードを単独で処理します。 - 常に
srt.mjsをバックグラウンドで実行します。 文字起こしには数分かかります。フォアグラウンドのシェルでタイムアウトすると、処理が途中で終了します。 - 言語が指定されていない場合 →
enをターゲットにします。 - 文字起こしのみ、翻訳なし(ユーザーが「字幕/トランスクリプトそのまま」、「オリジナル言語のSRTだけ」を要求した場合)→
--transcribe-onlyを--targetの代わりに使用して実行します。ダウンロードされたオリジナルSRTが最終的な成果物です。Translateセクションは完全にスキップします。 - 複数の言語は1つのコマンドで指定します(
--target en,ja)。入力ファイルごとに1つの字幕プロジェクトが作成され、その単一のオリジナルSRTを指定された各言語に翻訳します。 - 進捗を忠実に中継します。 ワーカーの標準出力の
[progress]行を、そのまま、または要約してチャットに表示します。インデントされた標準エラーの詳細ログは中継する必要はありません。バッチ処理の場合、ワーカーは入力ごとに[progress]行をストリームし、[status]ハートビート(subtitles 3/20、next check ~Nmのヒント付き)を出力します。起動から約3分後にバックグラウンド出力を確認し、その後はヒントされた間隔で確認し、新しい行を中継します。パーセンテージやETAをでっち上げないでください。 - テレメトリ用に自身のランタイムを(静かに)指定します。 ワーカーコマンドに
--host <claude-code|codex|cursor|antigravity|gemini>を追加し、自身が動作しているエージェントを指定します(わかる場合)。これは使用状況テレメトリにタグを付けるだけです。ユーザーに表示したり、尋ねたりしないでください。不明な場合は省略します。 - サポートされていないフォーマットは自動的にスキップされ、残りの処理は続行されます。スキップ通知を中継します。
- オフライン操作ではキーは一切不要です。キーチェックや登録を実行しないでください:
srt.mjs --check/--retime、ローカル動画+SRTを使用するstyle.mjs(--project以外はすべて)、ユーザーから直接渡されたSRTの翻訳。 - このスキルは、吹き替えスキルのライブラリを共有しています。
dubbingフォルダはsrtの隣にインストールされている必要があります(すべてのインストール方法で一緒に配布されます。srtフォルダのみを手動でコピーすると、これが壊れます)。
セットアップ(遅延方式 - 事前手順なし)
/dubbing と同じです。キー登録は、最初に実行する手順ではありません。 ワーカーは、Perso API を必要とするコマンド(抽出、または style.mjs --project)が実行された瞬間に自動的にゲートをかけ、ブラウザフロー(ファイルフォールバック)を開き、その時点で印刷された指示を中継します。ヘッドレス/SSHマシンでは、ブラウザフローをスキップし、ファイル/--import 登録を自動的に開始します。キーチェックや登録を積極的に実行しないでください。キーをチャットに貼り付けないでください。
実行
入力(ローカルパスまたはURL。不足している場合は再確認)を収集し、バックグラウンドで(ワーカーは抽出が実際に開始されるときに自身でキーをゲートします)実行します。
- 単一:
node scripts/srt.mjs "<file|URL>" [--target en] [--space "space name"] [--out folder] - 複数言語 / 複数入力:
node scripts/srt.mjs "<URL>" "<file>" --target en,ja - フォルダ(バッチ):
node scripts/srt.mjs "<folder>" [--target en] [--recursive] [--out folder] - 文字起こしのみ(翻訳なし):
node scripts/srt.mjs "<file|URL>" --transcribe-only
抽出されたオリジナルSRTファイルは、各ソースファイルの隣(または --out で指定されたフォルダ内)に、サーバーのファイル名(…_OriginalSubtitle_….srt)で保存されます。
保存場所 — /dubbing と同じポリシー:デフォルトは各ソースファイルの隣です。尋ねないでください。セッションの最初のジョブで、開始行にそれを明記し、すぐに開始します。このセッションで以前にユーザーが指定したフォルダは、変更されるまで適用され続けます(--out "<folder>")。翻訳されたSRTは、元のSRTと同じフォルダに配置されます。例外:すべての入力がURLの場合、開始前に保存場所を尋ねます。
スペース選択 — 複数のワークスペースがある場合、ワーカーはアップロード前に停止し、[space-select] 行(名前 | (プラン) | 残りクレジット)を出力し、停止します。ユーザーにはそれらのオプションのみを表示し(内部番号は表示しない)、どれか尋ね、--space "<space name>" を付けて再実行します。吹き替え可能なスペースが1つだけの場合→質問なし。PERSO_SPACE_SEQ はそれを固定します。
プラン制限を超えるメディア — このスキルは自動分割を行いません。ワーカーがメディアがプランの長さ/サイズ制限を超えていると報告した場合、そのメッセージを中継します。ユーザーは自分でファイルを分割/トリミングするか、プランをアップグレードしてから再試行できます。Freeワークスペースの場合、そのメッセージは [free-limit] 行として表示されます(より短いファイルか、アップグレード。続行フラグはありません)。それらを中継して停止します。
Freeプラン(ローカル .srt なし) — Freeワークスペースは通常通り文字起こしを行いますが、サーバーはすべてのダウンロードを拒否するため、ローカルには何も保存されません。ワーカーは Free plan — <name>: subtitles ready on Perso → <link> (downloads need a paid plan) と出力し、[srt-original] 行は出力しません。ファイルがないため、翻訳するものはありません:Translateセクションを完全にスキップし、リンクを配信された結果として中継し(実行は完了です。失敗したものも、再開するものもありません)、ダウンロード可能な .srt ファイルには有料プランが必要であることを言及します。
クレジット — 各字幕プロジェクトは、メディアの長さに比例してクレジットを消費します(入力ごとに1プロジェクト)。サーバーの課金が信頼できるものであり、正確な価格を引用しないでください。
翻訳(あなたがこの部分を行います)
ユーザーが直接SRTを手渡した場合(STTなし): ワーカーステップはなく、[srt-original] 行もありません。渡されたSRTを path として、ユーザーが要求した言語を langs として扱い、以下の手順1〜5に従います。手順3の {stem} はSRTファイル名自体から導出します。完全にオフライン:--check/--retime のみ。キーもクレジットも不要。
抽出が完了すると、ワーカーは入力ごとに1行、すべてのターゲット言語を載せて出力します。
[srt-original] {"input":"video.mp4","langs":["en","ja"],"path":"C:\\clips\\video_OriginalSubtitle_2026-07-15.srt","seq":389259}
langs が null の場合(--transcribe-only 実行)、翻訳するものはありません。そのファイルをそのままユーザーに配信し、ここで停止します。
翻訳の進捗を表示します。 STT抽出は完了しましたが、各言語への翻訳にも時間がかかります。それを可視化します。開始する前に、作成する言語を記載した1行を投稿します(例:「字幕を抽出しました。現在、日本語と英語に翻訳しています。」)。各言語のファイルを保存した後、1行の更新を投稿します(例:「日本語 ✓ (1/2)」)。これにより、ユーザーは複数言語の吹き替えと同様の言語ごとの進捗を確認できます。長いファイルの場合、そのセクションをバッチ処理している間、1つの言語内でしばらく応答がない場合がありますが、それは問題ありません。
各 [srt-original] 行について、path にある1つのファイルを langs のすべての言語に翻訳します。
ステップ1 — まずファイル全体を読み、コンテキストを構築します。 何かを翻訳する前に、path にあるSRTを最初から最後まで読み、以下を特定します。
- コンテンツの種類(講義、チュートリアル、vlog、ドラマ、広告など)と対象者
- 話し手のトーンとレジスター(フォーマル / カジュアル / ユーモラス / テクニカル)— そして、それに合ったターゲット言語のスタイルを決定します。
- 繰り返し登場する名前や用語 — ファイル全体で、それぞれに一貫した翻訳を1つ使用します。
ステップ2 — langs の各言語に、セクションごとに翻訳します(長いファイルはバッチ処理しますが、ステップ1で決定したトーンと用語をすべてのバッチに適用します。ステップ1はファイルごとに1回実行され、言語ごとではありません)。
- テキスト行のみを翻訳します。 キュー番号、タイムスタンプ行(
-->)、空白行、キューの数はそのままにします。翻訳中にタイムスタンプを変更したり、キューをマージ/分割したりしないでください(リタイミングは別の後続パス、ステップ5です)。 - 各キューのテキストは、自身のキュー内に収めます。 STTは、文法ではなく発話の長さでソースをカットするため、キューが途中で終わることがよくあります。翻訳でその区切りをそのまま反映しないでください。すべてのキューを読みやすい単位で終了し、継続部分はコンマや続く文でつなぎます。話し手が本当に遮られたり中断されたりした場合にのみ、断片を残します。
- 意味とムードが最優先です:ステップ1のトーンを維持した自然な翻訳を、字義通りの翻訳よりも優先します。慣用句、言葉遊び、ユーモアは、ターゲット言語の同等の表現で表現します。
- レイアウト — 各キューは最大2行のテキスト、各行はラテン文字で最大42文字(CJKは20文字)。 それより長い行は、プレーヤーによって強制的に3行以上のオンスクリーン行に折り返され、画像を覆います。自然な句の切れ目で行を区切ります。テキストが収まらない場合は、以下の優先順位で短縮します。
- 各キューの表示時間内に収めます: 予算 ≈ キューの長さ × 17 chars/sec(ラテン文字、CJKは9)。約21/sec(CJKは13)を超えると、字幕は読まれる前に消えます。通常、自然な翻訳は収まるため、ほとんどのキューはトリミング不要です — あふれるものだけを短縮します。
- 短縮する必要がある場合は、次の優先順位を維持します: 意味 → トーン/ニュアンス → 長さ。まずフィラー、冗長性、繰り返しを削除します。核となる情報、決めゼリフ、感情的な表現は最後まで保持します。言葉遊びが本当に収まらない場合は、ユーモアを失わない、より短い行に置き換えます — それを平板な要約にしてしまうのは最終手段です。
ステップ3 — 保存: UTF-8、同じフォルダに、ファイルごとに {stem}_{lang}_Subtitle.srt という名前で保存します。ここで stem は、[srt-original] 行の input フィールドから取得した入力ファイルの拡張子を除いたファイル名です(例:"input":"video.mp4" + ["en","ja"] → video_en_Subtitle.srt と video_ja_Subtitle.srt。URL入力の場合は、メディアタイトルまたは短いスラッグを使用します)。ダウンロードされたファイル名からステムを導出しないでください。サーバーはプロジェクトタイトルからそれを構築します。オリジナルのSRTファイルは保持し、削除や上書きはしないでください。
ステップ4 — 保存した各ファイルを検証します(オフライン — キー、ネットワーク、クレジットは不要):
node scripts/srt.mjs --check "<translated.srt>" --source "<original .srt>"
[check] FAIL 行は、ファイルがキューアラインメント、2×42レイアウト、または読み取り速度の上限を破っていることを意味します。リストされたキューのみを(同じ意味優先の優先順位で)書き直し、保存し、FAILがなくなるまで再実行します。WARN行はオプションのポリッシュです。これをステップ5の前に実行します。リタイミング後は、キュー数が設計上ソースと一致しなくなります。
ステップ5 — 読みやすさのリタイミング(オフライン。配信するファイルごとに1回、チェック合格後):
node scripts/srt.mjs --retime "<translated.srt>"
これにより、速すぎるキューを後続の無音部分に延長し、短い隣接キューを1つの2行イベントにマージし(Netflixスタイル)、ファイルをその場で書き換えます。キュー番号が変わる場合があります。変更されていないオリジナルSRTは1:1のタイミングマップを保持します。その後:
- それでも速すぎるとリストされているキュー(本当に速い発話)のテキストを短縮します。
- コメディ/ドラマコンテンツについては、
[retime] merged行を確認します。マージが決めゼリフを早めに見せていたり、意図的に中断されたラインを完了させている場合は、マージ前の状態から元のタイミングでそれら2つのキューを復元します。
保存された翻訳済みファイルのパスをユーザーに報告し、オリジナルがそのまま保持されていることを伝えます。ユーザーがPersoで字幕プロジェクトを開きたい場合は、[srt-original] 行の seq からリンクを構築します:https://perso.ai/en/workspace/vt/stt/<seq>。
スタイル設定と字幕の書き込み(ハードサブ)
必要に応じて、scripts/style.mjs を使用して、動画にスタイル設定された字幕トラックを書き込むことができます(恒久的なハードサブ)。これはローカルのffmpegステップです。キーは不要、クレジットも不要です(ただし、Persoからソースをダウンロードする --project を除く)。ffmpeg が必要です。ない場合は、ユーザーにインストールするように伝えて停止します。
いつ提供するか(2つのエントリポイント):
- 翻訳後: SRTが配信されたら、スタイル設定された字幕を追加することを提案します。自然なユーザー向けの文言で、「書き込む/ハードサブ」とは言いません。複数の言語がある場合は、すべてか一部かを尋ねます。
- 直接リクエスト(動画 + SRTを手渡された場合): プリセット選択に直接進みます。
フロー:
- 最初に必ずプリセットを表示します。適用にスキップしないでください。 表示方法はサーフェスによって異なります。
- Claudeアプリ(またはインタラクティブウィジェットをレンダリングできる任意のサーフェス): プリセットギャラリーを表示します。プリセットごとにタイル表示され、ユーザーが選択できるようにします。Apply ボタンがあり、選択内容を生成リクエストとして送信します。そちらが推奨されます。
- CLI / Antigravity / Codex / インタラクティブレンダリングがないその他の場所(ユニバーサルフォールバック):
assets/style_presets.png(静的プレビュー)を添付し、テキストメニューのためにnode scripts/style.mjs --list-presetsを実行します。 どちらも同じプリセットから来ています。ショートフォーム(9:16)/ ロングフォーム(16:9)でグループ化します。ユーザーはプリセットを選択するか、任意のスタイルを説明できます(例:「黄色いテキスト、黒い輪郭、下部に配置」)。向き別にデフォルトを提案しますが(縦向き→ショートフォーム、横向き→ロングフォーム)、ユーザーに選択させます。ユーザーが選択または説明した後にのみ適用します。
- 適用します。 ワーカーをバックグラウンドで実行します(エンコードには時間がかかります)。
- Perso STTプロジェクトから:
node scripts/style.mjs --project <seq> --preset <id> [--out folder] - ローカルファイルから:
node scripts/style.mjs "<video>" "<subtitle.srt>" --preset <id> [--out folder] - 書き込むSRTがPerso STT抽出(
[srt-original]ファイルまたはその翻訳)から来た場合は、--origin persoを追加します。ユーザー自身が提供した字幕ファイルの場合は、省略します。テレメトリのみ — 出力は変わりません。 - カスタムスタイル: ユーザーの説明を、任意のベースプリセットに重ねるオーバーライドフラグにマッピングします —
--position center|lower|bottom|upper、--font、--fontsize、--primary RRGGBB、--outline RRGGBB、--outline-width、--box RRGGBB@opacity|none、--karaoke/--no-karaoke、--highlight RRGGBB、--uppercase、--bold/--no-bold(--helpを参照)。 - フォント:
--font "<name>"はインストールされたフォントを使用します。インストールされていない名前は、自動的に最も近いシステムフォントにフォールバックします(関連する場合は言及します)。ユーザー提供のフォントファイル(.ttf/.otf/.ttc)は、--font-file "<path>"として指定します。フォントファミリー名はファイル自体から読み取られます。 - 複数の言語: 同じ
--presetを使用して言語のSRTごとに1回実行し、--lang <code>を追加して出力が...
- Perso STTプロジェクトから:
…[翻訳のため省略]