Communitygithub.com

TVideo: 실제 웹앱으로 자막 있는 1080p 튜토리얼 영상 제작

실제 웹앱을 Playwright로 커서가 보이게 녹화한 뒤 Hyperframes로 편집하는 Claude Code 플러그인입니다. 어떤 언어든 단계 자막, 누를 컨트롤의 줌과 하이라이트 링, 클릭음, 음악, 선택형 TTS를 넣어 작업마다 1080p MP4를 만듭니다.

TVideo: 실제 웹앱으로 자막 있는 1080p 튜토리얼 영상 제작란 무엇인가요?

튜토리얼 영상 레시피 1단계(사용법 영상). JiramedFirst/TVideo(2026-10-08 공개, MIT, README에 33초 데모 GIF와 스틸 포함). 스테이징 앱의 튜토리얼을 요청하면 Claude가 요청을 작업별 클립으로 나눠 목록을 함께 확정하고, 클립마다 Playwright 스크립트를 작성해 녹화 없이 리허설하며 모든 셀렉터를 검증한 뒤 video.webm과 timeline.json, clicks.json을 녹화합니다. Hyperframes 편집기는 영상을 브랜드 캔버스에 올리고, 읽을 시간이 필요한 곳에서 정지 화면을 유지하며, 눌러야 할 컨트롤을 줌하고 링으로 표시하고, 클릭마다 효과음, 음악과 선택형 HeyGen TTS를 더해 1080p로 렌더링합니다. 편집이 plan.json과 단계 타임라인에서 생성되므로 UI가 바뀌면 녹화, 가져오기, 빌드, 렌더링만 다시 하면 됩니다. 계정 정보는 환경 변수로만 받고, 공유 환경에서는 먼저 묻고, 실제 결제는 절대 완료하지 않습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JiramedFirst/TVideo/tree/HEAD/plugin/skills/tvideo

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

TVideo — 실제 웹 앱에서 만드는 튜토리얼 비디오

당신은 최종 사용자에게 웹 앱에서의 특정 작업 하나를 가르치는 짧은 비디오를 제작하고 있습니다. 시청자는 기술적이지 않습니다. 모든 프레임은 차분하고, 읽기 쉬우며, 실제처럼 보여야 합니다. 파이프라인은 두 부분으로 나뉘며, 세 개의 파일에서 만납니다:

recorder (Playwright)  ──►  video.webm + timeline.json + clicks.json  ──►  editor (Hyperframes)  ──►  MP4
  • Recorder (templates/recorder/)는 실제 앱을 구동하고, 보이는 커서를 그리며, 각 단계의 시작/종료와 모든 클릭이 발생하는 시점을 기록합니다.
  • Editor (templates/editor/build.mjs)는 푸티지를 브랜딩 캔버스에 배치하고, 시청자가 읽을 시간이 필요한 곳에서 정지 화면을 유지하며, 누를 컨트롤을 확대 + 링으로 표시하고, 모든 클릭에 클릭음을 넣은 후 렌더링합니다.

편집이 해당 파일들에서 생성되므로, UI 변경 후 재녹화는 녹화 → 가져오기 → 빌드 → 렌더링만 하면 됩니다. 이 방식을 유지하세요. 절대 index.html을 수동 편집하지 말고, plan.json / tvideo.config.json을 변경하고 다시 빌드하세요.

Phase 0 — 사전 점검

매 세션 시작 시 (첫 번째 답변과 함께, 사용자를 기다리게 하지 않도록 간단한 질문을 묻는 경우), 이 점검을 실행하고, 녹화 전에 누락된 부분을 수정하세요. 녹화 중에 누락된 도구를 발견하면 테이크를 낭비하게 됩니다.

필요 항목확인해결 방법
Node ≥ 20node -vNode 설치
ffmpeg / ffprobeffmpeg -versionbrew install ffmpeg / apt
Hyperframes CLI + skillsnpx hyperframes --versionnpx hyperframes skills update general-video (media-use, hyperframes-audio도 설치)
Playwright용 Chromiumrecorder 디렉토리에서: npx playwright install chromium—

이 세션에서 Hyperframes를 사용하지 않았다면 references/hyperframes-notes.md를 한 번 읽어보세요 (빌드 스크립트가 이미 따르고 있는 구성 규칙과 그 이유).

Phase 1 — 브리핑 (묻고, 가정하지 마세요)

한 번의 짧은 라운드로, 작업을 변경하는 사항을 수집하세요:

  1. 앱 URL과 환경. 스테이징/UAT/데모 환경을 선호합니다. 녹화는 앱을 실제로 구동합니다: 양식이 제출되고, 레코드가 생성되며, 이메일이 발송됩니다. 이를 명확히 말하고, 공유된 대상에 대해 녹화하기 전에 동의를 얻으세요.
  2. 로그인: 전용 데모 계정 (env vars를 통한 사용자 이름/비밀번호 — 절대 채팅에 붙여넣거나 파일에 쓰지 마세요). 로그인에 OTP/2FA가 필요하면, 실행 중 사용자가 코드를 붙여넣도록 계획하세요 (references/recording.md 참조).
  3. 플로우: 작업당 하나의 비디오. "시스템 사용 방법"을 각각 30–120초 길이의 클립으로 나누세요 (로그인, X 생성, X 편집/취소, Y 다운로드…). 시청자가 시청할 순서를 물어보세요.
  4. UI 및 캡션의 언어 (TV_LOCALE, lang).
  5. 브랜드: 로고 파일, 1–2가지 색상, 언어에 필요한 경우 글꼴 (번들된 IBM Plex Sans Thai는 태국어 + 라틴어 지원). 기본값은 중립적인 네이비/그린입니다.
  6. 오디오: 캡션 + 클릭 SFX가 기본값입니다. 음악: 번들된 CC BY 트랙 또는 없음. 내레이션은 선택 사항이며 TTS 할당량이 필요합니다 — references/narration.md 참조.

안전 결정 (브리핑 시, 녹화 전에 결정하세요)

이 비디오는 배포되며, 녹화는 실제 작업을 수행합니다. 트레이드오프를 설명하고, 안전한 옵션을 권장하며, 사용자가 결정하도록 한 후 따르세요.

  • 화면에 표시되는 데이터. 시청자가 보면 안 되는 데이터: 다른 고객의 이름, 실제 주문, 개인 이메일/주소/전화번호, 내부 테스트 레이블. 가상의 데모 계정을 권장합니다. 사용자가 개인 또는 실제 계정을 고집한다면, 정확히 무엇이 보일지 말하고, 명시적 동의를 받고, 모든 개인 값에 대해 mask를 계획하세요 (스냅샷에서 확인). 값이 실제인지 확실하지 않으면 물어보세요.
  • 취소 불가능하거나 금전적 단계 (결제, 송금, 실제 제3자에게 전송, 삭제, 게시). 실제 결제나 다른 취소 불가능한 작업을 촬영하기 위해 완료하지 마세요. 샌드박스/테스트 모드 (테스트 카드, 스테이징 게이트웨이)를 선호하세요. 없는 경우, 최종 확인 화면까지 녹화하고 거기서 멈춘 후, 마지막 캡션이 최종 클릭을 설명하게 하세요. 브리핑에서 이 점을 말하세요.
  • 프로덕션 vs 스테이징. 라이브 프로덕션 사이트에서 녹화하려면, 무엇을 생성할지 (주문, 이메일, 재고 변경)와 어떻게 정리할지 나열한 후 명시적 동의가 필요합니다. 그곳에서는 읽기 전용 또는 되돌릴 수 있는 플로우를 선호하세요.
  • 자격 증명. 비밀번호와 OTP는 사용자가 제어하는 env vars / 로컬 파일에 넣고, 절대 채팅이나 사용자가 만드는 파일에 넣지 마세요. 사용자가 이미 입력한 사용자 이름/이메일은 비밀은 아니지만, TV_USERNAME 이상으로 파일에 반복해서 쓰지 마세요.
  • 타사 로그인 (Google, Microsoft, SSO, 캡차). 자동화된 로그인은 일반적으로 봇 차단 또는 2FA에 걸립니다. 사용자가 헤드 브라우저에서 한 번 수동으로 로그인하게 한 후 (npx playwright codegen --save-storage=.auth/state.json <login URL>), 저장된 세션으로 녹화하고 TV_USERNAME을 설정하지 않은 상태로 두세요.
  • 게시. 전달 전에 개인 데이터가 있는지 다시 확인하고, 아웃트로에 음악 크레딧을 유지하세요 (CC BY는 저작자 표시 필요). 공개 페이지는 내부 교육보다 더 엄격한 대상입니다 — 개인정보 규칙을 엄격히 적용하세요.

Phase 2 — 발견 및 리허설

  1. 프로젝트별로 작업 폴더 생성 (예: tvideo-work/<app>/), 그런 다음 templates/recorder/를 recorder/로 복사하고 거기서 npm i 실행.
  2. 발견: 각 플로우 페이지를 열고 (Playwright MCP / 브라우저 도구, 또는 임시 스크립트), 안정적인 선택자를 선택하세요 — CSS 클래스보다 역할/레이블/test-id를 선호합니다. 촬영에 적합하지 않은 것들을 기록하세요 (recording.md 참조: 네이티브 <select> 팝업, 날짜 선택기, 즉시 스크롤 점프, 예약 창).
  3. 각 클립에 대해 하나의 스펙을 recorder/clips/NN-name.spec.ts로 작성하세요. clips/01-example.spec.ts를 따르세요: 먼저 createTimeline; 각 시청자에게 보이는 단계는 tl.step('<캡션 텍스트>', …)로 끝나며 expect로 끝납니다. tap()/typeInto()를 통한 클릭; 화면 아래에 있는 경우 glideTo(); 중요한 순간 후 hold(); 마지막에 await tl.save(). 사용자가 할 것처럼 값을 선택하세요 — 코드를 입력하는 대신 드롭다운/달력에서 선택.
  4. 리허설: TV_REHEARSE=1 npx playwright test — 비디오 없음, 일시 중지 없음. 여기서 모든 실패를 수정하세요. 비용은 몇 초이며, 망친 테이크를 방지합니다.

Phase 3 — 녹화

npx playwright test (또는 하나의 클립: npx playwright test clips/02-). 각 클립은 test-results/<clip>/ 아래에 video.webm, timeline.json, clicks.json을 씁니다. 즉시 복사하세요 (다음 단계에서 수행) — Playwright는 다음 실행 시 test-results/를 지웁니다.

단계 실패는 앱이 예상치 못한 일 (유효성 검사, 비즈니스 규칙, 느린 로드)을 했음을 의미합니다. 실패 스크린샷을 읽고, 스펙이나 데이터를 수정한 후 해당 클립을 다시 실행하세요. 테이크를 얻기 위해 어설션을 느슨하게 하지 마세요. 깨진 플로우의 녹화는 사용자에게 잘못된 것을 가르칩니다.

Phase 4 — 편집 설정

클립당 하나의 Hyperframes 프로젝트, recorder 옆에 (예: tvideo-work/<app>/clip-02/). hyperframes init는 자체 시작 파일을 씁니다. 템플릿을 덮어쓰는 것은 의도된 것입니다 (build.mjs가 index.html을 재생성합니다). 작업 폴더에서 실행:

npx hyperframes init clip-02 --non-interactive --example=blank
cp -R <skill>/templates/editor/. clip-02/
cp clip-02/tvideo.config.example.json clip-02/tvideo.config.json   # 브랜드, 글꼴, 로고, 음악, lang
cp clip-02/plan.example.json clip-02/plan.json                     # 제목, 아웃트로, tl.step당 하나의 단계
ls recorder/test-results/                                          # 클립의 폴더 이름이 길다 — 여기서 찾으세요
bash <skill>/scripts/import.sh recorder/test-results/<해당-폴더> clip-02
bash <skill>/scripts/sfx.sh clip-02                                # click-soft, whoosh-short, chime, sparkle

tvideo.config.json에서: lang과 readingCharsPerSec (≈15 영어, ≈12 태국어 — 느린 스크립트는 더 느리게 읽음), 브랜드 색상, logo (경로, 또는 텍스트 전용 카드의 경우 null)를 설정하세요. music.credit를 유지하세요 — 번들 트랙은 CC BY입니다.

plan.json 단계는 recorder의 tl.step과 1:1, 순서대로 매핑됩니다 (빌드가 불일치를 거부합니다). plan.json의 캡션은 시청자가 읽는 것입니다 — 짧은 지시사항으로 유지하세요 ("‘저장’을 클릭하세요"), 내레이션이 아닙니다. 보통 tl.step 레이블이 이미 좋은 캡션입니다. 그대로 복사하세요.

Phase 5 — 측정, 빌드, 확인

  1. 좌표를 찾기 위해 프레임을 추출: bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …. 좋은 시간: clicks.json의 각 클릭에서 약 0.3초 전 (커서가 이미 컨트롤 위에 있음 — 그것이 위치), 각 단계의 endMs에서 0.3초 전 (안정된 결과). 전체 크기 PNG를 읽으세요. 좌표는 녹화의 픽셀 (예: 1280×800)입니다.
  2. 필요에 따라 단계별로 추가하세요 (자세한 내용은 references/editing.md 참조):
    • zoom {scale,at} + ring {x,y,w,h} 누를 컨트롤에 — 확대는 링 주위를 중심으로 합니다 (확대의 고정점이 컨트롤 위에 있어야 하며, 그렇지 않으면 컨트롤이 가장자리로 밀려 잘림);
    • holdFirst: true 컨트롤이 클릭되면 사라질 때 (이동하는 버튼) — 먼저 클릭 전 프레임을 표시;
    • mask {x,y,w,h,text,after} 배송되지 말아야 할 값을 가리기 위해;
    • chimeAfter: <s> 성공 순간.
  3. node build.mjs를 실행한 후 npx hyperframes check를 실행하세요. 모든 오류를 수정하세요. 캡션 페이드인 중 대비 경고는 예상되며 해롭지 않습니다.
  4. 직접 눈으로 확인: build.mjs가 각 단계가 OUTPUT 타임라인에서 어디에 위치하는지 출력합니다 (출력 시간 ≠ 녹화 시간 — 인트로와 홀드가 이동시킵니다). 해당 윈도우 내에서 스냅샷을 찍으세요 — npx hyperframes snapshot --at <t…> --no-end, 링이 있는 각 정지 화면, 각 마스크, 각 단계 중간점에서 하나씩 — 그리고 접촉 시트를 읽으세요. 링은 컨트롤 위에 있어야 하고, 마스크는 정확히 덮어야 하며, 캡션은 화면에 표시된 것과 일치해야 합니다.

Phase 6 — 검토 및 렌더링

  1. 미리보기 열기: npx hyperframes render --quality draft -o renders/draft.mp4 및 open (Studio 미리보기 npx hyperframes preview --background도 작동하지만, 긴 클립에서 탐색이 끊길 수 있음; 렌더링은 그렇지 않음).
  2. 계획/구성 편집 및 재빌드, 또는 푸티지 자체가 잘못된 경우 (페이싱, 점프, 잘못된 데이터) 재녹화를 통해 피드백을 반복하세요. 푸티지 문제는 오버레이가 아닌 소스에서 수정하세요.
  3. 최종: npx hyperframes render --quality delivery -o renders/<클립-이름>.mp4. 경로, 지속 시간 및 크기를 보고하세요.
  4. 환경이 공유된 경우 앱에서 녹화가 생성한 것 (데모 주문/예약)을 정리하고, 정리한 내용을 말하세요.

문제 발생 시

references/troubleshooting.md에는 이 파이프라인이 이미 겪은 실패와 실제 원인 (푸티지/타임라인 드리프트, 네이티브 선택, 예약 창, 덮어쓰기된 test-results, SFX 중복 린트, 미리보기 끊김)이 나열되어 있습니다. 처음부터 디버깅하기 전에 확인하세요.

이 스킬의 파일

  • templates/recorder/ — Playwright 프로젝트: cursor.ts, timeline.ts, auth.setup.ts, playwright.config.ts, clips/01-example.spec.ts (플러그인 리포지토리의 examples/demo-app용으로 작성, plan.example.json과 함께 제공)
  • templates/editor/ — build.mjs, plan.example.json, tvideo.config.example.json, assets/fonts (OFL), assets/music (CC BY)
  • scripts/ — import.sh, frames.sh, sfx.sh, voice.mjs (선택적 TTS)
  • references/ — recording.md, editing.md, narration.md, hyperframes-notes.md, troubleshooting.md

관련 스킬