chenlikun2010/product-promo-video-skill

제품 홍보 영상 제작 (Remotion)

「素材 디렉토리 + 크리에이티브 아이디어」로 바로 재생 가능한 MP4 홍보 영상을 만듭니다. 주체는 Remotion(React 코드화 비디오) 로컬 렌더링으로, 재현 가능하고 쉽게 미세 조정이 가능합니다. 스크립트, TTS, 소량의 보충 컷은 우선 알리바바 바이리안 CLI bl을 사용합니다.

적합: 사진/실물 사진/미니프로그램 스크린샷/짧은 동영상 위주, 텍스트+모션 효과+더빙의 모션 그래픽스형 홍보 영상(전시장 루프, 제품 소개, 발표회 오프닝). 부적합: 많은 실사 촬영/복잡한 카메라 무빙이 필요한 장면. 소량의 부족한 장면은 바이리안 HappyHorse 모델로 보충한 후, 다시 Remotion으로 합성할 수 있습니다.

환경 사전 준비

• node(>=18) npm ffmpeg/ffprobe python3(numpy, requests 포함). 작업 시작 전 which node ffmpeg python3로 확인.
• bl CLI 설치 및 로그인 완료: bl --version, bl auth status. bl 사용 전 bailian-cli 스킬의 버전 사전 검사 규칙에 따라 버전을 확인합니다.
• 렌더링 시 인터넷 연결 필요 (최초 로드 Noto Sans SC 폰트).

표준 워크플로우 (순서대로 실행)

1. 素材 및 의도 파악

• 사용자에게 素材 디렉토리와 크리에이티브 아이디어/판매 포인트를 요청합니다. 먼저 디렉토리 목록을 출력합니다: find <dir> -type f \( -iname '*.jpg' -o -iname '*.png' -o -iname '*.mp4' -o -iname '*.mov' \).
• 핵심 이미지를 하나씩 Read (제품, 기능 포인트, 인터페이스 파악), 각 동영상에 대해 ffprobe로 길이/코덱/해상도 확인.
• 위험 요소 식별: ① 스크린샷에 불리한 데이터(예: "제때 약 복용률 4%")가 있는 경우 영상에서 React로 긍정적인 데이터로 덮어쓰기; ② 동일 제품에 여러 색상/모델이 있는 경우 메인 비주얼 선택; ③ 관련 없는 素材 제거.

2. 스토리보드 디자인, 먼저 사용자와 조율 (중요)

• AskUserQuestion을 사용하여 다음을 확인: 스타일, 길이(전시장 루프는 60–90초 권장), 화면 비율(가로 1920×1080 / 세로 1080×1920), 더빙 방식.
• 스타일은 기존 3가지 프리셋 중에서 바로 선택 제공(styles/STYLES.md 참조): warm 따뜻한 가족형 / guochao 활력 중국풍 / tech 비즈니스 테크. 각 세트는 이미 색상+장식+스토리보드가 구현되어 있어, 선택 후 스타일 적용 단계에서 바로 사용하고 처음부터 시각 디자인을 할 필요가 없습니다. 완전히 새로운 스타일이 필요하면 가장 유사한 것을 기반으로 수정합니다.
• 카피 어조는 스타일에 따라 결정: 감성 스토리텔링(warm/guochao) 또는 회사 제품 소개(tech).
• 바이리안을 사용하여 스크립트/스토리보드 초안을 작성한 후, 사람이 정리할 수 있습니다:

bl text chat \
  --system "Reply in 简体中文. 输出紧凑的产品宣传片分镜表." \
  --message "根据这些素材和卖点，写一版60秒产品宣传片分镜：<素材清单+卖点>"

• 스토리보드 표 산출: 각 컷(컷 번호/길이/화면/큰 자막/내레이션/사용할 素材). 전시장 영상 원칙: 소리 없이도 이해 가능(큰 자막 위주), 3초 안에 시선 사로잡기, 마지막에 처음으로 다시 이어져 루프 가능하도록.

3. 템플릿으로 프로젝트 생성

PROJ="$HOME/<영상명>"
cp -R ~/.claude/skills/product-promo-video/template "$PROJ"
cd "$PROJ" && npm install
mkdir -p public/assets public/audio out

템플릿에는 다음이 포함됨: theme.ts(색상/폰트/SCENE_FRAMES), components.tsx(KenBurns/BigTitle/Subtitle/Narration/BgMusic/PhoneMock/Chip), Video.tsx(TransitionSeries 크로스페이드), Root.tsx, scenes/AllScenes.example.tsx(완전한 예제, 수정 후 AllScenes.tsx로 저장하여 Video에서 참조).

4. 素材를 public/assets로 처리

• HEVC는 반드시 H.264로 변환(Chromium의 HEVC 디코딩 불안정): ffmpeg -y -i in.mp4 -c:v libx264 -pix_fmt yuv420p -crf 20 -an public/assets/weather.mp4
• 이미지는 복사하고 ASCII 파일명으로 변경(staticFile이 한글 경로에서 불안정): intro.jpg / device.jpg / app_home.jpg ....
• 불리한 데이터가 있는 스크린샷은 그대로 복사하고, 스토리보드 컴포넌트에서 React 카드를 그려 덮어씁니다.

5. 선택 사항: 바이리안 HappyHorse로 컷 보충

• 素材에 중요한 장면이 부족할 때 bl video generate / bl video ref를 사용하여 보충 컷을 생성할 수 있습니다. 素材가 충분하면 생략하고 Remotion 모션 효과만 사용합니다.
• 스킬에서 HappyHorse 동영상 생성 길이를 제한하지 마십시오. --duration은 사용자 요구, 예산 및 바이리안 모델 지원 범위에 따라 설정합니다. 더 긴 완성 영상이 필요할 경우 여러 클립을 생성한 후 Remotion/ffmpeg로 합성합니다.
• 시행착오 비용을 줄이기 위해, 첫 테스트는 720P, 5초 샘플로 방향을 확인한 후, 확인이 끝나면 실제 요구에 맞게 매개변수를 조정하는 것을 권장합니다.
• 텍스트-비디오 생성 예시 (저비용 테스트 샘플, 길이 조정 가능):

bl video generate \
  --model happyhorse-1.1-t2v \
  --prompt "明亮现代展厅里，一台智能健康设备在柔和灯光下缓慢旋转，商务科技质感，无文字，无logo" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/ai_device_5s.mp4

• 이미지-비디오 생성 예시 (저비용 테스트 샘플; 로컬 이미지는 --image로 직접 전달 가능, CLI가 자동으로 임시 파일 업로드):

bl video generate \
  --model happyhorse-1.1-i2v \
  --image public/assets/device.jpg \
  --prompt "保持产品外观一致，镜头轻微推进，背景干净，柔和反光，无文字" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/device_i2v_5s.mp4

• 생성 후 ffprobe로 길이/코덱 확인; HEVC이거나 브라우저에서 불안정하면 4단계에 따라 H.264로 변환합니다.

6. 카피 작성 + 알리바이리안 더빙 (첫 번째 선택)

• 내레이션을 narration.json에 작성: {"s1":"...","s2":"..."}, 키 이름은 스토리보드 컷에 해당하며 Narration file="s1.mp3"와 일치해야 합니다. 쉼표로 문장을 구분하면 TTS 자연스러운 멈춤에 도움이 됩니다.
• 첫 번째 선택: 바이리안 CosyVoice:

source ~/.claude/skills/product-promo-video/config/bailian.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_bailian.py \
  --script narration.json --out public/audio

• CLI를 직접 호출하여 단일 문장 생성:

bl speech synthesize \
  --text "一句产品宣传片旁白" \
  --voice longanwen_v3 \
  --language zh \
  --instruction "商务科技宣传片旁白，语气自信、清晰、温暖，语速适中" \
  --format mp3 \
  --out public/audio/s1.mp3

• Volcano Engine을 대안으로 사용:

source ~/.claude/skills/product-promo-video/config/volcano.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_volcano.py \
  --script narration.json --out public/audio

• code 3001 resource not granted 오류 = 계정 측 미승인: Volcano 콘솔에서 '음성 합성'을 활성화하고, 음색을 해당 appid에 추가한 후, appid/token 쌍을 확인합니다. 서비스가 방금 활성화된 경우 첫 번째 요청이 여전히 실패할 수 있으며, 스크립트에는 이미 재시도 로직이 포함되어 있습니다. 실패한 개별 요청은 따로 다시 실행하면 됩니다.
• 네트워크/권한 없을 때의 대비책: scripts/gen_tts_say.sh narration.json public/audio(macOS say, 음질은 보통, 임시용).
• 대형 모델 음색(더 자연스러움, 권장): *_bigtts / saturn_* / *_uranus_* 등 대형 모델 음색을 사용하는 경우 v3 인터페이스 사용: source config/seed.env 후 python3 scripts/gen_tts_seed.py --script narration.json --out public/audio. 음색 변경은 export SEED_SPEAKER=<음색 ID>로 덮어쓰면 됩니다. API Key 인증(X-Api-Key), 스트리밍 반환으로, v1(BV 음색)과는 다른 서비스/과금 체계입니다.
  • Resource-Id는 seed-tts-2.0 사용(seed.env 기본값). 실제 테스트 결과 saturn_* 및 *_uranus_* 음색이 모두 이 ID를 사용합니다. 잘못된 ID(예: seed-tts-1.0/volc.megatts.default) 사용 시 code 55000000 resource ID is mismatched with speaker 오류가 발생합니다.
  • 네트워크/프록시 지터로 인해 간헐적으로 RemoteDisconnected 오류가 발생할 수 있으며, 스크립트에는 예외 처리+재시도가 내장되어 있습니다(--retry 5).

7. 실제 오디오 길이로 장면 길이 보정 (중요, 그렇지 않으면 잘림)

~/.claude/skills/product-promo-video/scripts/measure_audio.sh public/audio

theme.ts의 SCENE_FRAMES에서 각 구간이 다음 조건을 만족하는지 확인:

장면 프레임 수 ≥ Narration의 delayFrames + ceil(오디오 초 × fps) + 마무리 여백(≥15 프레임 권장) 길이를 변경한 후에는 Video.tsx의 총 프레임 수를 함께 확인하세요(자동 합계, 일반적으로 수정 불필요).

8. 스타일 적용 / 스토리보드 컴포넌트 작성

• 첫 번째 선택: 기존 스타일 프리셋 적용(styles/STYLES.md). 선택한 스타일의 theme.ts, 장식 모듈, AllScenes.tsx를 src/ 해당 위치에 복사한 후, 본 영상 카피에 맞게 화면의 큰 자막 텍스트만 변경하면 됩니다. 세 가지: warm/guochao/tech.
• 수동 작성/미세 조정 스토리보드: components.tsx의 BigTitle(큰 자막), KenBurns, Subtitle, PhoneMock(crop 지원), Chip, FeatureCard 사용; 중국풍/테크는 각각 해당 장식 요소(도장/유리 카드/코너 마크/HUD)를 추가합니다.
• 각 구간에 <Narration file="sX.mp3" delayFrames={..} />를 배치합니다.
• 불리한 데이터 덮어쓰기: 해당 PhoneMock 위에 React 카드를 겹쳐 놓습니다(예제 MedsBadge 참조).

9. 배경 음악

python3 ~/.claude/skills/product-promo-video/scripts/gen_bgm.py \
  --duration <영상 시간+2> --out public/audio/bgm.mp3   # 선택: --semitones 조옮김 --gain 볼륨 조절

Video.tsx에는 이미 <BgMusic base={0.85} />가 포함되어 있으며, 자동으로 영상 길이에 맞춰 페이드 아웃되고 내레이션 아래에 위치합니다. 시끄럽게 느껴지면 base 값을 낮추세요.

10. 렌더링 + 자체 점검

npx remotion render Promo "out/<영상명>.mp4" --concurrency=2
~/.claude/skills/product-promo-video/scripts/verify.sh "out/<영상명>.mp4"

• --concurrency=2 사용: 높은 동시성(4)은 로컬에서 간헐적으로 Node 충돌을 일으킬 수 있습니다(출력이 Node.js v22.x 스택 끝만 남고 완성본 없음). 충돌 시 동시성을 낮추고 포그라운드에서 다시 실행하면 일반적으로 통과됩니다.
• 백그라운드에서 렌더링하는 경우, 충돌 시에도 exit 0으로 종료될 수 있으므로, 종료 코드만 보지 말고 out/ 디렉토리에 mp4 파일이 실제로 생성되었는지 반드시 확인하십시오.
• 그런 다음 Read로 /tmp/vchk의 키 프레임을 확인(한글/이모지/레이아웃 확인), verify.sh의 볼륨 확인(평균 약 -18~-23dB가 정상, 무음이 아니어야 함). 필요한 경우 silencedetect로 특정 내레이션이 완전히 발음되었는지 확인합니다.

11. 전달 및 변형

완성 영상 경로/사양/길이를 알립니다. 일반적인 추가 요청: 실사 짧은 동영상 삽입, 세로 화면 버전 제작(Root.tsx의 너비/높이 변경 + 레이아웃 재구성), 카피/색상/음악 변경 후 재렌더링. 또는 npm run dev로 Remotion Studio를 열어 실시간 미리보기를 할 수 있습니다.

핵심 주의사항 (반드시 준수)

• 내레이션은 반드시 <Sequence from={delayFrames}> 안에 넣어야 합니다. if(frame<delay) return null을 사용하여 "지연"시키면 안 됩니다. 이는 재생 시작을 늦추는 것이 아니라 오디오 시작 부분의 delay초를 건너뛰어 각 문장의 첫 글자가 잘리는 현상이 발생합니다(전형적 증상: "爸妈的药"가 "的药"만 읽힘). 템플릿의 Narration은 이미 올바르게 작성되어 있습니다.
• HEVC 동영상은 먼저 H.264로 변환한 후 <OffthreadVideo>를 사용해야 합니다. 그렇지 않으면 Chromium 렌더링 시 검은 화면/오류가 발생합니다.
• 素材는 ASCII 파일명으로 public/assets에 저장하고, staticFile('assets/xx.jpg')로 참조합니다.
• 한글 폰트는 @remotion/google-fonts/NotoSansSC를 사용합니다(템플릿 theme.ts에 이미 설정되어 있으며, 대체 폰트는 Apple 산돌고딕). 컬러 이모지는 Chromium에서 정상적으로 렌더링되므로 아이콘으로 안심하고 사용할 수 있습니다.
• 더빙 생성 후에는 반드시 길이를 다시 측정하고 SCENE_FRAMES를 보정해야 합니다. 다른 음색/말하기 속도에 따라 길이가 달라지므로, 그렇지 않으면 끝부분이 잘립니다.
• 5초 샘플을 프로덕션 제한으로 작성하지 마십시오. HappyHorse 보충 컷의 --duration은 사용자 요구, 예산 및 모델 지원 범위에 따라 결정됩니다. 긴 영상은 여러 AI 클립, 실제 素材 및 Remotion/ffmpeg를 연결하여 완성할 수 있습니다.
• AI 비디오 프롬프트에 텍스트/로고를 넣지 마십시오. 그렇지 않으면 오타나 변형된 로고가 생성되기 쉽습니다. 브랜드명, 판매 포인트, 자막은 모두 Remotion으로 오버레이합니다.
• Volcano 3001 오류는 대부분 계정 권한 문제이지 코드 문제가 아니므로, 더빙 단계의 문제 해결 절차를 따르십시오.
• Volcano 자격 증명은 config/volcano.env에 있습니다(비밀 키 포함, 외부 유출 금지). Secret Key는 이 HTTP 인터페이스에서 사용되지 않습니다.
• 모든 remotion 패키지의 정확한 버전을 동일하게 고정해야 합니다(remotion / @remotion/cli / @remotion/transitions / @remotion/google-fonts 모두 4.0.xxx, ^ 없이). caret을 사용하면 일부 서브 패키지가 더 새로운 버전으로 설치되어 export 'HtmlInCanvas' was not found in 'remotion' 같은 번들링 오류가 발생할 수 있습니다. 템플릿은 이미 고정되어 있습니다. 새 패키지를 설치한 후 node -e "..."로 버전 일관성을 확인하십시오.

파일 맵

• scripts/gen_tts_bailian.py - 알리바이리안 CosyVoice TTS(첫 번째 선택, bl speech synthesize 호출)
• scripts/gen_tts_volcano.py - Volcano 표준 TTS(BV 음색, v1 인터페이스, env에서 자격 증명 읽기, JSON에서 카피 읽기)
• scripts/gen_tts_seed.py - Volcano 대형 모델 TTS(bigtts/saturn/uranus 음색, v3 인터페이스, API Key 인증, 권장)
• scripts/gen_tts_say.sh - macOS 오프라인 대비책 더빙
• scripts/gen_bgm.py - 따뜻한 배경 음악 합성
• scripts/measure_audio.sh - 내레이션 길이 측정 → 프레임, SCENE_FRAMES 보정
• scripts/verify.sh - 완성 영상 자체 점검(사양/볼륨/키 프레임 추출)
• config/bailian.env - 바이리안 TTS 매개변수 · config/volcano.env - Volcano 표준 TTS 자격 증명 · config/seed.env - 대형 모델 TTS 자격 증명
• config/narration.example.json - 감성 스토리텔링 카피 예제 · config/narration.corporate.example.json - 회사 제품 소개 카피 예제
• styles/STYLES.md + styles/{warm,guochao,tech}/ - 세 가지 스타일 프리셋(색상+장식+스토리보드), 선택 후 프로젝트 src/에 복사
• template/ - cp -R로 바로 사용 가능한 Remotion 프로젝트 스켈레톤