Agentic Video Editing

Primitive-First Boundary

ScreenKite는 에이전트 기반 편집(Agentic Editing)을 단순하게 유지합니다. 앱은 결정론적인 편집 원시 요소(primitives)를 제공하며, 에이전트는 기획, 트랜스크립트(대본) 추론 및 편집 정책을 주도합니다.

이 역할 분담(경계)은 중요합니다. ScreenKite는 "현재 레이아웃은 어떤가요?", "이 범위를 컷(잘라내기) 하세요", 또는 "12.5초에서 17.0초까지 이 장면 레이아웃을 적용하세요"와 같은 요청에 답해야 합니다. 반면, 에이전트는 어떤 박자(beats)가 중요한지, 컷은 어디에 들어가는 것이 좋은지, 시각적 인서트(삽입)가 도움이 될지, 그리고 언제 반복(iteration)을 멈추어야 하는지 결정해야 합니다.

Start With Facts

다음과 같은 데이터 읽기를 기준점(baseline)으로 활용하세요:

• getProjectState(scope: "summary") : 타이밍, 트랙 및 전반적인 프로젝트 상태를 확인하는 가벼운 인덱스
• getProjectState(scope: "layout") : 장면 구성에 대한 유일한 정보 원천 (Source of Truth)
• getProjectResources() : 어떤 미디어가 실제로 존재하는지 확인
• exportTranscript(...) : 말하는 타이밍이나 단어 경계(word-boundary)에 따른 컷이 중요한 경우

트랜스크립트에 영문 제품명, API 또는 기타 고유 명사가 포함되어 있다면, 시각적 요소나 캡션(자막)을 만들기 전에 반드시 이를 교정(proofread)하세요. 잘못된 제품명이 들어가면 후속 작업물 전체에 그 오류가 퍼지게 됩니다.

Recommended Loop

1. 어떠한 계획을 세우기 전에 먼저 summary, layout 및 리소스(resources)를 읽어옵니다.
2. 타이밍이나 내레이션 내용이 중요하다면 트랜스크립트를 내보내(export) 검토합니다.
3. 먼저 비트(beats)를 기획한 다음, 어떤 범위에 컷, 레이아웃 변경, 캡션 또는 시각적 요소가 필요한지 결정합니다.
4. 화면 비율(aspect) 변경 전에는 setCanvas(..., dryRun: true)를 실행하고, 복잡한 레이아웃 작업을 전에는 setSceneLayout(..., dryRun: true)를 실행해 봅니다.
5. 변형(mutation) 적용은 editTimeline, setSceneLayout 및 manageEffects를 사용합니다.
6. 각 일괄 작업(batch) 후에는 getProjectState(scope: "visual") 또는 스냅샷을 통해 결과를 검증합니다.
7. 타임아웃된 변형(mutating call)을 재시도하기 전에 프로젝트 상태를 다시 읽어옵니다.

When to Use Each Primitive

• editTimeline : 컷, 트림(trims) 및 단어 경계 정리 작업 시
• setSceneLayout : 고급 레이아웃 DSL을 포함한 시간 범위 기반의 화면 구성 변경 시
• manageEffects : 캡션, 줌, 기타 이펙트 패스(effect passes) 적용 시
• vfxExportVideoSegment 및 vfxOverlayProcessedClip : 외부 렌더링 도구를 오가는 작업 시
• exportArtifact : 최종 산출물 파일, 스냅샷, SRT 및 특정 범위의 비디오 내보내기 시

Advanced Layout and B-Roll

ScreenKite의 시각 효과에서 화면 녹화(screen recording)는 여전히 핵심적인 유지 항목입니다. Advanced Layout(고급 레이아웃) 및 B-Roll은 일반적으로 화면 전체를 장악하기보다는, 짧고 보조적인 순간(supporting moments)으로 사용되어야 합니다.

만약 외부에서 시각적 요소를 렌더링하고 <ScreenKite.Visual />을 통해 배치한다면:

• 에셋을 타겟의 정확한 너비, 높이, fps 및 프레임 지속 시간에 맞게 렌더링하세요.
• 렌더링된 파일을 대부분이 비어있는 비디오 안을 떠다니는 작은 카드가 아니라, 전체 PiP 프레임 그 자체로 취급하세요.
• 애니메이션을 입장(entry) -> 안정적인 유지(settled hold) -> 내부 종료 효과 없음(no internal exit) 구조로 디자인하세요.
• 레이아웃 세그먼트 사이의 종료/퇴장 연출은 ScreenKite의 magicMove 트랜지션이 알아서 처리하도록 둡니다.

만약 예전에 더 길게 적용되었던 구간에 더 짧은 구간의 고급 레이아웃 창을 덮어씌워서 다시 적용하는 경우, 남겨진 꼬리(tails) 부분을 다시 pictureInPicture 상태로 되돌려 명확하게 정리하세요. 그렇지 않으면 낡고 예전의 고급 세그먼트가 의도했던 창을 초과해서 재생될 수 있습니다.

Guardrails

• 절대 단어 중간을 자르지 마세요(Never cut mid-word). 음성 타이밍이 중요할 때는 언제나 트랜스크립트의 단어 경계(word boundaries)를 사용하세요.
• 타임아웃 발생 후 변형(mutating call)을 재시도하기 전에는 반드시 프로젝트 상태를 다시 읽어오세요.
• 오버레이 렌더링을 타임라인에 다시 배치하기 전에, 렌더링 출력물이 타겟의 너비, 높이, fps, 프레임 지속 시간과 완벽히 일치하는지 맞추세요(Match).
• 생성된 결과물 파일은 .skbundle 외부에 저장되도록 유지하세요.
• 자체 평가 및 수정 루프(self-evaluation loops) 횟수에 제한을 두세요. 몇 번의 시도 후에도 시각적 검증(visual checks)이 계속 실패한다면 루프를 멈추고 레이아웃이나 원본 미디어를 직접 검사하세요.