vishalvana-belwo/belwo-claude-skills

내레이션이 포함된 데모 동영상 만들기

씬 파일을 작성합니다: 각 씬은 내레이션 텍스트와 그 텍스트가 재생되는 동안 실행되는 클릭 동작으로 구성됩니다. 스크립트는 내레이션을 음성으로 변환하고, 고정된 1600×900 해상도의 헤드리스 Chromium에서 앱을 구동하며 화면을 캡처한 후, 음성 해설과 자막이 포함된 MP4를 생성합니다. 페이지 위에 보이는 커서, 클릭 리플, 하이라이트 링, 타이틀 카드가 추가됩니다.

아래 모든 명령어는 PY(Windows에서는 python, macOS에서는 python3)와 DV("${CLAUDE_SKILL_DIR}/scripts/demo_video.py")를 사용합니다. 각 명령어는 일반 상태 줄(SCENE …, RECORDED …, CHECK OK, ERROR …)을 출력하므로, 추측하지 말고 이를 읽으십시오.

1. 설정 (머신당 한 번)

PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"

이 명령어는 ~/.claude-demo-video에 Playwright, Chromium, edge-tts가 포함된 개인 환경을 생성하고 ffmpeg를 확인합니다. READY 또는 누락된 항목에 대한 정확한 메시지로 종료됩니다. ffmpeg는 시스템 도구입니다: 사용자에게 설치 허락을 구하십시오 (Windows: winget install --id Gyan.FFmpeg -e, macOS: brew install ffmpeg). 스크립트는 일반적인 설치 폴더(WinGet, Chocolatey, Scoop, Homebrew)도 찾습니다. ffmpeg가 다른 곳에 있다면, 모든 명령어에 대해 DEMO_VIDEO_FFMPEG_DIR을 해당 폴더로 설정하십시오.

2. 작성 전에 사용자와 동영상 내용 합의

다음 사항을 묻거나 컨텍스트에서 확인하십시오:

• 누가, 왜 볼 것인가 (기능을 승인하는 검토자, 클라이언트, 신규 직원). 이에 따라 어조와 설명할 내용이 결정됩니다.
• 무엇을, 어떤 순서로 보여줄 것인가. 각 씬을 한 줄씩 제안하고 승인을 받으십시오. 3분에서 8분 사이를 목표로 하십시오.
• 음성. 기본값은 자연스러운 영어 신경망 음성(edge-tts)입니다. 내레이션 텍스트가 오디오 생성을 위해 Microsoft의 음성 서비스로 전송된다는 점을 사용자에게 알리십시오. 내레이션에는 기능 설명만 포함되어야 하며, 데이터가 포함되어서는 안 됩니다. 대안은 오프라인 시스템 음성(--offline)입니다: 기계 외부로 나가지 않지만, 음성이 로봇처럼 들립니다.
• 데이터. 데모 데이터만 기록하십시오: 가상 인물, @example.com 이메일, 명백히 가짜 프로젝트. 실제 고객이나 직원 기록을 절대 기록하지 말고, 녹화기를 프로덕션 환경에 사용하지 마십시오.

3. 앱 준비

• 앱이 실행 중이고 이 머신에서 접근 가능해야 하며, 일반적으로 로컬 빌드여야 합니다.
• 화면에 데이터가 필요하면, 데모 데이터용 시드 스크립트 와 이에 대응하는 정리 스크립트를 작성하고 시드를 실행하십시오. 데모 행에 태그(예: DEMO-로 시작하는 ID)를 붙여 정리 작업이 다른 데이터를 건드리지 않도록 하십시오.
• 나가는 이메일과 알림이 꺼져 있거나 가짜 주소로만 가도록 하십시오. 둘러보기에서 실제 버튼(제출, 승인 등)을 클릭하기 때문입니다.
• 데이터를 변경하는 씬(승인, 삭제)은 시드당 한 번만 녹화할 수 있습니다. 재녹화 전에 반드시 다시 시드하십시오.

4. 씬 파일 작성

사용자의 프로젝트에 생성하십시오(예: demo-videos/<name>.py). 절대 스킬 폴더 안에 만들지 마십시오. ${CLAUDE_SKILL_DIR}/reference/scenes-template.py에서 시작하십시오. 전체 실제 예제는 ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py를 참조하십시오(6분짜리 승인 동영상).

CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}

async def week(r):
    await r.click('.tsw-row:has-text("Approval screen")')
    await r.spot('.tsw-panel', 3)

SCENES = [
    ('week', "작업 행을 클릭하면 로그 패널이 바로 아래에 열립니다.", week),
]

• CONFIG['url']은 첫 페이지입니다. ready는 해당 페이지가 로드 되고 로그인되었을 때만 보이는 선택자입니다. 녹화기가 로그인이 성공했는지 확인하는 방법입니다.
• 내레이션: 씬당 한두 문장의 짧은 말입니다. 화면에 무엇이 있는지만 말하지 말고, 왜 중요한지 설명하십시오. 숫자와 기호는 발음되는 방식대로 작성하십시오("이 점 삼 영"). 내레이션에 데이터를 넣지 마십시오.
• 동작은 내레이션이 재생되는 동안 실행됩니다. 동작이 내레이션보다 짧아야 합니다. 녹화기는 내레이션이 끝날 때까지 기다렸다가 다음 씬을 시작합니다.

씬 헬퍼 (r은 녹화기; 그 외의 것은 r.page(Playwright 페이지)로 접근 가능):

헬퍼	기능
await r.goto('/path', wait_for=sel)	페이지 열기 (CONFIG['url'] 기준 상대 경로)
await r.click(target, dx=.5, dy=.5)	보이는 커서를 그곳으로 이동하고 클릭; dx/dy는 요소 내부의 지점 선택
await r.move_to(target)	클릭 없이 커서 이동
await r.type(target, 'text')	필드를 클릭하고 눈에 보이게 텍스트 입력
await r.select(target, value)	드롭다운 옵션 선택
await r.press('ControlOrMeta+K')	키보드 단축키 (Windows: Ctrl, macOS: Cmd)
await r.spot(target, seconds, pad)	주황색 하이라이트 링
await r.card(kicker, title, lines, bullets) / await r.uncard()	전체 화면 타이틀 카드 (인트로, 요약, 아웃트로)
await r.confirm_click(target, show=4)	confirm()을 호출하는 버튼용: 유사 대화상자를 표시한 후 수락
await r.download(target)	다운로드 버튼을 클릭하고 저장된 파일 경로 반환
await r.show_file(path)	로컬 파일 표시 (예: 다운로드한 보고서의 HTML 미리보기)
await r.scroll_top(), await r.scroll_x(selector, px)	부드러운 스크롤
await r.clear_toasts(selector)	버튼을 가리는 알림 토스트 제거
await r.wait(seconds)	일시 정지

target은 CSS 또는 Playwright 선택자 문자열('button:has-text("Approve")') 또는 Locator(r.page.locator('tr', has_text='Aarav').first)입니다.

5. 내레이션 생성, 녹화, 검토

PY DV voice  demo-videos/<name>.py     # 씬별 오디오 생성; 각 씬 길이 출력
PY DV record demo-videos/<name>.py     # 앱 구동 및 프레임 캡처
PY DV stills demo-videos/<name>.py     # 씬당 두 개의 스틸 이미지를 <name>-video/stills/에 생성

로그인. 'sign_in': True인 경우, 앱이 로그인되어 있지 않으면 브라우저 창이 열리고 녹화기가 SIGN_IN_NEEDED를 출력합니다. 사용자에게 해당 창에서 로그인하라고 알리십시오. 절대 자격 증명을 입력하거나 비밀번호를 요청하지 마십시오. 세션은 <name>-video/.profile에 저장되어 재녹화 시 다시 로그인할 필요가 없습니다.

빌드 전에 모든 스틸 이미지를 검토하십시오. 이미지를 읽어 확인:

• 올바른 페이지, 패널이 열림, 커서가 내레이션에서 언급된 위치에 있음;
• 동작을 가리는 요소 없음 (토스트, 쿠키 배너, 프로필 메뉴);
• 화면이 늘어나거나 잘리지 않음;
• 실제 개인 데이터가 화면에 없음.

SCENE_ERROR 줄이나 잘못된 스틸 이미지가 있으면 해당 씬 함수를 수정하고 다시 녹화하십시오 (씬이 데이터를 변경한 경우 먼저 다시 시드). reference/lessons.md에 지금까지 발생한 실패 사례와 해결 방법이 나와 있습니다. 문제가 보이면 이를 읽으십시오.

6. 빌드, 확인 및 전달

PY DV build demo-videos/<name>.py [--out "path/Name.mp4"]
PY DV check "path/Name.mp4" --size 1600x900

run은 씬이 작동하는 것으로 확인되면 voice, record, stills, build, check를 한 번에 수행합니다. 사용자에게 동영상의 경로와 길이, 그리고 내용을 알려주십시오. 사용자가 요청하지 않는 한 동영상을 업로드하거나 공유하지 마십시오.

7. 정리

• PY DV clean demo-videos/<name>.py는 저장된 로그인을 삭제합니다. 완료 후 항상 이 작업을 수행하십시오. 실제 세션을 보유하고 있기 때문입니다. --all은 프레임, 스틸 이미지, 오디오도 제거합니다.
• 데모 데이터 정리 스크립트를 실행하고, 시작한 앱 프로세스를 중지하십시오.

플랫폼 참고 사항

• macOS: python3를 사용하십시오. 자막은 Chromium이 그려서 비디오 위에 입혀지므로, 모든 곳에서 동일하게 보이며 libass로 빌드된 ffmpeg(Homebrew의 것은 아님)가 필요하지 않습니다. 녹화는 헤드리스로 이루어지므로 Retina 디스플레이가 비디오 크기를 변경하지 않습니다.
• --headed는 가시적인 창에서 녹화합니다. 앱이 헤드리스 브라우저를 거부하는 경우에만 사용하고, 녹화 중에는 창을 건드리거나 크기를 변경하지 말라고 사용자에게 요청하십시오.
• DEMO_VIDEO_HOME은 개인 환경의 위치를 변경합니다. DEMO_VIDEO_FFMPEG_DIR은 ffmpeg 폴더를 가리킵니다.