Video de Locución Completo (口播成片)
Fuente Oficial
Esta habilidad es creada y mantenida originalmente por chengfeng / AI产品自由.
https://github.com/Agentchengfeng/chengfeng-videocut-skills
Cuenta oficial: GitHub @Agentchengfeng; X @chengfeng240928; Xiaohongshu / WeChat Official Account / Bilibili / Douyin / Video Account AI产品自由.
Flujo Principal
Esta habilidad resuelve una sola cosa: convertir un video de locución en un video completo; la relación de aspecto y el estilo de animación están determinados por la configuración del usuario.
+-----------------------------+
| Entrada |
| Video + Subtítulos + Material opcional |
+--------------+--------------+
|
v
+-----------------------------+
| 1. Storyboard |
| Segmentación conceptual + Tipo de toma + Fuente visual |
+--------------+--------------+
|
v
+-----------------------------+
| 2. Vista previa de línea de tiempo |
| Video original/Capturas/HTML alineados con la locución |
+--------------+--------------+
|
v
+-----------------------------+
| 3. Síntesis |
| Exportar MP4 final según la relación de aspecto configurada |
+--------------+--------------+
|
v
+-----------------------------+
| Validación |
| ffprobe + Extracción de fotogramas clave |
+-----------------------------+
No presentes la tabla de indicaciones (cue table), los módulos HTML, el reproductor de revisión, el reproductor final ni el script de exportación como pasos separados del flujo de usuario. Son solo detalles de implementación dentro de los pasos "Vista previa de línea de tiempo" y "Síntesis".
Configuración del Usuario
Cada vez que se ejecuta esta habilidad, primero lee:
用户配置/default.json
Los elementos de configuración solo definen la selección actual del usuario:
{
"aspectRatio": "3:4",
"animationStyle": "xiaohei"
}
Valores compatibles:
3:4: Por defecto, vertical HD. Lienzo lógico1080x1440. Por defecto exporta a1620x2160con DPR1.5.16:9: Horizontal. Lienzo lógico y de exportación1920x1080.4:3: Horizontal. Lienzo lógico y de exportación1440x1080.animationStyle: Por defectoxiaohei. Las opciones disponibles provienen de动画/styles.json.
Los argumentos de línea de comandos tienen prioridad sobre la configuración del usuario. Cuando no hay argumentos explícitos, el script de exportación lee aspectRatio y el script de animación lee animationStyle. Para sobrescribir temporalmente la relación de aspecto:
--config /path/to/config.json
--ratio 16:9
--aspect-ratio 16:9
--width 1920 --height 1080
--dpr 1.5
No añadas configuraciones como preferencias visuales, plantillas, calidad de codificación, directorio de salida, márgenes de subtítulos, etc., en 用户配置/default.json. La configuración del usuario solo contiene la selección actual; el directorio de animaciones solo contiene el registro de opciones y las implementaciones de estilos específicos.
Estilo de Animación
La selección actual del estilo de animación se guarda en 用户配置/default.json:
animationStyle
El directorio de animaciones solo registra las opciones disponibles:
动画/styles.json
xiaohei corresponde a:
动画/ian-xiaohei-svg-motion/
Cuando un segmento de storyboard o un módulo HTML necesite animaciones explicativas, animaciones de proceso o resaltados con estilo dibujado a mano, usa por defecto las animaciones SVG con estilo de cómic negro (xiaohei). A menos que el usuario especifique explícitamente otro estilo de animación, no inventes un nuevo estilo sobre la marcha.
Entrada
Primero localiza estos archivos:
- Video principal:
source_cut.mp4,*_cut.mp4o el video editado especificado por el usuario. - Subtítulos:
subtitles.srt,video.srtosubtitles_with_time.json. - Guion opcional: Artículo, guion de locución, borrador del texto; solo se usa para entender la intención.
- Material opcional: Capturas de pantalla, páginas de producto, imágenes de comentarios, páginas de resultados, páginas de prueba en
assets/. - Reglas del proyecto: Si el proyecto actual tiene
AGENTS.mdoREADME.md, léelos primero.
Jerarquía de fuentes de verdad:
Audio real / Subtítulos > Video editado real > Archivos de material > Borrador del guion
Si el guion y los subtítulos reales no coinciden, los subtítulos y el audio tienen prioridad.
Paso 1: Storyboard
Por defecto, crea primero una página HTML de verificación de storyboard, no una tabla Markdown.
El proceso previo al storyboard debe ejecutarse en este orden:
- Segmentar por semántica de la locución: Agrupa las frases que hablan del mismo concepto, misma acción o misma evidencia en un solo segmento; no dividas mecánicamente por número de subtítulo.
- Luego, determina la tarea visual de cada segmento: ¿Es una demostración de operación, una explicación de imagen original, una prueba de resultado, una organización de conceptos o una expresión puramente textual?
- Luego, decide la fuente visual: Para segmentos que pueden probarse con grabación de pantalla real, captura de pantalla original, imagen original, prioriza el material original; solo diseña animaciones HTML / xiaohei cuando sea una explicación conceptual y la pantalla actual muestre principalmente texto, esté en blanco o tenga imágenes poco relevantes.
- Finalmente, entra en el diseño visual específico: Para cada segmento de animación HTML / xiaohei, primero escribe claramente su metáfora y acción independientes, luego implementa el módulo.
Ruta común:
review/storyboard-audit-vN.html
Por defecto basado en esta plantilla:
templates/storyboard-audit.html
El storyboard debe responder a la pregunta del usuario:
Cuando se dice esta frase, ¿qué debería ver la audiencia?
Al menos describe claramente para cada segmento:
- Rango de tiempo
- Número de subtítulo
- Locución completa
- Base de la segmentación semántica
- Tarea visual
- Tipo de toma:
Video original,Grabación de pantalla,Captura de pantalla original,Imagen original,Enfoque en infografía,Animación HTML,Texto + Animación - Fuente del material
- Acción de la cámara
Reglas de selección de toma:
- Demostración de operación: Usa el video original / grabación de pantalla original, no lo conviertas en una animación abstracta.
- Al hablar de contenido de imágenes, gráficos, capturas de error, capturas de producto: Usa directamente la imagen original o la captura de pantalla original; la animación solo debe hacer selecciones, anotaciones o enfoques locales.
- Operaciones reales, páginas de prueba, páginas de resultados, segmentos que requieren credibilidad: Conserva el video original o la captura de pantalla original.
- Las grabaciones de pantalla / fragmentos de video original se muestran por defecto en su formato original; solo cuando sea necesario evitar subtítulos uniformes posteriores, marca ese segmento como "ventana pequeña" de grabación de pantalla y deja un área segura para subtítulos en la parte inferior. No apliques la regla de ventana pequeña a todos los segmentos de grabación de pantalla de forma masiva.
- Organización de conceptos, relaciones de mecanismos, división de trabajo del sistema, resumen de puntos de vista, y cuando la pantalla actual muestre principalmente texto, esté en blanco o tenga imágenes poco relevantes: Crea animaciones HTML / xiaohei.
- Segmentos abstractos que pueden entenderse con texto breve: Usa texto + animación; el texto se encarga de nombrar, la animación de las relaciones y acciones.
- Si ya hay capturas de pantalla o infografías: prioriza su reutilización, no las redibujes.
- Cuando la misma imagen aparece varias veces, cada vez debe tener una tarea diferente: vista general, enfoque local, comparación, revisión de resultados.
- No hagas que todas las animaciones tengan la misma dinámica. Cada segmento de animación debe diseñar primero una metáfora de acción independiente y luego implementarla.
Estándares estrictos de diseño de storyboard:
- Una página solo cubre un concepto, una acción o un caso. Si en el mismo segmento de locución aparecen dos casos independientes, deben dividirse en dos páginas; no los metas en la misma tabla o animación para ahorrar páginas.
- Para cada segmento de animación HTML / xiaohei, primero debes escribir claramente "Cuando se dice esta frase, ¿qué sucede en la pantalla?" y luego implementarlo. La acción debe estar vinculada a una frase de locución o subtítulo específica; no apliques la misma entrada / parpadeo / ampliación de manera uniforme a todos los segmentos.
- Al hablar de imágenes originales, capturas de pantalla, páginas de resultados, el elemento visual principal debe ser el material original. El HTML solo se encarga de recortar, ampliar, seleccionar, anotar y cambiar el enfoque; no uses fotogramas de grabación de pantalla o redibujos para reemplazar la imagen original.
- Para imágenes largas y páginas web de resultados, recorta por defecto las áreas en blanco sin información. Prioriza mostrar el área que el público está escuchando; cuando la locución mencione el objeto correspondiente, puedes ampliar la imagen o parte correspondiente, dejando el resto en segundo plano.
- No deben aparecer rutas de material, instrucciones internas, explicaciones de acción o "Material original · img/xxx.png" en la pantalla del video. El storyboard puede escribir la fuente, pero la pantalla final solo debe conservar el contenido que la audiencia necesita ver.
- Si no es necesario un título, no lo pongas. En páginas de resultados, tablas, páginas de comparación de imágenes, prioriza que el elemento visual principal hable por sí mismo; solo conserva etiquetas cortas, nombres de modelo, nombres de métricas o anotaciones necesarias.
- Las páginas de comparación de datos priorizan tablas claras, alineación de columnas, etiquetas cortas y algunos resaltados. El tamaño de la fuente debe facilitar la lectura; no metas las palabras en cuadrados pequeños; si se puede explicar bien con una tabla simple, no hagas apilamientos complejos de tarjetas.
- Las tablas en videos cortos verticales no deben ser solo una pequeña tabla horizontal en el centro. La tabla debe ser el elemento visual principal durante la fase de datos, ocupando la zona segura principal; las instrucciones previas a la tarea, etiquetas de caso y frases de resumen solo aparecen en la fase de locución correspondiente, y deben desaparecer o retirarse a un espacio no ocupante al entrar en la fase final de comparación de datos.
- Las palabras de evaluación solo deben escribir resultados positivos/neutrales que la locución mencione explícitamente o que el剪辑 necesite enfatizar. Los elementos de comparación pueden dejarse en blanco o solo mostrar datos; no añadas palabras negativas como "lento y caro" a menos que la frase original de la locución sea ese juicio.
- Los iconos deben buscarse en el índice de la biblioteca de animaciones. No reemplaces iconos existentes de ChatGPT, Claude, Flash, Step, DeepSeek, Qwen, etc., con formas abstractas; los nuevos SVG proporcionados por el usuario deben almacenarse primero en la biblioteca de animaciones y actualizar el índice.
No entres en la vista previa de línea de tiempo antes de que se confirme la dirección del storyboard.
Paso 2: Vista previa de línea de tiempo (Timeline Preview)
Después de confirmar la dirección del storyboard, crea la vista previa de línea de tiempo.
Ruta común:
review/timeline-preview.html
Por defecto basado en esta plantilla:
templates/timeline-preview.html
La vista previa de línea de tiempo debe verificar:
- Si las transiciones de pantalla están alineadas con las frases de la locución.
- Si el video original ha sido reemplazado incorrectamente por HTML.
- Si los segmentos marcados como "ventana pequeña" de grabación de pantalla evitan el área segura de subtítulos en la parte inferior; los segmentos de grabación de pantalla no marcados no deben reducirse automáticamente a ventana pequeña.
- Si las capturas de pantalla, páginas y materiales de prueba están mal utilizados.
- Los materiales de imagen por defecto conservan los márgenes izquierdo y derecho; no los peguen al borde de la pantalla actual; solo reduce el tamaño por separado cuando sea necesario enfatizar la captura de pantalla completa.
- Si la pantalla tiene texto tapado, recortes o bordes negros.
- Los módulos HTML se ven bien por separado, pero ¿siguen funcionando cuando se colocan en toda la línea de tiempo?
Cuando la página de vista previa contenga video fuente, debe servirse con un servicio que admita HTTP Range; de lo contrario, el navegador no podrá buscar aleatoriamente y la barra de progreso se reiniciará. No uses un python -m http.server normal para previsualizar la línea de tiempo con MP4. Usa por defecto:
node ~/.Codex/skills/chengfeng-videocut-skills/口播成片/scripts/serve_range_preview.cjs \
--project-dir /absolute/path/to/project \
--port 8767
Genera cuando sea necesario:
docs/08-动画cue表-vN.md
html-modules/module-*.html
html-modules/xiaohei-*.html
Si se necesita hacer una nueva animación explicativa, primero lee animationStyle en 用户配置/default.json, luego busca la sub-habilidad (sub-skill) de animación correspondiente en 动画/styles.json.
Cada acción de animación debe estar vinculada a una frase de locución específica; no distribuyas el tiempo de manera uniforme. Las animaciones HTML de múltiples etapas deben gestionar explícitamente el estado de visibilidad: cuando aparezca la siguiente etapa, las tarjetas de explicación, etiquetas y anotaciones de la etapa anterior que ya no sean necesarias para la información deben ocultarse; no permitas que la etapa anterior siga ocupando el espacio visual principal, especialmente en tablas verticales, enfoques de capturas de pantalla y páginas de resultados.
Paso 3: Síntesis
Solo puedes sintetizar después de que el usuario haya confirmado la vista previa de la línea de tiempo.
Antes de la síntesis, crea o confirma:
final-player.html
Antes de escribir un nuevo final-player.html o un módulo HTML, lee:
references/artifact-contracts.md
Si el proyecto tiene módulos HTML, primero inyecta el modo de renderizado:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/write_render_mode.cjs \
--project-dir /absolute/path/to/project
La vista previa de la línea de tiempo y la exportación final deben usar el mismo contexto de renderizado HTML. Los módulos HTML deben incluir ?timeline=1&render=1 tanto en la página de vista previa como en final-player.html. La página de vista previa solo debe escalar proporcionalmente el lienzo final para que quepa en la ventana; los módulos no deben rehacer el diseño responsive basado en la ventana de vista previa.
Para la entrega en alta definición, no amplíes directamente el lienzo lógico CSS. Por defecto, 3:4 debe mantener un lienzo lógico de 1080x1440 y luego usar el DPR de captura de pantalla 1.5 para generar 1620x2160; de lo contrario, las tablas, tarjetas CSS y anotaciones de capturas de pantalla se volverán relativamente más pequeñas en la exportación, diferente a la vista previa.
Si hay una discrepancia de tamaño entre la vista previa y la exportación, primero verifica el CSS interno del módulo HTML, render-mode.js y el DPR de exportación. Confirma que el lienzo lógico de la vista previa y el de final-player sean los mismos. No vuelvas a exportar todo el video primero. La causa común es que el iframe de vista previa sea pequeño y se vea bien; el lienzo HD final activa límites de tamaño de vista previa como .photo-frame { max-width: ... }, .stage { width: min(...) }, .wrap { max-height: ... }, clamp(...), lo que hace que la exportación sea una "imagen pequeña". Orden de corrección:
- Usa
write_render_mode.cjspara regenerarhtml-modules/render-mode.js. - En la vista previa de la línea de tiempo, confirma que la URL del módulo HTML se haya convertido en
?timeline=1&render=1. - Confirma que
viewportenexport_final_video.cjssea el tamaño del lienzo lógico, ydprsea el factor HD. - Usa final-player para extraer un fotograma clave de ese módulo en el viewport de exportación real. Si es necesario, usa
getBoundingClientRect()para comparar el tamaño del contenedor visual principal.
Cuando proceses módulos SVG horizontales de xiaohei o SVG 16:9 en un lienzo vertical, está prohibido usar .wrap { transform: scale(...) } para resolver el problema de la "barra horizontal pequeña". El escalado general recortará los bordes izquierdo y derecho en el lienzo 3:4, especialmente las tarjetas de modelo, flechas y etiquetas de explicación distribuidas de izquierda a derecha. O bien reorganiza en una composición vertical, o mantén la zona segura completa; después de la modificación, debes extraer los fotogramas de los bordes izquierdo y derecho de ese módulo para verificar, no solo mirar el fotograma clave central.
Exportar el video final:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03
Por defecto, exporta para entrega en alta definición: fotogramas intermedios PNG sin pérdida, H.264 crf=14, preset=slow. Esto evita que la vista previa del navegador esté clara pero el texto pequeño y las líneas finas se vean suaves después de la exportación:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format png \
--crf 14 \
--preset slow
Solo cuando necesites ver el ritmo temporalmente y necesites un borrador rápido, degrada explícitamente:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format jpeg \
--quality 92 \
--crf 18 \
--preset medium
Las reglas de lectura de la relación de aspecto están en "Configuración del usuario". Cuando el proyecto difiera de la configuración del usuario, puedes pasar:
--config
--ratio
--aspect-ratio
--fps
--player
--stage
--frames-dir
--width
--height
--frame-format png|jpeg
--quality 100
--crf 14
--dpr 1.5
--device-scale-factor 1.5
Validación
La exportación exitosa no significa que el video final sea correcto. Debes hacer dos pasos:
- Usa
ffprobepara verificar la resolución, la tasa de fotogramas, la duración y el audio. - Extrae al menos 3 fotogramas clave y revísalos manualmente para asegurarte de que la imagen sea correcta.
- Para cada módulo HTML, extrae al menos 1 fotograma de final-player en el punto de tiempo de locución correspondiente y compáralo con el mismo punto de tiempo en la vista previa de la línea de tiempo; el tamaño, la posición, el recorte y la visibilidad deben ser consistentes. No uses solo
ffprobecomo evidencia de finalización.
Verifica la resolución según la relación de aspecto actual. Otras expectativas provienen de los valores predeterminados del script y la entrada real del proyecto. La configuración predeterminada actual es:
1620x2160
Lienzo lógico 1080x1440, DPR 1.5
3:4
30fps
Duración igual al video fuente editado
Con audio
Sin HUD, botones, línea de tiempo de revisión, UI del navegador
Límites
Adecuado para:
- Locución en chino
- Tutoriales, demostraciones de productos, presentaciones de resultados, explicaciones de conocimiento
- Videos ya editados y subtítulos disponibles; los materiales pueden añadirse después
- Video original + capturas de pantalla + imágenes de explicación HTML combinadas en un video final
No resuelve prioritariamente:
- Generar un video final solo a partir de un guion, sin video
- Edición compleja con múltiples cámaras y actores reales
- Ajuste de color fino y mezcla multipista que requieren archivos de proyecto de software de edición
- El usuario solicita directamente la publicación final sin haber visto el storyboard o la vista previa de la línea de tiempo
Higiene del Proyecto
Si agregas o modificas archivos dentro del área de trabajo de escritura del usuario, debes actualizar sincrónicamente el índice README del proyecto.
El registro de actividad local se unifica en:
log/
log/ solo registra experimentos locales, preferencias del usuario, conclusiones temporales y procesos de trabajo no publicados. Está prohibido subirlo a GitHub. Este directorio ya está ignorado por .claude/skills/.gitignore.
No agregues un nuevo README en este directorio de habilidad. Los archivos principales de esta habilidad solo conservan:
SKILL.md
templates/
references/
scripts/
用户配置/
动画/
动画/ se utiliza para consolidar sub-habilidades (sub-skills) de animación HTML/SVG/GSAP reutilizables para la creación de videos de locución, plantillas y reglas; los estilos opcionales están en 动画/styles.json, la selección actual está en 用户配置/default.json.