openvidstudio

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

프로젝트의 실제 실행 중인 앱에서 데모 비디오를 제작합니다. 모든 화면은 실제 제품에서 가져오며, 생성되지 않습니다.

시작하기 전에

preflight를 실행하세요. node, ffmpeg, Playwright의 Chromium, 앱이 실제로 응답하는지, 내레이션 엔진이 존재하는지 확인합니다. 각 실패는 해결 방법을 알려줍니다. 이를 건너뛰면 긴 렌더링 후에 누락된 종속성이 드러납니다.

도구가 등록되지 않은 경우 서버가 설치되지 않은 것입니다. 사용자를 MCP 구성의 이 항목으로 안내한 후 클라이언트를 다시 시작하세요:

{ "mcpServers": { "openvidstudio": { "command": "npx", "args": ["-y", "@openvidstudio/mcp-server"] } } }

순서

preflight -> extract_brand -> plan_beats -> [write VO] -> validate_beats -> 승인 게이트
  -> write_beats_file -> capture_screenshot -> scaffold_scene -> validate_scenes
  -> [plan_sound_effects] -> generate_narration -> stitch_composition -> contact_sheet
  -> render_video -> qc_extract_frames

1. 인테이크(Intake)

묻기 전에 먼저 파악하세요. 일반적인 요청은 "이 프로젝트의 데모 비디오를 만들어 주세요"이며 다른 것은 없습니다. 그것이 전체 브리핑이며 충분합니다.

사용자에게 묻기보다는 리포지토리를 먼저 읽으세요:

• README.md는 제품이 무엇인지와 종종 중요한 사항을 알려줍니다.
• package.json 스크립트는 앱을 시작하는 방법을 알려주며, dev 스크립트는 보통 포트를 지정합니다.
• 라우트나 페이지는 촬영할 내용을 알려줍니다.

그런 다음 직접 앱을 시작하고 응답하는지 확인하세요. 사용자에게 URL을 요청하지 마세요. dev 명령어를 찾아 실행하고 확인하세요. 시작하기 위해 알 수 없는 정보(예: 누락된 .env 또는 실행되지 않은 데이터베이스)가 필요할 때만 물어보세요.

리포지토리가 알려줄 수 없기 때문에 실제로 물을 가치가 있는 것은:

• 비디오 길이
• 리포지토리에 많은 기능이 있을 경우 보여줄 2~3가지
• 대상이 누구인지(랜딩 페이지 방문자 또는 이미 설치하려는 사람)

한 번에 한 가지 질문만, 그리고 리포지토리가 답할 수 없는 질문만 하세요. 시작부터 여섯 개의 질문을 한꺼번에 던지면 이 작업이 일처럼 느껴집니다. docs/PLANNING.md에 명확하지 않은 경우에 대한 전체 결정 트리가 있습니다.

작업을 마치면 결과를 보여주세요: mp4 경로, 길이, 그리고 contact_sheet 또는 몇 장의 qc_extract_frames 스틸샷. 아무도 보지 않는 렌더링은 전달된 비디오가 아닙니다.

1b. 리포지토리의 브랜드 적용

sourceRepo를 촬영 중인 리포지토리로 설정하여 extract_brand를 실행하세요. Tailwind v4 @theme 블록과 :root 사용자 정의 속성을 읽고, next/font 임포트에서 폰트를 선택하고, 찾은 최고의 로고를 복사하여 src/brand.ts에 씁니다.

scaffold_scene 전에 실행하세요. 사후에 테마를 적용하려면 다시 스캐폴딩해야 합니다.

반환된 unresolved 목록을 확인하고 중요한 항목을 수동으로 채우세요. 실제로 찾을 수 있는 것만 보고하며 그럴듯한 색상을 만들어내지 않으므로, 미해결 토큰은 실제 누락이지 실패가 아닙니다.

수동 작성 장면에 부과되는 한 가지 규칙: 모듈 범위가 아닌 컴포넌트 내부에서 토큰을 읽으세요. applyBrand는 공유 토큰 객체를 변형하므로, 파일 상단의 const MONO = \"${font.mono}"`는 기본값을 캡처하고 브랜드를 보지 못합니다. 대신 monoStack()과 uiStack()`을 사용하세요.

2. 비트(씬) 계획 수립

대상 길이와 기능을 지정하여 plan_beats를 실행하세요. 캡처 방법과 비트당 단어 예산이 포함된 연속적인 골격을 반환합니다.

해당 예산에 맞춰 내레이션을 작성하세요. validate_beats는 비트당 초당 2.3~2.9단어를 하드 플로어 및 천장으로 강제하므로, 너무 드문 경우 거부될 수 있습니다. 명시된 숫자에 맞춰 작성하면 왕복을 피할 수 있습니다.

모든 screenshot 비트에는 visual.url과 visual.interactions(배열, 비어 있을 수 있음)도 필요합니다. 다른 문서에는 이 점이 명시되어 있지 않습니다.

3. 승인 게이트

사용자에게 전체 비트 파일을 보여주고(요약이 아닌), 명시적인 승인을 기다리세요. 승인 전에는 아무것도 디스크에 쓰지 않습니다. 이는 제안이 아닌 프로토콜 규칙이며, 잘못된 비디오를 수정하는 데 한 시간이 아닌 한 문장이면 되는 지점입니다.

그런 다음 write_beats_file.

4. 캡처

각 스크린샷 비트에 대해 capture_screenshot을 실행하세요. 이는 원본별 Chrome 줌 불일치를 보정하여 작거나 흐리거나 잘못 프레임된 캡처를 방지합니다.

페이지에 진입 애니메이션이 있으면 wait 상호작용을 전달하세요. 그렇지 않으면 중간 상태가 캡처되어 깨져 보입니다.

5. 장면(씬)

각 비트에 대해 scaffold_scene을 실행하세요. 해당 비트의 자체 복사본과 길이를 사용하여 그대로 렌더링되는 장면을 생성합니다. 내용을 편집하고 구조를 재구축하지 마세요.

그런 다음 validate_scenes를 실행하세요. 성공적으로 렌더링되지만 단순히 잘못된 오류를 잡습니다: 전체 스테이지 너비로 배치된 콘텐츠는 카메라가 확대되면 카메라 배율로 나눈 보이는 영역에 맞춰 잘립니다. 또한 정적 카메라, 누락된 에셋, 내레이션이 없는 비트를 플래그합니다.

프롭에 대해서는 docs/API.md를 읽으세요. 라이브러리 소스는 읽지 마세요.

6. 내레이션

generate_narration을 실행하세요. stitch_composition이 찾는 비트당 하나의 클립을 작성하고, 시간 늘이기를 어떤 대가를 치르더라도 클립을 맞추지 않고 자연스러운 범위로 제한합니다. 비트가 맞지 않을 때는 스크립트나 비트 길이를 수정하고, 더 늘리지 마세요.

6b. 사운드 (내장된 것으로 충분하지 않은 경우에만)

합성된 팩에는 이미 클릭, 키스트로크, 벨, 블립, 성공 톤, 우우시 및 음악 배경이 포함되어 있으며, ffmpeg가 생성하므로 타사 권리가 없습니다. 이것을 선호하세요.

비디오에 정말로 다른 것이 필요한 경우 사용자에게 어떤 소리를 원하는지 물어본 후, 각 소리당 하나의 항목으로 plan_sound_effects를 실행하세요. 어떤 요청이 내장된 것으로 이미 처리되는지 알려주고, 나머지에 대해 Pixabay 검색 링크와 정확한 저장 경로를 반환합니다.

Pixabay에서 다운로드하지 않으며, 여러분도 해서는 안 됩니다. Pixabay의 이용 약관은 자동 수집을 금지하며 API가 실제 인간 요청을 위한 것이라고 명시하고, 사운드 효과 엔드포인트를 게시하지 않습니다. 사용자가 다운로드하고 여러분이 확인하세요. 이후 verify: true로 도구를 다시 호출하여 각 파일이 실제 오디오인지 확인하고 형식을 정규화하세요.

provider: "freesound"는 대신 자동으로 가져오지만, 사용자 자신의 API 토큰이 필요하며 가져온 모든 클립은 ATTRIBUTION.md에 기록됩니다. 해당 파일의 내용은 비디오 설명에 도달해야 하며, 그렇지 않으면 라이선스가 위반됩니다.

음악은 이 모든 것의 예외입니다. find_music_bed는 두 개의 CC0 퍼블릭 도메인 카탈로그(~9,400개 트랙)를 검색하고, import_music_bed는 사용자가 선택한 트랙을 다듬고, 페이드하고, 음량을 맞춰 public/audio/music-bed.mp3로 가져옵니다. 저작자 표시가 필요하지 않습니다. bgmusic 스킬에 자세한 내용이 있습니다. 합성된 배경음이 런칭이나 프로모션 작품에 너무 단순할 때 사용하세요.

7. 조립 및 확인

stitch_composition을 실행한 후 렌더링 전에 contact_sheet를 실행하세요. 연락처 시트는 비트당 두 프레임을 하나의 이미지로 보여주며 전체 렌더링의 일부만 사용합니다. 5분 비디오는 9000프레임이므로 중요합니다.

먼저 draft: true로 render_video를 실행하세요. 드래프트가 제대로 보일 때만 전체 품질로 렌더링하세요.

그런 다음 qc_extract_frames를 실행하고 docs/PIPELINE.md의 체크리스트를 따르세요.

QC에 실패하는 규칙

docs/STYLE.md에서 가져온 것으로, 가장 자주 어겨지는 규칙입니다:

• 선형 이징 없음. E.* 프리셋을 사용하세요.
• 모든 장면은 CinematicScene 내부에 있어야 함.
• 움직임은 절대 멈추지 않음. 정적 프레임은 실패입니다.
• 화면이나 내레이션에 엠 대시 없음.
• 자막은 overlay에 들어가야 하며 children이 아님. 그렇지 않으면 카메라가 움직일 때 화면 밖으로 밀려납니다.
• 스크린샷은 BrowserFrame 내부에만 사용. 녹화 및 AI 클립은 사용해서는 안 되며, 생성된 푸티지가 실제 캡처의 시각적 특징을 가지게 됩니다.

주장하지 말아야 할 것

실제 제품 UI(DOM 렌더링, 스크린샷 또는 녹화)는 근본 진실입니다. AI 생성 클립은 분위기 전용이며 제품 텍스트를 전달하지 않습니다. 내레이션이 어떤 것을 주장하면 시각적으로 보여줘야 합니다. 보여줄 수 없으면 대사를 다시 작성하세요.