셰이더 생성기
제출 전용(Submit-only): 백엔드 생성 작업을 생성하고 jobId를 반환합니다. 제출 후 작업 생애주기 추적에는 track_progress 도구를 사용하세요.
새 셰이더에는 항상 generate.ts를 사용하세요. 수동 작성은 기존 에셋 코드를 편집할 때만 사용하며, 생성 실패 시 폴백(fallback)으로 절대 사용하지 마세요.
생성 전 카탈로그 우선 규칙 — 기존 에셋 먼저 시도
셰이더를 생성하기 전에, 사용자가 read_project에 이미 표시된 정확한 에셋 ID를 언급하지 않는 한 browse_library를 호출하세요.
browse_library는 내장 효과, 내장 전환, 프로젝트 효과/전환 에셋의 진실 공급원(source of truth)입니다. 내장 에셋은 안정적인 전역 에셋 ID를 가지며 프로젝트별 DB 에셋이 아니므로 read_project 에셋 목록에 나타나지 않을 수 있습니다.
카탈로그 항목은 edit_item으로 적용하고, 절대 submit_shader를 호출하지 마세요.
좋은 카탈로그 검색 예시:
browse_library(query: "zoom")
browse_library(category: "transitions", query: "dissolve")
browse_library(category: "audio-fx")
사용자의 의도에 충분히 가까운 카탈로그 항목이 없을 때만 생성하세요.
builtin:zoom은 트랙 바운드(track-bound) 전용 — 아이템 바운드(item-bound) 사용 금지
기본 효과 모드는 "item-bound"입니다(targetItemId로 단일 아이템에 연결). builtin:zoom은 item-bound 모드에서 렌더링되지 않습니다 — 렌더러가 줌 데이터를 오직 트랙 바운드 효과 아이템에서만 읽기 때문입니다. Item-bound 줌은 DB에 조용히 삽입되지만 미리보기에는 아무것도 표시되지 않습니다.
mode: "track-bound"와 함께 trackId + trackBoundFrom + trackBoundDurationInFrames를 사용하세요. 이 세 필드는 필수입니다.
# 전체 비디오 클립에 줌 적용
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"}}]')
# 클립의 일부 구간에만 줌 적용 (예: 90~150프레임, 비트에 맞춘 펀치 줌)
edIT_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]')
trackId / fromFrame / durationInFrames는 read_project에서 가져오세요(각 비디오/이미지 아이템은 자체 trackId와 타임라인 프레임 범위를 표시합니다).
| 키 | 타입 | 범위 / 값 | 기본값 | 참고 |
|---|---|---|---|---|
magnification | number | 1–4 | 1.5 | 확대 배율; 1 = 확대 없음, 2 = 2배 |
focalPointX | number | 0–1 | 0.5 | 수평 초점(0 = 왼쪽, 1 = 오른쪽) |
focalPointY | number | 0–1 | 0.5 | 수직 초점(0 = 위, 1 = 아래) |
shape | select | punch / hold / slow-push / instant | hold | 애니메이션 곡선 |
focalMode | select | auto / manual | auto | auto는 피사체 자동 선택; manual은 focalPoint 사용 |
easeInFrames | number | 0–60 | 8 | 인입 프레임 수 |
easeOutFrames | number | 0–60 | 8 | 인출 프레임 수 |
기본 줌을 사용하려면 propertyOverrides를 아예 생략하세요. 변경하려는 키만 보내세요 — 패치(Patch) 의미론입니다.
트랙 바운드 vs 아이템 바운드 — 일반 규칙
스키마의 효과 아이템에는 두 가지 모드가 있습니다:
item-bound(기본값):targetItemId만 사용. 효과가 대상 아이템 전체 재생 구간을 덮습니다. 셰이더 효과, LUT, 색보정, 블러 등에 작동합니다.track-bound:trackId+trackBoundFrom+trackBoundDurationInFrames. 효과가 특정 아이템과 무관하게 트랙의 타임라인 범위를 덮습니다.builtin:zoom에 필수이며, 특정 타임라인 범위(예: 두 클립 경계의 전환 스타일 색상 변화)를 덮어야 하는 셰이더 효과에도 유효합니다.
셰이더 효과는 기본적으로 item-bound를 사용하세요. 다음 경우에 track-bound를 사용하세요: (a) 에셋이 요구하는 경우(줌), 또는 (b) 효과가 단일 아이템과 일치하지 않는 타임라인 범위를 덮어야 하는 경우.
내장 LUT 속성
edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"builtin:slog3-s709","propertyOverrides":{"intensity":1}}]')
| 키 | 타입 | 범위 | 기본값 | 참고 |
|---|---|---|---|---|
intensity | number | 0–1 | 1 | LUT 강도; 1 = 완전 적용 |
교체하려면: 효과를 삭제하고 다른 assetId로 다시 추가하세요. 제거하려면: 효과 아이템을 삭제하세요.
이는 사용자가 업로드한 .cube LUT 에셋과는 별개입니다(아래 "기존 LUT 에셋 적용" 참조). 후자는 assetId:"lut"를 사용하는 다른 코드 경로를 사용합니다.
베타 상태 게이트(Beta Status Gate)
새로운 셰이더 생성은 베타 버전입니다. 생성하기 전에 사용자에게 경고하고 명시적인 확인을 기다리세요.
사용자의 언어를 사용하세요. 한국어: "새로운 효과/전환 생성은 현재 베타 단계로, 불안정한 문제가 발생할 수 있습니다. 그래도 진행하시려면 도와드리겠습니다." 같은 요청에서 사용자가 이미 인지했으면 건너뛰세요.
지원 대상
효과와 전환은 video, image, gif 아이템에 적용됩니다.
유형 라우팅(Type Routing)
무엇이든 생성하기 전에, 먼저 비생성 경로 두 가지를 확인하세요:
- 카탈로그 항목 — 내장 및 프로젝트 효과/전환을 위해
browse_library사용. - 사용자가 업로드한
.cubeLUT 에셋이 이미 프로젝트 라이브러리에 존재하는 경우 — 별도 코드 경로이며, 아래 "기존 LUT 에셋 적용"을 참조하세요. 에셋은read_project에type: lut로 표시됩니다.
| 사용자 요구 사항 | --type |
|---|---|
| 비디오 외형 (색상, 블러, 글로우, 그레인, 왜곡) | effect |
| 색보정/룩 (틸-오렌지, 시네마틱, 빈티지, LUT 스타일) | effect |
| 가시성 제어 (마스크, 리빌, 와이프, 형태 컷아웃, 그라데이션 페이드) | effect |
| 클립 간 블렌드 (크로스페이드, 디졸브, 슬라이드, 3D 큐브/페이지 넘김) | transition |
표의 "LUT 스타일"은 LUT를 닮은 새로운 GLSL 색보정을 생성하는 것을 의미합니다. 사용자가 새로운 것을 원할 때만 해당됩니다. 라이브러리에 이미 있는 .cube 파일을 적용하려면 생성하지 말고 기존 에셋을 바인딩하세요.
생성 경로에 별도의 LUT 또는 마스크 생성기는 없습니다. 모두 effect입니다.
기존 LUT 에셋 적용
사용자가 업로드한 .cube 파일은 lut 에셋이 됩니다. 클립에 적용하는 것은 생성이 아닙니다. edit_item 호출 한 번으로, assetId가 리터럴 문자열 "lut"이고 propertyOverrides.lut가 실제 LUT 에셋 ID를 바인딩하는 효과 아이템을 연결하면 됩니다. (레거시 계약이며, 통합 LUT API는 LUT 효과 에셋 ID를 직접 바인딩합니다 — 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"}}}]')
핵심 사항:
assetId는 리터럴 문자열"lut"이며, LUT 에셋의 ID가 아닙니다. 실제 LUT 에셋 ID는propertyOverrides.lut.assetId안에 들어갑니다.intensity는 0–1; 기본값 1 (최대 강도).targetItemType기본값은video;image,gif도 지원합니다.- 기존 효과의 LUT를 교체하려면:
propertyOverrides.lut.assetId를 새 LUT 에셋 ID로 업데이트하세요. - 제거하려면: 효과 아이템을 삭제하세요.
이 경로에서는 generate.ts를 호출하지 마세요. assetId에 실제 LUT 에셋 ID를 전달하지 마세요. 편집기는 assetId === "lut"인지 확인하여 LUT 렌더러로 라우팅하며, UUID를 전달하면 조용히 아무것도 렌더링되지 않습니다.
사용법
submit_shader를 호출하기 전에 사용자의 의도를 구체적인 한 문장으로 다시 설명한 후 즉시 진행하세요. track_progress가 반환되면 생성된 내용을 한 줄로 설명하고 "유지할까요, 다시 생성할까요"와 같은 질문은 하지 마세요.
submit_shader({
type: "effect",
prompt: "RGB 분할을 이용한 색수차(Chromatic aberration)",
name: "Chromatic Aberration",
});
submit_shader({
type: "transition",
prompt: "부드러운 가장자리의 크로스페이드",
name: "Crossfade",
});
submit_shader({
type: "effect",
prompt: "시네마틱 틸-오렌지 색보정",
});
submit_shader({
type: "effect",
prompt: "더 강한 버전",
referenceAssetIds: ["effect_asset_id"],
});
전략
- 제출하고 중단하세요. 사용자에게 작업이 생성되었음을 알리세요.
- 제출 후 상태/대기를 위해
track_progress도구를 사용하세요. - 생성은 항상 라이브러리 에셋을 만듭니다. 타임라인이 준비되지 않았다고 거부하지 마세요.
- 적용(Apply)은 별도이며 선택 사항입니다. 사용자가 명시적으로 요청할 때만 적용하세요 ("加到视频", "apply", "用到第一段"). 모호할 경우 기본값은 라이브러리 전용입니다.
기존 속성 편집
셰이더 asset.properties, 적용된 효과/전환 item.propertyOverrides를 편집하거나, 하드코딩된 셰이더 값을 프로모션할 때는 먼저 references/property-changes.md를 읽으세요.
셰이더 properties가 배열임을 재확인하지만, 허용되는 셰이더 속성 타입은 number, boolean, color, select, vec2뿐입니다. 모션 그래픽 속성도 배열이지만 다른 타입 세트를 사용합니다.
매개변수
| 매개변수 | 설명 | 기본값 |
|---|---|---|
type | "effect" 또는 "transition" (필수) | — |
prompt | 셰이더 설명 (필수) | — |
name | 라이브러리에 표시될 에셋 이름 | — |
referenceAssetIds | 에셋 ID. 이미지 ID → 모델이 시각적 영감을 위해 이를 참조합니다. 효과/전환 ID → 스타일 앵커로 코드를 재사용합니다(제출당 최대 1개, 종류는 type과 일치해야 함). | — |
출력
{ success, job: { jobId, status }, manage: { status, wait, watch } } 반환.
타임라인에 적용
사용자가 명시적으로 요청할 때만. 먼저 read_project를 호출하여 최신 타임라인 상태를 가져오세요.
효과
edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<id>","assetId":"<id>","enabled":true,"propertyOverrides":{}}]')
전환
같은 트랙에 인접한 두 엔드포인트가 필요합니다. edit_item은 라이브 접합부(seam)의 실현 가능성을 검증하고, 정지 프레임이나 이웃 전환과의 중첩을 유발하는 지속 시간을 거부합니다. 추가가 실패하면 제안된 durationInFrames로 재시도하고, 클립을 잘라 핸들을 확보하고, 이웃 전환을 삭제/단축하거나, 하드 컷을 유지하세요.
edit_item(json: '{"adds":[{"type":"transition","assetId":"<id>","outgoingItemId":"<id1>","incomingItemId":"<id2>","durationInFrames":30}]')
검증 및 확인
백엔드 검증
generate.ts를 통해 생성할 때 백엔드가 자동으로 검증(트랜스파일, AST 보안, 클래스 구조, 실패 시 재시도)을 처리합니다.
수동 코드 확인
절대 셰이더 코드를 처음부터 작성하지 마세요. 새 셰이더에는 항상 generate.ts를 사용하세요. 이 섹션은 이미 생성된 기존 셰이더 코드를 수정할 때만 사용합니다.
셰이더 코드를 수동으로 작성할 때는 먼저 ${CLAUDE_SKILL_DIR}/references/design-principles.md를 읽으세요. 변경 사항이 편집 가능한 속성에 영향을 미치는 경우 ${CLAUDE_SKILL_DIR}/references/property-changes.md도 읽으세요.
일반적인 워크플로:
read_project를 셰이더assetId와code: true와 함께 호출하여 현재 소스를 읽습니다.- 자신의 컨텍스트에서 소스를 편집합니다.
edit_asset을action=update, 동일한assetId, 그리고 전체 대체 소스를json.code에 인라인으로 포함시켜 호출합니다. 업데이트 시 자동으로 검증이 실행됩니다. 코드가 유효하지 않으면 오류 세부 정보와 함께 업데이트가 거부됩니다.