kinocut은(는) 무엇을 하나요?
Kinocut은 에이전트가 직접 FFmpeg 명령어를 작성하는 대신 구조화된 비디오 편집 인터페이스가 필요할 때 사용합니다. MCP 도구, Python 클라이언트 및 CLI를 통해 편집, 분석, 자막, 오디오, Hyperframes, 레이어 합성 및 로컬 리퍼포징 워크플로우를 제공합니다.
기본 경로 (먼저 이 작업을 수행하세요)
kino doctor를 실행한 후kino --format json info <file>을 실행합니다.- 익숙하지 않은 작업의 경우, 사용자의 작업과 함께
search_tools를 호출하고(예: "필러 단어 제거" 또는 "얼굴을 프레임 안에 유지"), 반환된 도구의 필수 입력을 검사합니다. 지원되는 의도에 대해video_intent로 계획을 수립합니다(선택적goal=이 컷파일을 컴파일하며,360/desk/table/x4목표는360_assembly_plan도 제안합니다). 제안이 요청을 실제로 충족하는지 렌더링하기 전에 확인합니다. - 렌더링합니다(
video_cutfile_render,video_edit, 워크플로우 또는 단일 엔진 도구 사용). 360의 경우:video_review_decide로 해당 계획을 승인/거부한 후 렌더링합니다. 절대proposed계획을 렌더링하지 마십시오..insv는 거부되며, 스티칭된 360 MP4가 필요합니다. 안내:docs/360_ASSEMBLY.md. video-quality-check/assert_quality를 실행합니다. 건너뛰거나allow_fail이 없는 한repurpose및shorts-package동기화는 점수 80에서 실패-종료됩니다.- 인간의 시각/청각 검토. 영수증을 게시된 것으로 간주하지 마십시오.
심층 정보(구조, 복구, 합성, Hyperframes, Thin Sound S12): docs/TOOLS.md, docs/RESCUE.md, docs/WORKFLOWS.md. 워크플로우 허용 목록: probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.
필요할 때 관련 가이드를 로드하십시오. 편집 결정에는 소스 증거를 사용하고, 이름, 숫자, 부정 및 제한 사항을 보존하십시오. 누락된 증거나 지원되지 않는 작업은 보고하고, 소스 주장, 타임스탬프 또는 기능을 임의로 만들어 내지 마십시오. 계획 도구는 편집을 제안하지만, 그 존재가 필요한 감지기나 모델이 실행되었음을 의미하지는 않습니다. 코드는 타이밍, 변환, 검증 및 실행을 담당하며, 인간 검토는 모델 판단과 별개로 유지됩니다.
Revideo 로컬 코드-비디오 흐름 (개발 팁)
호출자가 검사 가능한 스테이징 프로젝트를 필요로 할 때 revideo_materialize, revideo_install 및 revideo_render를 사용하십시오. 동일한 보호 단계를 한 번의 호출로 처리하려면 revideo_render_job을 사용하십시오. 제공된 장면은 신뢰할 수 있는 실행 가능한 TypeScript이므로, 사용 전에 검사하고 신뢰할 수 없는 장면 코드를 절대 실행하지 마십시오. 종속성 설치 시 npm에 액세스할 수 있으며, 렌더링은 Kinocut의 고정 템플릿을 기준으로 로컬에서 실행됩니다. 렌더링 영수증은 관찰된 미디어와 출력 바이트를 정확한 범위의 디스크 내 작업 파일 다이제스트에 바인딩합니다. .mp4, .webm 및 .mov는 고정된 MP4, WebM 및 ProRes 4444 내보내기 모드를 선택하며, 게시 전에 확인됩니다. 영수증을 출력 바이트와 대조 확인하고, video_quality_check 및 video_release_checkpoint를 실행한 후, 인간의 시각 검토를 요구하십시오.
시작하기
- 설치 및 안전 계약은
../../README.md를 읽으십시오. - FFmpeg / Hyperframes / AI 추가 기능 전에
kino doctor를 실행하십시오.
인터페이스 선택
- MCP: Claude Code, Cursor, Codex 스타일 클라이언트 및 기타 에이전트 호스트에 가장 적합합니다.
uvx --from kinocut kino로 구성하십시오. - CLI: 직접적인 로컬 편집, 빠른 진단,
composite-layers --dry-run, 배치 작업 및 CI 친화적인 JSON 출력에 가장 적합합니다. - Python 클라이언트: 구조화된 결과, 출력 경로 및 저장된 레이어 계획 영수증이 필요한 반복 가능한 파이프라인에 가장 적합합니다.
360 듀얼 카메라 어셈블리 (게시 1.14.0)
소스가 모든 카메라(Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360 등)의 스티칭된 등장방형 360 MP4이고 요청이 분할/전환/PiP/단일의 두 가상 카메라인 경우 사용합니다.
video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=절대경로)또는Client.propose_360_assembly(...).- 카메라, 레이아웃 및 스토리보드 스틸을 보여줍니다. 요/피치를 임의로 만들지 마십시오.
video_review_decide/Client.decide_360_assembly를approve또는reject와 함께 사용합니다.- 승인된 계획만 렌더링합니다(
Client.render_360_assembly또는video_review_decide+output_path사용).
video_360_* MCP 도구나 kino 360 명령은 없습니다. CLI intent 및 review-decide는 이 컴파일러를 실행하지 않습니다. 디렉터 훅은 삽입된 JSON 제안자를 허용하며, 구성된 모델 이름만으로는 모델이 실행되지 않습니다. 클라우드 제안은 allow_cloud가 필요하며, 디렉터는 픽셀을 쓰지 않습니다.
제품 / 객체 매트 (게시 1.15.1, 현재 1.15.3)
선택적 객체-매트 추가 기능은 게시된 1.15.3에서 사용할 수 있습니다. 기존 hyperframes-remove-background / hyperframes_remove_background 명령을 사용하십시오. 기본 모델은 사람입니다. 카탈로그 SKU, 보석, 병, 신발, 포장 또는 사람이 아닌 것의 경우:
hyperframes_remove_background(info=true)— 모델을 나열하며 다운로드하지 않습니다.pip install "kinocut[object-matte]"그런 다음model="birefnet-general"을 설정합니다.- 제품 비디오에는 선택적으로
--mask-interval 3을 사용합니다. 남은 턴테이블/스탠드/삼각대/스위프에는 선택적으로 장비 오버레이를 사용합니다. composite-layers를 사용하여 쇼핑몰 플레이트에 합성합니다. 모든src를 사양 디렉토리 내에 유지합니다.
video_product_matte를 임의로 만들지 마십시오. 이는 새로운 MCP 도구가 아닙니다. 객체 추가 기능이 없을 때 사람 모델로 대체하지 마십시오. 안내: docs/PRODUCT_MATTE.md. 예시: examples/product-matte/.
전용 비디오 구조 (Rescue)
요청이 하나의 로컬 클립을 소스, 스토리 및 타임라인을 유지하면서 수정하는 것일 때 video_rescue_*, rescue-* 또는 Client.rescue_*를 사용하십시오.
필수 순서:
- 계획을 호출하고 계획 아티팩트를 저장합니다.
safe_repairs,recommendations,unavailable_repairs,blocked_repairs, 미리보기, 패키지 의도, 기능 및 예상 시간을 사용자에게 제시합니다.- 렌더링 전에 계획을 검사합니다.
safe_repairs의 ID에 대해서만 명시적 승인을 얻거나 유추합니다. ID 목록을 생략하면 검토된 계획의 모든 안전 ID를 의미합니다. - 정확히 승인된 안전 ID로 렌더링을 호출합니다.
- 렌더링 영수증을 검사한 후, 패키지 경로, 사용할 수 없는 사이드카, 무결성, 게이팅 검증, 개인정보 보호, 재개 및 정리 상태를 보고합니다.
검토되지 않은 계획에서 직접 렌더링하지 마십시오. 추천 ID, 사용 불가 ID 또는 차단된 ID를 승인에 추가하지 마십시오. 클라우드 도구를 사용하거나, 구조 자막을 굽거나, 소스를 다시 쓰거나, unavailable을 자동 실패로 처리하지 마십시오. 취소 또는 검증 실패는 승격되지 않거나 격리된 상태로 유지되어야 합니다.
결정론적 AI-비디오 검사
생성된 푸티지가 편집 결정 전에 증거를 필요로 할 때 video_ingest, video_preflight 및 video_inspect_temporal(또는 이에 상응하는 플랫 CLI 및 Python)을 사용하십시오. 먼저 수집한 후, 반환된 해시로 자산을 참조하십시오. 공개 경계에서 해당 자산 ID를 호스트 경로로 대체하거나 AssetRecord를 구성하지 마십시오. 시간적 검사는 전체 샘플링된 프레임 및 모션 스트립 패키지, 결정론적 결과 및 명시적으로 사용할 수 없는 제공자 기능을 반환합니다. 제공자 부재는 예상된 것이며 다운로드나 네트워크 대체를 유발해서는 안 됩니다.
관리형 AI-비디오 검토 및 복구 (Salvage)
정확한 자산 편집 결정 및 파생 복구를 위해 video_verdict, video_acceptance_eval, video_body_swap 및 video_salvage(또는 이에 상응하는 플랫 CLI 및 Python)을 사용하십시오. 승인되지 않은 판결은 에이전트 분석을 캡처할 수 있지만, 승인된 처분은 명시적 요구 사항, 역할 및 아티팩트 증거와 함께 활성화된 정확한 인간 결정을 바인딩해야 합니다. 승인 평가는 승인 작업이 아닌 파생된 것이며, 모든 복구 출력은 새로운 승인되지 않은 검토 슬롯에서 시작됩니다.
결정 ID를 임의로 만들거나, 저장되지 않은 승인을 전달하거나, 강제/우회 경로를 찾지 마십시오. 본체 스왑은 호출자가 명시적 정책을 선택하지 않는 한 지속 시간 불일치를 거부합니다. 복구에는 기존 비공개 프로젝트, 저장된 소스 자산, 경계가 있는 레시피 정책 및 정확한 승인 사양 ID가 필요합니다.
승인 평가는 활성화된 저장된 acceptance_spec_id 및 verdict_ids를 사용하며, 호출자가 구축한 증거 개체를 사용하지 않습니다. 공개 본체 스왑은 항상 먼저 project_dir을 사용하며, 두 소스 경로 모두 해당 정확한 프로젝트의 활성 자산으로 확인되어야 합니다.
이 워크플로우를 운영하기 전에 docs/AI_VIDEO_REVIEW_AND_SALVAGE.md를 읽으십시오. 모든 파생물을 새로운 승인되지 않은 작업으로 취급하고, 게시 전에 명시적인 인간 시각/청각 게이트를 유지하십시오.
구조 후 계획
요청에 의미론적 검색, 일반 정리 편집, 피사체 인식 변환, 복원, 합성, 창의적 조정 또는 원격 송신이 필요할 때 일치하는 video_* MCP 도구, 플랫 CLI 명령 또는 Client 메서드를 사용하십시오. JSON 호환 증거 및 의도를 전달하고, 별도의 렌더링 단계 전에 반환된 계획과 차이점을 제시하십시오.
소스 설명을 임의로 만들거나, 불확실성을 숨기거나, 계획에서 승인을 유추하거나, 로컬 실행자가 없다는 이유로 클라우드 제공자를 사용하지 마십시오. 원격 작업에는 별도의 송신 매니페스트와 승인이 필요합니다. 증거나 기능이 부족한 계획자는 기권해야 합니다.
레이어 합성
편집이 이미지, 비디오 또는 솔리드 레이어의 정렬된 스택인 경우, 특히 하단 3분의 1, 화면 속 화면 변형, 블러백 플레이트, 마스크/매트 또는 플랫폼별 레이아웃 변형의 경우 composite-layers / video_composite_layers를 사용하십시오.
에이전트가 변환, 불투명도, 시작/지속 시간 창, 마스크/매트 알파 소스 또는 게시 전에 검토할 수 있는 영수증이 필요할 때 원시 FFmpeg 필터 그래프보다 이 경로를 선호하십시오.
계획 우선 흐름:
canvas, 정렬된layers및 명시적output이 있는 JSON 사양을 작성합니다.kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json을 실행합니다.- 소스 해시, 필터 그래프 해시, 변환, 회전/피봇, 혼합 모드, 타이밍 창 및 마스크에 대한 레이어 계획을 검사합니다.
- 계획이 올바르게 보인 후에만 렌더링합니다.
video-quality-check,storyboard또는thumbnail,video_release_checkpoint를 실행합니다.
합성기는 허용된 전체 캔버스 및 위치 지정 혼합 모드(multiply, screen, overlay, darken, lighten)를 불투명도 및 타이밍 창과 함께 지원하며, 영수증은 layer_plan v2로 유지됩니다. normal이 아닌 혼합은 두 가지 기하학에서 불투명도 및 start/duration 창을 지원합니다: 명시적 크기 조정 없이 {0,0}에서의 전체 캔버스, 또는 양의 정수 width 및 height와 음이 아닌 정수 캔버스 내 위치를 모두 갖는 위치 지정 사각형. RGB 혼합은 서브샘플링된 크로마 평면에 색상 산술을 적용하지 않습니다. 스케일, 회전/피봇, 마스크/매트, 분수 위치 및 캔버스 외부 사각형은 연기되며 unsupported_blend_geometry로 실패-종료됩니다. 비디오 레이어 및 비디오 마스크는 선언된 시작 시간에 재생을 시작합니다. 모든 소스와 마스크를 사양 디렉토리 내에 유지하십시오. 출력은 비디오 전용입니다. anchor는 pivot과 구별되는 위치 별칭입니다. 회전 + 마스크, 오디오 합성 및 완전한 NLE 어댑터는 연기됩니다. 인간 검토 전에 영수증을 검사하십시오. 이를 완전한 NLE 대체품으로 취급하지 마십시오.
에이전트 워크플로우 엔진
편집이 단일 도구 호출이 아닌 다단계 작업인 경우, 워크플로우 엔진을 사용하여 하나의 JSON 작업 사양으로 계획, 검증, 렌더링, 복구 및 증명하십시오. video_workflow_*(MCP), workflow-*(CLI) 또는 Client.workflow_*(Python)을 통해 가능합니다. 작업은 검증된 엔진에 바인딩된 작은 허용 목록(probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in)이며, 미디어 참조는 기호적(@sources.*, @work/*, @outputs.*)이고 작업 공간에 국한되며, 모든 것은 실패-종료됩니다. ../../docs/WORKFLOWS.md를 참조하십시오.
계획 → 검증 → 렌더링 → 검사 → 재개:
workflow-validate --spec job.json— 저렴한 구조적 게이트; 아무것도 렌더링하지 않습니다.workflow-plan --spec job.json --save-plan plan.json— 드라이런 op 그래프 + 소스 프로브/해시; 미디어를 전혀 렌더링하지 않습니다.workflow-render --spec job.json --save-receipt receipt.json— 순차적으로 실행; 출처 영수증(단계별 해시, 정리 매니페스트, 결정론 주의사항)을 생성합니다. 배치 변형의 경우--all-variants를 추가합니다.workflow-inspect --receipt receipt.json— 영수증을 신뢰하기 전에 읽기 전용 무결성 재확인 + 인간 검토 포인터.workflow-render --spec job.json --resume receipt.json— 중간 파일을 유지한 상태로 실패한 작업을 재개합니다(변경된 사양의 경우 실패-종료).
영수증은 작업 공간 상대 경로만 저장합니다. 사양 및 예제 영수증에 홈 경로, 사용자 이름 및 토큰을 포함하지 마십시오.
워크플로우
- 먼저 입력을 검사합니다:
kino info <file>또는 MCP/Python에 상응하는 명령. - 위험이 적은 계획을 수립합니다: 트림, 크기 조정, 오디오 정규화, 자막, 오버레이, 효과 또는 Hyperframes 렌더링.
- 비용이 많이 들거나 파괴적인 내보내기 전에 미리보기 또는 드라이런 매니페스트를 선호합니다:
- 빠른 시각적 검토를 위한
preview. repurpose전의repurpose-plan.- 전체 렌더링 전의 Hyperframes
inspect,snapshot또는still. - 저장된 쇼츠 계획의 경우:
shorts-plan-show→shorts-review→shorts-render→shorts-package. - Thin Sound의 경우:
sound-capabilities그 다음sound-plan-validate/sound-voice-batch/sound-mix-render/sound-qa-loudness/sound-qa-asr(또는kino sound <action>). - 사운드 지속 시간, 이득, 음량 및 프로필 버전에 숫자 값을 제공하십시오. 부울은 강제 변환 전에 거부됩니다. 명시적으로 유효하지 않은 계획은 예제 계획을 선택할 수 없습니다. 유형이 지정된 계획은 재검증됩니다. 필드별 호환성 규칙은
docs/SOUND_INPUT_VALIDATION.md를 참조하십시오. - 실제 ASR은 해시된 오디오/참조 요청과 명시적 루트를 사용하며, 해당 트랜스크립트 ZIP을 보관하고 불일치를 정직하게 보고합니다. 캐시된 로컬 Whisper만 사용하며, 자동 다운로드는 없습니다. 레거시 해시 전용 호출은 시뮬레이션입니다.
docs/SOUND_ASR_REQUESTS.md를 참조하십시오. - 실제 모노/스테레오 PCM16 음량 QA의 경우,
SoundLoudnessRequest와 프로젝트 루트를 제공하고within_tolerance를 검사하십시오. 측정 성공이 준수를 의미하지는 않습니다. FFmpeg가 필요하며, 입력 없는 픽스처는 데모로 표시됩니다.docs/SOUND_LOUDNESS_REQUESTS.md를 참조하십시오. - 유지된 모노/스테레오 마스터링의 경우,
SoundMasterRequest와 명시적 루트를sound-master-render에 제공하십시오.docs/SOUND_MASTER_REQUESTS.md를 참조하십시오. 확인된 ZIP, 실제 정규화 모드 및 측정된 최종 정책 준수를 검사한 후, 릴리스 전에 들어보십시오. 입력 채널은 유지되며, 기존 출력은 절대 대체되지 않습니다. - 실제 로컬 EN/ES 캡션화의 경우,
docs/CLOSED_CAPTIONS.md를 참조하십시오. - 유지된 오디오 이퀄라이제이션의 경우,
docs/SOUND_EQUALIZATION.md를 참조하십시오.sound-equalize-profile에base_profile과target_profile을 사용하십시오.
- 빠른 시각적 검토를 위한
게시 및 종속성
- 체크포인트 및 게시는 게시, 릴리스 체크포인트, 불변성 가정 및 종속성 제약 조건을 설명하는
docs/PUBLISHING.md를 참조하십시오.
안전 및 보안
- Kinocut은 로컬 작업 공간을 존중하며, Myffmpeg 또는 에이전트가 제공한 바이너리 우회를 방지하기 위해 오픈 소스 Python 바인딩인 래핑된 ffmpeg-python을 사용합니다.
- 에이전트는 미디어 분석을 위한 외부 API 호출을 인식하지 못할 수 있습니다.
mcp_use_dotenv를 활성화하거나--env-file을 전달한 경우에만.env파일을 로드합니다. - 일부 Kinocut 제공자는 성능을 위해 로컬에 미리 빌드된 ffmpeg 바이너리를 자동으로 다운로드하며, 에이전트가 관여하지 않습니다.
- 신뢰하는 제공자에 대한 Skyvern API 토큰이 Kinocut MCP 전용
.env파일에 제공될 수 있습니다.
Kinocut 명령 참조
kino --help를 참조하십시오. 출력의 일부 예시:
Kinocut ─ 안전한 비디오 편집 표면
사용법: kino [OPTIONS] COMMAND [ARGS]...
명령:
doctor 종속성 확인
info 미디어 파일 정보
<action> 다양한 편집 동작
search-tools 도구 검색
video-intent 편집 의도 제안
video-cutfile-render 컷파일 렌더링
...
추가 문서
docs/TOOLS.md— 모든 MCP 도구, Python 메서드 및 CLI 명령에 대한 자세한 참조.docs/WORKFLOWS.md— 워크플로우 엔진 참조.docs/RESCUE.md— 비디오 구조 워크플로우.docs/AI_VIDEO_REVIEW_AND_SALVAGE.md— AI 비디오 검토 및 복구.docs/SOUND_INPUT_VALIDATION.md— 오디오 워크플로우 입력 검증.docs/PUBLISHING.md— 게시 체크포인트 및 종속성.