splicedeck

AI 에이전트가 구동하는 비디오 편집기, 사용자 컴퓨터에서 실행됩니다.

한 번의 호출로 템플릿에 컷을 입힙니다: 모션 그래픽, 오버레이, 자막, 그리고 컷을 맞출 비트 그리드. 소스에 대한 한 번의 패스로 정리된 롱폼 마스터와 세로 클립을 모두 얻을 수 있습니다. 또한 각 클라이언트, 채널 또는 쇼가 선호하는 편집 방식을 기억하여, 다음 편집이 이전 편집이 끝난 지점에서 시작됩니다.

드래그할 타임라인도, 생성할 계정도 없습니다. 아무것도 업로드되지 않습니다.

상태: 파이프라인이 처음부터 끝까지 실행되며, 메모리가 컷에 도달합니다.

오늘 소스가 전달 파일이 됩니다. 참조 머신(Windows 11, Python 3.13, ffmpeg 8.1.2)에서 실제 223 MB .mov 파일로 측정:

inspect   2.6 s     draft  27 ms     splice  27 ms     verify  42 ms
deliver   157 s  ->  1920×1080 h264 + aac, -23.0 LUFS, decodes clean

python -m pytest는 약 4분 만에 1425 통과, 2 건너뜀을 보고합니다. 31개의 동사가 CLI에 도달하고 그중 18개가 MCP 서버에 도달하며, 둘 다 하나의 테이블에서 생성되어 서로 분리될 수 없습니다.

한 가지 주요 기능은 아직 작동하지 않습니다. 인용문으로 자르려면 현재 매니페스트로는 얻을 수 없는 음성 바이너리가 필요합니다. 이를 계획하기 전에 작동하지 않는 것을 읽어보세요.

설치

Python 3.12 이상과 PATH에 ffmpeg 8.x가 필요합니다. splicedeck은 ffmpeg를 설치하거나 번들로 제공하지 않으며, docs/first-run.md §4에서 그 이유가 의도적임을 설명합니다.

설치 스크립트는 작업 공간 위치를 묻고, 정확한 명령을 보여준 후 ffmpeg 설치를 제안하며, 모든 것을 스캐폴딩하고 MCP 구성을 작성합니다:

curl -fsSLO https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.sh
less install.sh && bash install.sh

irm https://raw.githubusercontent.com/ihuzaifashoukat/splicedeck/main/install.ps1 -OutFile install.ps1
notepad install.ps1; powershell -ExecutionPolicy Bypass -File install.ps1

실행하기 전에 읽어보세요. curl | bash 원라이너는 README의 상당 부분이 위협 모델에 관한 프로젝트에 좋은 광고가 아닐 것입니다.

직접 수행하거나 테스트를 원한다면:

uv tool install splicedeck                    # or: pipx install splicedeck
git clone https://github.com/ihuzaifashoukat/splicedeck.git && cd splicedeck
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
.venv/bin/python  -m pip install -e ".[dev]"      # macOS, Linux

아직 PyPI에 없습니다. 릴리스가 없으므로 첫 번째 태그가 푸시될 때까지 uv tool install splicedeck은 404를 반환합니다. 그때까지는 스크립트, 클론 또는 uv tool install "git+https://github.com/ihuzaifashoukat/splicedeck.git"을 사용하세요.

docs/install.md에는 모든 경로, 플랫폼별 ffmpeg 명령, 환경 변수, 그리고 AI 에이전트에 붙여넣어 splicedeck을 설치하고 연결할 수 있는 프롬프트가 있습니다.

사용해보기

작업 공간 루트는 실행하는 디렉토리이며, spd init이 하나를 스캐폴딩합니다:

mkdir my-edit && cd my-edit
spd init                                      # bookmarks/ casebook/ elements/ ledger/ media/ profiles/ templates/
mkdir -p casebook/parties/demo
spd ready                                     # what is present, and what each gap blocks

init은 절대 덮어쓰지 않습니다. 프로필을 편집한 후 다시 실행하면 누락된 부분을 채우고 편집 내용은 그대로 둡니다. 작성하는 파일은 이 저장소가 제공하는 파일과 바이트 단위로 동일하며, python -m checks.starter --check가 이를 강제합니다.

그런 다음 media/ 아래에 푸티지를 넣고 컷:

spd inspect --path media/your-file.mov               # mints a source handle
spd draft --party demo --source s1 --bookmark baseline --profile wide-1080
spd apply --sheet c1 --template clean-master         # overlays, motion, beat grid
spd splice --sheet c1 --source a --in_ticks 0 --out_ticks 900000 \
           --source_in_ticks 0 --cause manual
spd verify --sheet c1
spd deliver --sheet c1

소스는 작업 공간 내부에 있어야 합니다. 드라이브 문자가 포함된 경로는 읽기 전에 PATH_OUTSIDE_WORKSPACE로 거부됩니다.

파티는 사람이 의도적으로 손으로 생성합니다. draft는 casebook/parties/<name>/이 존재할 때까지 UNKNOWN_PARTY를 거부합니다.

MCP 지원 어시스턴트에서 구동하려면 서버를 등록하세요:

{"mcpServers": {"splicedeck": {
  "command": "C:\\src\\splicedeck\\.venv\\Scripts\\python.exe",
  "args": ["-m", "splicedeck.surface.mcp"],
  "cwd": "C:\\src\\splicedeck"}}}

cwd는 작업 공간이어야 합니다. 작업 공간 루트가 작업 디렉토리이고 다른 것은 이를 발견하지 못하기 때문입니다. python -m splicedeck.surface.mcp --tools는 생성된 도구 목록을 출력하고 종료하며, 이를 통해 손상된 서버와 잘못된 호스트 구성을 구분할 수 있습니다. docs/mcp.md는 전체 가이드입니다.

템플릿: 한 번의 호출로 완성되는 룩

apply는 컷 시트에 명명된 템플릿을 입힙니다. 오버레이를 배치하고, 에이전트가 이후에 컷할 비트 그리드를 작성하며, 시트에 사용된 템플릿을 기록합니다.

오늘 네 가지가 제공됩니다:

템플릿의 오버레이는 선택적 모션 티어가 설치되면 애니메이션되고, 그렇지 않으면 정적 이미지로 대체됩니다. 6개의 애니메이션 컴포지션이 scenes/에 포함되어 있으며, 이 프로젝트를 위해 작성되었고 함께 라이선스됩니다.

슬롯은 강제됩니다. verify는 채워지지 않은 슬롯이 있는 시트를 통과시키지 않으며, 슬롯의 허용 오차를 벗어난 컷은 가장 가까운 법적 가장자리가 즉시 전송 가능한 호출로 반환되며 SLOT_TOO_TIGHT로 거부됩니다. 이것이 에이전트가 볼 수 없는 리듬을 맞출 수 있게 하는 것입니다.

직접 작성할 수 있습니다. spd compose --kind template은 수작업 템플릿 또는 요소 카드를 검증하고 작성합니다. 의도적으로 CLI 전용입니다: MCP 서버는 templates/에 쓸 수 없으며, docs/templates.md §4에서 이를 간과가 아닌 이유를 설명합니다.

메모리가 필요한 이유

편집은 수천 개의 작은 판단이며 거의 모두 반복됩니다. 펀치라인 후 얼마나 오래 유지할지. 이 화자의 군더더기가 노이즈인지 개성인지. 팔 길이만큼 떨어진 전화기에서 자막이 얼마나 커야 하는지. 상태 비저장 도구는 매 세션마다 해당 컨텍스트를 다시 제공하도록 강제하며, 이것이 "AI 편집"이 종종 기술적으로는 정확하지만 어조가 잘못된 결과물을 생성하는 이유입니다.

여기서는 한 번 내린 결정이 기록되고 재사용됩니다:

subtitle.size_px = 74
  when {surface: vertical, frame: 1080x1920}
  set by  a render you shipped and kept, 2026-08-02
  before  66

그 기록은 검토 가능한 텍스트로 저장소에 남습니다. 차이점을 읽고, 줄을 편집하여 잘못된 항목을 수정하며, 편집을 악화시킨 변경 사항을 git revert할 수 있습니다. 버전 관리하는 다른 모든 것과 같은 위치에 보관되는 동작 변경 로그입니다.

두 가지 규칙이 신뢰성을 보장합니다:

• 모델이 지속적인 것은 작성하지 않습니다. 기록은 사람이 한 행동을 설명합니다: 렌더를 출하하고 유지한 것, 컷이 제거한 순간을 복원한 것. 에이전트는 발생한 것을 가리킬 수 있습니다. 기억될 내용을 구성할 수는 없습니다.

• 모든 쓰기는 사람의 게이트를 통과합니다. 어떤 선호도 조용히 학습되지 않습니다.

이 루프는 오늘 실행됩니다. spd set, ship, keep, restore 및 discard는 파티의 해시 체인 원장에 행위를 추가하고 각각에서 제안을 준비합니다. 검증되지 않는 체인에는 행위를 추가할 수 없습니다. 그런 다음 spd review는 블라인드로 값을 묻고, 범위와 출하된 컷을 표시하지만 숫자는 절대 표시하지 않으며, 일치하는 답변은 봉인된 사례와 재생성된 findings.lock.txt가 됩니다. 다음 draft는 이를 기준으로 해결합니다: 북마크가 설정을 열고, 케이스북이 사람이 결정한 것을 재정의하며, 시트는 읽은 잠금을 기록합니다.

로컬 우선, 그리고 완전함

API 키나 클라우드 계정 없이 새 클론이 사용자 컴퓨터에서 완성된 전달 파일을 생성합니다. 이것이 기준선이며, 저하된 모드가 아닙니다.

클라우드 서비스는 어려운 오디오 또는 화자 분리를 위한 호스팅 음성 API와 같이 진정으로 도움이 되는 곳에서 켤 수 있지만, 필수가 되는 것은 없으며 어떤 전달물도 이에 의존하지 않습니다. ffmpeg는 자식 프로세스로 작업을 수행합니다. 절대 벤더링되거나 링크되지 않습니다.

또한 프로젝트는 사용자 하드웨어에 대해 추측하지 않습니다. 인코더 지원은 기능 목록을 읽는 대신 테스트 인코딩을 통해 입증됩니다. 기능 목록은 거짓말을 하기 때문입니다. 개발 머신에서 ffmpeg -encoders는 런타임에 실패하는 NVIDIA 인코더를 광고하는 반면, 실제로 작동하는 Intel 인코더는 모든 가이드에서 언급되지 않습니다.

작동하는 것

• 하나의 분석 패스, 두 개의 전달물. 전사 및 분석은 소스당 한 번 실행됩니다. 롱폼 마스터와 세로 클립 모두 동일한 결과를 읽습니다.

• 프레임 정확한 컷팅, 오디오 드리프트 없음. 오디오는 먹스까지 PCM으로 유지되며 한 번 인코딩됩니다. 전달된 샘플은 45 및 120 조인에 걸쳐 Python으로 구축된 참조 어셈블리와 바이트 단위로 동일합니다. 측정되었으며, 주장되지 않았습니다.

• 한 번의 호출로 템플릿 및 모션, 에이전트가 컷할 비트 그리드와 모션 티어가 없을 때 정적 폴백 포함.

• 가독성을 유지하는 자막. 크기 및 대비 하한은 렌더러에 의해 강제되며, 플랫폼 자체 인터페이스 아래에 위치할 텍스트는 그려지지 않고 거부됩니다. 글리프는 순수 stdlib TrueType 파서에 의해 모양이 지정되고 래스터화되므로, 각인은 바이트 재현 가능하며 골든으로 커밋됩니다.

• 불확실성을 인정하는 세로 프레이밍. 대상을 자신 있게 추적할 수 없을 때 자동 프레이밍을 거부하고 이유를 설명합니다. 자신 있게 잘못된 크롭은 정직한 거부보다 나쁩니다. 괜찮아 보이는 것을 아무도 검토하지 않기 때문입니다.

• 견고한 권리. 음악, 효과 및 스톡 푸티지는 출처와 허용 조건에 대한 기록을 전달합니다. 자산에 이 정보가 없으면 전달 실행이 거부됩니다.

• 자체 수정을 전달하는 유형화된 거부. 거부는 retry_with와 함께 도착하며, 이는 즉시 전송 가능한 호출 목록입니다. 102개의 코드가 있으며, 각각 구성 사이트와 도달 가능함을 증명하는 테스트가 있습니다.

작동하지 않는 것

이를 생략하는 상태 섹션이 이전 섹션을 무가치하게 만든 이유이기 때문에 명확히 명시합니다.

CHANGELOG.md에도 동일한 목록이 있으며, 둘은 동기화 상태를 유지해야 합니다.

모델 티어 아래의 두 티어는 작동합니다. subject: "centre"는 기하학적이며 아무것도 필요하지 않습니다. SPD_SIGHT_LOCATOR=reduce는 가중치 없는 로케이터를 선택하며, 순수 stdlib Python에서 시간적 중앙값 배경 차분으로 대상을 찾습니다. numpy나 컴파일된 확장이 전혀 없습니다.

참조 마스터에서 얼굴 검출기와 비교했을 때, 해당 로케이터의 중앙값은 프레임 너비의 0.1% 이내로 일치했습니다. 동일한 푸티지에서 확실도 0.26을 보고했으며 경로를 전혀 맞추지 못했습니다. 정적 배경에 거의 움직이지 않는 화자는 배경 차분이 잡을 것이 없기 때문입니다. 둘 다 올바른 답변입니다: 산술은 정확하며, 가중치 없는 티어의 정직한 한계는 중앙에 맞춰진 추측이 아니라 구멍입니다 (docs/framing.md §7). 움직이는 대상이 있는 푸티지는 잘 추적됩니다.

구동 방법

MCP 서버와 스킬을 통해, 따라서 모든 MCP 지원 어시스턴트가 사용할 수 있으며, 정확히 동일한 동사를 노출하는 CLI도 있습니다. 두 표면 모두 splicedeck/surface/verbs.py에서 생성되며, python -m checks.golden --check는 분리되면 빌드를 실패시킵니다.

서버는 2024-11-05부터 2026-07-28까지 다섯 가지 프로토콜 개정판을 지원하며, initialize 핸드셰이크와 server/discover 모두에 응답합니다.

실패는 유형화됩니다. 거절은 에이전트가 해석해야 하는 산문 대신 즉시 전송 가능한 호출 형태로 자체 수정 사항을 포함하므로, 복구는 한 번의 턴으로 이루어집니다:

{"ok": false, "verb": "draft", "refused": "BOOKMARK_UNKNOWN",
 "plain": "No bookmark by that name is shipped.",
 "needs_human": false,
 "retry_with": [{"verb": "draft", "args": {"bookmark": "baseline", "party": "demo",
   "profile": "wide-1080", "situation": "default", "source": "s1"}}]}

스킬

네 가지 스킬은 에이전트에게 동사 순서, 동사 사이의 함정, 그리고 거절을 다음 올바른 호출로 전환하는 방법을 가르칩니다. 이 스킬들은 .claude/skills/에 있으며, 클론은 설치 없이 바로 사용할 수 있습니다.

이 저장소는 또한 Claude Code 플러그인이자 자체 마켓플레이스입니다:

claude plugin marketplace add ihuzaifashoukat/splicedeck
claude plugin install splicedeck@splicedeck

또는 skills CLI가 지원하는 모든 에이전트(Codex, Cursor, OpenCode, Antigravity, Cline, Gemini CLI, Zed, Windsurf 포함)에 스킬을 설치할 수 있습니다:

npx skills add ihuzaifashoukat/splicedeck            # add --list to look first

두 경로 모두 스킬만 제공합니다. MCP 서버를 등록하지 않는데, 그 이유는 서버가 플러그인이나 스킬 설치 프로그램이 알 수 없는 절대 인터프리터 경로와 cwd를 필요로 하기 때문입니다. install.sh가 이를 자동으로 작성하며, docs/mcp.md에는 수동으로 작성하는 방법이 나와 있습니다.

다른 모든 에이전트 런타임은 AGENTS.md를 참조합니다.

설계

명세는 의도적으로 코드보다 먼저 작성됩니다.

에이전트의 영구 메모리는 단순한 기능이 아니라 보안 표면입니다. 공격자가 기록할 수 있는 모든 것은 해당 대화보다 오래 지속됩니다. 하나의 문서만 읽는다면 docs/security.md를 읽으십시오.

비목표

여러 소스에서 필름을 조립하는 것. 비디오나 음악을 생성하는 것. 타임라인 GUI. 실시간 협업. 호스팅 서비스. 어떤 순간이 클립이 될지 자동으로 선택하는 것(후보를 제시하고 사람이 선택하기를 기다리므로).

요구 사항

Python 3.12 이상 및 PATH에 ffmpeg 8.x가 필요합니다. 기본 경로에 컴파일된 Python 확장이 사용되지 않으므로 빌드 단계나 먼저 설치해야 할 플랫폼 런타임이 없습니다. Windows, macOS 및 Linux를 지원합니다. CI는 Ubuntu와 Windows를 대상으로 하며, macOS는 기계에서 테스트되지 않았습니다.

모션 티어는 추가로 Node와 scenes/ 내부의 npm install이 필요합니다. 이는 선택 사항이며, 없이 전달할 경우 정적 이미지로 대체됩니다.

기여

이슈 및 디자인 비판을 환영합니다. CONTRIBUTING.md가 시작점입니다: 설정, 실행할 검사, 동사 또는 거절 코드를 추가하는 방법, 그리고 장점과 관계없이 풀 리퀘스트가 거부되는 사항들입니다. 먼저 AGENTS.md를 읽으십시오. 열두 가지 엄격한 규칙은 중요하며, 이를 위반하는 변경은 그 이유만으로 거부됩니다.

참여함으로써 행동 강령에 동의하는 것으로 간주됩니다.

보안

취약점에 대해 공개 이슈를 열지 마십시오. SECURITY.md에 보고 경로와 범위가 명시되어 있습니다.

라이선스

Apache-2.0. 저작권 2026 Huzaifa Shoukat.