videoprompt 0.1.2

Plan, generate, edit, and validate multi-shot videos with Grok and xAI.

VideoPrompt CLI

VideoPrompt는 자연어 영상 아이디어를 구조화된 스토리보드로 기획하고, 승인된 샷을 xAI Video API로 생성한 뒤 FFmpeg로 정규화·연결·검증하는 Python CLI다.

요구 사항

• macOS
• Python 3.12 이상
• FFmpeg와 FFprobe
• grok CLI와 grok login으로 만든 OAuth 세션

설치

PyPI 릴리스 후 일반 사용자는 pipx로 설치한다.

brew install ffmpeg pipx
pipx ensurepath
pipx install videoprompt
grok login
videoprompt doctor

저장소에서 개발하거나 릴리스 검증을 수행할 때는 잠금 파일과 uv를 사용한다.

brew install uv
uv sync --locked --extra test
uv run videoprompt doctor

Video API 인증에는 XAI_API_KEY가 아니라 grok login으로 만든 OAuth 세션만 사용한다. 실제 영상 호출 전에는 Grok Usage와 xAI Billing 화면에서 사용량을 확인해야 한다.

기본 흐름

인자 없이 실행하면 Cinema 15단계 관제 TUI가 열린다.

videoprompt

TUI에서 / 또는 Enter를 입력하면 전체 명령 팔레트가 표시된다. 상단 상태 바에 현재 프로젝트·다음 READY/검토 단계가 유지된다. /new로 새 프로젝트를 만들거나 /open으로 기본 프로젝트 폴더와 현재 폴더의 기존 프로젝트를 고를 수 있다. 터미널에서는 메인 화면을 밀지 않는 오버레이(alt-screen)에서 ↑↓·Enter로 선택하고, 수정 시각·아이디어가 함께 보이며 번호·경로·폴더명 직접 입력도 된다. 연 뒤 /run, /review, /approve 순서로 진행할 수 있다. 명령의 고유한 앞부분도 인식하므로 /sta는 /status, /q는 /quit로 동작한다.

/new       /open       /status     /run
/review    /approve    /revise     /regen
/import    /prompt     /reopen     /help       /quit

/regen은 피드백 없이 해당 단계를 다시 뽑을 때 쓴다. 승인된 단계면 이후 단계도 무효화되며, 확인 후 바로 /run으로 이어갈 수 있다.

새 프로젝트는 기본적으로 ~/Movies/VideoPrompt/ 아래에 생성된다. 배포 환경이나 자동화에서 위치를 바꾸려면 VIDEOPROMPT_PROJECTS_DIR 환경 변수를 사용하거나 --project-dir 옵션으로 프로젝트 경로를 직접 지정한다.

export VIDEOPROMPT_PROJECTS_DIR="$HOME/Movies/MyVideoProjects"
videoprompt cinema create "영화 아이디어"

/run은 실제 공급자 사용량이 발생할 수 있음을 표시하고 기본값 No로 다시 확인한다. 10–13단계는 승인된 09단계 기준으로 씬/컷을 자동 일괄 실행하며 context 경로를 직접 치지 않는다. 10단계는 2x2(최대 4패널) 시트로 나누어 3컷·5~6컷 씬도 여러 장으로 처리한다. 10단계는 06·07·08 시트 중 해당 씬에 필요한 이미지만 골라 레퍼런스로 붙인다. 일괄 실행 중 일부 실패 시 완료분은 유지되고, 다시 /run하면 미완료 시트부터 이어서 재시도한다. 텍스트·이미지· 영상 생성 뒤에는 기존 guided review로 이어지며, 이미지는 Preview, 영상은 QuickTime Player로 열린다. TUI를 사용하지 않는 기존 videoprompt cinema ...와 legacy CLI 명령도 그대로 유지된다.

짧은 영상용 legacy 흐름은 기존처럼 직접 실행할 수 있다.

videoprompt make "비 오는 밤, 네온사인 아래 커피 광고" --duration 15 --auto

make는 프로젝트 폴더 경로와 생성된 스토리보드를 먼저 출력하고 이 스토리보드를 승인하시겠습니까? [y/N]에서 멈춘다. y로 승인해야 에셋과 영상 생성 단계로 넘어간다. 중단되거나 오류가 나도 출력된 프로젝트 폴더를 PROJECT 자리에 넣어 검토하거나 재개할 수 있다.

make --auto 프로젝트는 후보가 한 개이고 기술 검증·최소 점수를 통과하면 중요도와 관계없이 그 후보를 자동 선택한다. 기존 프로젝트에서도 videoprompt resume PROJECT --auto를 한 번 실행하면 이 모드를 저장할 수 있다. 복수 후보처럼 실제 선택이 필요하면 CLI가 절대 파일 경로를 출력하고 macOS의 Preview 또는 QuickTime으로 검토 파일을 자동으로 연다.

videoprompt plan "비 오는 밤, 네온사인 아래 커피 광고" --duration 15
videoprompt storyboard review PROJECT
videoprompt storyboard approve PROJECT
videoprompt run PROJECT
videoprompt status PROJECT

plan은 비용이 드는 미디어 생성을 수행하지 않는다. run은 승인된 스토리보드와 검증된 입력 프레임/레퍼런스가 있을 때만 Video API를 호출한다.

첫 run에서 누락된 스타일/프레임 자산을 Grok CLI로 만들 수 있다. 새 자산은 자동 잠금되지 않고 REVIEW_REQUIRED에서 멈춘다.

videoprompt assets review PROJECT
videoprompt assets approve PROJECT --asset style-v001-representative
videoprompt run PROJECT

자막·오디오를 켠 프로젝트는 승인된 파일을 다음 이름으로 배치한 뒤 편집한다.

edit/subtitles/subtitles.srt
edit/audio/narration.wav
edit/audio/music.wav

Cinema 15단계 워크플로

기존 make|plan|run|resume은 짧은 영상용 legacy 흐름으로 유지한다. 시나리오 기획부터 캐릭터·로케이션·오브젝트 시트, 컷·스토리보드·START FRAME, 멀티샷 영상, Suno·Artlist 음악 프롬프트까지 순서대로 제작할 때는 별도의 정식 videoprompt cinema 워크플로를 사용한다.

videoprompt cinema create "영화 아이디어"
videoprompt cinema list
videoprompt cinema status CINEMA_PROJECT
videoprompt cinema prompt CINEMA_PROJECT --step 1 --show
videoprompt cinema run CINEMA_PROJECT --step 1
videoprompt cinema review CINEMA_PROJECT --step 1
videoprompt cinema tui CINEMA_PROJECT
videoprompt cinema import CINEMA_PROJECT --step 6 --kind character-sheet --file FILE
videoprompt cinema approve CINEMA_PROJECT --step 6 \
  --artifact PROMPT_ARTIFACT --artifact SHEET_ARTIFACT

Cinema는 01~15의 승인 순서를 지키며, 06·07·08의 외부 생성 이미지는 가져와 승인한 뒤에만 다음 단계로 진행한다. 14·15의 결과는 음악 파일이 아니라 각각 Suno와 Artlist Artboards에 전달할 음악 프롬프트다. 단계별 입력·출력·게이트와 원본 내부 충돌 처리 정책은 docs/10-AI영화제작-15단계-계약.md를 따른다.

cinema run과 cinema import는 기본적으로 생성·반입 직후 guided review를 연다. 텍스트는 원문과 산출물 전문을 터미널에 표시하고, macOS 터미널에서는 이미지를 Preview, 영상을 QuickTime Player로 자동으로 연다. 자동 앱 실행은 --no-open, 대화형 검토는 --no-guided로 각각 끌 수 있다.

cinema review PROJECT [--step N] [--no-open]은 한 단계를 검토하고, cinema tui PROJECT [--step N] [--no-open]는 15단계 관제 화면에서 승인, 수정 요청, 06·07·08 시트(자동 Grok 생성 또는 수동 import)와 산출물 후보 선택을 이어서 처리한다. 여러 산출물을 비대화형으로 승인할 때는 --artifact ID를 반복한다. 승인된 ID 목록은 해당 revision의 snapshot으로 고정되어 이후 단계는 그 산출물만 사용한다.

검증

uv run --no-sync ruff check src tests scripts
uv run --no-sync pytest

공급자 smoke test는 기본 테스트에 포함되지 않으며 실제 사용량을 발생시킬 수 있다. OAuth 호출이 어느 원장에서 차감됐는지는 응답 메타데이터만으로 단정하지 말고 실행 전후 Grok Usage와 xAI Console Billing에서 직접 확인한다.

상세 계약과 한계는 docs를 참고한다. 패키지 버전 발행 절차는 docs/releasing.md에 정리돼 있다.