0xsline/openchatcut

Exportação

Use as ferramentas de exportação do OpenChatCut para entrega. Uma solicitação de exportação deve chamar submit_export (ou submit_render_job para assíncrono) e, em seguida, usar track_export para status e entrega final, quando o resultado não for retornado imediatamente.

Política padrão:

• Prefira submit_export quando o usuário pedir para exportar/compartilhar/finalizar a timeline do OpenChatCut.
• Mantenha os originais localmente por padrão durante a edição. Faça upload dos originais apenas quando uma exportação/prova em nuvem precisar de ativos remotos e o usuário não tiver proibido o upload.
• Não envolva o ffmpeg do sandbox como uma ferramenta do OpenChatCut. Use o ffmpeg do sandbox para processamento completo de vídeo apenas quando o usuário solicitar explicitamente uma operação independente de arquivo local fora de um fluxo de trabalho de edição do OpenChatCut. Para tarefas de edição do OpenChatCut, não produza uma renderização local pré-editada ou achatada como a revisão principal/entregável final; use a exportação do OpenChatCut.

Exportação Durável

Use submit_export para o caminho de execução:

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

As opções de codec de vídeo são h264 (MP4, padrão) e vp8 (WebM). As opções de taxa de quadros do vídeo correspondem à IU do editor: 24, 25, 30, 50 ou 60; omita fps para corresponder à timeline. A exportação de áudio é MP3: passe "format":"audio" e omita codec / fps, a menos que você passe explicitamente "codec":"mp3".

submit_export retorna um renderId durável. Alguns tipos de exportação, como arquivos de legenda, podem ser concluídos imediatamente e retornar downloadUrl; vídeo/áudio geralmente exigem track_export para aguardar a conclusão.

Após obter cada downloadUrl:

• Resolva a pasta Downloads do usuário: ~/Downloads no macOS/Linux, ou %USERPROFILE%\Downloads no Windows.
• Antes de acionar qualquer download do agente/navegador, verifique a pasta Downloads em busca de artefatos de download recentes do Chrome dos últimos minutos que correspondam ao nome de exportação esperado, extensão ou nome base da URL de renderização/download. Inclua arquivos concluídos e arquivos .crdownload em andamento.
• Se existir um .crdownload fresco correspondente, não acione outro download. Aguarde até que o Chrome remova o sufixo .crdownload e o tamanho final do arquivo pare de mudar, então use esse arquivo concluído.
• Se um arquivo concluído fresco correspondente já existir, use-o diretamente em vez de baixar novamente.
• Se apenas arquivos mais antigos existirem, trate-os como colisões, não como a exportação atual.
• Não sobrescreva um arquivo existente; escolha um nome de arquivo numerado seguro, como nome (1).mp4, quando necessário.
• Sempre baixe o arquivo de exportação finalizado na pasta Downloads, não em um diretório temporário/de trabalho.
• Sempre mostre o vídeo baixado inline no chat. Se houver vários vídeos exportados, baixe todos e mostre todas as prévias, não apenas o primeiro.

Se o projeto contiver ativos apenas locais, faça upload/registre substitutos legíveis em nuvem antes de renderizar, ou use o caminho de Exportação CLI Local quando o usuário quiser permanecer local.

Relate o renderId retornado quando presente. O trabalho também fica visível na fila de exportação no canto superior direito do editor, incluindo progresso e cancelamento. Use saveToMediaPool:true quando o usuário pedir para manter o resultado em Meus Materiais ou quando o fluxo de trabalho ativo padronizar explicitamente para materialização automática, como livestream-to-clips; caso contrário, o padrão permanece uma exportação normal para download. Para vídeos longos, chame track_export uma vez com action:"wait" e timeoutSeconds:20. Se retornar waitExpired:true, reporte que a renderização continua em segundo plano e encerre o turno. Verifique mais tarde com action:"status"; esperas repetidas só mantêm o turno do Agente aberto. Não inicie outra exportação para a mesma timeline enquanto esta renderização estiver ativa.

Use track_export quando o usuário perguntar sobre o status da exportação/renderização, ou quando o turno atual precisar genuinamente aguardar uma renderização de vídeo/áudio enviada. Exportações de conector concluídas retornam downloadUrl; para cada entrada concluída, baixe o arquivo para Downloads usando as regras de segurança de colisão acima e mostre inline no chat:

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

Para a exportação mais recente do projeto, omita renderIds e passe "latest": true. track_progress é para trabalhos de geração/transcrição/upload, não para trabalhos de renderização.

Para XML NLE, use submit_export com format:"xml":

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

Os valores de nleFormat são fcp_xml para XML Premiere (padrão) e fcp_xml_resolve para XML DaVinci Resolve. Omita timelineId para a timeline ativa, ou passe um ID/prefixo de timeline para uma timeline não ativa. Leia e relate avisos: legendas, sólidos, SVG, atributos de clipe não suportados e gráficos em movimento não renderizados podem ser descartados pelo formato XML. Gráficos em movimento são representados no XML apenas quando um fluxo de exportação de MG transparente em ProRes fornece motionGraphicRenderKeys; caso contrário, o exportador os relata como descartados.

Para download de origem do media pool, use request_asset_download em um ativo de origem baseado em arquivo. Ele retorna uma URL/caminho de download de backend protegido para a mídia de origem original. Não use pull_asset para downloads do usuário; pull_asset é apenas para sandbox.

Para arquivos de legenda, use submit_export com format:"subtitles":

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

Os formatos são srt e txt. A exportação usa o tempo real das palavras na timeline do item de legendas, escopo de origem, variantes de tradução, substituições de texto de exibição e campos de ritmo como wordsPerPage / maxCharactersPerLine, e cria um trabalho de exportação durável para download. É apropriado para arquivos de legenda para download. Ainda não reutiliza o planejador de páginas de legenda Remotion do navegador, portanto, as quebras de linha/página visuais são temporalmente corretas, mas aproximadas em vez de idênticas byte a byte à paginação de legenda queimada. Para timelines não ativas, passe timelineId de manage_timelines ou read_project.

Para um gráfico em movimento como ProRes 4444 transparente, use export_motion_graphic_prores:

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

Prefira itemId ao exportar uma instância de timeline específica, porque o item carrega propertyOverrides ativas, como texto editado. Use assetId para um gráfico em movimento do media pool; o backend usará a primeira instância de timeline para esse ativo quando presente, correspondendo ao comportamento de exportação do media pool do editor. Para vários gráficos em movimento, passe itemIds ou assetIds em uma chamada. Cada gráfico em movimento ainda se torna uma renderização durável separada; use track_export com os renderIds retornados para aguardar, depois baixe através de cada caminho de download de renderização retornado.

Ao preparar XML que deve referenciar gráficos em movimento renderizados, passe "filenameMode":"xml" e o mesmo timelineId para export_motion_graphic_prores, em seguida, mantenha as motionGraphicRenderKey / motionGraphicRenderKeys retornadas; após a renderização ser concluída, passe essas chaves e o mesmo timelineId em submit_export.motionGraphicRenderKeys com format:"xml".

Renderização Local (esta compilação)

Toda a renderização é local: submit_export / submit_render_job acionam o serviço de renderização local (Chrome headless sobre o mesmo estado de timeline que o editor mostra), lendo a mídia diretamente de /media/uploads/ no disco. Não há requisito de S3, CLI ou trabalho em nuvem para aguardar ativos baseados em disco.

• submit_export: legendas/XML retornam de forma síncrona; vídeo/áudio também renderizam na chamada nesta compilação (timelines longas podem demorar — avise o usuário em vez de fazer polling).
• submit_render_job + track_export: a rota assíncrona — retorna um renderId imediatamente, faça polling com track_export (renderIds / latest / onlyActive), depois entregue ao usuário o caminho de download retornado.
• Ativos ainda em placeholders blob: (upload em andamento) ainda não podem ser renderizados — aguarde track_progress target=upload reportar pronto antes de enviar.

Fallbacks

Se uma renderização falhar porque os bytes de um ativo estão faltando (placeholder nunca religado, arquivo excluído do disco):

1. Peça ao usuário para religar o ativo em 我的素材 (离线素材横幅) ou reimportar o arquivo.
2. Para mídia com origem em URL, execute download_media novamente para restaurar os bytes, depois reenvie.

Não diga ao usuário que ele precisa entender HTML-in-Canvas, Remotion ou detalhes internos de armazenamento, a menos que esteja depurando. Explique no nível do produto:

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

Rastreamento de Resultados

Para submit_export, registre:

• renderId
• timeline/intervalo/resolução/codec/fps
• que o usuário pode baixar do painel de trabalhos de renderização do editor

Registre IDs de ativos carregados e qualquer fallback tentado quando a exportação em nuvem foi bloqueada por ativos apenas locais.