fish-video-skill

---

name: fish-video-skill description: Crea un Short, Reel, TikTok, YouTube o video de LinkedIn premium y listo para subir sobre cualquier tema. Ideal para videos explicativos, promocionales, tours de producto o app, tutoriales con grabación de pantalla, Shorts motivacionales o 'un video como este' (un enlace de referencia). Comienza con una entrevista única (tema, plataformas, estilo, colores, voz, música, efectos de sonido, activos, grabación de pantalla, claves API) y luego no vuelve a preguntar hasta la revisión final. Investiga tendencias y hechos, analiza videos de referencia, recopila activos reales con licencia, graba la pantalla con zooms de enfoque y sonidos de clic, y renderiza gráficos en movimiento deterministas con una cámara 3D: collage de papel, tipografía cinética, diagramas de neón, metáforas con brillo, pizarras. Agrega una voz natural, una mezcla equilibrada para parlantes de teléfono y subtítulos destacados, ejecuta control de calidad y una autorevisión, empaqueta videos, miniaturas, títulos, descripciones, etiquetas y créditos, y limpia solo con permiso. versión: 2.1.0 licencia: MIT autor: ImuTechz compatibilidad: Python 3.10+ (se recomienda 3.12), Node 18+, un navegador Chromium (Brave/Chrome/Edge/Chromium), ffmpeg (incluido vía npm). Windows, macOS, Linux. Claves opcionales ELEVENLABS_API_KEY, PEXELS_API_KEY, PIXABAY_API_KEY, FREESOUND_API_KEY, YOUTUBE_API_KEY; cada una tiene una alternativa sin clave.

Fish Video Skill v2

Haces un video a partir de una conversación. Debe alcanzar la calidad de los mejores Shorts analizados en desgloses de referencia:

• algo nuevo en pantalla cada ~1 s
• activos reales con profundidad (textura, sombras de contacto, brillo)
• tipografía con un contraste de palabra héroe de 3×
• transiciones de objeto como portal
• un swish que aterriza antes de cada movimiento, risers que terminan en revelaciones, impactos en cortes flash
• una voz que se sitúa sobre una base musical audible

Una presentación de diapositivas con una voz genérica es un fracaso incluso si pasa el control de calidad.

Enrutador: carga la guía cuando llegues a la tarea

Lee solo lo que necesita el paso actual:

• El usuario dio solo una palabra, o quiere ideas de temas, o estás escribiendo el guión → de tema a video
• Elegir un estilo, paleta o apariencia → recetas de estilo, config/styles.yaml
• Una idea necesita explicación, o elegir colores por estado de ánimo → diseño de diagramas
• Escribir cualquier escena → catálogo de escenas, incluyendo reglas de movimiento y cámara
• Cualquier cosa sobre música, SFX o niveles, o "No puedo escuchar la música en mi teléfono" → diseño de sonido
• Elegir o dirigir una voz → dirección de voz
• Subtítulos y tipografía → subtítulos y tipografía
• Un sitio web o aplicación en pantalla → captura de tour web
• Un video de referencia para igualar → desgloses de referencia, análisis de video de referencia, análisis de tendencias
• Tamaños y límites de plataforma → especificaciones de plataforma
• Qué herramienta de código abierto usar → guía de campo

Flujo de trabajo no negociable

0 doctor ─▶ 1 ENTREVISTA (todas las preguntas, una vez) ─▶ confirmar ─▶ 2 investigación + tendencias + referencias (en paralelo)
  ─▶ 3 activos + captura de pantalla + voz (en paralelo) ─▶ 4 guión gráfico (escribes cada palabra) ─▶ compuerta
  ─▶ 5 imágenes fijas (apariencia) ─▶ 6 renderizar ─▶ 7 bucle de QA + REVISIÓN (corregir, rerenderizar, repetir) ─▶ 8 empaquetar ─▶ 9 revisión final ─▶ 10 limpiar (preguntar)

Reglas:

• Una entrevista, al inicio. Cada pregunta que necesita al usuario se hace en el paso 1, incluyendo voz y tono, colores, los pasos de pantalla, las claves API (con cómo obtener cada una) y los extras opcionales a instalar. Después de fishvideo interview <dir> --confirm, no haces preguntas. Decides a partir de las respuestas y la receta de estilo. Vuelves a contactar al usuario solo en estos casos:

  • (a) una parada opcional que eligieron en checkpoints
  • (b) una grabación de escritorio que deben realizar; aceptaron en la entrevista, y les dices exactamente cuándo empezar
  • (c) la revisión final
  • (d) permiso para limpiar

  Si el usuario luego dice algo diferente, sigue al usuario.

• Nunca escribas un guión antes de que se confirme la entrevista. fishvideo script, all y el render completo se niegan hasta que fishvideo gate pase.

• Nunca envíes texto de plantilla. El andamiaje es un esqueleto de TODOs. Escribes cada palabra en pantalla y cada línea de narración fresca para este video, por lo que la compuerta bloquea TODOs, frases hechas de v1 ("X, explicado", "en 60 segundos", "Gracias por ver") y cualquier línea copiada de examples/. Los ejemplos muestran estructura, nunca contenido.

• Los videos explicativos tienen un diagrama. Cualquier video con goal: explain necesita al menos un mecanismo de escena diagram, whiteboard, neonline o split-revelación. Una lista de viñetas no es una explicación.

Paso 0: doctor

La configuración (solo la primera vez) está en README.md: npm install, un venv, y pip install -r requirements.txt. Luego ejecuta:

.venv/Scripts/python scripts/fishvideo.py doctor --keys      # Windows (macOS/Linux: .venv/bin/python)

Nota qué claves y extras faltan. Preguntas exactamente sobre esos en la ronda 8 de la entrevista.

Configuración para el mejor resultado (haz esto, no lo omitas):

• Instala los extras tú mismo. Si doctor muestra un extra faltante, instálalo en el venv de la habilidad sin hacer que el usuario lo haga: pip install "rembg[cpu]" (recortes), pip install kokoro soundfile (voces locales naturales) y pip install faster-whisper (alinea la propia voz en off del usuario). También ejecuta fishvideo assets sfx-pack una vez si falta la biblioteca de SFX. Dile al usuario en una línea qué estás instalando y por qué. Solo omite un extra que el usuario rechace en la ronda 8.
• Pide las claves API. Son opcionales: todo funciona sin ellas a través de las alternativas gratuitas. Sí dan el mejor resultado: ElevenLabs da las voces más naturales, Pexels/Pixabay dan la mayoría de fotos y videos de archivo, Freesound da la mayoría de SFX, y la API de Datos de YouTube da los gráficos de tendencias. En la ronda 8, pide las que importan para este video, di cómo obtener cada una (los enlaces de registro gratuito están en doctor --keys), y acepta "no" o "después" sin insistir. Haz esto solo en la entrevista, nunca una vez que la creación haya comenzado.

Paso 1: la entrevista (estricta)

fishvideo new projects/<slug> --prompt "<la solicitud del usuario, textual>"
fishvideo interview projects/<slug>            # JSON: las preguntas abiertas, agrupadas en 8 rondas

El banco de preguntas es config/interview.yaml. Tiene 8 rondas y alrededor de 30 preguntas:

Ronda	Cubre
1	propósito
2	forma y estilo
3	colores, tipografía, textura
4	voz, entrega, música, SFX
5	activos reales y grabación de pantalla
6	contenido, hechos, CTA, idioma
7	subtítulos, miniatura, aprobaciones
8	claves API y extras

¿Solo una palabra o un área? Antes de la ronda 1, genera 5 ángulos de tendencia: yt suggest, yt search --recent-days 30 y trends (subagentes haiku, en paralelo), siguiendo de tema a video. Ofrécelos como la pregunta topic. El ángulo elegido impulsa todo lo que sigue.

Cómo preguntar:

• Pregunta una ronda por llamada AskUserQuestion (hasta 4 preguntas), usando las opciones exactamente como se listan. Las opciones recomendadas van primero. "Otro" siempre está disponible.
• Las preguntas de texto libre (free_text: true) van en un mensaje normal para esa ronda, junto con la llamada de opción múltiple de la ronda.
• Omite una pregunta solo cuando la solicitud ya la responda sin ambigüedad (from_prompt muestra lo que se detectó), y regístrala de todos modos.
• Registra cada respuesta: fishvideo interview <dir> --set style=paper-collage --set platforms='["shorts"]'. Las respuestas se asignan a brief.yaml: la paleta va a brand.colors, el estado de ánimo a la puntuación y el tempo, la voz y la entrega a la configuración de voz y la cadena posterior, y el estilo a la textura, el ritmo y el motivo.
• Voz: después de las rondas 4 y 6 (una vez que se conocen el idioma y la entrega), ejecuta fishvideo voices <dir> --audition. Dale al usuario las rutas de archivo en build/auditions/ para que puedan reproducirlas, y déjalos elegir. Esto sigue siendo parte de la entrevista.
• Claves: ofrece solo las claves faltantes que importan para sus respuestas. Explica cómo obtener cada una (el texto en el banco) y qué sucede sin ella. Si pegan claves, regístralas con --set keys_paste=.... Las claves van al .env ignorado por git de la habilidad y nunca se muestran, registran ni confirman. Si eligen extras, instálalos en el venv ahora (pip install "rembg[cpu]", kokoro soundfile, faster-whisper).
• Finalmente, lee fishvideo interview <dir> --summary de vuelta al usuario. Pide un simple "sí, adelante", luego ejecuta --confirm.

Paso 2: investigación, tendencias y referencias (ejecutar en paralelo)

Genera estos como subagentes en paralelo. Enrutamiento de modelo: haiku para barridos de búsqueda y consulta, sonnet para análisis y código rutinario, y tú (opus) para el guión, el guión gráfico, el juicio de diseño y la revisión final. Informa a cada agente con la ruta del proyecto y el archivo de salida exacto que debe producir. Los subagentes pueden no poder escribir archivos de informe; entonces devuelven el texto y tú lo guardas.

Tarea	Comando	Agente
Hechos y fuentes	búsqueda web, luego fishvideo research <dir> --url ... → research/facts.md	haiku
Tendencias	fishvideo trends <dir> --topic "<tema>" --region <IN/US> → research/trends.md (fórmulas de título, etiquetas, ganchos, longitud ideal de lo que está ranking ahora)	haiku
Búsquedas en YouTube	fishvideo yt search "<q>" -n 20 [--recent-days 30], yt info, yt subs, yt suggest	haiku
Desglose de referencia (cada enlace que el usuario dio, más 1–2 ejemplos principales de tendencia en el estilo elegido)	fishvideo yt download <url> --purpose reference --project <dir>, luego fishvideo dissect <dir>/reference/<file>.mp4 --out <dir>/reference/dissect --fps 4 [--vtt subs.vtt]. Lee cada hoja, el espectrograma y timeline.md, luego escribe reference/analysis.md con las nueve secciones de análisis de video de referencia	sonnet (visión)

De los desgloses, toma números: tasa de cambio, sincronización y nivel de swish, voz sobre fondo musical en dB, profundidad de duck, volumen, estilo de subtítulo. Escríbelos en brief.yaml → match: para que el guión gráfico y la mezcla puedan seguirlos. Copia la artesanía, nunca el contenido.

Paso 3: activos, pantalla y voz (ejecutar en paralelo)

Activos reales (cuando assets.policy es mixed):

• Buscar: fishvideo assets search <dir> "<sustantivo>" --kind photo|video|music|sfx [--providers wikimedia,pexels]. Abre las vistas previas en assets/_candidates/ y míralas.
• Descarga lo que elijas: fishvideo assets get <dir> <ids>. Cada archivo se registra en assets/credits.json con su licencia.
• Haz recortes: fishvideo assets cutout in.jpg out.png (rembg con isnet-general-use; nunca el modelo predeterminado no comercial).
• Prepara material de archivo: fishvideo assets clip <dir> <file> <clip_id> --start S --dur S da fotogramas para la escena footage.
• Obtén una sección de YouTube con CC-BY: fishvideo yt clip <url> <start> <end> <dest> --project <dir>. Rechaza videos sin CC.
• Licencias permitidas: CC0, PD, licencias de Pexels/Pixabay, CC-BY y CC-BY-SA (con crédito). Nunca NC o ND. Nunca un video de YouTube sin CC, material de un video de referencia, un logotipo que redibujes, o la semejanza de una persona real de manera engañosa.

Pantalla:

• website: lista las tomas bajo captures: y ejecuta fishvideo capture <dir>. Graba en solo lectura en tiempo virtual.
• desktop: fishvideo screenrec record <dir> <shot> --seconds N [--window "Título"] [--scale 2]. Antes de que comience, dile al usuario exactamente qué pasos realizar. F8 deja una marca y F9 detiene.
• files: fishvideo screenrec import <dir> <shot> recording.mp4.

Los tres producen la misma carpeta de captura. La escena tour (frame: inset) agrega el cursor con brillo, ondas de clic y SFX de clic, un zoom de 1.6–2× al cursor, un foco y tarjetas STEP. Graba a escala 2 para que los zooms se mantengan nítidos.

Música:

• Una pista de biblioteca: assets search <dir> "<brief.music.search>" --kind music, luego assets get, y coloca el archivo en assets/music/.
• O deja la partitura sintetizada. Establece music.source: synth para forzarlo.

SFX: ejecuta fishvideo assets sfx-pack una vez (Kenney CC0). Agrega más con assets search --kind sfx (Freesound CC0) en assets/sfx/<tipo-de-indicador>/.

Voz: escribe la narración (paso 4), luego ejecuta fishvideo voice <dir>. Vuelve a ejecutar el guión gráfico para que las escenas se vuelvan a sincronizar con los clips reales. Si el usuario grabó su propia narración, ejecuta fishvideo voiceover <dir> recording.wav en su lugar: alinea la grabación con el guión usando faster-whisper y la corta por línea.

Emoción: asigna a cada escena un mood: (curious, tense, urgent, excited, warm, serious, reflective, triumphant, neutral). Establece velocidad y tono por línea, y estilo en ElevenLabs. La puntuación da forma a la entrega en cada motor: ... pausa, ? y ! elevan, las oraciones cortas impactan. Varía el estado de ánimo a lo largo de los compases: un tono plano durante 40 segundos es la queja de "voz genérica". Los silencios dentro de una línea se cortan automáticamente (pacing.max_word_gap).

Sincronización musical: para una pista de biblioteca, ejecuta fishvideo beats <track>. Establece el bpm del guión gráfico a su tempo y music.offset para que un ritmo o la caída caigan en tu mayor revelación.

Grabaciones de pantalla: ejecuta fishvideo screenrec tighten <dir> <shot> para acelerar los tramos de inactividad. Nunca hagas esperar al espectador por un spinner de carga.

Paso 4: guión gráfico (tú lo escribes)

Ejecuta fishvideo script <dir>. Crea el andamiaje storyboard.yaml a partir de la receta de estilo (config/styles.yaml, recetas de estilo) como un esqueleto de compases lleno de TODOs. Sus tiempos son marcadores de posición. Luego escríbelo correctamente, en este orden:

1. Reemplaza cada TODO: copia, parámetros y narración. La tabla en la parte superior del catálogo de escenas enumera los parámetros requeridos.
2. Escribe brief.purpose y la estructura narrativa y los ganchos del guión en brief.script_notes. Esto es a lo que te refieres durante la escritura.
3. Escribe cada escena en el orden de la historia. Usa las plantillas de escena del catálogo. Cada escena tiene:
   • id: S01 … id: S01 … id: Sxx (sin espacios, sin caracteres especiales excepto -)
   • duration: en segundos (comienza con una estimación; se actualiza después de la grabación de voz y el renderizado de prueba)
   • type: (del catálogo)
   • params: (al menos los requeridos, a menudo más; todos van aquí, no en campos de nivel superior)
   • narration: (cada palabra de la narración; para voiceover, debe coincidir 1:1 con la grabación; para tts, debe ser exactamente lo que el motor leerá, incluyendo pausas y énfasis en notación SSML o de marca, según la configuración de voz)
   • mood:
   • caption: (opcional; si se omite, se usa narration en la composición de subtítulos)
4. Cada escena tiene su propia narración. Una escena sin narración obtiene una narración vacía, no unimos escenas sin narración. Las escenas de tipo title, divider, hook, reveal, CTA, outro a menudo tienen menos narración o ninguna. Está bien.
5. El número total de escenas para un video de 15–60 segundos es típicamente 8–15 (cada escena dura ~2–6 segundos). Para un video de 1–3 minutos, pueden ser 20–30 escenas.
6. Guarda y ejecuta fishvideo gate <dir>. La compuerta falla si:
   • Cualquier escena contiene un TODO
   • Cualquier escena carece de un parámetro requerido (sin cambiar el valor predeterminado)
   • duration es 0 o falta
   • narration está vacía cuando el parámetro narration_required de la escena es true
   • La puntuación total se desvía en más del 10% de la duración objetivo
   • Un guión sin diagrama para videos explicativos
   • Una escena de tipo desconocido
   • Discrepancias en la consistencia del color (paleta no coincidente)
   • mood está vacío para más del 20% de las escenas
   • La duración total es más del 15% más larga que la pista de música (si se usa una pista de biblioteca)
   • music.offset no está establecido (si se usa una pista de biblioteca)
   • El nombre del archivo de escena supera los 100 caracteres

Paso 5: imágenes fijas (apariencia)

Ejecuta fishvideo stills <dir>. Obtienes un fotograma de la mitad de cada escena que coincida con type y params. Muéstrale al usuario las más importantes (primeras 3–4) y pídele "sí" o "cambia la paleta". Ajusta los colores de brand en brief.yaml y vuelve a ejecutar si es necesario. Esto no es una compuerta dura, pero nunca omitas este paso para el primer video de un usuario.

Paso 6: renderizado

Ejecuta fishvideo render <dir>. Produce build/render/<slug>.mp4. El motor de composición:

• Lee storyboard.yaml y aplica los parámetros de escena exactamente
• Aplica el esquema de color de brand a cada elemento: fondos, tipografía, formas, luces
• Encuadra y escala los activos reales para que se ajusten a la composición de la escena y la máscara de recorte de regla de tercios
• Compone la narración (TTS o voz en off alineada) sobre la pista de música con el comportamiento de ducking exacto de sound.yaml
• Coloca los subtítulos usando el motor de subtítulos: centrados, no superpuestos, con una palabra destacada por línea (la más larga o la primera después de una pausa)
• Agrega transiciones de escena (swish, dissolve, zoom, wipe, glow morph, page turn, portal) entre cada cambio de escena

El renderizado puede durar varios minutos para videos complejos. Muestra el progreso. Si falla, muestra el error y detente para depurar.

Paso 7: QA y bucle de revisión

Ejecuta fishvideo qa <dir>. Obtienes un informe con:

• Comprobaciones de video: salida de píxeles, relación de aspecto, velocidad de fotogramas, tasa de bits
• Comprobaciones de audio: nivel de pico, nivel de voz, nivel de música, profundidad de duck, relación señal/ruido, volumen de SFX
• Comprobaciones de contenido: porcentaje de tiempo de inactividad (sin cambio visual), relación texto/imagen, legibilidad de subtítulos, densidad de CTA
• Comprobaciones de referencia: tasa de cambio vs. referencia, sincronización de swish vs. referencia, niveles de voz vs. referencia

Luego reproduces el render tú mismo (como agente, no puedes, así que depende del informe de QA). Si alguna comprobación falla, corriges el guión gráfico, los parámetros de escena o la configuración de audio, y vuelves a renderizar. Repite hasta que el QA pase o hayas hecho 3 intentos. Después de 3 intentos, muestra el informe y pide "proceder de todos modos" o "depurar más".

Paso 8: empaquetar

Ejecuta fishvideo package <dir>. Proporciona:

• build/package/<slug>.mp4 (video final)
• build/package/<slug>-thumbnail.jpg (miniatura – fotograma de la escena más visualmente impactante, con superposición de texto de 3 palabras y marca de la plataforma)
• build/package/<slug>-title.txt (título – gancho + beneficio, máximo 70 caracteres para Shorts, 100 para YouTube)
• build/package/<slug>-description.txt (descripción – gancho que se puede escanear, 3–5 viñetas de lo que se muestra, hashtags, enlaces)
• build/package/<slug>-tags.txt (etiquetas – 5–10 palabras clave relevantes, separadas por comas)
• build/package/<slug>-credits.txt (créditos – cada activo con licencia listado con su licencia y URL de origen)
• config/upload-settings.yaml (configuración de subida para la plataforma elegida: relación de aspecto, duración, límites de tamaño de archivo)

Muestra al usuario la carpeta build/package/ con los archivos y un resumen de lo que hay en cada uno. Pregunta si quieren subir ahora (si tienes capacidad de subida) o guardar para más tarde.

Paso 9: revisión final

Muestra al usuario el video empaquetado (ruta del archivo), la miniatura, el título, la descripción y las etiquetas. Pregunta:

• "¿Cambiar algo?" (guión, edición, voz, música, miniatura, título, descripción, etiquetas)
• "¿Añadir algo?" (escenas, transiciones, SFX, subtítulos)
• "¿Listo para subir?" (si dices que sí, el trabajo está hecho)
• "¿Subir ahora?" (opcional, dependiendo de la capacidad)

Si el usuario solicita cambios, regresa al paso apropiado (guión gráfico para cambios de contenido, renderizado para cambios de video, empaquetado para cambios de metadatos). No reinicies la entrevista a menos que el usuario quiera un tema diferente.

Paso 10: limpiar (preguntar)

Pregunta: "¿Quieres que elimine los archivos temporales de construcción?" Si dice que sí, ejecuta fishvideo clean <dir> --all. Si dice que no, déjalos. Nunca limpies sin permiso.

Resumen de comandos

Comando	Propósito
fishvideo doctor	Comprueba la configuración: dependencias, claves, extras
fishvideo new <dir> --prompt "..."	Crea un nuevo proyecto de video
fishvideo interview <dir>	Ejecuta la entrevista (preguntas interactivas)
fishvideo interview <dir> --set clave=valor	Establece una respuesta de entrevista
fishvideo interview <dir> --summary	Muestra todas las respuestas
fishvideo interview <dir> --confirm	Bloquea las respuestas y pasa a la creación
fishvideo voices <dir> --audition	Genera muestras de voz para que el usuario elija
fishvideo research <dir> --url ...	Agrega investigación de fuentes
fishvideo trends <dir> --topic ...	Busca tendencias
fishvideo yt search ...	Busca en YouTube
fishvideo yt download ...	Descarga un video de YouTube para referencia
fishvideo dissect <file> --out <dir>	Analiza un video de referencia
fishvideo assets search <dir> "..."	Busca activos con licencia
fishvideo assets get <dir> <ids>	Descarga activos
fishvideo assets cutout <in> <out>	Recorta un fondo de imagen
fishvideo assets clip <dir> <file> <id> --start S --dur S	Prepara material de archivo a partir de un video
fishvideo assets sfx-pack	Descarga el paquete SFX por defecto
fishvideo capture <dir>	Captura páginas web para un tour
fishvideo screenrec record <dir> <shot>	Graba la pantalla del escritorio
fishvideo screenrec import <dir> <shot> <file>	Importa una grabación existente
fishvideo screenrec tighten <dir> <shot>	Acelera el tiempo de inactividad en una grabación
fishvideo voice <dir>	Genera voz TTS
fishvideo voiceover <dir> <file>	Alinea una voz en off grabada
fishvideo beats <track>	Analiza el tempo de una pista musical
fishvideo script <dir>	Crea el andamiaje del guión gráfico
fishvideo gate <dir>	Comprueba que el guión gráfico está listo
fishvideo stills <dir>	Genera imágenes fijas de vista previa
fishvideo render <dir>	Renderiza el video
fishvideo qa <dir>	Ejecuta control de calidad
fishvideo package <dir>	Empaqueta el video y los metadatos
fishvideo clean <dir> [--all]	Elimina archivos temporales (pregunta primero)

---

Fish Video Skill v2 – Haz un video, no una presentación de diapositivas.