0xsline/openchatcut

Errores Conocidos

Forma raw de actualización de edit_item:

• Incorrecto: { "id": "abc", "fromFrame": 30 }
• Correcto: { "json": "{\"updates\":[{\"id\":\"abc\",\"fromFrame\":30}]}" }
• Usa esta misma forma updates para movimientos, recortes y cambios de pista comunes.

Forma raw de adición de edit_item:

• El nuevo elemento va dentro del array adds de la transacción json: { "json": "{\"adds\":[{...}]}" }.
• Usa edit_item para colocaciones simples de video, por ejemplo { "json": "{\"adds\":[{\"type\":\"video\",\"assetId\":\"...\",\"fromFrame\":0}]}" }.

Superposición en la línea de tiempo:

• Texto de error: Overlap: updated item at ... would overlap existing item at ... on this track.
• No fuerces la escritura ni elimines el elemento conflictivo en silencio.
• Reintenta la transacción edit_item con un trackId explícito disponible, por ejemplo una actualización que contenga "trackId":"V2", o pregunta al usuario qué capa debe ganar.

Restricciones de rutas del espacio de trabajo:

• push_asset en el MCP externo solo acepta URLs públicas http(s) como filePath. Rechaza rutas locales, rutas del espacio de trabajo y rutas de archivos adjuntos del chat.
• Para assets de gráficos en movimiento, pasa el código JSX mediante create_motion_graphic_from_code({ code:"...", name, width, height, durationInFrames }). push_asset ya no acepta un argumento code en línea.
• Copiar medios locales en el espacio de trabajo no es la solución para importaciones de video/audio/imagen/GIF; usa asset-import e import_media en su lugar.
• Usa import_media action=create_session, luego ejecuta el auxiliar de importación de medios de OpenChatCut una vez con el token devuelto para archivos retenidos por el cliente.

Fallo de conversión de video en navegador:

• El texto de error a menudo incluye Unable to convert video without dropping audio/video tracks o unknown_source_codec.
• Vuelve a ejecutar el auxiliar de importación de medios de OpenChatCut; él gestiona la conversión alineada con el frontend y mostrará un error accionable si la conversión es imposible.
• No pidas al usuario que reimporte el mismo archivo a través de la interfaz del editor como solución alternativa — la ruta de conversión es la misma, el error se repetirá. Arregla la fuente (re-codifica localmente con ffmpeg) o elige un archivo diferente.
• Después de que el asset de reemplazo se haya subido/transcrito, elimina el asset original fallido si no se usa. El pool de medios final limpio debe parecerse a una importación exitosa, no a una importación fallida más un reemplazo.

Requisitos de gráficos en movimiento:

• push_asset(type:"motion-graphic") requiere width, height, y duration o durationInFrames.
• El código MG debe pasar el validador de OpenChatCut.
• AbsoluteFill raíz no es válido para código MG generado; usa un div raíz con escalado.
• Evita declarar una variable local de nivel superior llamada scale dentro del código MG. El validador/tiempo de ejecución puede ya tener ese identificador reservado; usa un nombre específico como uiScale.

Advertencia sobre Zero en desarrollo local:

• Cuando el backend se ejecuta en un puerto no predeterminado, usa una configuración de view-syncer de Zero acorde.
• En esta POC, backend 3010, editor 5177 y view-syncer 4850 están intencionalmente aislados del stack anterior 3000/5173/4848.

Advertencia sobre el renderizador de fotogramas en línea de tiempo:

• Si view_timeline_frames falla para un fotograma, la ruta de escritura del proyecto aún puede estar sana — reintenta con menos fotogramas o un momento diferente antes de concluir algo.
• Los assets que aún usan placeholders blob: (subida en curso) se renderizan vacíos; espera a que track_progress target=upload antes de tratar un fotograma en blanco como un error.
• No informes éxito de prueba visual a menos que la herramienta devuelva contenido de imagen que confirme visiblemente el fotograma objetivo.