비디오 가이드 제작 스킬
모든 화면 녹화를 깔끔하고, 내레이션이 포함되며, 동적으로 주석이 추가된 사용자 가이드 비디오(.mp4 + .srt)로 변환합니다.
핵심 규칙(항상 준수)
- 사용자에게 제로 JSON / 제로 수동 준비 요구: 사용자는 녹화 경로(예:
C:\recordings\demo.mp4또는 프레임 폴더)와 옵션 가이드/흐름 노트만 제공하면 됩니다. 당신이 프레임을 추출하고, 전체 비디오를 분석하고, 레시피 JSON을 작성하고, 타이밍을 검증한 후 렌더링합니다. - 편집 전에 모든 3-FPS 프레임 분석: 예를 들어, 210초 녹화의 경우 3fps에서 약 630프레임이 생성됩니다. FFmpeg를 통해 모든 3fps 프레임을 추출하고, 630개 프레임 전체를 스캔하며, 생성된 모든 Storyboard Contact Sheet(
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
이 명령은 자동으로:
3 fps프레임(0001_frame.png ... 0NNN_frame.png, 예: 210초 동안 630프레임)을 번들 FFmpeg(engine.py --extract_frames --fps_extracted 3)를 통해 추출합니다.- 추출된 프레임의 100% (
0 .. N-1) 를 전역 차이 및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을 빽빽한 테이블 헤더에 배치하지 마세요. 핀이 인접한 열 레이블을 가릴 수 있습니다.- 각 단계의
[active_start, active_end]창에narration이 편안하게 맞는지 확인하세요.
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 경로를 제공합니다.