0xsline/openchatcut

Erros Conhecidos

Formato raw ao atualizar via edit_item

• Errado: { "id": "abc", "fromFrame": 30 }
• Correto: { "json": "{\"updates\":[{\"id\":\"abc\",\"fromFrame\":30}]}" }
• Use esta mesma estrutura de updates para movimentos, cortes e alterações de faixa comuns.

Formato raw ao adicionar via edit_item

• O novo item vai dentro do array adds da transação json: { "json": "{\"adds\":[{...}]}" }.
• Use edit_item para colocação simples de vídeo, por exemplo { "json": "{\"adds\":[{\"type\":\"video\",\"assetId\":\"...\",\"fromFrame\":0}]}" }.

Sobreposição na timeline

• Texto de erro: Overlap: updated item at ... would overlap existing item at ... on this track.
• Não force a gravação nem exclua o item conflitante silenciosamente.
• Repita a transação edit_item com um trackId explícito disponível, por exemplo uma atualização contendo "trackId":"V2", ou pergunte ao usuário qual camada deve prevalecer.

Restrições de caminho do workspace

• push_asset no MCP externo aceita apenas URLs http(s) públicas como filePath. Rejeita caminhos locais, caminhos do workspace e caminhos de anexos do chat.
• Para ativos de motion graphics, passe o código JSX via create_motion_graphic_from_code({ code:"...", name, width, height, durationInFrames }). push_asset não aceita mais um argumento code inline.
• Copiar mídia local para o workspace não resolve a importação de vídeo/áudio/imagem/GIF; use asset-import e import_media em vez disso.
• Use import_media action=create_session e depois execute o auxiliar de importação de mídia do OpenChatCut uma vez com o token retornado para arquivos mantidos pelo cliente.

Falha na conversão de vídeo no navegador

• O texto de erro geralmente inclui Unable to convert video without dropping audio/video tracks ou unknown_source_codec.
• Reexecute o auxiliar de importação de mídia do OpenChatCut; ele gerencia a conversão alinhada ao frontend e exibirá um erro acionável pelo usuário se a conversão for impossível.
• Não peça ao usuário para reimportar o mesmo arquivo através da interface do editor como alternativa — o caminho de conversão é o mesmo, o erro se repetirá. Corrija a fonte (reencodifique localmente com ffmpeg) ou escolha um arquivo diferente.
• Após o ativo substituto ser enviado/transcrito, exclua o ativo original com falha se ele não estiver em uso. O pool final de mídia limpo deve parecer uma importação bem-sucedida, não uma importação com falha mais um substituto.

Requisitos para Motion Graphics

• push_asset(type:"motion-graphic") requer width, height e duration ou durationInFrames.
• O código MG deve passar pelo validador do OpenChatCut.
• AbsoluteFill raiz não é válido para código MG gerado; use um div raiz com escala.
• Evite declarar uma variável local de nível superior chamada scale dentro do código MG. O validador/ runtime pode já reservar esse identificador; use um nome específico como uiScale.

Ressalva para desenvolvimento local com Zero

• Quando o backend roda em uma porta não padrão, use uma configuração de view-syncer Zero correspondente.
• Nesta POC, o backend 3010, o editor 5177 e o view-syncer 4850 estão intencionalmente isolados da pilha antiga 3000/5173/4848.

Ressalva do renderizador de frames da timeline

• Se view_timeline_frames falhar para um frame, o caminho de gravação do projeto ainda pode estar saudável — repita com menos frames ou um horário diferente antes de concluir algo.
• Ativos ainda em placeholders blob: (upload em andamento) renderizam como vazios; aguarde track_progress target=upload antes de tratar um frame em branco como um bug.
• Não relate sucesso de prova visual a menos que a ferramenta retorne conteúdo de imagem que confirme visivelmente o frame alvo.