Subtítulos
Esto es una tarea, no una etapa de un flujo. Se hace cuando el usuario lo pida—justo después de editar puede hacerse, si después de editar se borran dos frases, se puede hacer de nuevo.
Solo tiene un prerrequisito: que exista el libro de cuentas. No porque vaya después de la edición, sino porque sin libro de cuentas, no sabe qué frases se quedan ni en qué segundo del montaje final aparecen.
Necesita edit-list.json (libro de cuentas), transcript.json (transcripción palabra por palabra)
Produce subtitles.json
Termina y se detiene, no le dice al usuario qué hacer después.
Primero lee y ejecuta el contrato de fase del Skill de negocio, los criterios están en reglas de corrección de subtítulos, y la escritura de términos propios en el diccionario de términos de IA.
Quién decide qué
Esta es la base de todo, el resto se deduce de aquí.
Editar voz en off decide «qué frases se quedan y en qué momento» ← la única verdad temporal
Subtítulos decide «qué texto se muestra en pantalla» ← la única verdad visual
Una pantalla de subtítulos almacena una lista de IDs de palabras + el texto mostrado, no almacena segundos. El tiempo se calcula cada vez desde el libro de cuentas. Así, las dos cuentas no tienen un segundo conjunto de tiempos que pueda desviarse, y la invalidación puede ser precisa por pantalla: «las palabras de las pantallas 7 y 12 fueron cortadas», en lugar de ese «los subtítulos pueden estar desactualizados» que nadie puede verificar.
Los subtítulos almacenan su propio texto a propósito. La transcripción responde «qué dijo», los subtítulos responden «qué se muestra a la gente»— puntuación, muletillas eliminadas, la forma formal de términos propios, todo esto debería ser diferente. Forzar a una sola cadena a hacer ambas cosas significa que los subtítulos nunca podrán añadir comas.
0. Preparación
Primero ejecuta la «verificación de preparación» de Comprobar actualizaciones—si los skills están
actualizados, si el Runtime es compatible; la raíz del plugin también se localiza allí (en los comandos de este documento, <raíz-del-plugin> se sustituye por
esa ruta literal). Solo si está «preparado» se continúa; si es «necesita nueva sesión» o «detener», se ejecuta según su disposición
(incluyendo la prohibición de «crear interfaces alternativas propias»), el Skill de negocio no lleva lógica de entorno.
Si el resultado de preparación es runtime.kind=desktop-managed, reutiliza directamente el CLI estable ya instalado en la aplicación de escritorio y el mismo
servicio launchd/windows-task; no analices rutas de Electron, instales dependencias adicionales ni inicies un segundo Runtime.
1. Afirmaciones de entrada
node "<raíz-del-plugin>/scripts/ensure-running.cjs" --json
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" inspect "<directorio-del-proyecto>" --json
| Afirmación | Si no se cumple |
|---|---|
edit-list.json existe y tiene fragmentos | Di claramente que falta el libro de cuentas, pide al usuario que primero ejecute «Editar voz en off». No edites tú mismo. |
transcript.json existe | El proyecto no está listo, detente. No crees uno tú mismo. |
No afirmes source_cut.mp4, ni realices una transcripción. Los subtítulos no necesitan ninguna de las dos cosas—ver la siguiente sección.
2. Corregir texto: primero el diccionario, luego el guion
No es necesario retranscribir. La transcripción palabra por palabra original ya tiene marcas de tiempo, el libro de cuentas sabe qué segmentos se quedan— en qué segundo del montaje final cae cada palabra se calcula, no se escucha de nuevo:
El segundo de la palabra en el clip original ya está en la transcripción
Qué segmentos se quedan ya está en el libro de cuentas
El segundo de la palabra en el montaje final se calcula a partir de ambos
Pasar el ASR otra vez solo es volver a escuchar lo mismo, gastar dinero, tiempo y obtener un resultado peor—los términos propios habría que corregirlos de nuevo.
(transcript retranscribe es un remanente del diseño anterior, donde los subtítulos dependían de la transcripción del video editado para obtener la línea de tiempo.
Desde que los subtítulos cambiaron a anclar IDs de palabras, este problema ya no existe. Al hacer subtítulos, no lo uses.)
Dos herramientas diferentes, ambas deben usarse.
# Diccionario: la forma fija de este hablante, no necesita evidencia
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" transcript dictionary "<directorio-del-proyecto>" --dictionary "<raíz-del-plugin>/references/ai-term-dictionary.md" --json
# Guion: solo cuando el autor tiene un guion, necesita evidencia para cada cambio
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" transcript align "<directorio-del-proyecto>" --script "<archivo-del-guion>" --json
Diccionario Escribe siempre así Sin mirar el contexto, cambia directamente, lista qué cambios hizo
Guion Solo escribe así si el contexto coincide Necesita evidencia para cada cambio, si no coincide reporta «no me atrevo a decidir», no adivina
Por qué es necesario el diccionario, y no basta solo con el guion: las voces en off se regrababan. En un proyecto real, la misma frase se grabó cuatro veces, así que contextos como «conector X», «X es» aparecían varias veces cada uno, y align solo podía reportar «no me atrevo a decidir»— sigue la regla y no adivina, porque escribir mal un nombre es peor que oírlo mal. Tres ocurrencias de «X» solo se atrevió a cambiar una. El diccionario no tiene este problema: en el trabajo de este hablante, «X» es «X».
El diccionario es único, está a nivel de plugin en references/ai-term-dictionary.md: modifica la transcripción,
y tanto la edición de voz en off como los subtítulos usan la misma transcripción. No crees otro diccionario dentro de este skill.
Después de corregir, hay que ver esa lista. El diccionario no mira el contexto, por lo que también puede corregir mal—por ejemplo, normalizar «Skills» (Claude Skills, nombre propio plural) a «Skill». Si ves algo incorrecto, corrige el diccionario, no apliques parches en el comando.
transcript align solo reporta, no aplica. Para aplicar sus propuestas, convierte corrections en [{wordId, text}] y ejecuta:
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" transcript correct "<directorio-del-proyecto>" --file "<archivo-de-correcciones>" --json
Después de corregir la transcripción, las pantallas de subtítulos que referenciaban estas palabras se actualizarán en el mismo paso, reportando subtitles.updated.
Las que no se puedan cambiar (esa línea fue reescrita por alguien) entrarán en needsAttention, se reportan para que alguien las vea, no se adivina.
Cuando no haya una escritura confirmada como correcta ni en el diccionario ni en el guion, no se debe adivinar. Repórtalo para que el usuario complete el diccionario— al agregarlo al diccionario, el siguiente video será automáticamente correcto; adivinar correctamente una vez significa tener que adivinar de nuevo la próxima vez.
3. Dividir en pantallas
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" subtitle build "<directorio-del-proyecto>" --json
Cuatro reglas, en orden:
① Aquí se eliminó habla Los dos lados de lo eliminado están adyacentes en la línea de tiempo, sin relación de significado.
Eliminar «silencio» no cuenta—cortar una pausa en medio de una oración no puede dividir la oración.
② Cualquier signo de puntuación Dados por Huoshan, tanto el punto como la coma cuentan—**es el mismo nivel de granularidad que la división en segmentos de la edición de voz en off**,
ambos cortan en el mismo punto. La puntuación es más fuerte que cualquier evidencia temporal: un hablante puede decir dos frases seguidas sin respirar,
o hacer una pausa en medio de una oración.
③ Límite de párrafo + pausa **Solo se usa cuando esta palabra no tiene puntuación.** Es «cuando no hay puntuación, se adivina que la oración termina por el párrafo»,
si hay puntuación, debería ser gestionado por ② y la coma—ellos considerarán si la pantalla es lo suficientemente larga, ③ no lo hace.
(Si se activa ③ también en los límites con puntuación, en un proyecto real pasó de 40 a 43 pantallas, cortando más pantallas fragmentadas)
④ El espectador escucha una pausa larga Para dividir dentro de una oración, se necesita un silencio más largo para calificar.
La edición de voz en off y los subtítulos usan la misma puntuación y la misma granularidad: una coma/un segmento por pantalla.
Los fragmentos (una o dos palabras) se fusionarán, pero no se fusionan a través de un punto—«Mira» comienza una nueva oración, no es la cola de la oración anterior; fusionarla hacia atrás daría «...llamando a la CLI de GrokMira», dos oraciones pegadas.
Las frases cortas dichas rápidamente por el hablante se mantendrán (en un proyecto real, «cada mañana» y «ejecutar tarea» duraban 0.6 segundos cada una). Así es como realmente lo dijo, no se reporta como alarma. Una coma por pantalla produce inevitablemente este tipo de pantallas, reportarlo como alarma equivaldría a reportar una alarma por habla normal—si hay demasiadas alarmas, nadie las mira.
Las que sean más largas que una pantalla se dividen uniformemente en varias pantallas, una línea por pantalla. Si se cortan fragmentos de una o dos palabras, significa que ese límite de ② no es realmente un punto, y el fragmento se fusiona con la pantalla anterior.
El comando reporta cuatro cosas, todas deben revisarse:
stale Pantallas afectadas por cambios en la edición—preciso: qué pantalla, qué palabras se perdieron
tooFast Demasiadas palabras, no hay tiempo para leerlas
transcriptMoved La transcripción ya no es la original
Cuando ya hay subtítulos—detenerse y preguntar aquí
Sin --replace lo rechazará directamente. Este es el único lugar en este skill donde se debe pedir consentimiento al usuario,
porque --replace elimina el trabajo que la persona dedicó a dividir pantallas y redactar, y el producto no puede recuperarlo por sí mismo.
El usuario quiere cambiar algunas palabras No hagas build. Que las cambie directamente en Studio, o que te diga qué pantallas cambiar.
El usuario quiere empezar de cero Después de confirmar, añade --replace.
4. Revisión: ver pantalla por pantalla en Studio
node "<raíz-del-plugin>/scripts/videocut-cli.cjs" open "<directorio-del-proyecto>" --json
Al abrir, cambia a la pestaña «Subtítulos» en la columna izquierda. Una línea por pantalla: a la izquierda, número y tiempo; a la derecha, el texto; haz clic para editarlo directamente.
- Enter = nueva pantalla desde el cursor
- Retroceso al inicio de línea = fusionar con la pantalla anterior
- En la columna derecha, «Parámetros → Subtítulos», elige uno de los cuatro presets; un solo estilo para todo el video
- En la pantalla se ven los subtítulos directamente, la posición y el tamaño de fuente son proporcionales a la imagen—la vista previa y el producto final usan los mismos números
Durante la revisión, al menos confirma con el usuario: si los términos propios están correctos, si falta alguna palabra, si la división de oraciones se lee bien, si el tiempo de permanencia de cada pantalla es suficiente para leerla.
5. Hasta subtitles.json
Esta tarea ha terminado. No se realiza corte físico, ni storyboard, ni animación, ni renderizado del video final, y no se presiona al usuario para que haga el siguiente paso.
El informe debe escribirse por separado: el readback estructurado del Producto es API/readback PASS; la revisión real de frames del mismo proyecto en el navegador es visual frame PASS; si nadie ha visto realmente si los subtítulos coinciden con la imagen, siempre es human listening UNVERIFIED, no se puede sustituir con DOM, capturas de pantalla o detección de archivos.
Límite: Incrustar en el video no es parte de esta tarea
El método de entrega es incrustar en el video, y el video lo dibuja la etapa de exportación. La salida de los subtítulos es subtitles.json—
todas las dimensiones son porcentajes de la imagen, la exportación los convierte a píxeles según la resolución de salida, ambos lados usan los mismos números.
El mp4 exportado hoy no tiene subtítulos, ese paso aún no se ha hecho. El informe debe dejar claro este resultado, no digas simplemente «los subtítulos están listos»—el usuario pensará que el video final los tiene.
Recuperación y fallos
subtitles_exist: Ya hay subtítulos. Pregunta primero, no uses--replacedirectamente.revision_conflict: Otro lugar también está escribiendo. Vuelve a leer, no sobrescribas automáticamente.- El diccionario reporta «la fila N no se puede leer»: Es una fila de tabla con formato incorrecto. La regla solo reconoce filas de tabla (
| Escritura correcta | Mal escritura común |), los párrafos y listas se ignoran silenciosamente. transcript correctreporta «must not change any word id, time or gap flag»: La propuesta de cambio de texto incluía cambios de tiempo. Cambia solo el texto.runtime_unhealthy: No reinstales en bucle.- Ningún fallo debe hacer que «transcripción completada» se interprete como «subtítulos listos». Lo que sale del ASR es la materia prima, no el producto.