0xsline/openchatcut

Generador de Shaders

Solo envío: crea un trabajo de generación en el backend, devuelve jobId. Usa la herramienta track_progress para el ciclo de vida del trabajo después del envío.

Siempre usa generate.ts para nuevos shaders. La escritura manual es solo para editar código de assets existentes, nunca como alternativa cuando falla la generación.

Regla de catálogo primero: prueba los assets existentes antes de generar

Antes de generar un shader, llama a browse_library a menos que el usuario nombre un asset exacto que ya esté visible en read_project.

browse_library es la fuente de verdad para efectos integrados, transiciones integradas y assets de efectos/transiciones del proyecto. Los integrados son IDs de asset globales estables, no assets de base de datos por proyecto, por lo que pueden no aparecer en las listas de assets de read_project.

Aplica las entradas del catálogo con edit_item, no llames a submit_shader.

Buenas búsquedas en el catálogo:

browse_library(query: "zoom")
browse_library(category: "transitions", query: "dissolve")
browse_library(category: "audio-fx")

Genera solo cuando ninguna entrada del catálogo coincida lo suficientemente bien con la intención del usuario.

builtin:zoom solo está vinculado a pista – NO lo uses vinculado a elemento

El modo de efecto predeterminado es "item-bound" (se adjunta a un solo elemento mediante targetItemId). builtin:zoom NO se renderiza en modo item-bound – el renderizador lee los datos del zoom exclusivamente de los elementos de efecto vinculados a pista. Un zoom item-bound se inserta en la base de datos silenciosamente pero no muestra nada en la vista previa.

Usa mode: "track-bound" con trackId + trackBoundFrom + trackBoundDurationInFrames. Estos tres campos son obligatorios.

# Zoom en todo el clip de video
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<clip-trackId>","trackBoundFrom":<clip-fromFrame>,"trackBoundDurationInFrames":<clip-durationInFrames>,"propertyOverrides":{"magnification":1.5,"shape":"hold"}}]')

# Zoom en un subrango del clip (ej. fotogramas 90–150, un zoom rápido en un golpe de ritmo)
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]')

Obtén trackId / fromFrame / durationInFrames de read_project (cada elemento de video/imagen enumera su trackId y rango de fotogramas en la línea de tiempo).

Clave	Tipo	Rango / valores	Por defecto	Notas
magnification	número	1–4	1.5	Factor de zoom; 1 = sin zoom, 2 = 2× aumento
focalPointX	número	0–1	0.5	Punto focal horizontal (0 = izquierda, 1 = derecha)
focalPointY	número	0–1	0.5	Punto focal vertical (0 = arriba, 1 = abajo)
shape	selección	punch / hold / slow-push / instant	hold	Curva de animación
focalMode	selección	auto / manual	auto	auto elige el sujeto; manual usa focalPoint
easeInFrames	número	0–60	8	Fotogramas para suavizar entrada
easeOutFrames	número	0–60	8	Fotogramas para suavizar salida

Omite propertyOverrides por completo para el zoom predeterminado. Envía solo las claves que quieras cambiar: semántica de parche.

Bound a pista vs. bound a elemento: la regla general

Los elementos de efecto en el esquema tienen dos modos:

• item-bound (predeterminado): solo targetItemId. El efecto cubre toda la reproducción del elemento objetivo. Funciona para efectos de shader, LUTs, gradaciones de color, desenfoques.
• track-bound: trackId + trackBoundFrom + trackBoundDurationInFrames. El efecto cubre un rango de la línea de tiempo en una pista, independientemente de cualquier elemento. Obligatorio para builtin:zoom; también válido para cualquier efecto de shader cuando se quiere cubrir un rango específico de la línea de tiempo (ej. un cambio de color tipo transición en el límite de dos clips).

Por defecto, usa item-bound para efectos de shader. Usa track-bound cuando (a) el asset lo requiera (zoom), o (b) el efecto deba cubrir un rango de la línea de tiempo que no coincida con un solo elemento.

Propiedades de LUT integradas

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"builtin:slog3-s709","propertyOverrides":{"intensity":1}}]')

Clave	Tipo	Rango	Por defecto	Notas
intensity	número	0–1	1	Fuerza LUT; 1 = plena aplicación

Para cambiar: elimina el efecto y vuelve a añadirlo con un assetId diferente. Para eliminar: borra el elemento de efecto.

Estos están separados de los assets LUT .cube subidos por el usuario (ver "Aplicando un Asset LUT Existente" más abajo): esos usan una ruta de código diferente con assetId:"lut".

Puerta de Estado Beta

La generación de nuevos shaders está en beta. Antes de generar, advierte al usuario y espera confirmación explícita.

Usa el idioma del usuario. Chino: "新的特效/转场生成目前还是 beta 阶段，可能会有不稳定的问题。如果你坚持要做，我可以帮你实现." Omite si el usuario ya lo reconoció en la misma solicitud.

Destinos Soportados

Los efectos y transiciones se aplican a elementos de tipo video, image y gif.

Enrutamiento por Tipo

Antes de generar cualquier cosa, verifica primero dos rutas que no son de generación:

1. Entrada de catálogo – usa browse_library para efectos y transiciones integrados y del proyecto.
2. Asset LUT .cube subido por el usuario que ya existe en la biblioteca del proyecto – ruta de código separada, ver "Aplicando un Asset LUT Existente" más abajo. El asset aparece en read_project con type: lut.

El usuario quiere	--type
Apariencia de video (color, desenfoque, brillo, grano, distorsión)	effect
Gradación de color / look (teal-orange, cinemático, vintage, estilo LUT)	effect
Control de visibilidad (máscara, revelado, wipe, recorte de forma, desvanecimiento)	effect
Mezcla entre clips (crossfade, dissolve, slide, cubo 3D/volteo de página)	transition

"Estilo LUT" en la tabla significa generar una gradación de color GLSL nueva que se asemeje a una LUT – solo cuando el usuario quiere algo nuevo. Si quieren aplicar un archivo .cube que ya está en la biblioteca, no generes; vincula el asset existente.

No hay un generador separado de LUT o máscara para la ruta de generación – todo es effect.

Aplicando un Asset LUT Existente

Los archivos .cube subidos por el usuario se convierten en assets lut. Aplicar uno a un clip no es generación – es una sola llamada edit_item que adjunta un elemento de efecto cuyo assetId es la cadena literal "lut" y cuyo propertyOverrides.lut enlaza el ID del asset LUT real. (Contrato heredado; la API unificada de LUT enlaza directamente el ID del asset de efecto LUT – ver la descripción de edit_item).

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"lut","propertyOverrides":{"intensity":1,"lut":{"assetId":"<lut-asset-id>","assetType":"lut","type":"asset"}}}]')

Puntos clave:

• assetId es la cadena literal "lut", no el ID del asset LUT. El ID real del asset LUT va dentro de propertyOverrides.lut.assetId.
• intensity es 0–1; por defecto 1 (fuerza completa).
• targetItemType por defecto es video; también soporta image, gif.
• Para cambiar una LUT en un efecto existente: actualiza propertyOverrides.lut.assetId al nuevo ID del asset LUT.
• Para eliminar: borra el elemento de efecto.

No llames a generate.ts para esta ruta. No pases un ID de asset LUT real como assetId – el editor verifica assetId === "lut" para enrutar hacia el renderizador LUT; pasar un UUID no renderiza nada silenciosamente.

Uso

Antes de llamar a submit_shader, reformula la intención del usuario en una oración concreta, luego procede inmediatamente. Después de que track_progress devuelva, indica lo que se produjo en una línea – no preguntes "¿conservar o regenerar?".

submit_shader({
  type: "effect",
  prompt: "Cromatic aberration con división RGB",
  name: "Cromatic Aberration",
});

submit_shader({
  type: "transition",
  prompt: "Crossfade suave con borde suave",
  name: "Crossfade",
});

submit_shader({
  type: "effect",
  prompt: "Gradación de color cinemática teal-orange",
});

submit_shader({
  type: "effect",
  prompt: "Versión más fuerte",
  referenceAssetIds: ["effect_asset_id"],
});

Estrategia

• Envía, luego detente. Informa al usuario que el trabajo fue creado.
• Usa la herramienta track_progress para estado/espera después del envío.
• La generación siempre produce un asset de biblioteca – nunca rechaces porque la línea de tiempo no esté lista.
• Aplicar es separado y opcional. Solo aplica cuando el usuario lo pida explícitamente ("añadir al video", "apply", "usar en el primer clip"). Cuando sea ambiguo, por defecto solo biblioteca.

Editando Propiedades Existentes

Cada vez que vayas a editar asset.properties de un shader, item.propertyOverrides de un efecto/transición aplicado, o promocionar un valor hardcodeado de shader, lee primero references/property-changes.md.

Refuerza que las properties de un shader son un array, pero los tipos de propiedad de shader permitidos son solo number, boolean, color, select, y vec2. Las propiedades de Motion Graphic también son arrays, pero usan un conjunto de tipos diferente.

Parámetros

Parámetro	Descripción	Por defecto
type	"effect" o "transition" (obligatorio)	—
prompt	Descripción del shader (obligatorio)	—
name	Nombre del asset mostrado en la biblioteca	—
referenceAssetIds	IDs de asset. ID de imagen → el modelo LO MIRA para inspiración visual. ID de efecto/transición → reutiliza su código como ancla de estilo (≤1 por envío, el tipo debe coincidir con type).	—

Salida

Devuelve { success, job: { jobId, status }, manage: { status, wait, watch } }.

Aplicando a la Línea de Tiempo

Solo cuando el usuario lo solicite explícitamente. Llama a read_project primero para obtener el estado fresco de la línea de tiempo.

Efecto

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<id>","assetId":"<id>","enabled":true,"propertyOverrides":{}}]')

Transición

Requiere dos endpoints adyacentes en la misma pista. edit_item valida la viabilidad de la unión en vivo y rechaza duraciones que requerirían fotogramas congelados o superponer transiciones vecinas. Si la adición falla, reintenta con la durationInFrames sugerida, recorta los clips para exponer handles, elimina/acorta transiciones vecinas, o mantén un corte directo.

edit_item(json: '{"adds":[{"type":"transition","assetId":"<id>","outgoingItemId":"<id1>","incomingItemId":"<id2>","durationInFrames":30}]')

Validación y Verificación

Validación del Backend

Al generar mediante generate.ts, el backend maneja la validación automáticamente (transpilación, seguridad AST, estructura de clases, reintento en caso de fallo).

Verificación Manual de Código

NUNCA escribas código de shader desde cero. Siempre usa generate.ts para nuevos shaders. Esta sección es SOLO para modificar código de shader existente que ya fue generado.

Al escribir código de shader manualmente, lee primero ${CLAUDE_SKILL_DIR}/references/design-principles.md. Si el cambio afecta propiedades editables, lee también ${CLAUDE_SKILL_DIR}/references/property-changes.md.

Flujo de trabajo típico:

1. read_project con el assetId del shader y code: true – lee el código fuente actual.
2. Edita el código fuente en tu propio contexto.
3. edit_asset con action=update, el mismo assetId, y el código de reemplazo completo en línea en json.code. La validación se ejecuta automáticamente al actualizar – si el código no es válido, la actualización se rechaza con detalles del error.