Communitygithub.com

제품 설명 동영상

모든 소프트웨어 프로젝트(GitHub 저장소, 로컬 폴더, 스크레이퍼, 자동화, 봇, 웹사이트, CLI, API 또는 전체 도구 포트폴리오)를 AI 음성 해설, 자막 및 음악이 포함된 깔끔하고 커스텀 디자인된 애니메이션 설명 동영상으로 변환합니다. 코드를 분석하여 실제 사실을 추출하고, 프로젝트에 특화된 애니메이션을 설계하며(고정 템플릿이 아님), 레이아웃을 검사하고, 신경망 음성으로 내레이션을 제공하며, MP4(가로 또는 세로), SRT 자막 및 임베드 가능한 HTML 플레이어를 내보냅니다.

제품 설명 동영상란 무엇인가요?

이 스킬은 사용자가 구축한 모든 소프트웨어 프로젝트를 전문적으로 제작된 애니메이션 설명 동영상으로 자동 변환합니다. 사용자가 '데모 동영상', '설명', '홍보', '제품 둘러보기', '작동 방식' 애니메이션, '출시 동영상', 'README/랜딩 페이지 동영상', '소셜 클립'을 요청하거나, 단순히 '내 프로젝트를 시각적으로 설명할 수 없다', '내 저장소를 이해하기 쉽게 만들어 줘', '내 도구가 어떻게 작동하는지 애니메이션으로 보여줘'라고 말할 때 사용합니다. 심지어 '동영상'이라는 단어를 언급하지 않더라도 마찬가지입니다. 스킬은 먼저 프로젝트를 분석하여 언어, 기능, 라우트, 명령어 등 실제 사실을 추출합니다. 그런 다음 프로젝트에 맞춤화된 시각적 은유와 고유한 애니메이션을 포함한 스토리보드 JSON을 설계합니다. 이 스킬은 사용자의 개입 없이 가정을 추론하고 기본 동작을 수행하도록 설계되었습니다. 스토리보드의 각 장면에는 실제 음성 해설이 될 내레이션이 포함되며, 동영상 렌더링은 선택한 엔진(Edge TTS, OpenAI TTS, ElevenLabs 등)을 사용하여 오디오를 생성하고 자막을 자동으로 만듭니다. 출력에는 MP4 동영상(가로 16:9 또는 세로 9:16), 포스터 이미지, SRT 자막 파일, 임베드 가능한 HTML 플레이어, 스토리보드 JSON이 포함되며, 사용자가 편집하고 재렌더링할 수 있습니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 에이전트 환경에서 사용하도록 설계되었습니다. 스킬은 템플릿 기반 접근 방식을 피하고, 각 프로젝트에 맞춤화된 경험을 제공하는 것이 핵심입니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cheransanketh070-afk/claude-explainer-skill/tree/HEAD/product-explainer-video

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

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

문서

제품 설명 동영상은(는) 무엇을 하나요?

사용자가 만든 무언가를 가리키면, 당신은 낯선 사람이 1분 안에 이해할 수 있는 음성 해설이 포함된 세련된 애니메이션 설명 동영상을 반환합니다. 동영상은 이 프로젝트를 위해 설계되어야 합니다: 고유한 시각적 은유, 고유한 맞춤 애니메이션. 이름만 바꾼 일반 템플릿 동영상을 절대 만들어서는 안 됩니다.

분석(사실) → 디자인 브리프 → storyboard.json(내장 + 커스텀 장면) → 검증 → 콘택트 시트 QA → 수정 → 렌더링(+음성, +음악) → 전달

스크립트는 이 파일 옆에 있는 scripts/ 디렉토리에 있습니다. $SK = 이 스킬의 폴더(SKILL.md가 있는 곳)입니다.

0. 설정 확인 (10초)

python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list

누락된 항목: pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium. ffmpeg가 없으면 사용자에게 알립니다(MP4에 필요함; --html-only는 HTML 플레이어를 제공합니다). voiceover --list는 현재 작동하는 음성 엔진을 보여줍니다.

1. 설명할 내용 이해하기

먼저 추론하고, 거의 묻지 마십시오: 주제(단일 제품 또는 포트폴리오), 청중/목적(GitHub의 개발자, 고객, 소셜), 소스(로컬 경로, 업로드된 zip, GitHub URL, 라이브 사이트 또는 설명만). 기본값: 16:9, 45–75초, 개발자와 호기심 많은 비기술적 시청자, 음성 해설 켜짐. 정말 모호한 경우에만 하나의 짧은 질문을 하십시오(예: 저장소 15개, 힌트 없음). 그렇지 않으면 한 줄로 가정을 명시하고 진행하십시오. 사용자에게 인터뷰하지 마십시오.

2. 사실 수집 (절대 건너뛰지 마십시오: 동영상의 정직성을 유지합니다)

python3 $SK/scripts/analyze_project.py /path/or/git-url [more...] -o facts.json
python3 $SK/scripts/capture_site.py https://their-site.com -o site-capture     # 라이브 사이트: 스크린샷 + 페이지 사실

분석기는 설명, 언어, 기능, 실제 README 명령어, CLI 플래그, 라우트, 접속한 도메인, 출력물, 환경 변수, CI/cron 및 표시해도 안전한 REAL STATS를 출력합니다. 읽은 후, 사실이 부족할 때는 README와 1~3개의 핵심 소스 파일을 직접 읽으십시오(핵심 루프는 무엇입니까? 사용자가 실제로 실행하는 것은 무엇입니까? 출력은 어떻게 생겼습니까?). 클론 실패 또는 네트워크 오프라인 → zip 또는 README를 요청하십시오. 사이트 캡처 차단 → 스크린샷을 요청하거나 커스텀 장면으로 UI를 그리십시오.

3. 디자인 브리프, 그 다음 스토리보드

references/narrative-playbook.md(아크, 진실성 규칙), references/storyboard-schema.md(모든 장면 유형/필드) 및 references/custom-scenes.md(맞춤 장면 작성 방법)를 읽으십시오. assets/examples/의 참조 스토리보드는 좋은 예시를 보여줍니다; 이는 영감일 뿐, 템플릿이 아닙니다: 내용, 구조 또는 표현을 재사용하지 마십시오.

먼저 (간단히 기록하십시오):

  1. 한 문장으로 된 약속.
  2. 제품이 물리적으로 하는 일(장소 간에 이동하는 것)과 이를 보여주는 단일 시각적 은유.
  3. "아하" 순간 장면.
  4. 테마, 강조 색상(사용자의 브랜드 색상이 알려진 경우), bg 스타일, 속도: 제품의 성격에 맞춥니다.
  5. 어떤 2~4개의 장면이 커스텀(이 제품을 위해 그려짐)이고 어떤 일반적인 비트가 내장 구성 요소(제목, 문제, 단계, CTA...)를 사용할지.

그런 다음 storyboard.json을 작성합니다:

  • 아크: 훅 → 문제 → 작동 방식 → 간단하다는 증명 → 실질적 결과 → 좋은 이유 → CTA; 710개 장면, 4575초.
  • 품질 기준: 제품이 진정으로 평범한 CLI가 아니라면 최소 한 장면은 커스텀이어야 합니다; 아하 장면은 항상 커스텀이거나 신중하게 선택된 내장 장면이어야 합니다. 봇은 대화를 보여줍니다; 스크레이퍼는 페이지가 행이 되는 것을 보여줍니다; API는 요청과 응답을 보여줍니다; 대시보드는 실시간 숫자를 보여줍니다.
  • 모든 장면에 narration: 말하기 스타일, 15~35단어. 이것이 음성 해설, 자막 및 SRT가 됩니다.
  • 진실만: 명령어, 플래그, 기능, 라우트 및 숫자는 사실 또는 사용자로부터 온 것입니다. 터미널 출력 및 테이블 행은 예시일 수 있지만 일반적입니다; 절대 벤치마크, 고객 수 또는 능력을 허구로 만들지 마십시오. 통계 장면은 REAL STATS/README/사용자 숫자만 사용합니다.
  • meta.url을 저장소/사이트로 설정하고 하나의 명확한 CTA로 끝냅니다.

4. 검증, 그 다음 렌더링 전에 확인

python3 $SK/scripts/storyboard.py explainer/storyboard.json
python3 $SK/scripts/render_video.py explainer/storyboard.json --contact-sheet

콘택트 시트(~20초)는 레이아웃 감사(오프스테이지, 잘림, 생략, 자막 충돌 텍스트 및 커스텀 장면 JS 오류)를 실행하고 explainer-output/contact-sheet.png를 작성합니다. 확인하십시오: 비좁거나 잘린 부분 없음, 텍스트 읽기 쉬움, 장면이 서로 명확히 다름, 커스텀 장면이 의도적으로 보임. 콘택트 시트는 장면당 늦은 프레임 하나만 보여주므로, 모든 커스텀 장면에 대해 초기 및 중간 프레임도 검사하십시오: --still 3.2,6.5. 깨끗해질 때까지 수정하고 반복하십시오.

5. 음성 해설로 렌더링

cd explainer
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
  > render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log

DONE이 나올 때까지 계속 폴링하십시오(sleep 100; tail -c 300 render.log). 샌드박스 환경(claude.ai)에서는 도구 호출이 실행되는 동안에만 백그라운드 작업이 진행되므로, sleep 폴링이 렌더링을 진행시킵니다; 실행 중에 당신의 차례를 끝내지 마십시오. 사전 설정: draft (960×540, 15fps), standard (1280×720, 30fps, 기본값), final (1920×1080, 30fps). CPU 코어가 많을수록 빠릅니다(--workers N). 세로: meta.aspect: "9:16" 또는 --vertical. 느린 머신: --fps 24.

음성 해설은 자동입니다 (--voice auto, 기본값). 렌더러는 장면당 하나의 오디오 파일을 생성하고, 내레이션이 절대 잘리지 않도록 장면을 늘리며, 음성 아래에서 음악을 낮추고, 오디오를 캐시하여 재렌더링 시 비용이 들지 않게 합니다. 엔진 우선순위: ElevenLabs (ELEVENLABS_API_KEY) → OpenAI TTS (OPENAI_API_KEY) → Edge 신경망 음성 (pip install edge-tts, 무료, 키 불필요, 인터넷 필요) → Piper (오프라인 신경망) → macOS say → espeak-ng. 옵션: --voice-name en-US-AndrewNeural (모든 엔진의 음성 이름), --voice-rate +8% (Edge), --voice none (음악만), --voice-dir folder/ (사용자 자신의 scene-01.mp3… 파일 사용), meta.voice (스토리보드에 선택 사항 저장).

렌더러가 WARNING voiceover: no speech engine available을 출력하면, 동영상은 여전히 렌더링되고(음악만) voiceover.txt에 스크립트가 있습니다. 사용자에게 명확히 알리고, 한 줄 수정 사항을 알려주십시오: 인터넷을 활성화하고 pip install edge-tts (무료)를 실행하거나, API 키를 설정하거나, espeak-ng를 설치하십시오; 그런 다음 동일한 명령어를 다시 실행하십시오(음성과 인코딩만 다시 수행됨; 플레이어와 스토리보드는 변경되지 않음). claude.ai의 샌드박스는 일반적으로 인터넷에 연결되어 있지 않으므로, 이것을 예상하십시오: 그렇게 말하고, 무음 음악 동영상과 스크립트를 제공하고, Claude Code에서 로컬로 파이프라인을 실행하거나 API 키를 사용하여 음성을 추가할 수 있다고 설명하십시오. 로그에 voiceover: using '<engine>'이 명시되지 않는 한 동영상에 음성 해설이 있다고 주장하지 마십시오.

음악: 생성된 로열티 프리 배경 음악 (--mood calm|upbeat|tech 또는 meta.music_mood); --music none 또는 --music file.mp3.

6. 전달

explainer-output/의 출력물: <name>.mp4, <name>-poster.png, player.html (자체 포함된 대화형 플레이어; <iframe src="player.html?embed">로 임베드; 모션과 자막이 있지만 오디오는 없음), captions.srt, voiceover.txt, storyboard.resolved.json, voice/, 선택적 .gif.

확인: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <name>.mp4가 오디오 스트림을 표시하는지; 지속 시간이 일치하는지; 포스터를 확인하십시오. 전달물을 /mnt/user-data/outputs/에 복사하고 present_files를 사용하여 MP4를 먼저, 그 다음 포스터, 자막, player.html 및 storyboard.json을 표시하십시오(사용자가 편집하고 재렌더링할 수 있도록). 메시지는 짧게 유지하십시오: 장면당 한 줄, 가정한 내용, 사용된 음성 엔진, 조정 방법. 유용할 때만 변형을 제안하십시오: 9:16 소셜 컷(~30초), 다른 음성 또는 브랜드 색상, 다른 저장소용 동영상.

편집 및 재렌더링

storyboard.json(텍스트, 순서, 색상, 커스텀 장면 코드)을 편집하고, 콘택트 시트를 다시 실행한 다음 렌더링하십시오. 내레이션이 변경되면 변경된 장면만 다시 합성됩니다. 장면의 duration을 설정하여 길게 할 수 있습니다; 애니메이션과 내레이션에 필요한 것보다 짧게 줄어들지 않습니다.

포트폴리오 / "내 모든 도구"

한 번의 호출로 모든 저장소를 분석하고, 다양성을 보여주는 3~4개의 주력 제품을 선택하고, 각각에 고유한 시각적 은유를 가진 커스텀 또는 최적 장면을 할당하고, 나머지 제품의 features 그리드와 프로필 링크 CTA로 마무리하십시오. 이후 제품별 심층 동영상을 제안하십시오.

문제 해결

  • Playwright is not installed → 0단계 명령어.
  • 빈/검은 프레임 또는 scene error 줄 → 커스텀 장면의 JS가 예외를 발생시킴; 감사가 예외를 출력합니다. 코드를 수정하십시오.
  • 텍스트 잘림/생략 → 텍스트를 줄이거나, 항목을 제거하거나, 커스텀 레이아웃을 만드십시오.
  • 음성이 로봇처럼 들림 → espeak입니다; 대신 Edge/OpenAI/ElevenLabs/Piper를 사용하십시오.
  • 음성이 장면 타이밍과 일치하지 않음 → 타이밍은 자동입니다(장면이 오디오에 맞춰 늘어남); 자막이 너무 빠르게 느껴지면 내레이션을 줄이십시오.
  • 로그가 움직이지 않거나 렌더링이 종료됨 → 연결된 상태로 실행되었거나 폴링하지 않음; 분리하여 다시 시작하고 폴링하십시오.
  • 출력이 너무 긺 → 가장 약한 장면을 제거하십시오; 검증기가 약 90초 이상에서 경고합니다.

정직한 한계

모션 그래픽(다이어그램, 터미널, 코드, UI 목업, 맞춤 애니메이션)이며, 화면 녹화 또는 실사 영상이 아닙니다. 실제 UI의 경우 스크린샷을 전달하거나 인터페이스를 그리십시오. 음성 품질은 사용 가능한 엔진에 따라 다릅니다.

관련 스킬