j-guide-video

Video instructivo animado (diseño guiado)

Un paso del manual = una escena. La narración se sincroniza con las acciones: tomar herramientas, verter, abrir, tocar, ensamblar. El dibujo, el audio y la exportación se realizan completamente en Swift (CoreGraphics, AVFoundation) y la CLI jgv se encarga del guion, audio, subtítulos, imágenes fijas y exportación de video.

• <skill> es el directorio de este SKILL.md (${CLAUDE_SKILL_DIR}. Si no está disponible, cuando se instala como plugin es ${CLAUDE_PLUGIN_ROOT}/.claude/skills/j-guide-video; en otro caso, ~/.claude/skills/j-guide-video o .claude/skills/j-guide-video, el que exista).
• jgv a continuación se refiere a <skill>/bin/jgv. Solo la primera vez y después de actualizar el skill, se compila a sí mismo y el kit (DSL de dibujo y componentes) en Swift, lo que puede tomar decenas de segundos o minutos. La compilación se almacena en caché (~/Library/Caches/j-guide-video/) y los archivos del proyecto de video solo contienen los archivos específicos del tema (guion, bindings, cues, materiales SVG) (ver reference/environment.md). Si el usuario pide borrar la caché, ejecuta jgv clean --stale --dry-run para mostrar lo que se borrará, luego jgv clean --stale; para borrar toda la caché: rm -rf ~/Library/Caches/j-guide-video (se reconstruirá en la siguiente compilación). Si se ha cambiado la ubicación de la caché con J_GUIDE_VIDEO_CACHE, no borrar toda la carpeta, solo su contenido: build-*, shared-*, projects, avtts (porque la carpeta podría no ser dedicada).
• Los argumentos y opciones se muestran con jgv help <subcomando>. Las opciones desconocidas generan un error.
• <library> es la biblioteca del usuario (variable de entorno J_GUIDE_VIDEO_LIBRARY; si no está definida, ~/.config/j-guide-video. Si existe XDG_CONFIG_HOME, estará debajo de ella). Contiene herramientas y movimientos creados en videos anteriores (parts/) y configuraciones preferidas (defaults.json), y no se borra al actualizar el skill (ver reference/library.md).

procedure.md ─(jgv new = init・md2script --stubs・tts・timing)→ script.json・plantillas de cues y bindings・audio・timeline・subtítulos・tabla de tiempos
visuals/bind.swift (cómo dibujar herramientas y pantallas, con nombres) + cues/<proceso>.cue (movimientos por frase) ─(jgv check → jgv dev → jgv render → jgv overview)→ out/video.mp4

Lo que se debe comprobar primero

Entorno de ejecución

• Exclusivo para Claude Code en macOS (versión donde funcione Xcode reciente; solo probado en Apple Silicon, no en Intel Mac). Si se detecta Linux, Windows (incluyendo WSL2), Claude Code en web o Claude.ai, se debe informar y detener.
• Se necesita Xcode reciente o Command Line Tools (swift; xcode-select --install. No se ha probado con versiones antiguas). jgv se detendrá si faltan o están obsoletos; indicar al usuario cómo instalarlos (no ejecutar comandos que requieran sudo sin permiso). Solo la primera compilación de jgv requiere conexión a internet.
• La narración predeterminada usa las voces del sistema macOS ("voice": "auto" selecciona la voz de mayor calidad para el idioma del guion; lista con jgv voices).
• Los TTS disponibles para uso comercial son los TTS en la nube integrados y el modo command que se conecta a cualquier comando. Para los TTS en la nube, solo se necesita configurar la clave en una variable de entorno: google (GOOGLE_TTS_API_KEY; si es una clave de cuenta de servicio, GOOGLE_APPLICATION_CREDENTIALS), azure (AZURE_SPEECH_KEY, AZURE_SPEECH_REGION), amazon (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) y openai (OPENAI_API_KEY; se recomienda no usar para videos duraderos porque el modelo dejará de funcionar el 2027-01-06).
• El usuario debe proporcionar las claves y scripts. Claude no debe introducir ni mostrar claves API, ni abrir archivos de claves de cuentas de servicio (GOOGLE_APPLICATION_CREDENTIALS), ni llamar a APIs de pago sin autorización.
• Al manejar proyectos de video que no haya creado el usuario (zip, repositorios de terceros, guiones de terceros pasados con --base), antes de ejecutar jgv, mostrar y verificar con el usuario los archivos script.json y script.<idioma>.json (todos los guiones pasados a jgv tts, etc.) en cuanto a tts (si engine es un TTS de pago o qué comando está en command) y los archivos Swift en visuals/, parts/, kit/. jgv tts / timing / dev / check / snapshots / still / preview / catalog / render / build-langs (todos los comandos que generan audio o compilan y dibujan visuals) ejecutan esos comandos y código directamente.
• Los TTS de pago en la nube no se llaman hasta que se autorizan una vez con jgv tts --allow-cloud por proyecto y engine (jgv tts mostrará el número de líneas y caracteres y se detendrá). --allow-cloud solo se añade después de informar al usuario sobre el engine y el costo, y obtener su consentimiento (con jgv new --tts … y el engine en defaults.json de la biblioteca, los guiones creados con jgv new se autorizan automáticamente. Al heredar el engine de la nube de un guion de terceros con jgv new --base, jgv new se detendrá antes de crear nada y pedirá que se seleccione con --tts).
• La configuración de voz, velocidad, cada TTS, disco y caché se detalla en reference/environment.md.

Condiciones de uso de los videos generados

• Voz de macOS (predeterminada apple): Según la licencia de macOS de Apple (sección "Voices"), las voces del sistema solo se pueden usar para crear obras originales propias con fines personales y no comerciales. Los videos exportados se limitan a uso personal y no comercial; no se pueden publicar en redes sociales o sitios de video, ni usar para trabajo o en una empresa (esto incluye, según se interpreta, manuales internos) (resumen; el texto original está en la sección "Voices" de la licencia de macOS).
• TTS conectado a google / azure / amazon / openai / command: Sujeto a los términos de uso de ese TTS. Si el TTS permite uso comercial, se puede usar para publicación o trabajo. Si el TTS requiere créditos o indicación de que es voz generada por IA, se debe añadir en credit en script.json.
• Si la solicitud parece ser para publicación en redes sociales, sitios de video, trabajo o uso empresarial, antes de comenzar, informar al usuario y ofrecer la posibilidad de cambiar a un TTS de uso comercial. No hacer juicios legales (indicar al usuario que revise la licencia de macOS o los términos del TTS que usará).

0. Elegir el tipo de diseño

Determinar el tipo según el tema e informar al usuario brevemente (solo preguntar si hay duda). Indicar también la ubicación del proyecto (<dir> en el paso 2).

Tipo	--layout	Apariencia	Temas adecuados	Ejemplos completos (examples/)
Habitación	guide (predeterminado)	Una misma persona de pie en una habitación, usando herramientas. Los detalles pequeños se muestran en una tarjeta ampliada	Bebidas, tareas domésticas, cuidado de electrodomésticos, etc., donde "una persona maneja herramientas"	room-microwave-rice, room-mug-wash
Operación de pantalla	guide-screen	Sin persona. Se muestra la pantalla de un teléfono/navegador y se interactúa tocando, haciendo clic o escribiendo. A la derecha, notas de puntos; las áreas no relevantes se oscurecen	Procedimientos de uso de apps o servicios web	screen-alarm (teléfono)
Vista cenital	guide-topdown	Vista desde arriba de una mesa de trabajo, con ambas manos entrando desde la parte inferior de la pantalla	Cocina, manualidades, envoltura de regalos, etc., donde las manos son protagonistas	topdown-cucumber
Manual de ensamblaje	guide-manual	Papel cuadriculado blanco con dibujos isométricos en líneas, flechas punteadas, tornillos y lista de piezas	Ensamblaje de muebles, instalación de equipos, reemplazo de piezas	manual-smallbox
Formato vertical	Cualquiera de los anteriores + --vertical	1080×1920. Si es tipo habitación, la persona arriba y la tarjeta ampliada siempre visible debajo del mostrador (solo probado con tipo habitación)	Trucos cortos de vida diaria, recetas para ver en vertical en el teléfono	vertical-coffee

Si se necesitan versiones en varios idiomas, primero completar en un idioma y luego agregarlas en el paso "6. Crear versiones multilingüe".

1. Preparar el manual de procedimientos

Resumir el texto del usuario en el siguiente formato Markdown y guardarlo en <dir>/procedure.md (si ya está en este formato, usarlo directamente).

# Cómo preparar café de filtro en bolsa
## Preparar [prepare]
Prepara una taza, una bolsa de café de filtro y una tetera. Hierve el agua y déjala enfriar a unos noventa grados Celsius.
## Abrir la bolsa [open]
Sujeta la bolsa con ambas manos, rasga la tira superior por la línea marcada. Ábrela con cuidado para no derramar el café.

• # Título, ## Nombre del paso [tag], el texto se lee tal cual. El tag es opcional y se convierte en el nombre visual (open → Open). Solo debe contener caracteres alfanuméricos, - y _ que comiencen con una letra; de lo contrario se ignora y se genera algo como Step01.
• Las listas con viñetas o numeradas: un elemento = una oración. Los formatos de énfasis, enlaces y código en línea se eliminan al leer (no se leen etiquetas HTML, comentarios ni bloques de código. Se conservan los nombres de teclas como <Enter> <URL> y los signos de ángulo en lugares que se deben reemplazar). En japonés y chino, los saltos de línea también son separadores de oraciones (las líneas que terminan en coma de lectura se unen a la siguiente); en inglés y otros idiomas, las líneas en blanco son separadores de párrafos. Si falta puntuación al final de la oración, se agrega. Las tablas (líneas con | … |) y bloques de código no se leen (si se omiten tablas, se muestra una advertencia).
• Los pasos deben ser de 4 a 8, con 1 a 3 oraciones por paso. 1 oración = 1 segmento de animación; las comas (,, 、) = segmentos aún más finos, por lo que las oraciones deben estar estructuradas para que "qué hacer → cómo hacerlo" quede claro en cada frase (ejemplo: "Extiende los ganchos de papel, fíjalos al borde de tu taza.").
• Los tiempos de espera reales (reposo, secado, etc.) se acortan en el video.
• Si el texto del usuario es una nota, instrucción u otro formato libre, convertirlo al formato de manual según los criterios de reference/rewriting.md.

2. Crear el proyecto y convertirlo en guion

jgv new <dir> --kicker "RITUAL DIARIO / GUÍA DE CAFÉ" --layout guide

jgv new realiza en un solo paso: crear el proyecto (jgv init), generar el guion y las plantillas de cues (jgv md2script procedure.md -o script.json --stubs visuals), generar el audio y la línea de tiempo (jgv tts), y mostrar la tabla de tiempos de los cues (jgv timing; muestra línea.frase por paso y los segundos desde el inicio del paso). Usa <dir>/procedure.md como manual (si está en otra ubicación, se pasa como jgv new <dir> <ruta_al_manual> para copiarlo). Las opciones son las mismas que jgv md2script. Los comandos posteriores se ejecutan dentro de <dir>.

• <dir>: si el usuario especifica una ubicación, se usa esa. Si no, se crea sin preguntar fuera del skill y del repositorio donde se instaló (ejemplo: ~/Movies/jgv/<tema>). En ambos casos, antes de crear (al indicar el tipo en el paso 0), se debe informar la ruta completa (ejemplo: "Lo crearé en ~/Movies/jgv/shoulder-massage. Si prefieres otra ubicación, dímelo"). Crearlo en el directorio actual podría dejar archivos generados (out/, .jgv/) dentro del repositorio.
• --layout es el tipo elegido en el paso 0. Para formato vertical, añadir --vertical. --kicker es el nombre de la serie en la esquina superior izquierda.
• La apariencia del presentador (--presenter), la relación con defaults.json de la biblioteca, el TTS en la nube (--tts), la opción de no mostrar texto (--no-text, etc.) y proyectos de versiones anteriores (jgv migrate) se detallan en reference/options.md#opciones-de-jgv-new. Si defaults.json ya contiene kicker / layout, solo añadir --kicker / --layout cuando el usuario lo especifique o cuando el tipo elegido en el paso 0 sea diferente.
• Si jgv new se detiene por un error, el comando elimina lo que creó y restaura el estado original (los archivos que ya existían se conservan). Corregir la causa y volver a ejecutar el mismo jgv new (si se interrumpió, consultar la sección de solución de problemas en reference/tips.md).

Resultado (funciona de principio a fin en este punto): script.json, cues/<Visual>.cue por paso (con el número línea.frase y el comentario de la oración al inicio), visuals/<Visual>.swift (una línea que llama al cue; no tocar), visuals/bind.swift (plantilla del binding), .jgv/timeline.json, out/subtitles.srt.

Corregir la lectura en japonés

• En japonés, en speak de cada línea de script.json, se pueden mejorar números, letras y palabras difíciles de leer. Para corregir la lectura, escribir en katakana (el hiragana podría unirse al anterior o siguiente, causando confusión; por ejemplo, "や／は／いせつ…" en lugar de "ハイセツブツ" que no causa error).
• Usar jgv yomi para ver la lectura por palabra y advertencias, y corregir lecturas incorrectas. jgv yomi usa el análisis de macOS independientemente del engine, por lo que para TTS en la nube es solo una referencia (corregir a katakana funciona con cualquier engine). (Tipos de advertencias y cómo corregirlas en reference/tips.md#lectura-en-japonés).
• Después de corregir speak, ejecutar jgv tts (vuelve a leer solo las líneas corregidas) y luego jgv timing (vuelve a mostrar la tabla de tiempos).
• Si el usuario señala una lectura incorrecta, después de corregirla, preguntar en el paso 7 si se debe agregar a readings en defaults.json de la biblioteca.

3. Definir herramientas y pantallas (binding)

Determinar qué objetos (herramientas, equipos, pantallas) se mostrarán en cada paso, dónde colocarlos y dónde poner las manos, y escribirlo como binding en visuals/bind.swift (cuya plantilla crea jgv new). Es único para todos los pasos. La sintaxis se describe en reference/cue.md en la sección "binding".

• Antes de escribir, leer un ejemplo completo del mismo tipo (seleccionar de la lista en examples/README.md y leer su visuals/bind.swift y cues/*.cue; se pueden copiar movimientos y colocaciones similares).
• Priorizar componentes del kit y piezas en parts/ del proyecto (piezas de la biblioteca). Para la apariencia, leer reference/props-catalog.png; la lista completa está en reference/visual-kit.md en la sección "herramientas". Para argumentos, puntos de agarre (KETTLE_PARTS, etc.), buscar con jgv api やかん (se puede buscar por nombre, nombre en japonés o descripción; solo jgv api muestra la lista de nombres; también muestra parts/ del proyecto); no usar grep sobre el código fuente del kit.
• Si una herramienta no existe, dibujarla en visuals/props.swift siguiendo las reglas de reference/prop-style.md y verificar con el preview (PROPS_PREVIEW) usando jgv preview. Si el usuario tiene un SVG, se puede colocar en assets/ y dibujar con Svg("nombre") (ver visual-kit.md en "Materiales SVG (assets)").
• Las posiciones fijas y escalas de las herramientas deben ser constantes con nombre (ejemplo: let MW = Pt(1080, GUIDE.counterY). Para vertical, LAYOUT_PORTRAIT.counterY). Así, al corregir, solo se cambia en un lugar.
• Las herramientas y equipos que la persona toca con las manos deben colocarse cerca de la persona (en horizontal, hasta aproximadamente x 1150) (jgv check mostrará una advertencia si las manos están demasiado lejos).
• Los pasos de "lo que necesitas", "notas", "antes/después" y "resumen" pueden usar los tipos de escena del kit (PrepareItems, NoteCards, BeforeAfter, SummaryList) en el dibujo del binding.
• Los puntos clave de la apariencia por tipo se describen en reference/implementation.md en la sección "Puntos clave por tipo".

4. Escribir los movimientos de los pasos con cues

Escribir cues/<Visual>.cue para cada paso. Los números de tiempo línea.frase provienen de los comentarios al inicio de la plantilla (# 0.0 Arroz congelado, 0.1 aún envuelto, …) y de la tabla de tiempos de jgv new / jgv timing. La sintaxis está en reference/cue.md. Copiar movimientos similares de los ejemplos completos del mismo tipo (examples/). Los cues son de solo unas pocas líneas a unas decenas, por lo que no se necesita un subagente para cada paso; el proceso principal escribe todos los pasos de forma continua.

init <Load
0.0+.3 H>mw.handle~.45
0.0+.35 mw.open=0~.6
0.2+.45 P mw.start;mw.on=1~.2;mw.disp=cd 2:00 0:[email protected];timer timer [email protected]
1.1+.7 H>dish.gripL~.4;dish.in=0
1.1+.77 dish@PLATE~.5;steam dish.top

• Para cada frase, escribir una línea: "qué hacer → cómo hacerlo" (mover en el tiempo de la frase que se lee). Los tiempos de espera se representan con un temporizador circular (timer) y la anotación "el tiempo de espera se ha acortado".
• Para las manos (H>, C>, P), el tiempo es "tiempo de llegada"; para otros, es "tiempo de inicio". Al alinear valores con el movimiento de la mano, adelantar el tiempo del valor en la duración del movimiento de la mano.
• Los pasos a partir del segundo comienzan con init <paso_anterior para heredar el estado final. Si se quiere mantener la tarjeta ampliada abierta, en el paso anterior poner card.exit=0 y en el siguiente card.enter=0.
• Los detalles finos con las manos (abrir, recoger, frotar, girar) se muestran en la tarjeta ampliada (card, C>). La persona señala a la izquierda de la tarjeta (H>gesture). El paso final debe incluir el producto terminado, una marca de verificación (check) y un efecto de vapor o destello.
• Evitar pantalla estática: mientras hay narración, debe haber movimiento (vapor, oscilación (wave), ondas, etc.).

cd <dir> && jgv check

Corregir el cue y el binding hasta que no haya líneas con ! (errores: nombre incorrecto, manos demasiado lejos, soltar un objeto mientras se mueve, movimientos más allá de 0.5 segundos antes del final, solapamiento de texto o marcos, etc.). Las líneas con H / C muestran la tabla de tiempos de las manos (de qué segundo a qué segundo, de dónde a dónde). Las líneas S1→S2 muestran valores diferentes en los límites de los pasos (solo deben aparecer los que se cambiaron intencionalmente). Si solo se corrige el cue, no se recompila, por lo que se puede verificar rápidamente. Cómo leer las líneas y corregirlas: sección "jgv check" en cue.md.

Los movimientos especiales que no se pueden expresar con cues se escriben en Swift en el dibujo del binding y se controlan desde el cue mediante valores (sección "Escribir en Swift" en cue.md). También se puede usar el método anterior de escribir un storyboard y luego implementar en paralelo con subagentes para cada paso (ver reference/implementation.md).

5. Verificación completa → exportación

cd <dir> && jgv dev

jgv dev realiza todas las verificaciones en un solo paso: jgv tts (vuelve a leer solo las líneas cambiadas) → compilación → jgv check (si hay !, se detiene aquí) → jgv snapshots solo de los pasos cambiados desde la última ejecución de jgv dev.

• Los errores de compilación del binding, etc., aparecen con el nombre del archivo y el número de línea: visuals/bind.swift:12:5: error: ….
• Al final, en la línea Imágenes a verificar:, aparece una lista para leer. La primera vez, y cuando se cambian archivos Swift, assets/, colores, etc., o cuando todos los pasos cambian, se genera out/snapshots/sheet.png completo. Cuando solo cambian los cues, se generan out/snapshots/scene-N/sheet.png para los pasos modificados (incluyendo los que heredan con init <paso_anterior). Cambiar el guion cambia la duración del video y la barra de progreso, por lo que generalmente se genera todo. Para forzar la regeneración completa: jgv dev --all.
• Abrir y verificar obligatoriamente la lista de Imágenes a verificar: con el comando Read, corregir si es necesario y volver a ejecutar jgv dev. (Cuando solo se regeneran los pasos modificados, el out/snapshots/sheet.png completo anterior permanece; no confundir). Los desfases de tiempo de las manos se ven más rápido en la tabla de tiempos de jgv check que en las imágenes.
• Para detalles pequeños que no se ven bien en la lista (líneas punteadas, texto de notas, posición de manos y agarres), se puede leer un fotograma individual de la misma carpeta (la mitad del tamaño del video; el nombre del archivo es el número de línea que aparece al exportar, ej: 03.png; con jgv snapshots --scene=N --phrases se generan por frase, ej: 02-04.png. jgv dev no tiene la opción --phrases).

Qué verificar en las imágenes:

• ¿La mano está en el mango de la herramienta? ¿La herramienta flota o se superpone?
• ¿La acción en pantalla coincide con el contenido de la frase? (Ej: en la línea "rasgar", ¿la tira está rota?)
• ¿Se pueden leer las etiquetas de subpasos y las anotaciones en la tarjeta ampliada? Las superposiciones de texto, anotaciones y marcos, y los elementos que sobresalen de la pantalla, los muestra jgv check en las líneas ! segundos-segundos:; en las imágenes, verificar superposiciones entre objetos, objetos dibujados dos veces, y que el dibujo del binding no se superponga con los títulos o la barra de subtítulos (esto no lo detecta jgv check). Si se usó --no-text / --no-notes, verificar que no aparezcan textos explicativos.

Si no hay problemas, exportar y luego crear la página de resumen:

cd <dir> && jgv render && jgv overview

out/overview.html es una página que muestra la narración, los archivos visuales, las imágenes fijas y los materiales SVG de cada paso (se abre en el navegador). Informar al usuario la ubicación de out/video.mp4, out/subtitles.srt y out/overview.html; si se puede enviar, enviar el video. Luego continuar con el paso "7. Guardar en la biblioteca".

Los ajustes de color, voz, etc., la resolución de errores y ejemplos prácticos escritos en Swift (demo/ del repositorio) se describen en reference/tips.md.

6. Crear versiones multilingüe

Primero completar el video en un idioma, luego seguir los pasos de reference/multilang.md para añadir script.<idioma>.json y exportar todo junto con jgv build-langs (el video es común; solo se reemplazan el guion y los textos en pantalla).

7. Guardar en la biblioteca

Después de la exportación, entre lo creado en este video, proponer al usuario guardar en la biblioteca aquellas herramientas y movimientos que podrían ser útiles para otros temas (visuals/props.swift, shared.swift, las formas de dibujar herramientas escritas en el binding), las configuraciones que el usuario eligió como preferidas (colores, voz, velocidad, etc., pero no el kicker específico del tema) y las correcciones de lectura que el usuario señaló (readings). Preguntar al usuario si desea guardarlos en la biblioteca (si no hay candidatos o todos ya están en la biblioteca, no preguntar). Al guardar, seguir los pasos de reference/library.md en la sección "Guardar después de completar el video" y colocar los archivos en <library>/parts/ y <library>/defaults.json. Esto reducirá el trabajo de dibujo y configuración en videos futuros.