frankhzh-source/digital-human-video-pipeline

Pipeline de producción de video con avatar digital (verificado localmente en todas las etapas ✅)

2026-09-21/22 probado de principio a fin: 74,8s de locución → 15,6s de clip de prueba (imagen A7 + clon de voz MiniMax + empaquetado HyperFrames) con 0 fallos en todo el flujo. Todos los scripts en D:\workbuddy\Claw\Claw, ejecutados con D:/Anaconda3/envs/ai/python.exe -X utf8 (faster_whisper en este entorno). 2026-09-29 añadido: [0] Compuerta de consistencia de guion: el eslogan/frase de cierre fue reescrito dos veces (ver sección de compuerta), ahora es un paso previo obligatorio con veto absoluto.

Resumen del flujo (compuerta + seis pasos)

[0] Compuerta de guion (obligatorio) → [1] Audio maestro → [2] Transcripción ASR + tabla de segmentos → [3] Clonación de voz MiniMax (receta B2)
    → [4] HeyGen photo avatar + sincronización de labios → [5] Capa transparente HyperFrames (ProRes4444)
    → [6] Composición ffmpeg (subtítulos/efectos de sonido/música de fondo/sonoridad) → Video final + portada

[0] Compuerta de consistencia de guion (obligatorio, veto absoluto, antes de cualquier acción de generación)

Contexto: el eslogan/SLOGAN/frase de cierre fue reescrito dos veces (2026-09-28: las cuatro preguntas de apertura cambiaron de dirección + perdieron el eslogan, retrabajo de 24 créditos; 2026-09-29: "ocupar la fuente" se cambió a "curso obligatorio"). Lección: confiar en la memoria/voluntad no es fiable: las reglas están escritas en la memoria, la infracción ocurre en medio de la tarea, cuando las reglas ya no están en contexto. La solución es reemplazar "voluntad" por "mecanismo": registro + verificación rígida del script + compuerta de aprobación manual.

Tres reglas de hierro:

1. El eslogan/SLOGAN/frase de cierre/firma debe verificarse palabra por palabra contra la fuente original — fuente = segmento ANCHOR del script TTS por fragmentos o fuente de subtítulos del video final, prohibido improvisar, prohibido "ajuste oral";
2. Borrador primero cita el original: después de redactar cualquier nuevo párrafo, primero pega el texto original que contiene el eslogan palabra por palabra para que el usuario lo apruebe, solo después permitir la entrada a generación;
3. Antes de la generación paga, debe pasar la compuerta: antes de acciones que consuman créditos como TTS/HeyGen, la verificación del eslogan debe pasar.

Operación (dos piezas):

• Registro: Consistencia de guion_borrador final.json (fuente autorizada única, las nuevas frases finales deben ser aprobadas por el usuario y registradas);
• Verificación: D:/Anaconda3/envs/ai/python.exe -X utf8 Herramienta_verificación de eslogan.py <archivos de destino...>
  • Soporta .md/.txt/.json (lectura directa), .ass (eliminar etiquetas, extraer texto de subtítulos), .py (extraer literales de cadena, cubre constantes de guion TTS);
  • Normaliza automáticamente puntuación/espacios en blanco y realiza coincidencia de subcadenas; closed_targets solo muestra advertencia, no bloquea;
  • exit 0 = PASAR, puede continuar; exit 1 = FALLAR, prohíbe entrar en generación paga; --self-test autocomprobación.
• Explicación detallada del mecanismo: references/copy-slogan-gate.md (versión publicada).

Puntos de integración de la compuerta (ejecutar uno por uno en cada período):

Momento	Acción
Después del borrador, antes del TTS	Herramienta_verificación de eslogan.py Herramienta_TTS período XX.py → debe PASAR
Antes de enviar HeyGen	Verificar de nuevo (evitar desviaciones por modificaciones intermedias)
Después del montaje final, antes de publicar	Herramienta_verificación de eslogan.py <sub.ass> <guion de publicación.md> → PASAR solo permite enviar a Feishu/publicar
Manejo de fallos	Rellenar palabra por palabra contra la fuente original; si es una frase final realmente nueva → usuario aprueba → actualizar registro → re-ejecutar PASAR

[1] Requisitos del maestro

• Final de oración completo (no usar versión truncada); sonoridad -16 LUFS; grabación limpia de 30–90s puede servir como material de registro de clonación.
• Para registro de clonación usar Audio_locución original_092211_final de oración_69s.m4a (no usar la versión de 74.8s con frases incompletas).

[2] Transcripción ASR + tabla de segmentos

D:/Anaconda3/envs/ai/python.exe -X utf8 Herramienta_transcripción ASR podcast.py <audio> --md transcripción_xxx.md

• Genera marcas de tiempo a nivel de palabra (.asr_cache/*.json con caché, re-ejecución instantánea); según transcripción, dividir en aproximadamente 5 segmentos, marcar S1–S5 y puntos de información;
• Segmento de prueba seleccionar 18–30s: el que contiene lectura mixta chino/inglés y pausas es el más representativo.

[3] Clonación de voz MiniMax + locución

Herramienta: Herramienta_clonación de voz MiniMax_genérica.py (clave .secrets/minimax.key + minimax_group.txt, conexión directa al sitio nacional sin proxy).

• --check gratis → --clone --yes clonar (regla voice_id: ≥8 caracteres alfanuméricos, comenzar con letra, usar haifengv1) → --t2a locución;
• Receta de locución fijada como "B2": speech-2.8-hd + speed:0.95, sin etiqueta de emoción (usuario acepta: tono ok, entonación de B2 aceptable);
• Prioridad de ajuste para tono rígido: mejorar oralidad del guion > speed 0.95 > emotion=happy > re-clonar con material más largo;
• Referencia de coste: HD 3.5 yuanes/10k caracteres, una oración < 1 centavo.

[4] HeyGen avatar digital

Prerrequisito: debe activar el proxy (verificar escucha en 127.0.0.1:7890 + prueba de conectividad mcp.heygen.com).

• Herramientas: Herramienta_preparación clip de prueba podcast A7_2026-09-21.py (gratis: verificar cuota/esquema/imagen/cargar audio) → Herramienta_envío clip de prueba podcast A7_2026-09-21.py (compuerta --yes);
• Imagen A7 + motor avatar_v; salida de clip en ~2 minutos, verificar con probe después de descargar;
• ⚠️ Coste unitario real ~0.85 créditos/segundo (clip de 15.7s probado 13 créditos, 559→546). Antes de enviar el video completo, tomar un segmento de 30s del medio para verificar el precio.

[5] Capa transparente HyperFrames (tarjetas/animaciones de gráficos)

Proyecto: _cards_hf/compositions/v2_testcard.html (cambiar guion solo modificar texto + marcas de tiempo).

• Modo de control: gsap.timeline({paused:true}) registrado en window.__timelines["main-video"] + elementos data-start/data-duration;
• Renderizado (aproximadamente 4.5–5 minutos de tiempo de máquina, overlay_v2.mov 172MB conservar hasta la versión final, no eliminar a medio camino — eliminarlo requiere re-renderizar 5 minutos):

export PATH="/d/ffmpeg:/c/Users/admin/.workbuddy/binaries/PortableGit/versions/1.2.0/usr/bin:$PATH"
cd _cards_hf && npx hyperframes render -c compositions/v2_testcard.html -f 25 --format mov \
  -o "../_v2/overlay_v2.mov"

• ⚠️ Cuatro escollos obligatorios (todos probados y superados):
  1. El elemento raíz debe tener data-composition-id="...", de lo contrario HF_DE_COMPOSITION_ROOT_MISSING;
  2. Utilizar data-width/data-height para el tamaño del fotograma (data-composition-width no se lee → produce salida vertical 1080×1920);
  3. En la ruta PATH de la máquina de renderizado deben estar tanto ffmpeg como ffprobe (en D:\ffmpeg faltaba ffprobe → npm i ffprobe-static --registry=https://registry.npmmirror.com se resuelve en un minuto; no descargar el paquete de 114MB desde gyan.dev, en China ~20KB/s y se desconecta);
  4. La salida del renderizado es 1920×1080, al componer escalar a 1072 para alinear con el video final.

[6] Composición ffmpeg y entrega

Herramienta: Herramienta_composición clip v2_2026-09-22.py (copiar una copia cada período, solo modificar las constantes SRC/OV/subtítulos/puntos en la parte superior).

• Cadena: zoompan punch-in (8.45/13.25s al 5% cada uno) → overlay ProRes4444 → subtítulos ASS (la ruta ass= debe ser ruta relativa con barras normales, las barras invertidas serán escapadas y tragadas) → tres efectos de sonido (adelay para alinear) → cama BGM (sidechaincompress para atenuación de voz) → loudnorm -14 LUFS;
• Subtítulos: división de oraciones con marcas de tiempo a nivel de palabra, palabra resaltada {\c&H6ABEE9&}palabra{\r} (BGR dorado); portada tomar fotograma en 13.8s.

BGM / Paradigmas de efectos de sonido (ya documentados: Organización_Paradigmas de BGM y efectos de sonido para video de conocimiento_2026-09-22.md)

Locución de conocimiento = Paradigma BGM B "acompañante informativo": el BGM es la luz del aula, no la música de fondo de un escenario.

1. Sin melodía (punteo/cuerda pulsada, no "canta"); 2. Rango medio/alto C4+ (notas largas ligadas en graves = drone de atmósfera = sensación opresiva, lección del v2.2); 3. Silencios con notas cortas; 4. BPM 88–104 ajustado a la velocidad del habla; 5. Frecuencias evitar voz 300Hz–3.4kHz; nivel -28~-32 LUFS relativo a voz + sidechain ducking (threshold 0.028 / ratio 7 / attack 180ms / release 1000ms).

• Dos preajustes en make_bgm_pluck (predeterminado) / make_bgm_pad (A/B de respaldo), cambiar con una sola palabra BGM_STYLE; cambiar estilo solo modificar tabla de acordes.

Tres efectos de sonido (receta fija, solo cambiar puntos): whoosh transición (lowpass ≤2400) → tick feedback (1.2–1.6kHz, volumen mínimo) → thump énfasis (≤2 veces en todo el video para signos de exclamación); relación de volumen énfasis 0.24 : transición 0.22 : feedback 0.165; cualquier ventana de 2s ≤1 punto.

Registro de costes (medidos reales)

Ítem	Coste
ASR / ffmpeg / HyperFrames / composición BGM	0
Clonación MiniMax	9.9 yuanes/tono (solo se cobra la primera síntesis); TTS ≈0.02 yuanes/frase
Clip de prueba HeyGen	13 créditos / 15.7s; 69s completo estimado ~59 créditos, versión 2:44 estimada ~140

Lista de verificación (revisar ítem por ítem después de la salida)

0. Compuerta de eslogan: Herramienta_verificación de eslogan.py <sub.ass> <guion de publicación.md> PASAR (frases finales palabra por palabra en su lugar, reglas de hierro de la sección [0]);
1. volumedetect: mean ≈ -17dB / max ≤ -2.5dB (sin clipping);
2. Tomar 3 fotogramas (tarjeta de gráfico / tarjeta de palabra clave / tarjeta de conclusión): rostro y manos sin obstrucción (zona segura: tarjeta izquierda 56–546px, tarjeta derecha 1150–1860px, título superior 84px, subtítulo inferior 200px);
3. Tres puntos de escucha: primeros 3s con energía, voz destacada, sensación de permanencia al final.

Pendientes (obligatorio antes de la versión final)

• Aprobación del maestro completo: versión de 69s con final de oración o volver a cortar el segmento completo de 2:44 (versión de 74.8s con frases incompletas desactivada);
• Incremento del video completo: tarjetas de capítulo A7 ×5 segmentos, S4 frase por frase en pantalla, expandir BGM a bucle de 4–8 compases + coda, tarjeta de atención de 3s.