Video Agent Runtime

에이전트 네이티브 비디오 편집 — 내구성 있는 계획, 검토 가능한 버전, 결정적 렌더링을 기반으로 합니다.

비디오를 불투명한 셸 명령이 아닌 구조화된 데이터로 편집하세요.

빠른 시작 · 에이전트 및 MCP · 음성 및 보이스 · 모바일 · 문서 · 벤치마크

무엇인가요?

Video Agent Runtime은 Claude Code, Codex 또는 MCP를 지원하는 모든 클라이언트와 같은 에이전트를 위한 헤드리스 편집 엔진입니다.

모델이 FFmpeg 명령을 직접 작성하는 대신, 미디어를 내구성 있는 프로젝트 데이터로 변환합니다:

Transcript → EditingStrategy → EditPlan / EditPatch → Timeline → Version → Preview → Approval → Export

모델은 무엇을 변경해야 하는지 결정합니다. 런타임은 해당 변경이 허용되는지 검증하고, 트랜잭션 방식으로 적용하며, 결과를 렌더링하고, 모든 변경 사항을 검토 가능하고 되돌릴 수 있게 유지합니다.

이 도구는 토킹헤드 비디오, 인터뷰, 팟캐스트, 강의, 화면 녹화, 롱폼-투-숏폼 워크플로우를 위해 설계되었습니다.

[!NOTE] 이 도구는 데스크톱 NLE가 아니며 Premiere나 CapCut을 재현하려 하지 않습니다. 기본 인터페이스는 에이전트, CLI, MCP 클라이언트 또는 검토 중심의 모바일 호스트입니다.

Related MCP server: video-editor

작동 방식

flowchart LR
    A[Source video] --> B[ASR + visual evidence]
    B --> C[Transcript / Timeline context]
    C --> D[LLM proposes EditingStrategy]
    D --> E{User approves?}
    E -- no --> D
    E -- yes --> F[Structured EditPlan]
    F --> G[Validate + Diff + Apply]
    G --> H[Immutable Version]
    H --> I[Preview render]
    I --> J{Review}
    J -- feedback --> K[EditPatch or Replan]
    K --> G
    J -- approve --> L[Final export]

일반적인 상호작용은 다음과 같습니다:

Import interview.mp4
↓
"剪成一分钟，开头抓人，删掉废话"
↓
Agent proposes a hook-first strategy
↓
User approves
↓
Runtime validates and applies an EditPlan
↓
Preview
↓
"前 20 秒还是太慢"
↓
Minimal EditPatch → new Version → new preview
↓
Final approval → export

핵심 기능

음성 및 보이스

음성은 자막 부가 기능이 아닌 일급 편집 하위 시스템입니다. ASR은 편집기가 사용하는 의미적 타임라인을 생성하고, TTS 및 VoiceProfile 출력은 명시적 프로젝트 자산 및 타임라인 클립이 됩니다.

ASR

TTS 및 음성 정체성

음성 복제는 절대 자동으로 이루어지지 않습니다. 복제된 VoiceProfile은 명시적 승인 증거, 품질 검증된 참조, 그리고 공급자가 지원하는 경우 정확한 트랜스크립트 기반 참조 범위가 필요합니다. 다중 화자 미디어는 조용히 추측되지 않습니다.

모델 코드, 가중치, 음성 자산 및 호스팅 API는 서로 다른 라이선스 또는 상업적 조건을 가질 수 있습니다. 공급자 구성을 배포하기 전에 음성 모델 연구 및 음성 정체성을 읽으세요.

에이전트 및 MCP

모든 공개 표면은 동일한 VideoAgentCore 위의 얇은 어댑터입니다. 별도의 프로젝트 또는 타임라인 모델을 유지하지 않습니다.

Claude Code / Codex 연결

저장소를 빌드한 다음 MCP 지원 클라이언트를 stdio 서버에 연결하세요:

npm install
npm run build

mcp.example.json에는 최소 구성 형태가 포함되어 있습니다. 공급자 비밀은 환경 또는 보안 호스트 저장소에서 읽으며 프로젝트 JSON에 절대 기록되지 않습니다.

빠른 시작

요구 사항

• Node.js 22+

• 실제 미디어 렌더링을 위한 FFmpeg / FFprobe

• 로컬 음성 모델을 위한 선택적 Python 환경

설치 및 확인

npm install
npm run typecheck
npm test
npm run build
npm run smoke:mcp
npm run demo

npm run demo는 로컬에서 합성 소스 미디어를 생성하고 트랜스크립트 → 전략 → 버전 → 미리보기 → 피드백 패치 → 내레이션 → 최종 FFmpeg 내보내기를 통해 실제 프로젝트 워크플로우를 구동합니다.

유료 모델 호출 없이 현재 머신을 확인하세요:

npm run cli -- doctor

공급자 구성

.env.example에서 관련 값을 환경에 복사하세요.

# Workspace
VIDEO_AGENT_WORKSPACE=./video-projects

# Planner
VIDEO_AGENT_PLANNER=openai
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=...

# Local ASR example
VIDEO_AGENT_ASR=qwen3-asr
VIDEO_AGENT_ASR_MODEL=Qwen/Qwen3-ASR-0.6B

# Local TTS / voice example
VIDEO_AGENT_TTS=qwen3-tts
VIDEO_AGENT_TTS_MODEL=Qwen/Qwen3-TTS-12Hz-0.6B-Base
VIDEO_AGENT_PYTHON=python

기타 지원 옵션은 .env.example에 직접 문서화되어 있습니다.

실제 공급자 검증

일반 CI는 의도적으로 대용량 음성 모델을 다운로드하거나 유료 자격 증명을 사용하지 않습니다. 실제 공급자는 명시적 수용 하네스를 통해 검증됩니다:

VIDEO_AGENT_REAL_ACCEPTANCE=true \
VIDEO_AGENT_ASR=qwen3-asr \
VIDEO_AGENT_PLANNER=openai \
VIDEO_AGENT_TTS=qwen3-tts \
OPENAI_API_KEY=... \
npm run eval:speech-real

하네스는 실제 단계 지연 시간, ASR/TTS 실시간 계수, 공급자/모델 메타데이터, Node 컨트롤러 RSS 및 사용 가능한 경우 대략적인 GPU 메모리를 기록합니다. 승인된 보이스 클론 수용은 별도로 활성화해야 하며 임의의 화자에 대해 조용히 실행될 수 없습니다.

여러 실행 후 다음으로 비교 가능한 결과를 집계하세요:

npm run benchmark:speech-summary

실제 음성 수용, 벤치마크 및 음성 모델 연구를 참조하세요.

모바일 호스트

모바일 대상은 로컬 우선, 제로 애플리케이션 서버 아키텍처를 중심으로 설계되었습니다:

Mobile App
  ├── VideoAgentCore
  ├── durable ProjectRepository
  ├── Workflow / Job Queue
  ├── Timeline / EditPatch / Version
  ├── native media adapters
  └── direct BYOK provider access when configured

소스 미디어는 기본적으로 기기에 유지됩니다. 원격 공급자는 추론에 필요한 승인된 ContextPack/증거만 수신합니다. API 자격 증명은 프로젝트 JSON이 아닌 보안 호스트 저장소를 통해 참조됩니다.

[!WARNING] 현재 iOS/Android 구현은 여전히 소스 수준 네이티브 호스트 프로토타입입니다. TypeScript/모바일 계약은 CI에서 확인되지만, 네이티브 Xcode/Gradle 빌드, 실제 기기 미디어 정확성, 열 동작 및 백그라운드 내보내기 신뢰성은 여전히 문서화된 기기 검증 패스가 필요합니다.

docs/mobile/README.md 및 네이티브 호스트 상태에서 시작하세요.

아키텍처

                 Agent / CLI / MCP / Mobile
                          │
                          ▼
                    VideoAgentCore
                          │
        ┌─────────────────┼──────────────────┐
        ▼                 ▼                  ▼
     Workflow          ProjectStore       Job Queue
        │                 │                  │
        └──────────┬──────┴──────────┬──────┘
                   ▼                 ▼
              Edit / Timeline    Provider contracts
                   │                 │
             Version / Diff     ASR / LLM / TTS
                   │                 │
                   └────────┬────────┘
                            ▼
                         Renderer
                            │
                         Preview
                            │
                      Review / Export

주요 불변 조건은 간단합니다: 런타임이 상태를 소유하고, 모델은 구조화된 변경을 제안합니다.

패키지 경계, 영속성 레이아웃 및 복구 의미론에 대해서는 architecture.md를 읽으세요.

문서 및 개발

README는 제품 진입점입니다. 기술 세부 사항은 docs/ 아래에 있습니다.

프로젝트 상태

Node 런타임이 검증된 기본 경로입니다: CLI, MCP, 내구성 있는 프로젝트 상태, FFmpeg 렌더링, 작업, 결정적 평가, 음성 공급자 어댑터 및 실제 공급자 수용 도구가 구현되어 있으며 외부 모델 가중치나 유료 자격 증명이 필요하지 않은 곳에서 CI로 커버됩니다.

실제 로컬 모델 품질, 지연 시간, VRAM 및 호스팅 모델 동작은 여전히 옵트인 인수 테스트 하네스를 통해 대상 머신에서 측정되어야 합니다. CI는 그러한 실행이 발생했다고 가장하지 않습니다.

모바일 호스트는 네이티브 컴파일과 실제 기기 검증이 완료될 때까지 소스 수준 프로토타입으로 남아 있습니다.

보안 원칙

• 에이전트는 편집 API를 통해 임의의 셸 실행 권한을 받지 않습니다.

• 원시 FFmpeg 문자열은 권위 있는 편집 상태가 아닙니다.

• API 키는 프로젝트 JSON, ProviderCall 레코드 또는 벤치마크 보고서에 영구 저장되지 않습니다.

• 워크플로가 원격 증거를 명시적으로 승인하지 않는 한 소스 미디어는 로컬에 유지됩니다.

• 음성 복제에는 명시적 승인과 출처가 필요합니다.

• 지원되지 않는 렌더러/프로바이더 기능은 조용히 저하되는 대신 명시적으로 실패합니다.

전체 경계는 docs/security.md를 참조하세요.

라이선스

MIT. LICENSE를 참조하세요.