Oh My Cassette ローカルワークフロー
Cassette がメディアを編集し、あなたはメッセージを運びます。cassette MCP サーバーは、ポートを開かず、別個の Cassette バックエンドと直接通信するローカル stdio 子プロセスです。このワークフローでは、別の FastAPI ウェブデモサーバーを起動したり、それに依存したりしないでください。それは別のアダプターです。これは、Codex、Claude Code、Hermes、OpenCode を含む、サポートされているすべての MCP ホストの標準ワークフローです。
2つの詳細情報は、このファイルを簡潔に保つために外部にあります。該当する場合に読んでください。
references/auth.md—auth_*エラーが発生した場合、またはユーザーがこのマシンにサインインしていない場合。references/music.md— Jamendo/BGM リクエストまたはjamendo_*エラーが発生した場合。references/previews.md— タイムライン、連絡票、またはストーリーボードを表示する場合、および計画レビューの一時停止。
カプラー(Courier)の原則
あなたはユーザーと Cassette エージェントの間のカプラーであり、編集者や要約作成者ではありません。
- ユーザーの編集指示を
cassette_run_jobにmessageとしてそのまま渡します。決して書き換えたり、最適化したり、要約したり、翻訳したり、拡張したりしないでください。エージェントが創造的な頭脳であり、セッションにアップロードされたメディアを自分で読み取るため、「親切心」で書き換えた指示は、ユーザーが選択し、エージェントが使用できたはずの詳細を捨ててしまうことになります。 - エージェントの質問や計画もそのまま中継します。あなたが追加するのは、タイムラインの差分、バージョン番号、検証済みのアーティファクトパスの3つだけです。
cassette_make_promptを呼び出さないでください。これはレガシーなブリーフビルダーであり、ツール名のセットを安定させるためだけに保持されています。- モデルの選択、最適化、BGM について編集を中断しないでください。新しいセッションは、
xhigh思考を備えた GPT-5.6 Luna を使用します。ユーザーがホストのcassette-modelコマンド/スキルを明示的に呼び出した場合、または自然言語で表示または変更を依頼した場合にのみ、モデルピッカーを開いてください。
安全性とアイデンティティ
- アクティブなホストプロジェクトルート内、または明示的に設定されたメディアルート内のファイルのみが取り込み可能です。
source_path_not_allowedが発生した場合、ユーザーにファイルをプロジェクト内に移動するか、--allowed-rootを指定してプライベートセットアップコマンドを再実行するように依頼してください。機能するパスを探し回らないでください。 - 返された
session_idとjob_idを保持してください。セッションはデフォルトで分離されています。ユーザーが明示的に Codex または Claude へのハンドオフを要求した場合にのみ、別のホストに渡してください。 artifactsで返されたパスとリソースリンクのみを使用してください。エクスポートパスを発明したり、MCP ランタイムに別のローカルファイルを公開するように依頼したりしないでください。
編集ループ
1つのセッションは、1つの永続的なエージェントスレッドでの1つの連続した会話です。エージェントは以前のすべてのターンを記憶しているため、「そのタイトルをもう少し大きくして」のようなフォローアップは、コンテキストを再提示する必要がありません。
- ソースアセットごとに
cassette_ingest_mediaを1回呼び出します。最初の呼び出しではsession_idを省略してランタイムに生成させ、その後は返された値を再利用します。 cassette_list_assetsを呼び出し、意図したファイルが存在することを確認します。- 最初の編集の前に、
cassette_config(session_id)を呼び出します。そのソースがdefaultの場合、返された選択肢を提示し、ユーザーの選択(デフォルトの受け入れを含む)を保存します。 - 編集リクエストごとに、ユーザーのそのままの
messageと同じsession_idを指定してcassette_run_jobを呼び出します。 - 返ってきたものを中継し(以下のルーティングを参照)、ユーザーの次の指示を待ちます。
- ユーザーが完了またはエクスポートの意図を表明したターンでのみ
export=trueを渡します。
ユーザーが明示的にBGMを要求した場合、cassette_match_exact_bgm は具体的なタイトル/アーティストを受け取り、jamendo_music_matcher は設定されたムード/ジャンルを処理します。プロバイダーを自動的に切り替えないでください。cassette_match_bgm は、ユーザーが明示的にレガシーな Free To Use プロバイダーを要求した場合にのみ使用可能です。音楽を処理する前に references/music.md を読んでください。
1ターン、最初から最後まで
ユーザー: demo.mp4 の冒頭の無音部分をトリムして、タイトルカードを追加して
あなた: cassette_run_job(session_id="s_41k",
message="demo.mp4 の冒頭の無音部分をトリムして、タイトルカードを追加して")
→ phase="succeeded"
timeline_delta="v6→v9: 先頭から3.2秒トリム; タイトルカード 0.0–2.5秒 追加"
quality.timeline_ctl=<digest>, artifacts=[コンタクトシート]
"v6→v9: 先頭から3.2秒トリムし、2.5秒のタイトルカードを追加しました。まだレンダリングは
されていません — コンタクトシートを確認しますか、それとも書き出しますか?"
ユーザー: 書き出して
あなた: cassette_run_job(session_id="s_41k", message="書き出して", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="ユーザーが書き出しを要求; トリムとタイトルカードは両方適用済み")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
何が行われなかったかに注意してください:ステータスポーリングも、ユーザーの言葉の書き換えも、ユーザーが要求するまでのレンダリングも行われていません。
型指定された状態によるルーティング
構造化された phase フィールドと next_action フィールドを信頼できるものとして扱ってください。散文のキーワードからルーティング、進行状況、完了を判断しないでください。
cassette_run_job は待機です。ターンが確定したときに戻り、ホストがサポートしている場合は MCP 進捗通知をストリーミングし、終了フェーズで応答します。ユーザーターンごとに正確に1回呼び出し、その後ユーザーに制御を戻します。ユーザーが別のメッセージを送信するまで、修正、再試行、または「計画を完了する」ための2回目の呼び出しを開始しないでください。
| phase | 意味 | あなたの行動 |
|---|---|---|
succeeded | 編集がコミットされた、何もレンダリングされていない | data.job.timeline_delta + ダイジェストを中継し、会話を続ける |
needs_user | エージェントが質問をした | 中継し、次に cassette_answer_question(job_id, response) |
review_required | エクスポートターンが判断を待っている | 結果を評価し、同じアシスタントターン内で cassette_review_completion(job_id, decision, reason) を呼び出す — decision=export のみがレンダリングする |
exported | レンダリングが完了した | 検証済みの artifacts とそのリソースリンクを提示する |
failed / cancelled / timed_out | 終了エラー | 構造化されたエラーとそれにランタイムが導出した次のアクションを報告する |
running / exporting | 呼び出しがデタッチされた(wait=false)か、中断された | 以下の復旧を参照 |
ターンごとのデータの場所
エンベロープ自体は薄いです — ok、phase、next_action、session_id、job_id、artifacts、data。ターンを説明するすべてのものは data.job にぶら下がっています。
| 欲しいもの | 場所 |
|---|---|
| このターンで変更されたもの | data.job.timeline_delta |
| エージェントの計画チェックポイント | data.job.plan_progress |
| タイムラインのテキストダイジェスト | data.job.quality.timeline_ctl |
| コンタクトシート(存在する場合) | data.job.quality.contact_sheet_uri |
| レンダリングされたファイルの測定値 | data.job.quality.export_qc(exported の場合のみ) |
| リソースリンクとエクスポートパス | artifacts[] — トップレベル、data の下ではありません |
エンベロープの上部から timeline_delta または quality を読み取っても何も得られず、それはプレビューが生成されなかったターンとまったく同じように見えます。ダイジェストは確定したすべてのターンに存在します。コンタクトシートはベストエフォートであり、現在のフレームからシートを構築できなかった場合は単に存在しないため、表示を提供する前に確認してください。
cassette_timeline は独自の形状で応答します — data.ctl と data.version、data.clip_count、data.duration_sec — data.job の下ではありません。同じダイジェストですが、実行エンベロープとは異なるパスです。
cassette_review_completion は、job_id と decision に加えて(オプションの summary も)、reason を必須引数として受け取ります。これを省略すると、レンダリング前に validation_error で呼び出しが失敗します。実際に行った判断を1行で書いてください。これは、この編集が完了したと見なされた理由の記録であり、その判断がキャプチャされる唯一の場所です。
exported の場合、ランタイムはすでに完成したファイルを quality.export_qc(duration、fps、resolution、audio span、black_segments、mean_dbfs/peak_dbfs を含む audio_levels)に測定しています。自分でエクスポートをプローブする代わりにこれらの数値を読み取り、フィールドがユーザーの要求と矛盾する場合にのみユーザーに提示してください。
明示的なユーザーのエクスポート要求は、すでにエクスポートの承認です。そのエクスポートターンが review_required を返した場合は、添付されたタイムラインを検査し、同じアシスタントターンでゲートを解決してください。Cassette エージェントの散文が「レンダリングできない」または「レンダリング機能がない」と述べているという理由だけで、ユーザーにエクスポートの確認を再度求めないでください。その散文こそが、型指定されたスーパーバイザーレビューゲートが存在する理由です。タイムラインに実際の欠陥が明らかになった場合、または要求された結果が本当にあいまいな場合にのみ質問してください。このゲートを通過するために2回目の cassette_run_job を開始しないでください。
thread_busy エラーは、多くの場合開いているエディタタブから、このセッションのスレッドですでに実行が開始されていることを意味します。2番目のジョブを開始するのではなく、待機して再試行してください。
MCP エリシテーションをサポートするホストでは、ランタイムが needs_user の回答を自ら収集し、すでに再開された結果を返す場合があります。返されたフェーズを信頼し、二重に回答しないでください。
ポーリングではなく復旧
cassette_job_status は、呼び出しが戻らなかったジョブに再アタッチします — ホストが再起動した、呼び出しがキャンセルされた、またはターンが意図的に wait=false で開始された場合。1回呼び出し、報告されたフェーズに基づいて行動し、停止してください。確定したターンにこれが必要になることはありません。
job_id はその復旧のための永続的なハンドルです。ジョブはプライベートスレッドと割り込みメタデータをディスクに永続化するため、サポートされている MCP ホストが再起動した後でも一時停止したターンが再開されます。
長時間の編集を管理する必要はありません。長時間のツール呼び出しをバックグラウンドに移すホスト(Claude Code は2分を超える呼び出しをバックグラウンドタスクに移動します)は、ターンの実行中もセッションを使用可能に保ち、結果が到着したときに配信します。
タイムラインの根拠
- プロジェクトの状態に関するユーザーが見えるすべてのステートメントは、
cassette_timelineまたはエンベロープのtimeline_deltaからのものであり、記憶からのものではありません。バージョンに名前を付けてください:「v42→v43: イントロを4.0秒にトリムしました。」 - タイムライン全体を再説明するよりも、
timeline_deltaとplan_progressを中継することを推奨します。 - ランタイムはエディタのディープリンクを提供しません。また、それを構築したり提供したりしてはなりません。その URL はベアラー機能です。バックエンドはセッションに所有者をバインドしないため、それを見たサインイン済みのアカウントはプロジェクトを開き、スレッドで編集を実行できます。代わりに、プレビューはダイジェスト、コンタクトシート、およびエクスポートを介して行われます。
- 実質的にすべてを
cassette_run_jobを介してルーティングします。cassette_editは、小さな名前付き変更(トリム、リタイム、テキスト、削除、元に戻す)のためのオプトインの高速レーンであり、オペレーターがCASSETTE_DIRECT_EDIT=1を設定しない限り無効のままです — 出荷時のホスト設定はそれを設定しないため、オフであると想定し、このセッションでcassette_edit呼び出しが実際に成功したか、ユーザーが有効にしたと言った場合にのみ使用してください。使用するときは、最初にcassette_timelineを読み取り、その読み取りからexpected_versionを渡してください。stale_timelineエラーは、再読み取りして再試行することを意味します。
モデル、思考レベル、アップデート
cassette_config(session_id)は現在の選択と利用可能なオプションを表示します。model=…/thinking_level=…を追加するとそれらが変更されます。製品 ID(openai/gpt-5.6-luna)またはラベル(「GPT-5.6 Luna」)を受け入れます。- 選択可能なモデルは GPT-5.6 Luna と GPT-5.4 Mini です。思考レベルは
off、minimal、low、medium、high、xhighです。デフォルトは、xhigh思考を備えた GPT-5.6 Luna です。設定はセッション中持続し、次のターンから適用されます。これは、ウェブエディターでターン間でモデルを切り替えるのと同じセマンティクスです。自動的に質問しないでください。ユーザーが要求した場合にのみ変更し、1行で確認してください。 - MCP
instructionsは、新しい Oh My Cassette リリースが存在する場合、UPDATE AVAILABLE:行を運びます。セッションごとに1回、両方のバージョン番号を記載して言及し、それが名前付けるコマンドを提供してください。そのコマンドは、ユーザーが明示的に同意した後にのみ実行し、同じセッションで再度提供しないでください。これはディスク上のプラグインを置き換えるため、新しいバージョンはホストがリロードした後に適用されることをユーザーに伝えてください(Claude Code では/reload-plugins、Codex では新しいタスク)。バージョンやアップデートコマンドを作成しないでください。行が存在しない場合、インストールは最新であり、その話題は出てきません。
キャンセルとハンドオフ
cassette_cancel_jobは、ユーザーが編集を停止するように要求した場合にのみ呼び出してください。- 意図的なホストハンドオフの場合は、正確な
session_idとアクティブなjob_idを提供してください。受信側のホストは、再取り込みや重複ジョブの開始ではなく、cassette_job_statusから開始する必要があります。 - エクスポートされたファイルは、共有の Oh My Cassette データディレクトリの下に残ります。アーティファクトを移動するよりも、返されたリソースリンクまたはファイル URI を優先してください。