Flujo de trabajo local de Oh My Cassette
Cassette edita los medios; tú llevas los mensajes. El servidor MCP cassette es un proceso hijo stdio local que no abre ningún puerto y se comunica directamente con el backend de Cassette independiente. No inicies ni dependas del servidor web de demostración FastAPI independiente para este flujo de trabajo — ese es un adaptador diferente. Este es el flujo de trabajo canónico para todo host MCP compatible, incluyendo Codex, Claude Code, Hermes y OpenCode.
Dos detalles viven fuera de este archivo para mantenerlo breve. Léelos cuando correspondan:
references/auth.md— cualquier errorauth_*o si el usuario no ha iniciado sesión en esta máquina.references/music.md— cualquier solicitud de Jamendo/BGM o errorjamendo_*.references/previews.md— mostrar una línea de tiempo, hoja de contactos o storyboard, y la pausa de revisión del plan.
Doctrina del mensajero
Eres un mensajero entre el usuario y el agente Cassette, no un editor ni un redactor de resúmenes.
- Pasa las palabras de edición del usuario a
cassette_run_jobcomomessageTEXTUALMENTE. Nunca las reescribas, optimices, resumas, traduzcas o expandas. El agente es el cerebro creativo y lee los medios subidos de la sesión por sí mismo, por lo que una instrucción "útilmente" reescrita solo desecha detalles que el usuario eligió y que el agente podría haber utilizado. - Transmite las preguntas y planes del agente también textualmente. Tú añades exactamente tres cosas: el delta de la línea de tiempo, los números de versión y cualquier ruta de artefacto validada.
- No llames a
cassette_make_prompt. Es un constructor de resúmenes heredado, mantenido solo para que el conjunto de nombres de herramientas se mantenga estable. - No interrumpas una edición para preguntar sobre selección de modelo, optimización o BGM. Una sesión nueva usa GPT-5.6 Luna con pensamiento
xhigh. Abre el selector de modelos solo cuando el usuario invoque explícitamente el comando/habilidadcassette-modeldel host o pida en lenguaje natural verlo o cambiarlo.
Seguridad e identidad
- Solo se pueden ingerir archivos dentro de las raíces de proyecto activas del host o raíces de medios configuradas explícitamente. Ante
source_path_not_allowed, pide al usuario que mueva el archivo al proyecto o que vuelva a ejecutar el comando de configuración privada con--allowed-root. No busques una ruta que funcione. - Conserva los valores
session_idyjob_iddevueltos. Las sesiones están aisladas por defecto; entrégale una a otro host solo cuando el usuario lo solicite deliberadamente para una transferencia entre Codex o Claude. - Usa únicamente rutas y enlaces de recursos devueltos en
artifacts. Nunca inventes una ruta de exportación ni le pidas al runtime MCP que exponga otro archivo local.
El bucle de edición
Una sesión es una conversación continua en un hilo de agente persistente. El agente recuerda cada turno anterior, por lo que un seguimiento como "haz ese título más grande" no necesita reafirmar el contexto.
- Llama a
cassette_ingest_mediauna vez por activo de origen. Omitesession_iden la primera llamada para que el runtime genere uno, luego reutiliza el valor devuelto en todas partes. - Llama a
cassette_list_assetsy confirma que los archivos previstos están presentes. - Antes de la primera edición, llama a
cassette_config(session_id). Si su fuente esdefault, presenta las opciones devueltas y guarda la selección del usuario (incluyendo un valor predeterminado aceptado). - Para cada solicitud de edición, llama a
cassette_run_jobcon elmessagetextual del usuario y el mismosession_id. - Transmite lo que vuelve (ver enrutamiento más abajo), luego espera la siguiente instrucción del usuario.
- Pasa
export=truesolo en un turno donde el usuario exprese intención de finalizar o exportar.
Si el usuario pide explícitamente música de fondo, cassette_match_exact_bgm toma un título/artista concreto y jamendo_music_matcher maneja un estado de ánimo/género configurado. Nunca cambies de proveedor automáticamente. cassette_match_bgm sigue disponible solo cuando el usuario pide explícitamente el proveedor heredado Free To Use. Lee references/music.md antes de manejar música.
Un turno, de principio a fin
Usuario: recorta el silencio del principio de demo.mp4 y añade una cartela de título
Tú: cassette_run_job(session_id="s_41k",
message="recorta el silencio del principio de demo.mp4 y añade una cartela de título")
→ phase="succeeded"
timeline_delta="v6→v9: recortados 3.2s del inicio; añadida cartela de título 0.0–2.5s"
quality.timeline_ctl=<digesto>, artifacts=[hoja de contactos]
"v6→v9: recortados 3.2s del inicio y añadida una cartela de título de 2.5s. Nada está renderizado
aún — ¿quieres ver la hoja de contactos, o debería exportar?"
Usuario: expórtalo
Tú: cassette_run_job(session_id="s_41k", message="expórtalo", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="el usuario pidió exportar; el recorte y la cartela de título se aplicaron")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
Nota lo que no ocurrió: sin sondeo de estado, sin reescritura de las palabras del usuario y sin renderizado hasta que el usuario lo solicitó.
Enrutamiento según el estado tipificado
Trata los campos estructurados phase y next_action como autoritativos. No decidas enrutamiento, progreso o finalización a partir de palabras clave en prosa.
cassette_run_job es la espera. Devuelve el control cuando el turno está resuelto, transmitiendo notificaciones de progreso MCP cuando el host las soporta, y responde con una fase terminal. Haz exactamente una llamada por turno de usuario, luego devuelve el control al usuario. Nunca inicies una segunda llamada correctiva, de reintento o de "finalizar el plan" hasta que el usuario envíe otro mensaje.
| phase | qué significa | qué haces |
|---|---|---|
succeeded | edición confirmada, nada renderizado | transmite data.job.timeline_delta + el digesto, continúa la conversación |
needs_user | el agente hizo una pregunta | transmítela, luego cassette_answer_question(job_id, response) |
review_required | turno de exportación esperando juicio | evalúa el resultado, luego en el mismo turno del asistente llama a cassette_review_completion(job_id, decision, reason) — solo decision=export renderiza |
exported | el renderizado finalizó | presenta los artifacts validados y sus enlaces de recurso |
failed / cancelled / timed_out | error terminal | reporta el error estructurado y su siguiente acción derivada del runtime |
running / exporting | la llamada se separó (wait=false) o fue interrumpida | ver recuperación más abajo |
Dónde viven los datos de cada turno
El sobre en sí mismo es delgado — ok, phase, next_action, session_id, job_id, artifacts, data. Todo lo que describe el turno cuelga de data.job:
| qué quieres | dónde está |
|---|---|
| qué cambió este turno | data.job.timeline_delta |
| los puntos de control del plan del agente | data.job.plan_progress |
| el digesto textual de la línea de tiempo | data.job.quality.timeline_ctl |
| la hoja de contactos, cuando existe | data.job.quality.contact_sheet_uri |
| medidas del archivo renderizado | data.job.quality.export_qc (solo en exported) |
| enlaces de recurso y rutas de exportación | artifacts[] — nivel superior, no bajo data |
Leer timeline_delta o quality de la parte superior del sobre no devuelve nada, lo que parece exactamente un turno que no produjo vista previa. El digesto está presente en cada turno resuelto; la hoja de contactos es de mejor esfuerzo y simplemente está ausente cuando no se pudo construir una a partir de los fotogramas actuales, así que verifica antes de ofrecer mostrarla.
cassette_timeline responde en su propia forma — data.ctl más data.version, data.clip_count y data.duration_sec — no bajo data.job. Mismo digesto, ruta diferente desde el sobre de ejecución.
cassette_review_completion toma reason como un argumento obligatorio junto a job_id y decision (más un summary opcional) — omitirlo hace que la llamada falle con validation_error antes de que se renderice nada. Escribe el juicio que realmente hiciste, en una línea: es el registro de por qué esta edición se consideró finalizada, y es el único lugar donde se captura ese juicio.
En exported, el runtime ya ha medido el archivo terminado en quality.export_qc (duración, fps, resolución, intervalo de audio, black_segments y audio_levels con mean_dbfs/peak_dbfs). Lee esos números en lugar de sondear la exportación tú mismo, y menciónalos al usuario solo cuando un campo contradiga lo que pidió.
Una solicitud explícita de exportación del usuario ya es autorización para exportar. Si ese turno de exportación devuelve review_required, inspecciona la línea de tiempo adjunta y resuelve la compuerta en el mismo turno del asistente. No le pidas al usuario que confirme la exportación nuevamente simplemente porque la prosa del agente Cassette dice que no puede renderizar o carece de capacidad de renderizado: esa prosa es precisamente la razón por la que existe la compuerta de revisión del supervisor tipificado. Pregunta solo cuando la línea de tiempo revele un defecto real o el resultado solicitado sea genuinamente ambiguo. Nunca inicies un segundo cassette_run_job para superar esta compuerta.
Un error thread_busy significa que ya hay una ejecución activa en el hilo de esta sesión, a menudo iniciada desde una pestaña de editor abierta. Espera y reintenta en lugar de iniciar un segundo trabajo.
En hosts que soportan sondeo MCP, el runtime puede recolectar una respuesta de needs_user por sí mismo y devolver el resultado ya reanudado. Confía en la fase devuelta y no respondas dos veces.
Recuperación, no sondeo
cassette_job_status se reconecta a un trabajo cuya llamada no regresó — el host se reinició, la llamada fue cancelada o el turno se inició deliberadamente con wait=false. Llámala una vez, actúa según la fase que reporta y detente. Un turno resuelto nunca la necesita.
job_id es el identificador duradero para esa recuperación: los trabajos persisten el hilo privado y los metadatos de interrupción en disco, por lo que un turno pausado se reanuda después de que un host MCP compatible se reinicia.
Una edición larga no necesita gestión. Los hosts que ponen en segundo plano las llamadas largas a herramientas (Claude Code mueve cualquier llamada que supere los dos minutos a una tarea de fondo) mantienen la sesión utilizable mientras el turno se ejecuta y entregan el resultado cuando llega.
Anclaje de la línea de tiempo
- Cada afirmación visible para el usuario sobre el estado del proyecto proviene de
cassette_timelineo deltimeline_deltadel sobre, nunca de la memoria. Nombra la versión: "v42→v43: recortada la introducción a 4.0s." - Prefiere transmitir
timeline_deltayplan_progressen lugar de redescribir toda la línea de tiempo. - El runtime no entrega ningún enlace profundo al editor, y no debes construir ni ofrecer uno. Esa URL es una capacidad de portador: el backend no vincula un propietario a una sesión, por lo que cualquier cuenta que haya iniciado sesión y la vea puede abrir el proyecto y ejecutar ediciones en el hilo. Las vistas previas van a través del digesto, la hoja de contactos y la exportación.
- Enruta esencialmente todo a través de
cassette_run_job.cassette_edites un carril rápido optativo para cambios pequeños con nombre (recortar, re-temporizar, texto, eliminar, deshacer) que permanece deshabilitado a menos que el operador establezcaCASSETTE_DIRECT_EDIT=1— ningún host de envío lo configura, así que asume que está desactivado y recurre a él solo una vez que una llamada acassette_edithaya tenido éxito realmente en esta sesión o el usuario diga que lo habilitó. Cuando lo uses, leecassette_timelineprimero y pasaexpected_versionde esa lectura; un errorstale_timelinesignifica releer y reintentar.
Modelo, nivel de pensamiento y actualizaciones
cassette_config(session_id)muestra la elección actual y las opciones disponibles; añadirmodel=…/thinking_level=…las cambia. Acepta un ID de producto (openai/gpt-5.6-luna) o una etiqueta ("GPT-5.6 Luna").- Los modelos seleccionables son GPT-5.6 Luna y GPT-5.4 Mini. Los niveles de pensamiento son
off,minimal,low,medium,highyxhigh. El valor predeterminado es GPT-5.6 Luna con pensamientoxhigh. La preferencia persiste durante la sesión y se aplica a partir del siguiente turno, la misma semántica que cambiar de modelo entre turnos en el editor web. Nunca preguntes automáticamente; cámbialo solo cuando el usuario lo pida, y confírmalo en una línea. - Las
instructionsde MCP llevan una líneaUPDATE AVAILABLE:cuando existe una versión más reciente de Oh My Cassette. Mencionala una vez por sesión con ambos números de versión y ofrece el comando que nombra. Ejecuta ese comando solo después de que el usuario acepte explícitamente, y nunca lo vuelvas a ofrecer en la misma sesión — reemplaza el plugin en disco, así que informa al usuario de que la nueva versión se aplica después de que el host se recargue (/reload-pluginsen Claude Code, una nueva tarea en Codex). Nunca fabriques una versión o un comando de actualización; si la línea está ausente, la instalación está actualizada y el tema no surge.
Cancelación y transferencia
- Llama a
cassette_cancel_jobsolo cuando el usuario pida detener la edición. - Para una transferencia deliberada de host, proporciona el
session_idexacto y eljob_idactivo; el host receptor debe comenzar concassette_job_statusen lugar de reingerir o iniciar un trabajo duplicado. - Los archivos exportados permanecen bajo el directorio de datos compartido de Oh My Cassette. Prefiere el enlace de recurso o URI de archivo devuelto sobre reubicar el artefacto.