VibeFrame

코딩 에이전트가 사용자의 제공 키와 초과할 수 없는 지출 한도 내에서 실제 비디오를 생성하도록 하세요.

VibeFrame은 Claude Code, Codex, Cursor 또는 bash 기능을 수행할 수 있는 모든 에이전트를 위한 CLI 및 MCP 서버입니다.
이는 작성된 개요(brief)를 계획으로 변환하고, 최신 모델(Seedance, Runway, Kling, Gemini Omni)로부터 에셋을 생성하며, 완성된 MP4 파일을 렌더링합니다.
모든 유료 단계는 드라이 런(dry run)과 하드 --max-cost 한도 뒤에 위치하며, 모든 실패는 스택 트레이스 대신 기계가 읽을 수 있는 복구 조치로 반환됩니다.

CI

GitHub stars

한 아틱 밤 동안 한 사진작가가 만들어낸, 1080p의 엔드투엔드 생성 결과물입니다.
▶ 전체 렌더링 영상 보기

무언가를 지출하기 전에 가격을 파악하세요

--dry-run은 제공자(provider)를 호출하거나 단 하나의 키가 필요 없이 전체 빌드의 가격을 산정합니다.
여기에 --max-cost를 결합하면, 추정 비용이 설정된 한도를 초과할 경우 빌드가 시작되지 않습니다:

vibe build film --dry-run --max-cost 3 --json

{
  

이는 하위 레벨의 컴포지션 엔진을 대체하는 것이 아니라 감싸는(wraps) 방식입니다:

| Layer | Owns | 
| :--- | :--- |
| [Remotion](https://github.com/remotion-dev/remotion) | React 기반의 프로그래밍 방식 비디오 및 컴포넌트 중심 모션 그래픽.
| ... | 

이 표를 하나의 문장처럼 읽어보세요: 장면 구성(scene composition)은 위임되지만, 생성(generation)은 그렇지 않습니다. 만약 작업이 순수하게 HTML 장면 작성 및 렌더링에만 국한된다면, Hyperframes를 직접 사용하세요. 그것이 더 나은 도구이며, 어쨌든 `vibe scene install-skill`을 사용하면 해당 스킬이 자동으로 설치됩니다. VibeFrame은 유료 생성이 필요한 경우(예: 최신 이미지 및 비디오 모델, 장면 간 캐릭터 연속성, 내레이션, 비용 상한선, 빌드 보고서, 또는 컴포지션 레이어 주변의 편집 단계)에 활용해야 합니다.

설치하기 전에 알아두면 좋을 한 가지 결과가 있습니다: 전체 파이프라인은 제공업체 키 없이 로컬에서 $0으로 실행됩니다. 왜냐하면 이 무료 부분은 위임된(delegated) 부분이기 때문입니다. 여기에는 Kokoro 내레이션, 에이전트 작성 HTML/CSS 장면, 헤드리스 Chrome 및 FFmpeg이 포함됩니다.

이는 워크플로우가 자신에게 맞는지 확인하는 가장 저렴한 방법이며, 전체 과정은 [docs/hyperframes.md](docs/hyperframes.md#the-zero-key-render-start-to-finish)에서 확인할 수 있습니다. 이 도구의 목적이 아닙니다: 아래의 유료 생성 경로는 그렇습니다.

VibeFrame은 HeyGen과 제휴 관계가 없습니다.
종속성 및 출처(provenance)에 대한 참고 사항은 [CREDITS.md](CREDITS.md)를 참조하세요.

## 설치

```bash
curl -fsSL https://vibeframe.ai/install.sh | bash
vibe doctor

Node.js 20 이상, FFmpeg, 그리고 Chrome(또는 Chromium)이 필요합니다.
vibe doctor는 이 세 가지를 모두 확인하고 각 제공업체 키가 어떤 명령을 잠금 해제하는지 목록으로 보여줍니다.

생성(Generation)은 키가 필요한 유일한 것입니다.
FFmpeg 편집, Kokoro 내레이션, 장면 구성(scene composition), 감지(detection), 타임라인 작업(timeline work), 그리고 렌더링(rendering)은 모두 로컬에서 처리됩니다.
실제로 사용하는 제공업체에 따라 OPENAI_API_KEY, FAL_API_KEY, GOOGLE_API_KEY, RUNWAY_API_SECRET, 또는 KLING_API_KEY를 vibe setup을 통해 또는 환경 변수로 추가하십시오.

CLI는 @vibeframe/cli (바이너리 vibe)로, MCP 서버는 @vibeframe/mcp-server로 게시됩니다.
이 프로젝트에는 bare한 vibeframe npm 패키지가 없습니다. 이 이름은 관련 없는 패키지에 속하므로, npx vibeframe을 실행해도 이 도구가 작동하지 않습니다.

설치기는 CLI를 XDG 데이터 디렉토리(기본값: ~/.local/share/vibeframe)에 배치합니다.
사용자 범위 키는 ~/.vibeframe/config.yaml에 저장되며, vibe setup --scope project는 ./.vibeframe/config.yaml을 작성합니다.
프로젝트 설정이 현재 디렉토리 또는 그 상위에 존재할 경우, VibeFrame은 이를 격리하여 사용하고 사용자 범위 키를 병합하지 않습니다.

git clone https://github.com/vericontext/vibeframe.git
cd vibeframe && pnpm install && pnpm build
pnpm vibe --help

간략한 내용(brief)으로 비디오 빌드하기

vibe init launch --from brief.md            # 또는 --from "VibeFrame용 30초 런칭 영상"
vibe build launch --dry-run --max-cost 5    # 가격 책정(price it)
vibe build launch --max-cost 5              # 생성(generate)
...

brief.md는 지저분한 메모, 링크 또는 단일 줄이 될 수 있습니다.
init이 생성하는 것은 사용자가 소유하게 되는 프로젝트입니다:

launch/
  STORYBOARD.md     제목(title), 지속 시간(duration), 화면 비율(aspect), 제공업체(providers), 출연진(cast) - 및 연출 산문(direction prose)
  DESIGN.md         팔레트(palette), 타이포그래피(typography), 레이아웃(layout), 모션(motion), 전환 효과(transitions)
...

각 장면은 마크다운 파일입니다. 그 프런트매터(frontmatter)는 단서(cues)를 담고, 본문(body)은 연출 지침을 담습니다:

---
type: Scene
duration: 5
...

큐(cue)의 값은 생성할 프롬프트이거나, 이미 가지고 있는 파일에 대한 프로젝트 상대 경로일 수 있습니다. 예를 들어, video: "media/broll.mp4"는 새로운 것을 생성하는 대신 사용자의 푸티지(footage)를 재사용합니다.

장면들은 파일 이름 순서대로 재생되므로, vibe storyboard move는 번호를 다시 매겨 순서를 바꿉니다. 파일을 직접 편집하거나 코딩 에이전트에게 조사 및 수정을 요청할 수 있습니다.
나머지는 관례입니다: 공급하는 푸티지(footage)는 media/, 생성된 것은 assets/, 출력물은 renders/에, 그리고 제공자, 모델, 품질 계약은 vibe.config.json에 위치합니다.

구조화된 출력을 위해 모든 명령어에 --json을 추가하세요.
plan, build, preview, render, 그리고 두 개의 inspect 명령어는 전체를 다시 빌드하는 대신 --beat <id>를 받아 한 비트(beat)씩 작동합니다.
storyboard, status, 그리고 scene repair는 비트 편집, 비동기 작업 폴링, 결정론적 수정 기능을 담당합니다.

이 다섯 가지가 일반적인 큐이며, 전체적으로는 15개가 있고, vibe storyboard validate는 이 범위를 벗어나는 모든 것에 대해 경고합니다.
프로필(--profile minimal | agent | full), 전체 큐 어휘(the cue vocabulary), 그리고 전체 프로젝트 흐름은 docs/projects.md에 있습니다.

지불하는 비용: 한 캐릭터, 많은 장면

각 장면은 keyframe 스틸 이미지와 video 모션 프롬프트를 쌍으로 사용합니다.
먼저 저렴한 이미지 스토리보드를 생성하고 검토한 다음, 승인한 스틸 이미지에만 애니메이션을 적용하세요.
이는 스틸 이미지가 비디오보다 훨씬 저렴하기 때문에 프로젝트 비용을 예산 범위 내로 유지하는 가장 경제적인 방법이기도 합니다.

vibe build my-film --skip-video   # keyframe 스틸 이미지만 (저렴) - 먼저 검토하세요
vibe build my-film --beat wonder --stage assets --force --skip-video  # 특정 비트 재작업
vibe build my-film --max-cost 12  # 승인된 스틸 이미지 애니메이션화 (image-to-video)

두 모델 모두의 프롬프트 작성법은 AI 비디오 프롬프팅 플레이북에 있습니다.

일회성 에셋 및 편집

이 작업들은 프로젝트나 스토리보드가 필요하지 않습니다:

vibe generate image "영화 같은 제품 데모 프레임" -p openai -o frame.png
vibe generate video "인터페이스가 세련된 데모로 애니메이션화되는 과정" -p seedance -i frame.png -o motion.mp4
vibe generate narration "스토리보드부터 시작하세요." -o narration.mp3
...

재현 가능한 다단계 워크플로우를 위해, vibe run pipeline.yaml은 --dry-run 및 --resume 옵션과 함께 예산이 책정된 YAML 파이프라인을 실행합니다.
위 모든 작업의 작동 예시는 docs/recipes.md에서 확인할 수 있습니다.

에이전트 기반 구동

호스트의 에이전트 루프를 외부 루프로 사용하고, --json으로 CLI를 구동하며, build-report.json과 review-report.json을 루프 상태로 활용합니다.
순방향 패스(forward pass)가 위의 빌드 흐름이라면, 이를 루프로 만드는 것은 복구 패스(recovery pass)입니다:

"렌더링 검토에서 품질 문제 수정"
-> review-report.json 읽기
-> vibe scene repair launch --json
...

inspect는 사전 분류된 nextActions를 반환합니다: safeToAutoRun:true는 자동으로 실행하고, requiresConfirmation:true일 때는 질문하며, retryWith는 오직 폴백(fallback)으로만 사용합니다.
fixOwner는 누가 행동하는지 알려줍니다. `

프롬프트에 이 내용을 작성할 필요는 없습니다.
vibe context가 이를 출력하므로, 호스트 에이전트를 시작하려면 "vibe context를 읽고, --max-cost 5 아래의 brief.md에서 launch/을 구축하라"만으로 충분합니다.
작동 보고서가 포함된 전체 계약은 docs/projects.md에 있습니다.

표면(surface)을 탐색하려면:

vibe schema --list                  # 전체 명령어 목록, 진실의 원천
vibe schema --list --surface public # 첫 실행 제품 경로만
vibe schema --list --filter free    # 비용 등급으로 좁히기
...

호스트 연결하기

vibe init은 하나의 AGENTS.md (그리고 이를 가져오는 CLAUDE.md)를 작성합니다.
이것이 전체 계약입니다: Codex, Cursor, Aider, Gemini CLI, OpenCode 및 다른 모든 bash 지원 에이전트가 동일한 파일을 읽으며, 호스트별 스캐폴드가 없습니다.

CLI가 주 실행 환경이며, MCP는 타입 지정 도구 호출을 선호하는 호스트를 위한 것입니다.
vibe host는 기본적으로 설정을 출력하고, --write를 사용하면 이를 적용합니다:

vibe host setup all                                   # 모든 호스트에 대한 스니펫 출력
vibe host setup cursor --write                        # .cursor/mcp.json 작성
vibe host setup claude-desktop ~/dev/videos --write   # 작업 공간 디렉터리 전달
...

Claude Desktop 사용자: JSON을 편집하는 대신 사전 구축된 확장 프로그램을 설치하세요.
vibeframe.mcpb를 다운로드하여 설정 → 확장 프로그램에 넣은 다음, 작업 공간 폴더를 선택합니다.

@vibeframe/mcp-server (바이너리 vibeframe-mcp)를 수동으로 연결하려면 다음을 추가하세요:

{

- [docs/projects.md](docs/projects.md): 프로젝트 파일, 프로필, 캐릭터, 키프레임, 그리고 호스트 에이전트 루프에 대한 내용입니다.
- [docs/recipes.md](docs/recipes.md): 완성된 엔드투엔드(end-to-end) 예시들입니다.
- [docs/hyperframes.md](docs/hyperframes.md): VibeFrame이 끝나고 컴포지션 엔진이 시작되는 지점, 그리고 제로키 렌더에 대한 내용입니다.
- [docs/ai-video-prompting.md](docs/ai-video-prompting.md): 이미지 및 비디오 모델을 위한 프롬프트 작성법입니다.
- [MODELS.md](MODELS.md): 제공업체(provider) 및 모델 참고 자료입니다.
- [CONTRIBUTING.md](CONTRIBUTING.md): 패키지 맵, 개발 환경 설정(dev setup), 테스트, 그리고 `pnpm scaffold:*` 생성기에 대한 내용입니다.
- [ROADMAP.md](ROADMAP.md)와 [CHANGELOG.md](CHANGELOG.md).

기여를 환영합니다: 버그 수정, 제공업체 통합, CLI 사용자 경험(UX) 개선, 문서화, 그리고 테스트가 가능합니다.

## 라이선스

MIT. [LICENSE](LICENSE) 참고.