Metadata-Version: 2.4
Name: videoprompt
Version: 0.1.2
Summary: Plan, generate, edit, and validate multi-shot videos with Grok and xAI.
Project-URL: Homepage, https://github.com/sSUuYeON/videoprompt
Project-URL: Repository, https://github.com/sSUuYeON/videoprompt
Project-URL: Issues, https://github.com/sSUuYeON/videoprompt/issues
Author: VideoPrompt contributors
License: MIT License
        
        Copyright (c) 2026 VideoPrompt contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,cli,ffmpeg,grok,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: prompt-toolkit<4,>=3.0.52
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: rich<15,>=13.7
Requires-Dist: typer<1,>=0.12
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == 'release'
Requires-Dist: twine<7,>=6; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-asyncio<2,>=1.0; extra == 'test'
Requires-Dist: pytest<9,>=8.2; extra == 'test'
Requires-Dist: ruff==0.15.22; extra == 'test'
Description-Content-Type: text/markdown

# VideoPrompt CLI

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

## 요구 사항

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

## 설치

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

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

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

```bash
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가 열린다.

```bash
videoprompt
```

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

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

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

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

```bash
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 흐름은 기존처럼 직접 실행할 수 있다.

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

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

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

```bash
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`에서 멈춘다.

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

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

```text
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` 워크플로를 사용한다.

```bash
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`](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으로 고정되어 이후 단계는 그 산출물만 사용한다.

## 검증

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

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

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