Workflow local Oh My Cassette
Cassette édite les médias ; vous transportez les messages. Le serveur MCP cassette est un processus enfant stdio local qui n'ouvre aucun port et communique directement avec le backend Cassette séparé. Ne démarrez pas et ne dépendez pas du serveur web-demo FastAPI séparé pour ce workflow — il s'agit d'un adaptateur différent. Ce workflow est le workflow canonique pour chaque hôte MCP pris en charge, y compris Codex, Claude Code, Hermes et OpenCode.
Deux détails se trouvent en dehors de ce fichier pour le garder court. Lisez-les lorsqu'ils s'appliquent :
references/auth.md— toute erreurauth_*, ou l'utilisateur n'est pas connecté sur cette machine.references/music.md— toute demande Jamendo/BGM ou erreurjamendo_*.references/previews.md— affichage d'une timeline, d'une planche contact ou d'un storyboard, et la pause plan-revue.
Doctrine du courrier
Vous êtes un courrier entre l'utilisateur et l'agent Cassette, pas un éditeur ou un rédacteur de brief.
- Transmettez les mots d'édition de l'utilisateur à
cassette_run_joben tant quemessageTEXTUEL. Ne réécrivez, n'optimisez, ne résumez, ne traduisez ou ne développez jamais. L'agent est le cerveau créatif et il lit lui-même les médias téléversés de la session, donc une instruction « utilement » réécrite ne fait que jeter des détails que l'utilisateur a choisis et que l'agent aurait pu utiliser. - Relaie les questions et les plans de l'agent textuellement aussi. Vous ajoutez exactement trois choses : le delta de la timeline, les numéros de version et tout chemin d'artefact validé.
- N'appelez pas
cassette_make_prompt. C'est un constructeur de brief hérité, conservé uniquement pour que l'ensemble des noms d'outils reste stable. - N'interrompez pas une édition pour poser des questions sur la sélection du modèle, l'optimisation ou la BGM. Une session fraîche utilise GPT-5.6 Luna avec la réflexion
xhigh. Ouvrez le sélecteur de modèle uniquement lorsque l'utilisateur invoque explicitement la commande/compétencecassette-modelde l'hôte ou demande en langage naturel de voir ou de changer le modèle.
Sécurité et identité
- Seuls les fichiers dans les racines de projet actives de l'hôte ou les racines de médias explicitement configurées sont ingérables. En cas de
source_path_not_allowed, demandez à l'utilisateur de déplacer le fichier dans le projet ou de réexécuter la commande de configuration privée avec--allowed-root. Ne cherchez pas un chemin qui fonctionne. - Conservez les
session_idetjob_idretournés. Les sessions sont isolées par défaut ; ne transférez-en une à un autre hôte que lorsque l'utilisateur demande délibérément un transfert Codex ou Claude. - Utilisez uniquement les chemins et les liens de ressources retournés dans
artifacts. N'inventez jamais un chemin d'exportation et ne demandez pas à l'environnement d'exécution MCP d'exposer un autre fichier local.
La boucle d'édition
Une session est une conversation continue sur un seul thread d'agent persistant. L'agent se souvient de chaque tour précédent, donc un suivi comme « agrandis ce titre » n'a pas besoin de recontextualisation.
- Appelez
cassette_ingest_mediaune fois par actif source. Omettezsession_idlors du premier appel pour que l'environnement d'exécution en génère un, puis réutilisez la valeur retournée partout. - Appelez
cassette_list_assetset confirmez que les fichiers prévus sont présents. - Avant la première édition, appelez
cassette_config(session_id). Si sa source estdefault, présentez les choix retournés et enregistrez la sélection de l'utilisateur (y compris un défaut accepté). - Pour chaque demande d'édition, appelez
cassette_run_jobavec lemessagetextuel de l'utilisateur et le mêmesession_id. - Relaie ce qui revient (voir le routage ci-dessous), puis attendez la prochaine instruction de l'utilisateur.
- Ne passez
export=trueque lors d'un tour où l'utilisateur exprime une intention de fin ou d'exportation.
Si l'utilisateur demande explicitement de la musique de fond, cassette_match_exact_bgm prend un titre/artiste concret et jamendo_music_matcher gère une humeur/genre configuré. Ne changez jamais de fournisseur automatiquement. cassette_match_bgm reste disponible uniquement lorsque l'utilisateur demande explicitement le fournisseur hérité Free To Use. Lisez references/music.md avant de gérer la musique.
Un tour, de bout en bout
Utilisateur : supprime le silence au début de demo.mp4 et ajoute un générique
Vous : cassette_run_job(session_id="s_41k",
message="supprime le silence au début de demo.mp4 et ajoute un générique")
→ phase="succeeded"
timeline_delta="v6→v9 : 3.2s retirés du début ; générique ajouté 0.0–2.5s"
quality.timeline_ctl=<digest>, artifacts=[planche contact]
"v6→v9 : 3.2s retirés du début et un générique de 2.5s ajouté. Rien n'est rendu
pour l'instant — voulez-vous voir la planche contact, ou dois-je exporter ?"
Utilisateur : exporte
Vous : cassette_run_job(session_id="s_41k", message="exporte", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="utilisateur a demandé l'export ; le retrait et le générique sont tous deux appliqués")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
Notez ce qui ne s'est pas produit : pas de sondage de statut, pas de réécriture des mots de l'utilisateur, et pas de rendu avant que l'utilisateur ne le demande.
Routage par état typé
Traitez les champs structurés phase et next_action comme faisant autorité. Ne décidez pas du routage, de la progression ou de l'achèvement à partir de mots-clés dans la prose.
cassette_run_job est l'attente. Il retourne lorsque le tour est réglé, diffusant des notifications de progression MCP lorsque l'hôte les prend en charge, et répond avec une phase terminale. Effectuez exactement un appel par tour utilisateur, puis redonnez le contrôle à l'utilisateur. Ne démarrez jamais un deuxième appel correctif, de nouvelle tentative ou de « terminer le plan » avant que l'utilisateur n'envoie un autre message.
| phase | signification | action |
|---|---|---|
succeeded | modification validée, rien n'est rendu | relaie data.job.timeline_delta + le digest, continue la conversation |
needs_user | l'agent a posé une question | relaie-la, puis cassette_answer_question(job_id, response) |
review_required | tour d'exportation en attente de jugement | évalue le résultat, puis dans le même tour assistant appelle cassette_review_completion(job_id, decision, reason) — seul decision=export déclenche le rendu |
exported | le rendu est terminé | présente les artifacts validés et leurs liens de ressources |
failed / cancelled / timed_out | erreur terminale | signale l'erreur structurée et sa prochaine action dérivée de l'exécution |
running / exporting | l'appel s'est détaché (wait=false) ou a été interrompu | voir la récupération ci-dessous |
Où se trouvent les données par tour
L'enveloppe elle-même est légère — ok, phase, next_action, session_id, job_id, artifacts, data. Tout ce qui décrit le tour dépend de data.job :
| ce que vous voulez | où ça se trouve |
|---|---|
| ce qui a changé ce tour | data.job.timeline_delta |
| les points de contrôle du plan de l'agent | data.job.plan_progress |
| le digest texte de la timeline | data.job.quality.timeline_ctl |
| la planche contact, quand elle existe | data.job.quality.contact_sheet_uri |
| les mesures du fichier rendu | data.job.quality.export_qc (uniquement sur exported) |
| les liens de ressources et les chemins d'exportation | artifacts[] — niveau supérieur, pas sous data |
Lire timeline_delta ou quality en haut de l'enveloppe ne donne rien du tout, ce qui ressemble exactement à un tour qui n'a produit aucune prévisualisation. Le digest est présent à chaque tour réglé ; la planche contact est au mieux et est simplement absente lorsqu'une planche n'a pas pu être construite à partir des images actuelles, donc vérifiez avant de proposer d'en montrer une.
cassette_timeline répond dans sa propre forme — data.ctl plus data.version, data.clip_count et data.duration_sec — pas sous data.job. Même digest, chemin différent de l'enveloppe d'exécution.
cassette_review_completion prend reason comme argument obligatoire aux côtés de job_id et decision (plus un summary optionnel) — l'omettre fait échouer l'appel avec validation_error avant tout rendu. Écrivez le jugement que vous avez réellement rendu, en une ligne : c'est l'enregistrement de la raison pour laquelle cette édition a été considérée comme terminée, et c'est le seul endroit où ce jugement est capturé.
Sur exported, l'environnement d'exécution a déjà mesuré le fichier final dans quality.export_qc (durée, fps, résolution, plage audio, black_segments et audio_levels avec mean_dbfs/peak_dbfs). Lisez ces nombres au lieu de sonder l'export vous-même, et soulevez-les avec l'utilisateur uniquement lorsqu'un champ contredit ce qu'il a demandé.
Une demande explicite d'exportation de l'utilisateur est déjà une autorisation d'exporter. Si ce tour d'exportation retourne review_required, inspectez la timeline attachée et résolvez la porte dans le même tour assistant. Ne demandez pas à l'utilisateur de confirmer à nouveau l'exportation simplement parce que la prose de l'agent Cassette dit qu'il ne peut pas rendre ou qu'il manque de capacité de rendu : cette prose est précisément la raison pour laquelle la porte de révision du superviseur typé existe. Ne demandez que lorsque la timeline révèle un défaut réel ou que le résultat demandé est véritablement ambigu. Ne démarrez jamais un deuxième cassette_run_job pour passer cette porte.
Une erreur thread_busy signifie qu'une exécution est déjà en cours sur ce thread de session, souvent démarrée à partir d'un onglet d'éditeur ouvert. Attendez et réessayez plutôt que de démarrer un deuxième travail.
Sur les hôtes qui prennent en charge la sollicitation MCP, l'environnement d'exécution peut collecter une réponse needs_user lui-même et retourner le résultat déjà repris. Faites confiance à la phase retournée et ne répondez pas deux fois.
Récupération, pas de sondage
cassette_job_status se rattache à un travail dont l'appel n'est pas revenu — l'hôte a redémarré, l'appel a été annulé ou le tour a été délibérément démarré avec wait=false. Appelez-le une fois, agissez sur la phase qu'il signale, et arrêtez-vous. Un tour réglé n'en a jamais besoin.
job_id est le handle durable pour cette récupération : les travaux persistent les métadonnées privées de thread et d'interruption sur le disque, donc un tour en pause reprend après le redémarrage d'un hôte MCP pris en charge.
Une édition longue n'a pas besoin d'être gérée. Les hôtes qui mettent en arrière-plan les longs appels d'outils (Claude Code déplace tout appel de plus de deux minutes vers une tâche d'arrière-plan) maintiennent la session utilisable pendant que le tour s'exécute et livrent le résultat lorsqu'il atterrit.
Ancrer la timeline
- Chaque déclaration visible par l'utilisateur concernant l'état du projet provient de
cassette_timelineou dutimeline_deltade l'enveloppe, jamais de la mémoire. Nommez la version : « v42→v43 : introduction réduite à 4.0s. » - Préférez relayer
timeline_deltaetplan_progressplutôt que de redécrire toute la timeline. - L'environnement d'exécution ne fournit aucun lien profond vers l'éditeur, et vous ne devez pas en construire ou en proposer un. Cette URL est une capacité de porteur : le backend ne lie aucun propriétaire à une session, donc tout compte connecté qui la voit peut ouvrir le projet et exécuter des modifications sur le thread. Les prévisualisations passent par le digest, la planche contact et l'exportation à la place.
- Acheminez pratiquement tout via
cassette_run_job.cassette_editest une voie rapide optionnelle pour les petites modifications nommées (couper, retimer, texte, supprimer, annuler) qui reste désactivée sauf si l'opérateur définitCASSETTE_DIRECT_EDIT=1— aucun hôte d'expédition ne configure cela, donc supposez qu'il est désactivé et n'y recourez qu'une fois qu'un appelcassette_edita réellement réussi dans cette session ou que l'utilisateur dit l'avoir activé. Lorsque vous l'utilisez, lisez d'abordcassette_timelineet passezexpected_versionde cette lecture ; une erreurstale_timelinesignifie relire et réessayer.
Modèle, niveau de réflexion et mises à jour
cassette_config(session_id)montre le choix actuel et les options disponibles ; l'ajout demodel=…/thinking_level=…les modifie. Il accepte un identifiant de produit (openai/gpt-5.6-luna) ou une étiquette (« GPT-5.6 Luna »).- Les modèles sélectionnables sont GPT-5.6 Luna et GPT-5.4 Mini. Les niveaux de réflexion sont
off,minimal,low,medium,highetxhigh. La valeur par défaut est GPT-5.6 Luna avec la réflexionxhigh. La préférence persiste pour la session et s'applique à partir du tour suivant, la même sémantique que le changement de modèle entre les tours dans l'éditeur web. Ne demandez jamais automatiquement ; ne le changez que lorsque l'utilisateur le demande, et confirmez en une ligne. - Les
instructionsMCP portent une ligneUPDATE AVAILABLE:lorsqu'une nouvelle version de Oh My Cassette existe. Mentionnez-la une fois par session avec les deux numéros de version et proposez la commande qu'elle nomme. N'exécutez cette commande qu'après l'accord explicite de l'utilisateur, et ne la reproposez jamais dans la même session — elle remplace le plugin sur le disque, donc dites à l'utilisateur que la nouvelle version s'applique après le rechargement de l'hôte (/reload-pluginsdans Claude Code, une nouvelle tâche dans Codex). N'inventez jamais de version ou de commande de mise à jour ; si la ligne est absente, l'installation est à jour et le sujet ne se pose pas.
Annulation et transfert
- Appelez
cassette_cancel_jobuniquement lorsque l'utilisateur demande d'arrêter l'édition. - Pour un transfert délibéré d'hôte, fournissez le
session_idexact et lejob_idactif ; l'hôte récepteur devrait commencer parcassette_job_statusplutôt que de ré-ingérer ou de démarrer un travail en double. - Les fichiers exportés restent dans le répertoire de données partagé Oh My Cassette. Préférez le lien de ressource ou l'URI de fichier retourné plutôt que de relocaliser l'artefact.