music-video

¿Qué hace music-video?

Convierte una canción terminada en un video musical a 24 fps. La canción es el audio maestro. Los intervalos de las escenas la cubren exactamente una vez.

Disparadores

• music video / MV / lyric video / visualizer / storyboard
• 音乐视频 / MV合成 / 歌词动画 / 歌曲动画

Capacidades

• code: inicializa un proyecto fijo con p5.js y p5.brush, luego anima la canción en JavaScript.
• hybrid: inspecciona imágenes de personajes locales, fotogramas de escenas y clips de video, luego los ensambla. No se llama a ninguna API de generación de imágenes o video.
• Análisis local de ritmo, onset, baja frecuencia y volumen para puntos de corte y señales de animación.
• Ensamblaje exacto por fotograma con la canción original como única banda sonora.

Entradas

Requeridas:

• song: audio local (.mp3, .wav, .m4a, .flac, .ogg, .aac)
• brief: la idea visual, la audiencia y las referencias necesarias
• mode: code o hybrid

Opcionales:

• lyrics: texto o .srt. Requerido antes del storyboard cuando el tiempo de la voz importa.
• assets: directorio de imágenes fijas y clips para hybrid
• aspect: 16:9 (predeterminado), 9:16, 1:1 o 4:3

Si el usuario desea crear primero una canción, usa text-to-music, luego regresa aquí con el archivo elegido.

Salidas

• <project>/output/final.mp4
• docs/CREATIVE_BRIEF.md, docs/STORYBOARD.md, docs/TASKS.md y docs/PROGRESS.md
• audio/analysis.json, y docs/inspect.json cuando existen activos

Flujo de trabajo

Ejecuta python3 skills/music-video/scripts/mv.py desde la raíz del repositorio. Si esta habilidad está instalada en otro lugar, usa el scripts/mv.py junto a este archivo. Crea el proyecto fuera del directorio de la habilidad.

1. Elige code cuando el video se dibuja en JavaScript. Elige hybrid cuando el usuario proporciona imágenes fijas o clips. Pregunta una vez cuando ninguno está claro.
2. Inicializa un proyecto aislado:

python3 skills/music-video/scripts/mv.py init \
  --project ./mv-project --song ./song.mp3 --lyrics ./lyrics.txt --mode code

python3 skills/music-video/scripts/mv.py init \
  --project ./mv-project --song ./song.mp3 --lyrics ./lyrics.srt \
  --assets ./clips --mode hybrid --aspect 16:9

3. Analiza la canción. Trata los cambios de tempo como aproximados y confirma los límites de las secciones desde el audio:

python3 skills/music-video/scripts/mv.py analyze --project ./mv-project

4. Obtén la temporización de la letra. Si el usuario no la proporcionó, usa speech-to-text solo cuando NOIZ_API_KEY o ~/.config/noiz/api_key ya existan. Nunca imprimas la clave. Si ninguna existe, pide letras o marcas de tiempo y no subas la canción.
5. Lee references/opus-5.5-prompt.md y síguelo. Escribe el brief creativo y el storyboard antes del código de escena o ensamblaje. Revisa la apertura y el pico principal antes de construir los otros capítulos.
6. En modo code, lee <project>/animation/ANIMATION_GUIDE.md antes de dibujar. Establece PROJECT.bpm y PROJECT.offset desde audio/analysis.json. El lienzo de la plantilla fija es 1920×1080; cambia studio.html y la ventana del renderizador antes de usar otra relación de aspecto. Verifica el movimiento con el renderizador de la plantilla:

node render.mjs --sheet=1,2,3 --out=../output/sheets/pilot.jpg
node render.mjs --strip=START:END --out=../output/sheets/pilot-motion.jpg
node render.mjs --clip --range=START:END --out=../output/pilots/opening.mp4

Ejecuta estos dentro de <project>/animation. Pasa --chrome o establece CHROME_PATH cuando Chrome no esté en una ubicación estándar. Una hoja de contactos solo muestra el diseño. Una --strip, o la reproducción de la apertura, pico y final, es la revisión de movimiento. 7. En modo hybrid, inspecciona los medios locales y detente si falta un clip requerido. No generes un reemplazo.

python3 skills/music-video/scripts/mv.py inspect --project ./mv-project

8. Escribe timeline.json usando references/timeline.schema.json. Los intervalos son inclusivos en start_frame y exclusivos en end_frame.
9. Ensambla y verifica el resultado:

python3 skills/music-video/scripts/mv.py assemble --project ./mv-project

Línea de tiempo

{
  "fps": 24,
  "width": 1920,
  "height": 1080,
  "audio": "audio/source.mp3",
  "scenes": [
    {
      "id": "opening",
      "start_frame": 0,
      "end_frame": 240,
      "source": "output/pilots/opening.mp4",
      "source_start": 0,
      "fit": "cover",
      "transition": "fade",
      "fade_frames": 6
    }
  ],
  "overlays": []
}

fade permanece dentro de su propia escena. No superpongas escenas para crear un fundido cruzado.

Finalización

Termina solo cuando cada elemento sea verdadero:

• [0, ceil(duration × 24)) está cubierto exactamente una vez, sin espacios ni superposiciones.
• final.mp4 tiene un flujo de video y la canción original completa.
• La apertura, el pico principal y el final fueron revisados en movimiento.
• La última historia leída tiene tiempo para aterrizar.
• docs/PROGRESS.md no tiene bloqueos abiertos.

Seguridad

init --mode code clona JohnHeibel/ClaudeAnimationBase en el commit 0ac8bf2b31942376cb6b8c4074715595d512acd2 dentro del proyecto. Esa plantilla tiene licencia MIT. El análisis, inspección, renderizado y ensamblaje se mantienen locales. El modo híbrido no sube medios y no llama a un servicio de generación de imágenes, video o música.

Requisitos

• ffmpeg y ffprobe
• Python 3.9+
• analyze: uv pip install 'numpy>=2,<3'
• Modo code: git, Node.js y Google Chrome
• Modo hybrid: solo activos locales

Limitaciones

• Esta habilidad no compone música, genera efectos de sonido ni crea imágenes y video a través de una API.
• La cuadrícula de ritmo asume un tempo mayormente constante.
• Los rellenos de acuarela en modo code pueden tomar segundos por fotograma sin una GPU discreta. Pide al renderizador que evite esos rellenos en gráficos integrados.
• El ensamblaje rechaza un clip que es más corto que su escena en lugar de congelarlo o re-temporizarlo.