dengyie/onevideo

onevideo은(는) 무엇을 하나요?

OneVideo는 "비디오 하나 만들기"를 10단계로 나눕니다. 각 단계에는 감독 문서(stages/<id>.md), 저장된 산출물(plan/*.json), 그리고 기계적 게이트가 있습니다. 사람의 승인이 필요한 단계는 승인을 거쳐야 하며, 승인 시 산출물의 해시가 잠깁니다. 공유 렌더링 엔진은 template/에 있고, 프로젝트 디렉토리에는 데이터만 넣습니다.

작업 방식

1. onevideo status는 각 단계의 상태와 다음에 읽어야 할 감독 문서를 보여줍니다. 각 단계에 진입하면 먼저 해당 stages/<id>.md를 읽고 작업을 시작하세요.
2. 창작 단계(research, proposal, script, storyboard)는 AI가 JSON/Markdown을 작성하고 onevideo validate를 실행한 후, 산출물을 사용자에게 보여주고 사용자가 확인하면 onevideo approve <stage>를 실행합니다. 사용자가 명시적으로 권한을 위임하지 않는 한 사용자를 대신해 승인하지 마세요.
3. 비창작 단계는 CLI로 실행합니다: tts, music, assets fetch, depth, timeline, render, qc. 또한 build를 사용하면 QC까지 한 번에 실행할 수 있습니다(부족한 에셋은 자동 다운로드, depth 도구가 있으면 깊이 맵과 밝기 그리드 자동 생성). publish는 review가 승인된 상태여야 합니다.
4. 구조는 시청자의 질문 순서에 맞춥니다(proposal은 질문 체인을 작성, script는 각 장면에 question 작성). 화면은 세 가지 라인으로 분업합니다: 내레이션 설명, 화면 텍스트는 키워드만, 화면은 증거 제공(storyboard.md).
5. 스토리보드는 모션 엔진 방식으로 작성하며, 한 페이지에 한 카드식으로 만들지 마세요. 먼저 references/motion-rules.md를 읽고 examples/spacex-motion을 참고하세요. 실사는 주인공 중심(footage 속도 조절, 타이틀을 피사체 뒤에 배치), 디지털은 canvas에서 연속 비행, 각 장면에는 shots가 있으며, 훅과 결론은 매 문장마다 word 키워드를 하나씩, 음악이 있으면 music.offset: "auto"를 작성하세요. onevideo timeline이 보고하는 리듬 경고(화면이 4.5초 이상 새로움 없음, 연속 동일 전환)는 처리하거나, 유지하는 이유를 사용자에게 설명하세요.
6. 렌더링 후 반드시 onevideo qc를 실행하고, out/qc/frames/의 모든 프레임을 하나씩 확인하여 화면에 문제가 없음을 확인한 후 approve review를 실행하세요.

당신은 감독입니다

리듬은 당신이掌控합니다: 각 샷이 왜 여기 있는지, 얼마나 머무를지, 어떻게 전환할지는 모두 당신이 결정하여 스토리보드에 작성합니다. CLI와 모델은 단지 도구일 뿐이며, 그들이 제시한 결론은 당신이 확인 후 채택해야 합니다.

• 화면이 부족하면 직접 만드세요: assets.json에 generate를 작성하면 이미지를 생성할 수 있습니다(variants: 2–4로 여러 장 생성, 비전 모델이 brief에 따라 하나를 선택, 모든 대안은 public/assets/<id>.take<k>.*에 유지되며, 선택이 마음에 들지 않으면 pick으로 변경). 비디오 생성도 가능합니다(kind: "video", from: <이미지 id>로 한 장의 이미지를 첫 프레임으로 삼아 움직임 생성). 생성 실패 시 동일 엔트리의 url/query로 폴백되므로, 주요 에셋에는 대체 출처를 남겨두는 것이 좋습니다. 실제 소스를 찾을 수 있을 때는 실제 소스를 우선 사용하고, 생성된 에셋은 샷 보충, 분위기 조성, 컨셉 이미지 용도로만 사용하며 뉴스 실사로 가장할 수 없습니다.
• 영상 검토: onevideo sheet는 완성된 영상을 초 단위로 연락표로 펼쳐줍니다(out/qc/sheet-NN.jpg, 각 장면이 시작하는 프레임도 함께 출력). Read를 사용해 연락표를 보면 프레임별로 넘기는 것보다 훨씬 빠릅니다. onevideo look은 비전 모델이 편집 기준으로 영상을 검토하고 결과를 out/qc/look.json에 기록하며, 각 의견에는 시간 지점과 장면이 포함됩니다. 이는 단지 보조 의견일 뿐입니다: 먼저 연락표나 stills에서 문제가 실제로 존재하는지 확인한 후 스토리보드를 수정하세요.
• 먼저 15초 샘플을 만드세요: 전체 영상을 렌더링하기 전에 render --draft --scenes hook,ipo(또는 --from 0 --to 15)로 시작 부분을 렌더링하여 스타일, 더빙, 글자 크기, 리듬이 모두 맞는지 확인한 후 전체를 렌더링하세요.
• 반복: 스토리보드 수정 → timeline(rhythm/echo 경고 처리) → render --draft [--scenes …] --note "무엇을 수정했는지" → sheet --vs prev로 이전 버전과 비교/look → 다시 수정. 각 라운드에서는 한 가지만 수정하고, 수정 후 비교하여 개선되었는지 확인한 후 다음 작업으로 넘어가세요. 확인된 사항은 handoff --lock "…"으로 기록하고 이후에 다시 건드리지 마세요.
• 인계: 세션을 변경하거나 서브 에이전트에게 작업을 넘기기 전에 먼저 onevideo handoff를 실행하세요. 그러면 단계, 확정된 매개변수, 에셋 품질 검사, 최근 몇 버전의 렌더링, 검토 의견 및 처리 대기 중인 경고를 plan/handoff.md에 기록하고, 수동으로 작성된 "잠금 / 다음 라운드에만 수정 / 비고" 세 섹션을 유지합니다. 기존 프로젝트를 인계받을 때는 먼저 plan/handoff.md를 읽으세요.
• 병렬 처리: 조사, 에셋 찾기, 에셋 생성은 서로 독립적이므로 서브 에이전트에게 병렬로 할당할 수 있습니다. 스토리보드와 리듬은 직접 작성하고 외주를 주지 마세요.

하드 규칙

• 내레이션의 모든 숫자는 plan/research.json의 facts에서 찾을 수 있어야 하며, facts에는 출처가 있어야 합니다(numbers 게이트). 게이트를 통과하기 위해 출처를 조작하지 마세요.
• 에셋은 허용 목록 라이선스(references/licensing.md)만 사용하며, CC BY 에셋은 저자와 출처를 명시해야 합니다.
• API 키는 환경 변수 또는 로컬 설정에서만 읽고, 출력하거나 프로젝트 파일에 기록하지 마세요. 공유 키(MANGO_API_KEY 등)는 api.mangoqwq.com으로만 전송하며, baseUrl을 변경하려면 전용 keyEnv를 설정해야 합니다. ~/.zcode의 프로바이더 설정은 ONEVIDEO_ZCODE_PROVIDER=1이 명시적으로 설정된 경우에만 읽습니다.
• 승인된 산출물이 변경되면 해당 단계는 stale로 표시되며, 사용자에게 다시 보여주고 approve해야 합니다. script를 변경한 후에는 반드시 tts를 다시 실행해야 합니다. 그렇지 않으면 timings 게이트에서 오류가 발생하고 렌더링이 차단됩니다. timeline.json을 수동으로 수정하지 마세요.

명령어

onevideo init <dir> --pipeline data-explainer|documentary|shorts|promo [--style midnight-data] [--aspect 16:9] [--example spacex-motion|spacex-ipo|promo-demo]
onevideo status | validate [--strict] | approve <stage> [--note …]
onevideo tts [--sample|--dry|--force|--only a,b]   # 문장별 합성 → plan/timings.json (음량 정규화 포함)
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # generate 포함: AI 이미지/비디오 생성
onevideo depth [asset ids] [--step N]               # 깊이 맵 + 밝기 그리드: 주체 통과, 키워드 회피, 자동 배경 추가, 자막 회피
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # 실제 인터페이스 스크린샷 (자체 헤드리스 Chrome 실행)
onevideo screen <asset> [--at s] [--threshold 40]   # 실사 촬영에서 검은 화면의 사각형 찾기 → footage.screen 클립
onevideo stems                                     # stem별로 분리된 트랙 WAV 내보내기 → out/publish/stems/
onevideo timeline | stills [--scene id] [--at 0.3,0.7] | studio
onevideo render [--draft] [--scenes a,b | --from s --to s] [--note …]   # 매번 하나의 버전 → out/versions/vN
onevideo versions                                   # 렌더링 기록: 버전, 범위, 타임라인 해시, 비고
onevideo handoff [--lock …] [--next …]              # 인계 페이지 → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # 음향 효과 / Lottie / 샷 레시피
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # 연락표 → out/qc/sheet-NN.jpg; --vs 이전 버전과 비교
onevideo look [--focus "자막 가독성"] [--models a,b]   # 비전 모델 영상 검토 → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

전역 설치가 되지 않은 경우 node <repo>/cli/onevideo.mjs …로 호출합니다.

참고

• 파이프라인 정의: pipelines/*.json; 시각 스타일: styles/*.json
• 작문: references/writing-ko.md · 발음: references/tts-pronunciation.md
• 장면 및 모션: references/motion-rules.md(먼저 읽기) · references/scene-catalog.md
• 데이터 및 라이선스: references/data-integrity.md · references/licensing.md
• 품질 검사: references/qc-thresholds.md
• 예제: examples/spacex-motion/(모션 엔진 데모, 36초) · examples/spacex-ipo/(데이터 차트 버전, 85초) · examples/promo-demo/(프로모 파이프라인: capture 스크린샷 + device 장면, 20초); onevideo init demo --example spacex-motion