adityaleksono/walkthrough-video

워크스루 비디오

"이 기능을 설명해줘"를 짧은 MP4로 만듭니다: 실제 앱 화면, 설명하는 음성, 자막, 사람처럼 움직이는 커서, 그리고 설명 중인 요소 주변의 링. 사용자는 브리핑을 하고 검토합니다. 나머지는 모두 당신이 합니다.

이 작업에는 다른 어떤 것보다 중요한 하나의 검토 게이트가 있습니다: 녹화 전에 사용자가 내러티브를 승인해야 합니다. 문구 변경은 스크립트에서는 몇 초, 비디오에서는 몇 분이 걸리며, 잘못된 주장은 문서에서 발견하는 것이 훨씬 저렴합니다.

필요한 것

• 앱의 소스 코드와, 열고 로그인할 수 있는 인스턴스(로컬 또는 개발/스테이징 환경). 프로덕션에서는 절대 녹화하지 마세요: 실제 버튼을 클릭합니다.
• 앱 프로젝트 내 Playwright(node_modules/playwright 또는 @playwright/test). E2E 테스트가 있는 대부분의 프로젝트에는 이미 있습니다. 없다면: npm i -D playwright && npx playwright install chromium.
• PATH에 ffmpeg와 python3가 있어야 합니다.
• 최종 음성을 위한 텍스트 음성 변환 키(Murf 또는 ElevenLabs). 키가 없으면 --provider say가 macOS 음성을 사용하며, 초안 테이크에는 괜찮습니다. references/voices.md를 참조하세요.

먼저 이것들을 확인하고 무엇이 누락되었는지 명확히 말하세요. 사용자에게 API 키를 채팅에 붙여넣도록 요청하지 마세요: 환경 변수나 git에 무시되는 파일에 넣고 위치를 알려달라고 하세요.

워크플로우

1. 브리핑 받기

네 가지가 필요합니다. 요청이 이미 말하지 않은 것만 물어보세요.

• 목표와 대상. "새 권한 페이지를 CTO와 조율"은 "신규 멤버에게 앱 게시 방법 가르치기"와 다른 비디오를 만듭니다. 대상이 길이, 어휘, 설명할 양을 결정합니다.
• 흐름. 보여줄 순서. 사용자가 제공하면 개선하고 무엇을 변경했는지와 그 이유를 말하세요: 더 나은 순서, 누락된 단계, 아무것도 추가하지 않는 단계. 그들은 비디오를 요청했지, 목록의 전사를 요청한 것이 아닙니다.
• 길이. 기본값은 60-120초, 한 가지 주제입니다. 흐름에 더 필요하면 두 개의 비디오를 제안하세요.
• 음성. 선호하는 제공자와 음성이 있다면. 없으면 기본값을 사용하세요.

2. 한 글자도 쓰기 전에 실제 앱에서 흐름을 따라가보기

앱을 실행하고, 데모 계정으로 로그인하고, Playwright나 브라우저로 흐름의 모든 단계를 직접 수행하세요. 내레이션이 주장할 각각의 것이 실제로 사실인지 확인하는 것입니다.

이것이 이 스킬의 가치 대부분이 나오는 곳입니다. 기능은 종종 기억이나 명세서에서 설명되지만, 앱은 약간 다르게 동작합니다. 앱이 사용자가 말한 대로 동작하지 않으면, 멈추고 관찰한 내용을 알려주세요. 그것을 덮기 위한 내레이션을 작성하지 말고, 조용히 단계를 빼지 마세요.

그동안 버튼과 메뉴의 정확한 레이블을 기록하세요. 내레이션은 화면에 표시된 단어를 사용해야 합니다.

3. 데모 데이터 시드하기

비어 있거나 반쯤 망가진 계정의 워크스루는 버그 리포트처럼 보입니다. 스토리에 필요한 것을 만드세요: 조직, 다른 역할을 가진 몇 명의 사용자, 신뢰할 수 있는 이름의 항목. 가상 이름만 사용하세요(Acme, Northwind, example.com): 이 비디오는 전달됩니다.

생성하거나 변경한 모든 것의 목록을 유지하세요. 9단계에서 되돌릴 것입니다.

4. 내러티브 작성 후 검토를 위해 멈추기

표 형태로 작성하고 비디오가 생성될 위치 옆에 <nn>-<slug>.script.md로 저장하세요:

| # | 화면 | 음성 해설 | ~초 |
|---|---|---|---|
| 1 | 작업 목록 정지 상태. 목록에 링. | 이것은 팀 작업 목록입니다. / 팀의 모든 사람이 동일한 작업을 볼 수 있습니다. | 5 |
| 2 | 커서를 **작업 추가**로 이동, 양식 열림. 이름 입력, **작업 저장** 클릭. | 추가하려면 작업 추가를 선택하고, / 이름을 지정하고, / 저장하세요. | 7 |

/는 장면의 내레이션을 자막 줄로 나누는 표시입니다. 작성하기 전에 references/narrative.md를 읽으세요: 페이싱, 줄 길이, 전/후 카드, 그리고 이 비디오를 따라가기 어렵게 만드는 실수들을 다룹니다.

표를 사용자에게 보여주고 기다리세요. 예상 총 길이를 말하세요. 흐름을 변경했다면 여기서 말하세요. 승인할 때만 계속 진행하세요. 변경을 요청하면 수정된 표를 다시 보내세요.

5. 음성 생성하기

승인된 내레이션을 scenes.json에 작성하세요. 한 행당 하나의 항목, / 표시에서 줄을 나눕니다:

[{ "id": "02", "lines": ["추가하려면 작업 추가를 선택하고,", "이름을 지정하고,", "저장하세요."] }]

python3 scripts/tts.py scenes.json --audio-dir work/audio --provider murf

이것은 장면당 하나의 클립과 durations.json을 작성합니다. 음성은 의도적으로 녹화보다 먼저 옵니다: 각 장면은 클립이 지속되는 동안 화면에 유지되므로, 클립 길이가 먼저 존재해야 합니다. 다시 실행하면 텍스트가 변경된 장면만 다시 생성합니다.

6. 녹화 스크립트 작성 및 드라이 런

example/record.cjs를 복사하고 이 흐름에 맞게 장면을 다시 작성하세요. scripts/walkthrough.cjs는 다음을 제공합니다:

헬퍼	사용법
scene(id, async () => {...})	하나의 내레이션 장면. 자막을 표시하고 음성이 끝날 때까지 대기합니다.
clickAt(locator)	커서를 요소로 부드럽게 이동, 누름 표시, 클릭합니다. locator.click() 대신 이것을 사용하세요, 그렇지 않으면 눈에 보이는 원인 없이 일이 발생합니다.
moveTo(locator)	클릭하지 않고 무언가를 가리킵니다.
typeInto(locator, text)	필드를 클릭하고 읽을 수 있는 속도로 입력합니다.
ring(locator) / ring(null)	음성이 말하는 것을 강조합니다. 음성이 넘어가면 제거합니다.
step('2/4 단계 · 저장')	시청자에게 현재 위치를 알려주는 왼쪽 아래 레이블입니다.
card({ title, subtitle })	전체 화면 제목 카드, 종료 장면용.
card({ before, after })	전/후 비교. card(null)은 숨깁니다.
login: async (page) => {...}	record()의 옵션. 화면 밖에서 로그인하여 비디오가 스토리가 시작되는 곳에서 시작되도록 합니다.

CSS보다 역할 및 레이블 로케이터(getByRole, getByLabel)를 선호하세요: 리스타일링에도 견디고 내레이션이 사용하는 이름과 동일합니다. 환경에 따라 데이터가 다를 수 있는 경우 런타임에 화면에서 이름을 읽어오세요.

먼저 dry로 실행하세요:

node record.cjs <app-repo> work/rec work/audio/durations.json dry

드라이 런은 아무것도 녹화하지 않으며 음성을 기다리지 않으므로, 잘못된 선택자는 전체 테이크가 아닌 몇 초면 됩니다. 모든 장면이 실행될 때까지 수정하세요.

7. 녹화 및 조립

node record.cjs <app-repo> work/rec work/audio/durations.json
python3 scripts/mux.py --rec work/rec --audio-dir work/audio --output walkthrough-videos/<nn>-<slug>.mp4

녹화기는 각 장면의 클립 길이를 동작에 걸린 시간 옆에 출력합니다. 음성 후에 몇 초의 침묵으로 플래그가 지정된 장면은 말해진 것에 비해 너무 많은 일이 발생한 것입니다: 동작을 줄이거나 음성이 더 말할 것을 주세요.

mux.py는 MP4, 일치하는 .srt, 그리고 <name>.sheet.jpg를 작성합니다.

8. 사용자보다 먼저 직접 확인하기

연락처 시트(장면당 한 프레임)를 여세요. 잘못된 요소에 있거나 누락된 링, 논의 중인 것을 가리는 자막, 잘못된 화면의 장면, 개발자 도구 배지나 오류 토스트가 촬영된 경우, 실제 개인 데이터를 찾으세요. 시트에서 확인하기 어려운 경우 ffmpeg로 단일 프레임을 추출하세요.

그런 다음 비디오를 다음 정보와 함께 전달하세요: 길이, 승인된 내러티브에서 변경된 사항(있는 경우), 확인할 수 없었던 사항.

사용자가 변경을 원하면 먼저 내러티브로 돌아가세요. 표를 수정하고, 보여주고, 승인을 받은 후에 변경된 것만 다시 생성하세요. 대부분의 피드백("너무 빠르다", "무엇이 변경되었는지 놓쳤다", "필터도 언급해줘")은 스크립트에 대한 것이며, 녹화만 수정하면 더 이상 스크립트와 일치하지 않는 비디오가 생성됩니다.

9. 되돌리기

테이크가 변경한 것을 취소하세요. 3단계의 목록과 녹화 자체가 클릭한 것을 사용하여: 변경된 설정, 생성되거나 제거된 항목, 데모 계정 상태. 그런 다음 사용자에게 무엇이 복원되었고 무엇을 의도적으로 남겼는지(예: 다음 비디오를 위해 유지할 시드 데이터) 알려주세요. 취소할 수 없는 것이 있으면 말하세요.

파일

산출물은 사용자가 찾을 수 있는 한 곳에 모아두며, 기본값은 프로젝트의 walkthrough-videos/입니다:

walkthrough-videos/
  03-add-a-task.mp4
  03-add-a-task.srt
  03-add-a-task.script.md

작업 파일(scenes.json, 오디오, 원시 녹화, 녹화 스크립트)은 리포지토리 외부나 git에서 무시되는 폴더에 보관하세요. 크기가 크고 녹화 스크립트는 앱의 한 순간에 대한 선택자를 보유합니다. 스크립트와 .srt는 보관할 가치가 있습니다: 다음 수정을 작은 편집으로 만듭니다.

문제가 발생하는 경우

• 네이티브 컨트롤이 녹화되지 않습니다. 네이티브 <select> 드롭다운, 파일 선택기 또는 브라우저 대화상자는 브라우저가 페이지 외부에 그립니다. moveTo로 컨트롤을 가리키고, selectOption/setInputFiles로 값을 설정하고, 내레이션이 선택된 것을 말하게 하세요.
• 오버레이가 탐색 후 사라집니다. 모든 페이지 로드 시 다시 생성되며 현재 단계와 자막이 복원됩니다. 페이지가 document.body를 완전히 교체하면, 안정화된 후에 step()을 다시 호출하세요.
• 장면이 페이지 준비 전에 시작됩니다. 장면이 다루는 것을 기다린 후(await locator.waitFor())에 scene()을 호출하세요. scene() 내부가 아니라, 그래야 로딩 시간이 내레이션으로 덮이지 않습니다.
• 처음 몇 초는 빈 페이지입니다. mux.py는 첫 번째 장면 이전의 모든 것을 자릅니다. scene('01') 전에 탐색과 대기를 수행하세요.
• 카메라에 로그인 표시. login 옵션을 사용하세요. 아무도 비밀번호 필드를 볼 필요가 없으며, 자격 증명이 공유 비디오에 표시되어서는 안 됩니다.