Exportar (archivo final)
Esta es la última etapa de la cadena, el único lugar en todo el producto donde realmente se dibujan píxeles.
Antes de ella, todo son anotaciones: el libro de cuentas registra "qué palabras decir", los subtítulos registran "qué escribir en la pantalla", las capas visuales registran "qué superponer", y la vista previa combina estos tres elementos en tiempo real para que el usuario los vea, sin guardarlos en disco. La exportación los quema en un solo archivo.
Requiere edit-list.json (obligatorio), subtitles.json, visuals.json + modules/
Produce archivo_final.mp4
Herramientas necesarias: Google Chrome en la máquina (para renderizar subtítulos y animaciones como imágenes). FFmpeg / FFprobe instalado desde el escritorio ya está dentro del directorio administrado del producto; la instalación solo por CLI aún requiere ffmpeg ≥ 6 en el sistema. Si falta Chrome, se mostrará un error claro; no intentes evitarlo: sin él no hay capa de subtítulos ni capa de animaciones.
Primero, lee y ejecuta la sección "Nivel de conclusión" del contrato de fase del skill de negocio. La exportación no entra en la máquina de estados de edición: no modifica ningún archivo del proyecto, no escritura en CAS, no avanza la etapa; el resultado es un archivo nuevo, y volver a ejecutarlo lo sobrescribe. Por lo tanto, no necesita confirmación.
0. Preparación
Primero, ejecuta la verificación de preparación del skill de actualización: comprobar si los skills están actualizados, si el Runtime es compatible; la raíz del plugin también se localiza allí (en los comandos de este documento, <raíz_del_plugin> se sustituye por esa ruta literal). Solo si está "listo" se continúa; si es "requiere nueva sesión" o "detener", se sigue su disposición (incluyendo la prohibición de "interfaz alternativa casera"), el skill de negocio no tiene su propia lógica de entorno.
Si el resultado de preparación es runtime.kind=desktop-managed, reutiliza directamente el CLI estable ya instalado por la aplicación de escritorio, las herramientas multimedia y el mismo servicio launchd/windows-task; no analices rutas de Electron, instales FFmpeg/Bun aparte ni inicies un segundo Runtime.
Comandos
node "<raíz_del_plugin>/scripts/ensure-running.cjs" --json
node "<raíz_del_plugin>/scripts/videocut-cli.cjs" export <proyecto> --dry-run --json # Primero ver el plan, sin codificar
node "<raíz_del_plugin>/scripts/videocut-cli.cjs" export <proyecto> --json # Generar archivo final (por defecto 2x, velocidad de fotogramas original)
node "<raíz_del_plugin>/scripts/videocut-cli.cjs" export <proyecto> --out /ruta/archivo_final.mp4 --json
node "<raíz_del_plugin>/scripts/videocut-cli.cjs" export <proyecto> --scale 1 --json # Solo resolución original
node "<raíz_del_plugin>/scripts/videocut-cli.cjs" export <proyecto> --keep-work --json # Conservar archivos intermedios y PNGs fotograma a fotograma para depuración
Si ensure-running falla por identidad incorrecta, conflicto de puertos o servicio no saludable, detenerse inmediatamente; no se permite usar foreground como reemplazo temporal para continuar la exportación.
Dos pasos, no ejecutar solo el segundo
① --dry-run primero informa el plan: duración, fotogramas, número de pantallas de subtítulos, número de capas visuales, número de segmentos de zoom, resolución de salida.
Léelo al usuario. Si los números no coinciden, el error está antes; diez minutos de codificación no lo arreglarán.
② Ejecución real: cuatro fases de progreso: assemble → overlay → compose → verify
Las warnings en --dry-run deben transmitirse textualmente. Solo reportan una cosa: algunas pantallas de subtítulos o capas visuales cuyas palabras ya fueron cortadas, por lo que no aparecerán en el archivo final. Esto es decisión de la etapa anterior, no algo que la exportación deba ocultar.
Nitidez: el video original es el límite; verificar su resolución antes de ampliar
Antes de exportar, verifica la resolución original (el campo source de --dry-run ya la tiene):
Ancho original ≥2560 (grabación nativa Retina) → --scale 1, la salida es nativa, el mejor caso
Ancho original <1920 (p. ej., 960×720) → detenerse primero: preguntar al usuario si tiene una exportación de alta definición de la misma grabación.
La herramienta de grabación a menudo puede reexportar la misma grabación a 3x resolución,
cambiar la fuente es más efectivo que cualquier posprocesamiento (ver sección siguiente). Si realmente no hay → --scale 2
--scale 2 es útil para fuentes de baja resolución porque: ampliar el original no lo hace más nítido, pero los subtítulos y animaciones se redibujan según la resolución de salida—el espectador realmente lee estos elementos; cuando la plataforma comprime de nuevo, la imagen más grande recibe un bitrate más alto.
No ajustes --fps para "hacerlo más nítido". La velocidad de fotogramas sigue al video original; cambiarlo solo desincronizará el muestreo de las animaciones con la grabación de pantalla.
Cambio de fuente: cuando el usuario proporciona una versión de alta definición de la misma grabación
Esto no forma parte del flujo de exportación—la exportación en sí siempre es de solo lectura. El cambio de fuente es una operación independiente sobre el material, después del consentimiento explícito del usuario; luego se vuelve a la exportación normal.
Primero determinar si es la misma grabación (las dos primeras condiciones son suficientes):
ffprobe -v error -show_entries format=duration -of csv=p=0 <dos_archivos> # Duración exacta al milisegundo
ffmpeg -v error -i <archivo> -map 0:a:0 -c copy -f md5 - # Flujo de audio bit a bit idéntico
# Luego extraer dos o tres fotogramas para comparar visualmente el contenido
Audio bit a bit idéntico = misma línea de tiempo: todas las palabras, libro de cuentas, subtítulos, capas visuales están vinculadas al ID de palabra; ninguna necesita modificarse. Esto es exactamente lo que significa "vincular palabra, no segundo" en el cambio de fuente.
Cuatro pasos para cambiar la fuente (se realizó realmente el 2026-07-29; el paso ③ se omitió entonces, y la vista previa de edición mostró inmediatamente "error de generación": la huella no está solo en un lugar; busca todas las huellas antiguas con grep para encontrarlas antes de actuar):
① Reemplazar archivos input/source.mp4 y uploads/source.mp4 son enlaces duros entre sí —
eliminar ambos, copiar el nuevo archivo a input/, y crear el enlace duro de vuelta a uploads/
(en macOS usar ln; en Windows usar New-Item -ItemType HardLink)
② Actualizar huella El source.sha256 en project.json debe cambiarse al del nuevo archivo
③ Buscar otro lugar workbench.json también guarda la huella sourceSha256,
y la previsualización de edición verifica precisamente este archivo—omitirlo hace que la vista previa se niegue a generarse
(Este es el comportamiento correcto del producto: si la huella no coincide, es mejor fallar que mostrar una vista previa antigua falsa)
④ Reexportar --scale 1 — cambiar la fuente es para obtener píxeles nativos; no ampliar más
Medida de seguridad: usa tu herramienta de búsqueda en todo *.json del directorio del proyecto para buscar los primeros 8 caracteres de la huella antigua; procesa cada lugar encontrado (los registros de caché como preview-edited/current.json se recalcularán automáticamente, no es necesario modificarlos manualmente).
Si el audio es diferente (regrabado, cortado, duración distinta) no es cambio de fuente, es un nuevo proyecto: las palabras deben transcribirse de nuevo y todas las anotaciones quedan invalidadas. No lo fuerces.
Verificación: tres cosas; sin una, la exportación no está completa
① El comando se completa con éxito El producto compara dimensiones, fotogramas, pistas de audio del archivo final con el plan punto por punto.
Si no coinciden, se genera un error readback_mismatch, el archivo se deja en disco como evidencia,
y la exportación no se considera completa
② Extraer fotogramas y ver píxeles Extraer fotogramas del archivo final y mirarlos. Al menos cubrir: un segmento de zoom,
un segmento de animación de pantalla completa, un segmento solo con subtítulos, y un borde entre capas
③ Escucha humana Nadie lo ha hecho realmente; siempre registrar como human listening UNVERIFIED
② No se permite usar capturas de pantalla de la vista previa como sustituto. La vista previa y el archivo final son dos rutas de renderizado distintas; la verificación busca precisamente si coinciden—usar imágenes de la vista previa como evidencia del archivo final es dar por supuesto lo que se está verificando.
Para juzgar el zoom, busca puntos de referencia discriminatorios; la impresión general engaña (ocurrió realmente el 2026-07-29): La pantalla con zoom 1.6x todavía parece "una página completa" en vista general; en miniatura, casi no hay diferencia con la visión general—antes se juzgó erróneamente un fotograma de zoom correcto como "zoom perdido", perdiendo media hora y reexportando dos veces. El método correcto es buscar evidencias que solo el recorte puede causar: elementos cortados por la mitad (burbujas partidas), bordes desvanecidos (barra lateral, barra de título). Compáralo con el mismo fotograma del video original para decidir de inmediato.
Para extraer fotogramas, usa ffmpeg:
ffmpeg -v error -ss 8.84 -i archivo_final.mp4 -frames:v 1 -y frame.png
Dónde buscar si hay problemas
--keep-work deja tres cosas en .chengfeng-videocut/export/ del proyecto, que separan directamente "cuál mitad falló":
assembled.mkv Solo la edición, sin ninguna superposición. Si falla = error en libro de cuentas o cortes
overlay/*.png Solo las superposiciones, con fondo transparente. Si falla = error en estilo de subtítulos o módulos
spans/*.mp4 Segmentos después de la composición. Si falla = error en zoom o alineación
Tabla de correspondencia:
Archivo final sin subtítulos/animaciones ¿Los overlay PNG son completamente transparentes? ¿El módulo no aceptó seek?
Animación se queda en primer fotograma El módulo no implementó seek, o la línea de tiempo GSAP no está paused
Pantalla completamente blanca Al módulo le falta `:root { color-scheme: dark }`
El cuadro de zoom está torcido El viewBox del módulo y el zoom de la capa no son el mismo conjunto de números
Archivo final más corto que el plan Algún span tiene menos fotogramas; ver el error en la fase compose
Destello de un segmento de video original en borde de capa La captura de overlay es obsoleta (validación de marcador de fotograma falló). El producto se basa en una barra de marcador de fotograma en la parte superior de cada página para demostrar que cada captura pertenece a un fotograma específico; si vuelve a ocurrir, primero verificar que el overlay PNG tenga la barra de marcador en la parte superior y que compose la haya recortado
No se encuentra Chrome Instalar Google Chrome; no cambiar a otra ruta de renderizado
Lo que NO está permitido
- No declarar "exportación exitosa" como "verificación aprobada"—el retorno exitoso del comando solo significa que el producto coincide consigo mismo, no que la imagen sea correcta
- No usar capturas de pantalla de vista previa, DOM, logs como sustituto de la extracción de fotogramas del archivo final
- No declarar human listening PASS si nadie escuchó
- No modificar archivos del proyecto (cambiar subtítulos, eliminar capas, mover libro de cuentas) para que la exportación funcione. Exportación es solo lectura, no escritura
- No hacer el trabajo de etapas anteriores en la exportación: si faltan subtítulos, ve a escribirlos; si falta imagen, ve a crearla; no improvises aquí