Auto-Loom

모든 웹 앱을 내레이션이 포함된 자가 구동 MP4로 바꿔보세요. 페이지가 스크롤되고, 요소가 하이라이트되며, 경로 사이를 이동하는 동안 AI 음성이 나레이션합니다 — 밀리초 단위로 정확하게 맞춰집니다. 수동 스크린 레코딩도, 고생한 Loom 테이크도 필요 없습니다. 나레이션 한 줄을 수정하고 몇 분 안에 다시 렌더링하세요.

작동 방식: ElevenLabs가 스토리보드의 각 비트(beat)별로 오디오 클립 하나를 생성합니다. ffprobe가 각 클립의 정확한 길이를 측정합니다. Playwright가 해당 시간만큼 브라우저를 구동하면서 창을 녹화합니다. ffmpeg가 최종 MP4에 캡션 트랙을 먹싱합니다. 오디오 길이가 기준 시간(ground truth)이 되며, 비주얼은 이에 종속되므로 동기화가 정확합니다.

이 폴더가 전체 엔진입니다. 동반 스킬들은 이 동일한 스크립트를 얇게 감싼 진입점입니다:

auto-loom-proof — 소프트웨어 팩토리 증명 영상: 카메라 앞에서 빌드의 승인 기준을 비트별로 하나씩 수행합니다.

이 SKILL.md는 엔진과 개발자 모드를 다룹니다: 여러분은 코드베이스를 가지고 있고, 앱이 localhost에서 실행 중이며, JSX에 안정적인 선택자를 추가할 수 있습니다.

설정 (1회, 약 3분)

cd <이-스킬-폴더>
bash scripts/setup.sh        # Playwright + Chromium 설치, .env.local 생성
# .env.local 편집 → ElevenLabs API 키 추가
node scripts/doctor.mjs      # node, ffmpeg, playwright, 키, 음성 확인

아직 ElevenLabs 계정이 없나요? 관리자의 추천 링크로 가입하세요: https://try.elevenlabs.io/atherial

doctor.mjs는 누락된 항목에 대한 정확한 수정 방법을 출력합니다. 요구 사항: Node 18+, ffmpeg (brew install ffmpeg), ElevenLabs API 키. 음성 옵션: references/voices.md.

간이 테스트 (30초, example.com 녹화):

node scripts/run.mjs --beats examples/smoke-beats.json

0단계 — 먼저 사용자와 인터뷰하세요

바로 빌드를 시작하지 마세요. 다음을 물어보세요:

1. 어떤 URL 또는 앱을 녹화합니까? 로컬에서 실행 중인가요?
2. 수신자는 누구입니까 — 이름과 상황은?
3. 어떤 이야기인가요? 무엇이 변경되었거나 처음으로 보여주는 것인가요?
4. 강조해야 할 특정 기능, 지표 또는 섹션은 무엇인가요?
5. 분위기는 어떤가요? (클라이언트 업데이트, 내부 데모, 잠재 고객 쇼케이스)
6. 앱에 로그인이 필요한가요? (references/auth.md 참조 — 채팅에서 절대 비밀번호를 묻지 마세요)
7. 목표 길이 — 30초, 60초, 75초?

급할 때: 1~3번만 묻고 나머지는 앱에서 추론하세요.

1단계 — 스토리보드 작성 (`beats.json`)

코드를 건드리기 전에 나레이션을 작성하고 그대로 승인받으세요. 대본 규칙과 적합한 비트 프레이밍은 references/tts-rules.md에 있습니다.

{
  "meta": {
    "title": "Acme 대시보드 둘러보기",
    "slug": "acme-walkthrough",
    "cta": "피드백을 보내주시면 다음 단계로 넘어가겠습니다.",
    "targetLengthSec": 70
  },
  "baseUrl": "http://localhost:3000",
  "viewport": { "width": 1920, "height": 1080 },
  "beats": [
    {
      "id": 1,
      "page": "/dashboard/insights",
      "text": "안녕하세요 Jim. AI 가시성 트래커에 몇 가지 업데이트를 배포했습니다.",
      "actions": [
        { "fn": "waitFor",    "sel": "[data-vn=kpi-row]" },
        { "fn": "scrollToEl", "sel": "[data-vn=kpi-row]", "opts": { "instant": true } },
        { "fn": "hl",         "sel": "[data-vn=kpi-row]" }
      ]
    }
  ]
}

전체 스키마: schema/beats.schema.json. 액션 테이블 및 선택자 가이드: references/actions.md. 로그인 옵션 (스크립트 단계 또는 저장된 세션): references/auth.md.

비용을 지출하기 전에 확인하세요:

node scripts/validate.mjs --beats <file>       # 구조 + TTS + 페이싱 린트
node scripts/run.mjs --beats <file> --script-only   # 나레이션 출력 후 중단

유효성 검사기는 알 수 없는 액션, 누락된 선택자, TTS 문제 (em 대시, 단순 이니셜리즘, 긴 문장), 목표 길이에 맞지 않는 페이싱을 잡아냅니다.

--script-only는 비용 절감 검토 게이트입니다: 각 비트의 나레이션을 비트별 시간 추정치와 함께 출력하고 ElevenLabs 호출이나 녹화 전에 종료합니다. 여기서 대본을 승인받은 후, 플래그 없이 다시 실행하여 크레딧을 사용하세요.

2단계 — 페이지 계측 (개발자 모드)

Playwright에는 안정적인 선택자가 필요합니다. 코드베이스에 접근 가능하면 컴포넌트 JSX에 data-vn 속성을 추가하세요:

<div data-vn="kpi-row" className="grid grid-cols-4 gap-4">
<Card data-vn="competitor-chart" ...>

그런 다음 참조하세요: { "fn": "hl", "sel": "[data-vn=kpi-row]" }.

녹화 중 인터랙티브 드릴다운을 억제하세요. role="button" / tabIndex={0}이 있는 클릭 가능한 카드는 하이라이트 중 자동 포커스되어 영상 중간에 드로어를 열 수 있습니다. 데모 모드 플래그로 게이트하세요: {!isDemoMode() && <MetricBreakdownSheet ... />}.

로컬에서 앱에 인증이 필요하면, 데모 모드(인증 우회, 나레이션 숫자와 정확히 일치하는 fixture 데이터)를 연결하거나 references/auth.md의 인증 경로를 사용하세요.

CSP 참고: 레코더는 bypassCSP: true로 Chromium을 실행하므로 엄격한 CSP 페이지에 presenter.js를 주입할 수 있습니다. 라이브 세션이 있는 프로덕션 앱을 가리키는 경우, 해당 자동화 브라우저 컨텍스트 내에서 Content-Security-Policy가 비활성화된다는 점을 알아두세요.

3단계 — 단일 명령어

node scripts/run.mjs --beats <file>

이 명령은 실행합니다: 유효성 검사 → 오디오 (텍스트 해시로 캐시됨) → 사전 점검 (녹화 전에 모든 선택자를 해결하는 헤드리스 패스) → 녹화 → 캡션 → 먹싱 → 확인. 출력은 demo-video-out/<slug>/에 저장됩니다:

<slug>-demo.mp4 — 최종 영상 (H.264/AAC, 소프트 캡션 트랙)
<slug>-demo-contact-sheet.png — 육안 검사를 위한 샘플 프레임
qa/beat-NN.png — 각 비트의 유지 시점 정확한 스크린샷
captions.srt, audio/, video/recording.webm

모든 플래그: --script-only (1단계의 검토 게이트 — ElevenLabs 호출이나 녹화 전에 나레이션 대본을 출력하고 종료), --preflight-only (선택자만 확인, 비용 없음), --skip-audio (시각적 변경만 — 오디오 재사용), --skip-preflight (헤드리스 선택자 확인 건너뛰기 — 사전 점검이 방금 통과했고 변경된 것이 없을 때만), --burn-captions (트랙을 제거하는 플랫폼을 위해 캡션을 픽셀에 하드코딩), --no-captions, --out <dir>, --env <envfile>.

4단계 — 보내기 전에 확인

run.mjs는 길이(MP4 = 오디오 합계 ± 0.5초 이내), 오디오 레벨(무음 트랙 감지)을 확인하고 QA 스크린샷을 생성합니다. 그래도 육안으로 확인해야 합니다:

연락처 시트 + qa/beat-NN.png: 각 프레임은 해당 비트가 나레이션하는 내용을 보여줍니다 — 로그인 페이지, 오류 상태, 예상치 못한 모달이 없어야 합니다.
첫 번째 비트는 수신자의 이름을 말하고, 마지막 비트는 CTA를 그대로 전달합니다.

반복 작업

나레이션 수정 → 다시 실행; 변경된 비트의 오디오만 재생성됩니다.
시각적/페이싱 수정 → --skip-audio.
선택자 깨짐 → --preflight-only가 정확히 어떤 비트와 선택자인지 보여줍니다.

알려진 문제점

핫 리로드는 주입된 presenter를 지웁니다. 이미 처리됨 — presenter는 각 비트 전에 다시 주입됩니다. 하지만 녹화 중에는 앱을 편집하지 마세요.
포트 변경. 3000번이 사용 중이면 yarn dev가 3001번을 사용합니다 — baseUrl을 업데이트하세요.
무료 vs 유료 음성. 클론/라이브러리 음성은 무료 요금제에서 payment_required 오류를 발생시킵니다. doctor.mjs가 렌더링 전에 이를 감지합니다.
i18n 리디렉션. /en/dashboard → /dashboard 리디렉션은 올바르게 따라지며, 동일 페이지 비트는 다시 탐색하지 않습니다.
전송. MP4는 자체 포함되어 있습니다 — 이메일, Slack, LinkedIn DM, Notion 임베드, 또는 Descript로 가져와 개인 인트로를 추가할 수 있습니다.

MikeFishbeinAtherial/infinite-headcount

infinite-headcount란 무엇인가요?

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

문서