0xsline/openchatcut

Exportación

Utiliza las herramientas de exportación de OpenChatCut para la entrega. Una solicitud de exportación debe llamar a submit_export (o submit_render_job para asíncrono), luego usar track_export para el estado y la entrega final cuando el resultado no se devuelva de inmediato.

Política predeterminada:

• Prefiere submit_export cuando el usuario pide exportar/compartir/finalizar la línea de tiempo de OpenChatCut.
• Mantén los originales locales de forma predeterminada durante la edición. Sube los originales solo cuando una exportación/prueba en la nube necesite activos remotos y el usuario no haya prohibido la subida.
• No envuelvas el trabajo de ffmpeg del sandbox como una herramienta de OpenChatCut. Usa ffmpeg del sandbox para el procesamiento completo de video solo cuando el usuario solicite explícitamente una operación independiente de archivo local fuera de un flujo de trabajo de edición de OpenChatCut. Para tareas de edición de OpenChatCut, no produzcas un renderizado local preeditado o aplanado como revisión principal/entregable final; usa la exportación de OpenChatCut.

Exportación Duradera

Usa submit_export para la ruta de ejecución:

{
  "format": "video",
  "codec": "h264",
  "resolution": "1080p",
  "fps": 30,
  "name": "final-cut"
}

Las opciones de códec de video son h264 (MP4, predeterminado) y vp8 (WebM). Las opciones de fotogramas por segundo de video coinciden con la UI del editor: 24, 25, 30, 50 o 60; omite fps para que coincida con la línea de tiempo. La exportación de audio es MP3: pasa "format":"audio" y omite codec / fps a menos que pases explícitamente "codec":"mp3".

submit_export devuelve un renderId duradero. Algunos tipos de exportación, como los archivos de subtítulos, pueden completarse inmediatamente y devolver downloadUrl; el video/audio generalmente requiere track_export para esperar la finalización.

Después de obtener cada downloadUrl:

• Resuelve la carpeta de Descargas del usuario: ~/Downloads en macOS/Linux, o %USERPROFILE%\Downloads en Windows.
• Antes de activar cualquier descarga del agente/navegador, verifica la carpeta de Descargas en busca de artefactos de descarga de Chrome recientes de los últimos minutos que coincidan con el nombre de exportación esperado, extensión o nombre base de la URL de render/descarga. Incluye tanto los archivos completados como los archivos en progreso .crdownload.
• Si existe un .crdownload fresco coincidente, no actives otra descarga. Espera hasta que Chrome elimine el sufijo .crdownload y el tamaño final del archivo deje de cambiar, luego usa ese archivo completado.
• Si ya existe un archivo completado fresco coincidente, úsalo directamente en lugar de descargar de nuevo.
• Si solo existen archivos más antiguos, trátalos como colisiones, no como la exportación actual.
• No sobrescribas un archivo existente; elige un nombre de archivo numerado seguro como nombre (1).mp4 cuando sea necesario.
• Siempre descarga el archivo de exportación terminado en la carpeta de Descargas, no en un directorio temporal/workspace.
• Siempre muestra el video descargado en línea en el chat. Si hay varios videos exportados, descárgalos todos y muestra cada vista previa, no solo la primera.

Si el proyecto contiene activos solo locales, sube/registra reemplazos legibles en la nube antes de renderizar, o usa la ruta de Exportación CLI Local cuando el usuario quiera permanecer local.

Informa el renderId devuelto cuando esté presente. El trabajo también es visible en la cola de exportación en la parte superior derecha del editor, incluido el progreso y la cancelación. Usa saveToMediaPool:true cuando el usuario solicite conservar el resultado en Mi Media o cuando el flujo de trabajo activo tenga como predeterminado explícito la materialización automática, como livestream-to-clips; de lo contrario, el valor predeterminado sigue siendo una exportación descargable normal. Para videos largos, llama a track_export una vez con action:"wait" y timeoutSeconds:20. Si devuelve waitExpired:true, informa que el renderizado continúa en segundo plano y finaliza el turno. Verifícalo más tarde con action:"status"; las esperas repetidas solo mantienen el turno del Agente abierto. No inicies otra exportación para la misma línea de tiempo mientras este renderizado esté activo.

Usa track_export cuando el usuario pregunte sobre el estado de la exportación/renderizado, o cuando el turno actual necesite genuinamente esperar un renderizado de video/audio enviado. Las exportaciones de conectores completadas devuelven downloadUrl; para cada entrada completada, descarga el archivo a Descargas usando las reglas de seguridad contra colisiones anteriores y muéstralo en línea en el chat:

{
  "action": "status",
  "renderIds": "abc123"
}

Para la exportación del proyecto más reciente, omite renderIds y pasa "latest": true. track_progress es para trabajos de generación/transcripción/subida, no para trabajos de renderizado.

Para XML NLE, usa submit_export con format:"xml":

{
  "format": "xml",
  "nleFormat": "fcp_xml_resolve",
  "timelineId": "abc123"
}

Los valores de nleFormat son fcp_xml para XML de Premiere (predeterminado) y fcp_xml_resolve para XML de DaVinci Resolve. Omite timelineId para la línea de tiempo activa, o pasa un id/prefix de línea de tiempo para una línea de tiempo no activa. Lee e informa advertencias: los subtítulos, sólidos, SVG, atributos de clip no compatibles y gráficos en movimiento no renderizados pueden ser eliminados por el formato XML. Los gráficos en movimiento solo se representan en XML cuando un flujo de exportación de MG transparente-ProRes proporciona motionGraphicRenderKeys; de lo contrario, el exportador los informa como eliminados.

Para la descarga de fuente del pool de medios, usa request_asset_download en un activo de origen respaldado por archivo. Devuelve una URL/ruta de descarga de backend protegida para el material de origen original. No uses pull_asset para descargas de usuario; pull_asset es solo para sandbox.

Para archivos de subtítulos, usa submit_export con format:"subtitles":

{
  "format": "subtitles",
  "subtitleFormat": "srt"
}

Los formatos son srt y txt. La exportación usa la sincronización real de palabras en la línea de tiempo del elemento de subtítulos, el alcance de la fuente, las variantes de traducción, las anulaciones de texto mostrado y los campos de ritmo como wordsPerPage / maxCharactersPerLine, y crea un trabajo de exportación descargable duradero. Es apropiado para archivos de subtítulos descargables. Todavía no reutiliza el planificador de páginas de subtítulos de Remotion del navegador, por lo que los saltos de línea visual/saltos de página son correctos en tiempo pero aproximados, no idénticos byte a byte a la paginación de subtítulos quemados. Para líneas de tiempo no activas, pasa timelineId de manage_timelines o read_project.

Para un gráfico en movimiento como ProRes 4444 transparente, usa export_motion_graphic_prores:

{
  "itemId": "abc123",
  "filenameMode": "asset"
}

Prefiere itemId al exportar una instancia de línea de tiempo específica, porque el elemento lleva propertyOverrides activos, como texto editado. Usa assetId para un gráfico en movimiento del pool de medios; el backend usará la primera instancia de línea de tiempo para ese activo cuando esté presente, coincidiendo con el comportamiento de exportación del pool de medios del editor. Para varios gráficos en movimiento, pasa itemIds o assetIds en una sola llamada. Cada gráfico en movimiento sigue siendo un renderizado duradero separado; usa track_export con los renderIds devueltos para esperar, luego descarga a través de cada ruta de descarga de render devuelta.

Al preparar XML que debe hacer referencia a gráficos en movimiento renderizados, pasa "filenameMode":"xml" y el mismo timelineId a export_motion_graphic_prores, luego conserva el motionGraphicRenderKey / motionGraphicRenderKeys devuelto; después de que el renderizado se complete, pasa esas claves y el mismo timelineId en submit_export.motionGraphicRenderKeys con format:"xml".

Renderizado Local (esta compilación)

Todo el renderizado es local: submit_export / submit_render_job impulsan el servicio de renderizado local (Chrome sin cabeza sobre el mismo estado de línea de tiempo que muestra el editor), leyendo medios directamente de /media/uploads/ en el disco. No hay requisito de S3, ni CLI, ni trabajo en la nube para esperar en activos respaldados por disco.

• submit_export: los subtítulos/XML se devuelven sincrónicamente; el video/audio también se renderizan en la misma llamada en esta compilación (las líneas de tiempo largas pueden tomar un tiempo: advierte al usuario en lugar de sondear).
• submit_render_job + track_export: la ruta asíncrona: devuelve un renderId inmediatamente, sondea con track_export (renderIds / latest / onlyActive), luego entrega al usuario la ruta de descarga devuelta.
• Los activos que todavía están en marcadores de posición blob: (subida en vuelo) aún no se pueden renderizar: espera a que track_progress target=upload informe que está listo antes de enviar.

Fallos

Si un renderizado falla porque faltan los bytes de un activo (el marcador de posición nunca se reenlazó, el archivo se eliminó del disco):

1. Pide al usuario que reenlace el activo en 我的素材 (离线素材横幅) o vuelva a importar el archivo.
2. Para medios provenientes de URL, vuelve a ejecutar download_media para restaurar los bytes, luego reenvía.

No le digas al usuario que necesita entender HTML-en-Canvas, Remotion o los internos de almacenamiento a menos que esté depurando. Explica a nivel de producto:

• "本地快速导出"
• "素材还在上传，稍等再导"
• "需要先重新链接本地素材"

Traza del Resultado

Para submit_export, registra:

• renderId
• línea de tiempo/rango/resolución/códec/fps
• que el usuario puede descargar desde el panel de trabajos de renderizado del editor

Registra los IDs de activos subidos y cualquier fallo intentado cuando la exportación en la nube fue bloqueada por activos solo locales.