Video Guide Maker Skill
원시 화면 녹화를 세련되고 내레이션이 추가된 동적 주석 사용자 가이드 동영상(.mp4 + .srt)으로 변환합니다.
핵심 규칙 (항상 준수)
- JSON 없음 / 사용자 수동 준비 없음: 사용자는 녹화 경로(예:
C:\recordings\demo.mp4또는 프레임 폴더)와 선택적 가이드/흐름 노트만 제공합니다. 에이전트가 프레임을 추출하고, 전체 비디오를 분석하며, 레시피 JSON을 작성하고, 타이밍을 검증한 후 렌더링합니다. - 편집 전 모든 3-FPS 프레임 분석: 예를 들어, 210초 녹화는 3fps로 약 630프레임을 생성합니다. FFmpeg를 통해 모든 3-fps 프레임을 추출하고, 630개 프레임을 모두 스캔하며, 생성된 모든 스토리보드 연락처 시트(
storyboard_*.png)를 검사하고, 전체 해상도0NNN_frame.png프레임(또는inspect_frame_slice사용)을 검사한 후 레시피 단계를 작성합니다. - 음성, 톤 및 사전 편집 계획 게이트: 최종 렌더링 전에
validate_recipe(--plan_only)를 실행하고, 편집 계획(단계 수, 지속 시간, 도크 영역, 내레이션)을 제시한 후 사용자에게 확인을 요청하거나 음성 및 톤을 선택하도록 합니다. — 사용자가 명시적으로"auto proceed"(또는"just render")를 주문한 경우는 예외입니다. - 최초 실행 자동 설정: 클론 후
.venv가 없으면python bootstrap.py를 한 번 실행합니다(또는tool_executor.py를 직접 실행하면 자동으로 부트스트랩됩니다).
단계별 에이전트 워크플로우
1단계 — 3-FPS 프레임 추출 및 모든 프레임 분석
create_guide 실행(MCP 또는 CLI tool_executor.py를 통해):
# CLI / Codex / Cursor / Antigravity 셸:
echo '{"tool":"create_guide","video_path":"<VIDEO_PATH>","user_flow_notes":"<OPTIONAL_NOTES>"}' | python tool_executor.py
다음 작업을 자동으로 수행합니다:
- 번들 FFmpeg(
engine.py --extract_frames --fps_extracted 3)를 통해3 fps프레임을 추출합니다(0001_frame.png ... 0NNN_frame.png, 예: 210초의 경우 630프레임). - 추출된 모든 프레임(
0 .. N-1) 을 전역 diff와8×6공간 블록 탐지기를 모두 사용하여 스캔합니다(드롭다운, 버튼 클릭, 체크박스, 모달이 절대 누락되지 않도록 함). - 다음을 출력합니다:
storyboard_01.png,storyboard_02.png, ... — 전체 비디오를 포함하는 라벨이 지정된 연락처 시트로,#frame, 타임스탬프, 이벤트 태그(PAGE_TRANSITION/UI_ACTION/IDLE_HOLD) 및 변경된 영역을 나타내는 청록색 박스가 포함됩니다.analysis_3fps.json— 전체 타임라인 세그먼트 + 변경된 픽셀 경계 상자[x1, y1, x2, y2]+trim_candidate유휴 홀드.recipe_draft.json— 시작용engine.py레시피 스키마.
2단계 — 스토리보드 및 키 프레임 시각적 검사 (필수)
storyboard_paths에 나열된 모든storyboard_*.png이미지를 열고 읽습니다.- 사용자의 전체 여정을 처음부터 끝까지 추적합니다: 페이지 로드, 양식 작성, 팝업/모달, 긴 정적 구간(
trim_candidate: true) 및 잘라내야 할 잘못된 클릭을 기록합니다. - 강조할 단계에 대해 특정 전체 해상도
0NNN_frame.png이미지를frames_dir에서 열고(좁은 프레임 범위 내에서 빠르게 동작이 발생하는 경우inspect_frame_slice호출) 다음을 수행합니다:- 정확한 UI 버튼/필드/메뉴 텍스트를 읽습니다.
boxes,arrows,spotlight및zoom에 대한 정확한[x1, y1, x2, y2]좌표를 측정합니다.
3단계 — 최종 recipe.json 작성
schemas/recipe.schema.json과 일치하는 깔끔한 recipe.json을 저장합니다(실제 예제는 examples/recipe_create_exam.json 참조):
- 필수 최상위 필드:
source_video,frames_dir,fps_extracted: 3.0,input_source: "auto",branding_text,preset(tech_hud|clean_light|minimal|high_contrast),tone(friendly|professional|energetic|calm|corporate),default_voice,dock_mode: "auto",total_duration: "auto",audio_timing_mode: "auto_shift",export_subtitles: true.- (
"theme"을 문자열로 설정하지 마십시오 — 대신"preset"을 사용하십시오.)
- (
timeline_mapping: 편집된 출력 세그먼트를 3-FPS 소스 프레임에 깔끔하게 매핑합니다(start_sec,end_sec,source_frame_start_3fps,source_frame_end_3fps) — 지루한 일시 중지를 건너뛰고 반복적인 타이핑 구간을 가속 처리하십시오!steps: 동기화된 항목(id,start_time,active_start,active_end,step_num,step_title,narration,sub,boxes,arrows, 선택적spotlight/zoom).boxes[].label이 밀집된 테이블 헤더 위에 배치되지 않도록 하여 필이 인접한 열 레이블을 가리지 않도록 합니다.narration이 각 단계의[active_start, active_end]창에 편안하게 맞도록 합니다.
4단계 — 계획 검증 및 음성/톤 확인
사전 비행 검증 실행(Edge-TTS 클립 합성, [AGENT:] 플레이스홀더 및 중복 확인, 동적 도크 영역 출력):
python tool_executor.py --args '{"tool":"validate_recipe","recipe_path":"<PATH_TO_RECIPE_JSON>"}'
음성: en-IN-NeerjaNeural (인도 여성), en-IN-PrabhatNeural (인도 남성), en-US-JennyNeural (미국 여성), en-US-GuyNeural (미국 남성), en-GB-SoniaNeural (영국 여성), en-GB-RyanNeural (영국 남성).
톤: friendly, professional, energetic, calm, corporate.
[OVERLAP WARNING]이 나타나거나has_overlaps가 true이면 단계 창을 확장하거나 내레이션을 다듬고 중복이 0이 될 때까지 다시 검증합니다.- 사용자가 자동 진행을 주문하지 않은 한, 짧은 사전 편집 계획을 공유하고 렌더링 전에 음성 및 톤을 확인합니다.
5단계 — 렌더링 및 출력 시각적 확인
python tool_executor.py --args '{"tool":"render_guide","recipe_path":"<PATH_TO_RECIPE_JSON>","output_path":"<OUTPUT_MP4>","export_srt":true}'
FFmpeg 스냅샷 확인을 통해 렌더링된 2~3개의 프레임을 검사하여 상자, 화살표, 브랜딩 필 및 HUD 도크가 UI 텍스트와 충돌하지 않는지 확인한 후 .mp4 및 .srt 경로를 전달합니다.