sridhar-raj/video-craft

Video craft

하나의 기준, 두 가지 작업. 누군가가 촬영한 영상을 편집하거나, 브랜드 키트와 카피로 영화를 제작합니다. 어떤 작업이든 렌더링 전에 계획되고, 정확한 스크립트로 렌더링되며, 완료 사실을 알리기 전에 측정을 통해 검증됩니다.

비디오가 완성된 것처럼 보이게 만드는 요소, 순서대로:

1. 구조. 처음 3초 안에 후크가 있고, 하나의 아이디어만 있으며, 시간을 낭비하는 요소가 없어야 합니다.
2. 리듬. 컷과 움직임이 대사와 비트에 맞춰져야 하며, 정체되거나 급한 느낌이 없어야 합니다.
3. 공예 디테일. 모든 컷 주변에 숨 쉴 공간, 잘 읽히는 자막, 감속하여 제자리에 안착하는 모션, 충분히 크고 클리핑되지 않는 사운드.
4. 증명. qa.py가 통과되고 콘택트 시트를 확인해야 합니다.

빠른 경로

요청	수행 방법
"이 녹화본을 다듬어/정리해 줘"	transcribe → plan_cuts → EDL 검토 → render → qa
"여기서 Shorts/Reel/TikTok 만들어 줘"	위와 동일, 추가로 captions.py --style punch, render.py --preset shorts --fit crop (또는 화면 녹화의 경우 blur)
"자막 추가해 줘"	transcribe.py → captions.py → render.py --captions (또는 .srt 파일 제공)
"배경 음악 추가해 줘"	render.py --music bed.mp3 (음성 아래 자동 덕킹)
"음량을 키우거나 오디오를 고쳐 줘"	render.py --voice --denoise, 목표는 platforms.md 참조
"브랜드 인트로 / 로고 리빌 / 인트로 영상"	films/brand-sting 복사, 브랜드 키트 채우기, 스틸 → 드래프트 → 마스터 → qa
"런칭 비디오 / 프로모션 / 광고"	films/launch 복사, 카피 작성, 포맷 선택, 스틸 → 드래프트 → 마스터 → qa
"이 비디오를 점검해 줘"	qa.py video.mp4 --sheet sheet.jpg [--safe]
이미 Remotion 프로젝트가 있는 경우	references/remotion.md 참조

요구 사항

편집을 위해 ffmpeg 6+ 및 Python 3.9+ 필요. 음성 인식: pip install faster-whisper (또는 openai-whisper, whisper.cpp). 영화 제작: Node 18+ 및 Playwright (npm i -D playwright && npx playwright install chromium). 자막은 ffmpeg에 libass가 있을 경우 libass로 인코딩되고, 없을 경우 Pillow로 그려집니다 (pip install pillow). 설치된 항목을 확인하려면 python3 scripts/doctor.py를 실행하세요.

모든 스크립트는 --help를 지원합니다. 작업별 폴더 구조: work/는 중간 파일, out/는 최종 결과물.

영상 편집

python3 scripts/transcribe.py raw.mp4 -o work/words.json            # 단어 수준 자막
python3 scripts/plan_cuts.py raw.mp4 --words work/words.json -o work/edl.json
python3 scripts/captions.py work/words.json --edl work/edl.json --style clean -o work/cap
python3 scripts/render.py work/edl.json -o out/final.mp4 --preset youtube \
        --captions work/cap.cues.json --music bed.mp3 --voice --zoom auto
python3 scripts/qa.py out/final.mp4 --edl work/edl.json --sheet out/sheet.jpg \
        --words work/words.json --words-check

1. 먼저 대본을 읽고 구조를 결정하세요: 무엇을 완전히 제거할지 (섹션 컷은 깔끔하게 읽히고, 문장 중간 컷은 긴박하게 읽힙니다), 후크는 무엇인지. 필요시 전체 섹션 결정 사항을 EDL의 segments에 수동으로 추가하세요.
2. plan_cuts.py는 무음 데드 에어(숨 쉴 정도로만 줄이고 완전히 제거하지 않음), 필러, 버려진 재녹음(마지막 테이크는 유지)을 제거합니다. 침묵은 녹음별로 측정되며, 모든 경계는 실제 오디오에 스냅되고, 패딩은 비대칭입니다(앞 80ms, 뒤 140ms). 제거된 단어 영역에는 절대 닿지 않습니다. 목록을 확인하세요: 강조된 반복은 재녹음처럼 보일 수 있습니다.
3. 체크포인트 긴 작업의 경우 담당자와 확인: 전후 시간, 제거된 섹션, 삭제된 재녹음. 그들의 피드백이 EDL 편집이 됩니다.
4. render.py는 단일 ffmpeg 그래프로 모든 작업을 수행합니다: 프레임 정확한 트림, 모든 컷에 8ms 페이드, 일정 프레임 레이트, 펀치인, 리프레이밍, 자막, 음성 다듬기, 덕킹된 음악, 투패스 음량 조절.
5. qa.py를 실행한 후 콘택트 시트를 확인하세요. --words-check는 결과물을 다시 전사하고 컷으로 인해 누락된 단어를 알려줍니다.

판단, 수치 및 실패 모드: references/editing.md. 오디오: references/sound.md.

영화 제작 (브랜드 인트로, 런칭 스팟, 광고)

cp -r films/brand-sting my-film && python3 scripts/sfx.py --out my-film/sfx
# my-film/index.html의 PARAMS 편집 (또는 --params '{"name": "...", ...}' 전달)
node scripts/render_film.mjs my-film/index.html --stills 0.5,1.6,2.4,3.5 -o work/stills  # 확인
node scripts/render_film.mjs my-film/index.html --draft -o work/draft.mp4                 # 리듬 판단
node scripts/render_film.mjs my-film/index.html --blur 4 -o out/intro.mp4                 # 마스터
python3 scripts/qa.py out/intro.mp4 --no-gaps --sheet out/intro.sheet.jpg --safe

1. 브랜드 키트 먼저 (references/brand-intro.md): 공식 로고 파일, 헥스 색상, 폰트, 정확한 단어, 레지스터, 포맷, 사운드, 모든 숫자의 출처. 로고를 다시 그리거나 색상을 변경하지 마세요. 주장, 고객 또는 제품 UI를 지어내지 마세요.
2. 코드보다 비트 시트 먼저: 각 비트의 시간, 움직임 요소, 이징 종류, 사운드. 하나의 레지스터(프리미엄, 클린, 테크, 볼드, 플레이풀)를 선택하고 전체 타임라인을 일관성 있게 구성하세요.
3. assets/film.js 위에 구축: 모든 픽셀은 t의 함수입니다. Film.tween, Film.spring, Film.stagger, Film.random(seed) 사용; CSS 애니메이션, 타이머 또는 Date.now는 사용하지 마세요. HTML을 브라우저에서 열어 실시간으로 스크러빙할 수 있습니다.
4. 모든 비트에서 스틸, 그 다음 드래프트, 마지막으로 마스터. 비디오를 렌더링하기 전에 스틸에서 문제를 고치세요. 마스터는 초당 약 2~5프레임으로 렌더링되며, 드래프트는 10배 빠릅니다.
5. 사운드는 영화의 일부입니다. scripts/sfx.py는 사운드 키트(히트, 붐, 후시 ×3, 라이저, 팝, 틱, 차임, 배경음)를 합성합니다; 큐는 영화 설정에 있으며 렌더러에 의해 믹싱되고 음량이 설정됩니다. 히트의 피크는 리빌 프레임에 정확히 맞춰집니다.

템플릿: films/brand-sting (3~7초 로고 리빌, 5가지 레지스터, 16:9 / 9:16 / 1:1) 및 films/launch (15초 후크 → 문제 → 리빌 → 증명 → CTA, 세 가지 포맷, 9:16은 플랫폼 안전 영역 내, *단어* 강조). 이를 시작점으로 사용하세요; 브리프에 필요하면 구조를 변경하세요.

원칙 (타이밍, 역할별 이징, 스태거, 글자 크기, 색상, 원인이 있는 전환, 피해야 할 일반적인 스타일, 이를 잡아내는 테스트): references/motion.md.

항상 적용되는 규칙

• 모든 트림은 다시 인코딩합니다. 스트림 복사 트림은 키프레임에 스냅됩니다.
• 모든 결과물은 일정한 프레임 레이트를 사용합니다. H.264 + yuv420p + AAC + +faststart.
• 음량은 측정 기준: 웹 및 소셜은 -14 LUFS / ≤ -1 dBTP, 팟캐스트는 -16.
• 텍스트는 안전 영역 내에: 9:16에서 상단 288px, 하단 672px, 오른쪽 192px(1080×1920 기준) 내에 배치. 1080 해상도에서 글자 크기 ≥ 28px.
• 정직한 콘텐츠: 실제 로고, 출처가 있는 실제 숫자, 실제 제품 UI 사용; 음악, 음성 또는 영상이 생성된 경우 명시합니다.
• 라이선스 음악만 사용. 비디오나 스트리밍 서비스에서 오디오를 추출하지 마세요.
• 완료 = 검증됨: qa.py 통과, 시트 확인, 확인할 수 없는 사항은 명확히 언급.

파일 목록

경로	설명
scripts/transcribe.py	단어 시간이 포함된 words.json 생성 (faster-whisper / whisper / whisper.cpp)
scripts/plan_cuts.py	EDL: 일시 정지, 필러, 재녹음 제거, 사유 포함
scripts/captions.py	편집된 타임라인에 SRT, 스타일 ASS, 큐 JSON 생성
scripts/render.py	EDL → 완성된 비디오 (프리셋, 리프레임, 자막, 음악, 음량)
scripts/qa.py	포맷, 길이, 검은 프레임, 프리즈, 무음, 음량, 단어, 콘택트 시트
scripts/sfx.py	합성 사운드 키트
scripts/render_film.mjs	HTML 영화 → MP4 (드래프트, 모션 블러 포함 마스터, 스틸, 포스터)
scripts/doctor.py	설치된 항목 및 누락된 항목 확인
assets/film.js	결정적 모션 엔진 + 스크러버 포함 브라우저 미리보기
films/	brand-sting 및 launch 템플릿
references/	편집, 모션, 브랜드 인트로, 사운드, 플랫폼, ffmpeg, remotion 관련 문서