script-to-guide - 대본과 스크린샷으로 만드는 말하는 제품 가이드

script-to-guide는 대본과 스크린샷을 넣으면 내레이션이 붙은 제품 사용 가이드를 만들어 주는 Claude Code / Codex 스킬입니다. 결과물은 작은 정적 웹 페이지이고(샘플은 1.4MB), 파일이 필요하면 MP4로도 냅니다. 화면의 모든 강조, 확대, 커서 이동은 내레이션의 단어에 걸리므로 타임라인에 손으로 놓는 것이 없습니다.

GitHub: SilverNine/script-to-guide, MIT, 한국어 샘플 가이드, 영어 샘플 가이드, 동작 갤러리

npx skills add SilverNine/script-to-guide

설치한 뒤 에이전트에게 “회원가입 흐름을 2분짜리 가이드로 만들어 줘”처럼 요청합니다. 2026-10-25에 v0.1.0을 공개한 초기 단계입니다.

데모

샘플은 mermandraw.com에서 코드 작성, 테마 선택, 내보내기, 링크 공유를 안내합니다. 재료는 대본 하나, 캡처 4장, 장면 파일 하나이고, 모든 강조는 cue(장면, 단어)로 걸었습니다.

왜 영상 파일이 아닌가

제품 화면은 바뀝니다. 녹화한 영상은 그때마다 다시 찍어야 하지만, 대본에서 만든 가이드는 고쳐서 다시 빌드하면 됩니다.

• 키프레임 대신 큐: cue(장면, 단어)가 모든 강조와 커서 이동을 내레이션에 묶습니다. 문장을 바꾸고 다시 합성하면 화면이 따라옵니다
• 재촬영 대신 캡처 한 장 교체: 버튼 자리가 바뀌면 그 캡처만 바꾸고 다시 빌드합니다
• 웹 페이지: 대본이 글자라서 선택하고 검색할 수 있습니다. 배속과 단계 이동이 기본이고, 따라하기 모드는 단계마다 멈춰서 보는 사람이 자기 앱에서 직접 해 보게 합니다. <iframe>으로 어디든 넣습니다
• 필요하면 영상으로: 같은 타임라인을 헤드리스 브라우저에서 프레임 단위로 찍어 MP4와 자막(SRT)으로 냅니다. 영상 프레임워크 의존성이 없습니다
• 받아쓰기로 확인한 내레이션: 합성한 음성을 whisper로 다시 받아써서 대본과 비교합니다. 사전에 등록한 오독은 개수로, 나머지는 일치도 점수로 알려 줍니다

작동 방식

1. 대본을 씁니다. 문단마다 어느 장면인지, 화면에 무엇이 보여야 하는지 적습니다
2. 에이전트가 웹 앱을 헤드리스 브라우저(Playwright)로 캡처합니다. 직접 찍은 스크린샷도 됩니다
3. 단어 단위 타임스탬프를 주는 음성 합성으로 내레이션을 만들고, 자막과 장면 시간표를 뽑습니다
4. 장면 파일의 cue가 스포트라이트, 번호 핀, 확대경, 커서 클릭 같은 동작을 해당 단어 시점에 겁니다
5. 정적 페이지(dist/<이름>/index.html) 또는 MP4로 빌드합니다

동작은 스포트라이트, 번호 핀, 확대경, 커서 클릭, 말풍선, 타이핑, 화면 전환, 카메라 줌, 가리기, 제목, 챕터, 단계 목록, 대화창까지 13가지 카드로 정리했습니다. 카드마다 의도, 쓸 때와 피할 때, 매개변수, 알려진 함정, 예시가 있어 에이전트가 골라 씁니다.

음성

• Edge(기본): API 키 없이 쓰는 Microsoft Edge 음성
• ElevenLabs: 키를 설정하면 사용. 샘플 가이드가 이 음성입니다
• Supertonic: 내 컴퓨터에서 돌아가는 로컬 음성, 한국어 지원
• 무음: 레이아웃 작업과 CI용

사용 기술

• 플레이어: React 단일 페이지 앱을 app.js 하나로 묶음. 시계가 오디오 재생 위치라서 화면과 소리가 어긋나지 않습니다
• 엔진: Node.js 진입점 stg.mjs 하나로 설치, 캡처, 음성 합성, 받아쓰기 확인, 웹 빌드, MP4 렌더링
• 캡처와 렌더링: Playwright Chromium, ffmpeg
• 받아쓰기 확인: Python 가상환경의 whisper
• 스킬 구성: SKILL.md 진입점, 단계별 참고 문서, 동작 카드 13종, 동작 갤러리, 영어와 한국어 샘플 가이드

범위

macOS와 Linux에서 Node 18 이상, Python 3.10 이상, ffmpeg가 필요합니다. Windows는 시험하지 않았습니다. 코드는 MIT이고, 음성 결과물은 고른 음성 제공자의 약관을 따릅니다.