lilei0311/skill-digital-human-video

Video con Humano Digital · Habilidad del Agente

Objetivo

Recibir un tema o un guion preparado y producir un video vertical de talking-head con humano digital AI: guion -> MiniMax TTS -> HeyGen sincronización labial -> FFmpeg añadir subtítulos, título, identificador AI, PIP/BGM opcional -> MP4 + texto de publicación. En la primera ejecución solo se crea el Look ID del humano digital y se clona la voz (Voice ID); en llamadas posteriores se reutilizan, sin crear de nuevo. Se proporciona una vista previa de 15 segundos con coste de HeyGen; por defecto, el usuario debe ver la vista previa antes de producir la versión completa. Solo tras la aprobación explícita del usuario se ejecutan las dos fases consecutivas.

Instalación y Verificación

• Coloca la habilidad en ~/.codex/skills/digital-human-video o ~/.claude/skills/digital-human-video, asegurando que SKILL.md esté en la raíz de la carpeta.
• Python 3.10+, pip install -r requirements.txt, tener ffmpeg/ffprobe instalados en el sistema (con libass y codificador H.264). Funciona mejor con fuentes chinas disponibles.
• Copia .env.example a .env, y establece las claves de forma local y segura; no pidas al usuario que pegue claves, fotos o grabaciones de voz en el chat. Nunca incluyas .env en Git.
• Primero ejecuta: python scripts/dhv.py doctor, luego python scripts/dhv.py run --topic '...' --out ./outputs/example --dry-run.

Flujo de Operación (En Orden)

1. Confirmar Permisos y Materiales. Solo se aceptan retratos/voces reales de la persona o con autorización expresa. Prohibido replicar, suplantar o engañar a la audiencia sin consentimiento. Verificar permisos para fotos/videos y audio por separado; los videos sintetizados por AI deben llevar una identificación clara. La música y los materiales PIP deben tener licencia.
2. Configuración Única. La mejor muestra de voz es una grabación limpia de 30 a 60 segundos (MiniMax oficial acepta de 10 segundos a 5 minutos, ≤20MB, mp3/m4a/wav). Subir video/foto en HeyGen v3 para crear Avatar; se recomienda una foto frontal de alta definición. El entrenamiento de video puede requerir un consentimiento/verificación independiente de la persona real, que debe completarse, y el entrenamiento es asíncrono. Usa avatars para consultar los Look ID ya entrenados. Proporciona MINIMAX_VOICE_ID y HEYGEN_AVATAR_ID al pipeline posterior.
3. Primero Redactar el Guion. Si el usuario no proporciona texto, el LLM escribe automáticamente: gancho de 3 segundos → 2~3 argumentos → resumen, especificando audiencia, plataforma y duración estimada. No se pueden inventar datos no verificables. La creatividad en la edición/dirección puede ser manejada por Claude Opus 5.5 o por Codex; el modelo se encarga del guion y la planificación, el procesamiento real de medios lo ejecuta FFmpeg.
4. Vista Previa. run --mode preview: Reutiliza state.json y script.txt si existen; sintetiza audio para aproximadamente los primeros 55 caracteres (unos 15 segundos), genera el video del humano digital y produce preview_final.mp4. La duración de la vista previa no se garantiza exactamente 15 segundos si la velocidad del habla es diferente.
5. Plan de Dirección/Edición. Si el agente actual es Claude Opus 5.5 o se le puede delegar, pásale script.txt, el tema, la marca y la lista de materiales para que genere edit-plan.json, cumpliendo estrictamente las claves JSON de examples/edit-plan.json: headline, brand, key_points[{text,start,end}], pip_start/end, subtitle_font_size, music_volume (0~0.3). Los tiempos de inicio/fin deben estar dentro de la duración del video final. --edit-plan hace que FFmpeg ejecute animaciones de tarjetas de texto clave/PIP, estilos de subtítulos y volumen de BGM; si no hay Opus, Codex/el agente actual genera el mismo JSON. El modelo solo toma decisiones, no pretende renderizar el video por sí mismo.
6. Revisar y Ejecutar. El usuario verifica sincronización labial, claridad, derechos de autor, subtítulos y realismo. Si todo está bien, ejecuta run --mode full --approve; si ya hay autorización y se ha elegido explícitamente no hacer revisión manual, ejecuta run --mode full --auto-approve para producir las dos fases automáticamente. No publicar directamente en redes sociales sin autorización.
7. Validar y Entregar. Verifica la duración de full_final.mp4, sincronización audio-video, subtítulos, superposición de títulos, volumen de música, identificador de síntesis AI, y entrega publish.md. Antes de publicar externamente, se debe verificar la veracidad de los hechos y las reglas AIGC de la plataforma.

Uso desde CLI (En la raíz de la habilidad)

# Inicialización: caricatura y audio propios, solo usar flag de consentimiento si se tiene autorización legal conocida
python scripts/dhv.py avatar --file ./myself.mp4 --kind digital_twin --name 'My Presenter' --i-own-the-likeness
python scripts/dhv.py avatars  # El entrenamiento puede requerir espera o verificación oficial
python scripts/dhv.py clone --file ./myvoice.wav --voice-id MyBrandVoice2026 --i-own-the-voice

# Vista previa: por defecto, el modelo de texto MiniMax escribe el guion; también se puede pasar --script-file para omitir el LLM
python scripts/dhv.py run --topic 'Cómo ayuda la IA a las empresas a reducir procesos repetitivos' --out ./outputs/ai-workflow --mode preview --edit-plan ./examples/edit-plan.json

# Solo después de la revisión del usuario se ejecuta el video completo
python scripts/dhv.py run --topic 'Cómo ayuda la IA a las empresas a reducir procesos repetitivos' --out ./outputs/ai-workflow --mode full --approve

# Con aprobación explícita para desatendido, un solo comando para vista previa + video final (las llamadas API de video se facturan por separado para cada segmento)
python scripts/dhv.py run --topic 'Entiende el humano digital en un minuto' --out ./outputs/demo --mode full --auto-approve

# Materiales opcionales
python scripts/dhv.py run --script-file ./script.txt --out ./outputs/manual --mode preview --music ./licensed-bgm.mp3 --broll ./owned-broll.mp4

Directrices de Ejecución para el Agente

• No describir --dry-run o pruebas unitarias como "ejecución real en HeyGen/MiniMax". Sin claves válidas de pago y materiales autorizados, solo se pueden verificar renderizados offline o formatos de solicitud.
• Si una llamada API asíncrona agota el tiempo de espera, mostrar el video_id en state.json y reutilizarlo, no reconstruir desde cero para evitar facturación duplicada.
• La clonación de voz requiere autenticación real en MiniMax; si voice_id no se usa para TTS formal en 7 días, podría caducar. Priorizar intentar con el timbre existente, no clonar silenciosamente de nuevo.
• Los archivos de subtítulos de la plataforma pueden no ser precisos palabra por palabra; si no se devuelve un SRT utilizable, la herramienta generará subtítulos de tiempo estimado y marcará approximate en state.json. Revisar antes de entregar; para precisión palabra por palabra, se recomienda un ASR adicional.
• Ante límites de tamaño de video, políticas de entrenamiento, autenticación o cuota, reportar el error específico, no afirmar que se completó automáticamente.
• No iniciar sesión ni publicar directamente en Douyin, Kuaishou, WeChat Video, Xiaohongshu, Bilibili, etc., ya que no se ha integrado la API de autorización de esas plataformas; solo generar publish.md para revisión antes de publicar.
• Evitar incluir claves API, grabaciones originales, timbres similares y activos generados originalmente en repositorios de código públicos.

Referencias

• Para detalles de API y configuración regional, consulta references/api.md.
• Para entrega y solución de problemas, consulta README.md.