omerozgul11/app-training-video-skill

앱 교육 동영상

실제 애플리케이션으로 전문 교육 동영상을 만듭니다. 동영상은 1920 × 1080 H.264 코덱에 AAC 내레이션이 포함됩니다. 각 음성 문장에 자막이 입혀지고, 모든 챕터는 카드로 시작하며, 긴 대기 시간은 제거됩니다. 재현 가능합니다. UI가 변경되면 캡처와 렌더링을 다시 실행하면 동영상이 최신 상태로 유지됩니다.

작동 방식:

1. 스토리보드에 내레이션 텍스트, 챕터 및 브랜딩 정보가 저장됩니다.
2. narrate.py가 각 세그먼트를 오프라인 Kokoro 음성으로 읽습니다. 클라우드 서비스, 계정, 비용이 필요 없습니다.
3. 캡처 스크립트는 Playwright로 실제 앱을 구동합니다(실제 마우스 움직임, 보이는 커서 및 클릭 리플 포함). Chrome의 스크린캐스트 프레임을 녹화하고 내레이션이 끝날 때까지 각 세그먼트를 유지합니다.
4. render.py가 클립, 카드, 자막 밴드 및 음량이 정규화된 내레이션 트랙을 조합합니다.
5. review.py가 결과를 확인하고 게시하기 전에 검토할 수 있는 콘택트 시트를 만듭니다.

스크립트는 이 파일 옆의 scripts/ 디렉토리에 있습니다. 내레이션을 작성하기 전에 references/storyboard.md를 읽고, 캡처 스크립트를 작성하기 전에 references/capture-guide.md를 읽으십시오. 두 문서에는 일반적인 재녹화를 방지하는 교훈이 담겨 있습니다.

0. 일회성 설정

bash <skill>/scripts/setup.sh

이 명령은 ~/.cache/app-training-video/ 디렉토리를 생성합니다(TRAINING_VIDEO_HOME 환경 변수로 재정의 가능). 다음을 포함합니다:

• 고정된 패키지가 포함된 개인 Python 3.10–3.13 환경
• Kokoro 음성 모델(~350 MB)과 Inter 글꼴, SHA-256 검증됨
• Chromium

모든 스크립트는 해당 환경의 Python(PY=~/.cache/app-training-video/venv/bin/python)으로 실행하고 스토리보드 경로를 전달하십시오. 모델 파일이 이미 다른 곳에 있다면 MODEL_SOURCE=<dir>을 먼저 실행하여 재사용하십시오. ffmpeg는 번들로 제공됩니다(imageio-ffmpeg). 시스템 전체에 설치되는 것은 없습니다.

1. 앱과 대상 이해하기

무엇이든 작성하기 전에 직접 앱을 사용하거나(또는 사용자 가이드를 읽고) 다음을 파악하십시오:

• 시청자: 신규 고객, 현장 직원, 내부 사용자
• 그들이 반드시 익혀야 할 한 가지 워크플로우: 입력부터 결과까지
• 공개해도 안전한 데모 데이터
• 앱을 깨끗한 상태로 시작하는 방법: URL 또는 실행 명령어, 그리고 새 데이터 폴더 또는 데모 계정
• 브랜딩: 회사명, 제품명, 버전, 로고 PNG, 강조 색상, 아웃트로 연락처 정보

찾을 수 없는 내용은 사용자에게 물어보십시오. 전체 워크플로우에는 67분, 단일 기능에는 6090초가 적당합니다.

2. 스토리보드 작성

assets/storyboard.example.json을 프로젝트 옆에 storyboard.json으로 복사하고 references/storyboard.md에 따라 작성하십시오. 간단히 말하면:

• 세그먼트당 10~35초의 음성
• "n · Title" 형식의 챕터, 각 챕터의 첫 번째 세그먼트에는 card: "chapter" 설정
• intro 및 outro 카드
• 음성을 위한 약어 철자, caption_replacements로 원래 형식 복원

촬영 전에 사용자에게 내레이션을 보여주십시오. 지금 변경하는 것은 저렴하지만 나중에는 비용이 많이 듭니다.

3. 내레이션

$PY <skill>/scripts/narrate.py storyboard.json

각 세그먼트의 길이를 출력합니다. 텍스트가 변경된 세그먼트만 다시 음성화합니다. 발음이 중요하다면 video-build/audio/에서 한두 개의 WAV 파일을 들어보고 철자를 조정한 후 다시 실행하십시오.

4. 캡처 스크립트 작성 및 실행

scripts/capture_template.py를 스토리보드 옆에 capture.py로 복사하고, 스킬의 scripts/ 경로를 설정한 후, 스토리보드 순서대로 촬영할 각 세그먼트에 대해 with rec.segment('<id>'): 블록을 하나씩 작성하십시오. 블록 내에서 내레이션이 설명하는 대로 정확히 수행하십시오:

• rec.click, rec.hover, rec.type, rec.drag, rec.scroll, rec.park
• 느린 작업 주위에는 rec.cut()을 사용하고, 가시적인 결과를 기다리십시오

레코더는 비어 있지 않은 frames/ 폴더를 거부하므로 이전 프레임이 섞이지 않습니다.

$PY capture.py storyboard.json

각 세그먼트는 촬영된 길이를 내레이션 길이와 비교하여 출력합니다. 첫 번째 중단 단계, 페이지 오류 또는 촬영되지 않은 세그먼트에서 실행이 실패합니다(상태 incomplete). 단계를 수정하고 video-build/frames/를 비운 후 다시 실행하십시오.

5. 렌더링 및 검토

$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json

빌드 폴더에 다음이 출력됩니다:

• <output_name>.mp4
• .srt 자막 파일
• -chapters.txt (YouTube 설명에 붙여넣기)
• -poster.jpg
• -timeline.json
• -review.jpg: 세그먼트당 하나의 스틸 이미지

콘택트 시트를 열어 확인하고 MP4 자체를 샘플 점검하십시오. 다음을 확인하십시오:

• 모든 세그먼트에 올바른 화면이 표시되는지
• 오류 배너, 빈 플롯, 튀어나온 대화 상자가 없는지
• 커서가 설명 중인 내용을 가리지 않는지
• 자막이 올바르게 읽히는지

선택자가 일치하더라도 화면이 잘못될 수 있으므로 동영상을 완료했다고 말하기 전에 이 검토가 필요합니다.

6. 전달

사용자에게 MP4, SRT(대부분의 플레이어는 이름이 일치하면 자동으로 로드함), 챕터 목록을 제공하십시오. 길이와 크기를 언급하십시오. 게시하려면 MP4와 SRT를 함께 업로드하십시오. storyboard.json과 capture.py를 프로젝트와 함께 보관하십시오. 다음 UI 변경 후에는 4~5단계를 다시 실행하고(문구가 변경된 경우 3단계도) 동영상을 업데이트할 수 있습니다.

문제 해결

증상	해결 방법
Need Python 3.10–3.13	python3.12를 설치하거나 setup.sh 실행 전에 PYTHON=을 설정하십시오.
앱이 시작되었는데도 launch()가 타임아웃됨	앱이 출력을 버퍼링합니다. Python 서버는 python -u로 실행하거나 ready 정규식을 확인하십시오.
Linux에서 Chromium 시작 실패	$PY -m playwright install --with-deps chromium
로케이터 타임아웃 또는 두 요소 일치	영역으로 범위를 좁히거나 exact=True와 함께 get_by_role을 사용하십시오(캡처 가이드 참조).
세그먼트가 내레이션보다 훨씬 긴 경우	느린 작업이 rec.cut() 안에 있지 않습니다.
잘못된 발음	speech에서 철자를 다시 쓰고 caption_replacements 규칙을 추가한 후 narrate.py를 다시 실행하십시오.
자막 동기화 불일치	자막 타이밍은 내레이션 길이를 따릅니다. 긴 문장을 줄이거나 세그먼트를 분할하십시오.