minhhoasqtt-prog/hmhshare-mkt-bien-tap-vlog-hyperframes

Editar vlog con HyperFrames

Convierte un video de charla grabado en bruto (con algunos rellenos) en un video 16:9 compacto, con mensaje claro, color bonito y texto.

Filosofía original / Fuentes

• Walter Murch, Regla de los Seis (In the Blink of an Eye): emoción 51% > historia 23% > ritmo 10% > dirección de la mirada > espacio 2D > espacio 3D. Seleccionar segmentos por emoción y flujo narrativo primero, los errores visuales se solucionan después.
• Casey Neistat: inicio → contexto → contenido → final; jump cuts intencionados; uso abundante de rellenos.
• Talking-head: la voz es la columna vertebral (L-cut), los rellenos se superponen, los punch-in ocultan los jump cuts.
• Ya probado: vlog grabado en coche de 11:22 → 5:22, 23 segmentos, 29 bloques de texto (plan de ejemplo en references/vi-du-plan.json).

Cuándo usar / NO usar

• Usar: video largo de una persona hablando (vlog, charla, livestream grabado, grabado en coche) que necesita acortarse + rellenos + texto, formato horizontal 16:9.
• No usar: short vertical 9:16 tipo TikTok con subtítulos que avanzan palabra por palabra; video con avatar IA / doblaje; solo necesitas subtítulos manteniendo el video original (usa /embedded-captions de HyperFrames).

Prerrequisitos

Instala según HUONG-DAN-CAI-DAT.md, luego ejecuta node <skill>/scripts/kiem-tra-may.mjs — debe mostrar todos ✓.

• ffmpeg/ffprobe, Node ≥ 18, npx hyperframes (probado con 0.8.168–0.8.169).
• whisper-cli (whisper.cpp) + modelo ~/.whisper-models/ggml-large-v3-turbo.bin (se puede cambiar con las variables WHISPER_BIN, WHISPER_MODEL).
• Mac: usa VideoToolbox, por lo que el corte es rápido (~2× tiempo real con 2.7K HEVC 10-bit); Windows/Linux: cambia a libx264 (más lento).
• Espacio en disco libre ≥ 0,6 GB por minuto de video de salida + 3 GB. La primera renderización descarga chrome-headless-shell (~150 MB).
• La fuente Be Vietnam Pro está incluida en assets/fonts/ (licencia SIL OFL, no requiere conexión).

Flujo de trabajo

S=<carpeta de la skill>/scripts (normalmente .claude/skills/hmhshare-mkt-bien-tap-vlog-hyperframes/scripts) W=<carpeta de trabajo>, ej. ~/vlog-lam-viec/<slug>. Los archivos de medios pesados deben estar aquí, NO en carpetas de sincronización en la nube (Google Drive, OneDrive, Dropbox…), ya que irá lento y dará errores.

Paso 1 — Preparación (máquina, ~1–3 minutos).

node $S/01-chuan-bi.mjs --work $W --main "<video principal>" --broll "<relleno1>,<relleno2>,..."

Resultado: probe.json, contact.jpg, loi-thoai.txt (marcas de cada palabra), main_clean.wav, proxies de relleno hfproj/media/bNN*.mp4 + broll.json. Si se vuelve a ejecutar, omite lo ya existente (usa --force para rehacer).

Paso 2 — Edición IA (lee references/chon-doan-bien-tap.md atentamente). Mira contact.jpg (posición del hablante → tam_zoom, lugar para el texto), lee loi-thoai.txt completo, define audiencia + mensaje (pregunta al usuario si no está claro), luego escribe $W/plan.json sección doan según references/plan-json.md. Prueba rápida de duración total:

node $S/02-cat-doan.mjs --work $W --main "<video principal>" --chi-tinh   # solo imprime ban-cat.txt, no corta

→ Punto de control (humano): si el usuario quiere revisar antes, envía la tabla ban-cat.txt y detente. Por defecto: continúa, incluye la tabla de montaje en el informe final.

Paso 3 — Corte + filtrado de audio + revisión de uniones (máquina).

node $S/02-cat-doan.mjs --work $W --main "<video principal>"

Genera hfproj/media/main_cut.mp4/.wav, segs.json, kiem-tra-noi.json. Si algún segmento muestra advertencia de palabra cortada, compara con cut-words.json (Whisper a veces falla); si es un error real, ajusta lui_dau/them_cuoi y vuelve a ejecutar.

Paso 4 — IA escribe texto + compone composición. Lee ban-cat.txt, escribe plan.json secciones chu (basado en doan + sau), canh_tram (por defecto {"nhip":20}), luego:

node $S/03-dung-hyperframes.mjs --work $W
cd $W/hfproj && npx hyperframes check --json        # debe: lint 0 errores, layout 0, contraste todo correcto
npx hyperframes snapshot --at <marcas que imprime el script>  # IA revisa contact sheet: saltos de línea feos, texto sobre rostro, color

Corrige plan/texto → vuelve a ejecutar 03 hasta que el fotograma esté limpio (si el texto es muy largo, acorta la frase, no reduzcas la fuente).

Paso 5 — Render + exportación (máquina, ~1,5× duración del video en Mac M1 Pro).

node $S/04-render-xuat.mjs --work $W --out "<carpeta de destino>" --quality delivery

Verifica duración, audio, LUFS, genera soat.jpg, luego copia el video + du-an-hyperframes/ + plan/segs/transcripción a la carpeta de destino. La IA revisa soat.jpg por última vez.

Paso 6 — Informe. Entrega al usuario: ruta del video, duración antes/después, tabla de montaje por marcas (segmentos clave, ideas principales), qué se eliminó, qué partes modificar en plan.json. Limpia caché de render (ver Notas).

Referencias

• scripts/lib.mjs: ffmpeg/whisper/búsqueda de frases, selección de códec según máquina.
• scripts/01-chuan-bi.mjs · 02-cat-doan.mjs · 03-dung-hyperframes.mjs · 04-render-xuat.mjs · kiem-tra-may.mjs.
• scripts/template.tpl: marco HTML + GSAP (9 tipos de texto, punch-in, integración de rellenos, Ken Burns).
• references/plan-json.md: formato del plan + tabla de tipos de texto · references/vi-du-plan.json: plan real de 23 segmentos / 29 textos.
• references/chon-doan-bien-tap.md: reglas de selección de segmentos, estructura narrativa, ritmo visual.
• Documentación de HyperFrames: https://hyperframes.heygen.com (si la máquina tiene las skills hyperframes, hyperframes-cli, léela también).

Notas / gotchas

• Las marcas de palabra de Whisper tienen un retraso de ~0,3–0,5 s respecto al audio real: el script ya adelanta 0,3 s el punto de entrada; si aún se corta, añade lui_dau.
• No crees proxies de todo el video original 2.7K/4K (11 minutos tardan ~40 minutos): solo corta los segmentos seleccionados (paso 3).
• No coloques un segundo archivo .html en la raíz de hfproj/: HyperFrames reporta multiple_root_compositions. La plantilla está en scripts/.
• Las advertencias de lint nested_structure_needs_subcomposition / timeline_track_too_dense son sugerencias de organización, se pueden ignorar.
• El render guarda caché de decodificación en la carpeta temporal del sistema ($TMPDIR/hyperframes-extract-cache-* en Mac/Linux, %TEMP% en Windows; ~2 GB para 5 minutos de video): bórrala al terminar.
• La fase "Checking browser" que dura varios minutos la primera vez es descargando el navegador, no se ha colgado.
• Si la transcripción tiene muchos errores ortográficos: el texto en pantalla debe escribirse correctamente, no copies la transcripción tal cual. Los subtítulos corridos para todo el video aún no están implementados en esta skill.
• Video HDR/LOG: conviértelo a SDR primero (el paso 1 mostrará una advertencia); el colorizador en tiempo real solo maneja Rec.709.
• La tarjeta de memoria de la cámara debe estar conectada desde el paso 1 hasta el final del paso 3 (el paso 3 lee el archivo original). Lo mejor es copiar el video al disco antes.
• Windows: las rutas con espacios deben ir siempre entre comillas.

Salida

<carpeta de destino>/: <slug>.mp4, du-an-hyperframes/ (index.html + config, sin medios), plan.json, segs.json, ban-cat.txt, loi-thoai.txt, kiem-tra-noi.json, broll.json, soat.jpg.