splicedeck

Un editor de vídeo que un agente de IA maneja, ejecutándose en tu propia máquina.

Una sola llamada arregla un corte en una plantilla: gráficos animados, superposiciones, subtítulos y una cuadrícula de ritmo para cortar en ella. Una sola pasada sobre una fuente te da tanto un máster de formato largo limpio como clips verticales. Y recuerda cómo le gusta ser cortado a cada cliente, canal o programa, así que el siguiente montaje empieza donde terminó el anterior.

No hay línea de tiempo que arrastrar ni cuenta que crear. No se sube nada.

Estado: el pipeline se ejecuta de principio a fin, y la memoria llega al corte

Una fuente se convierte en un archivo entregado hoy. Medido en la máquina de referencia (Windows 11, Python 3.13, ffmpeg 8.1.2) contra un .mov real de 223 MB:

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 reporta 1425 aprobados, 2 omitidos en unos cuatro minutos. Treinta y un verbos llegan a la CLI y dieciocho de ellos llegan a un servidor MCP, ambos generados desde una misma tabla para que no se desvíen.

Una característica destacada no funciona todavía. Cortar citando necesita un binario de habla que ningún manifiesto puede obtener actualmente. Lea Qué no funciona antes de planificar en función de ello.

Instalar

Necesitas Python 3.12 o superior y ffmpeg 8.x en tu PATH. splicedeck no instala ni incluye ffmpeg, y docs/first-run.md §4 explica por qué eso es intencionado.

El script de instalación pregunta dónde va el espacio de trabajo, ofrece instalar ffmpeg después de mostrarte el comando exacto, crea todo y escribe una configuración 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

Léelo antes de ejecutarlo. Un comando curl | bash en una línea sería una mala publicidad para un proyecto cuyo README trata en gran parte sobre un modelo de amenaza.

Si prefieres hacerlo tú mismo, o quieres las pruebas:

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

Aún no en PyPI. No hay ninguna versión, por lo que uv tool install splicedeck dará 404 hasta que se suba la primera etiqueta. Hasta entonces usa el script, un clon, o uv tool install "git+https://github.com/ihuzaifashoukat/splicedeck.git".

docs/install.md tiene todas las rutas, los comandos de ffmpeg por plataforma, las variables de entorno, y un prompt que puedes pegar en un agente de IA para que instale y configure splicedeck por ti.

Probarlo

La raíz del espacio de trabajo es cualquier directorio en el que ejecutes, y spd init crea uno:

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 nunca sobrescribe. Volver a ejecutarlo después de haber editado un perfil completa lo que falta y deja tus ediciones intactas. Los archivos que escribe son idénticos byte a byte a los que envía este repositorio, y python -m checks.starter --check lo exige.

Luego coloca tu material grabado en media/ y corta:

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

Las fuentes deben estar dentro del espacio de trabajo. Una ruta con una letra de unidad es rechazada como PATH_OUTSIDE_WORKSPACE antes de leer nada.

Una "party" (sesión/proyecto) es creada por un humano, a mano, a propósito. draft rechaza UNKNOWN_PARTY hasta que exista casebook/parties/<nombre>/.

Para manejarlo desde un asistente compatible con MCP, registra el servidor:

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

cwd debe ser el espacio de trabajo, porque la raíz del espacio de trabajo es el directorio de trabajo y nada más lo descubre. python -m splicedeck.surface.mcp --tools imprime la lista de herramientas generada y sale, que es como se distingue un servidor roto de una configuración de host rota. docs/mcp.md es la guía completa.

Plantillas: el aspecto en una llamada

apply viste una hoja de corte en una plantilla con nombre. Coloca las superposiciones, escribe la cuadrícula de ritmo contra la que el agente luego corta, y registra en la hoja qué plantilla usó.

Cuatro vienen incluidas hoy:

Las superposiciones de una plantilla se animan cuando el nivel de movimiento opcional está instalado, y caen en una impresión estática cuando no lo está. Seis composiciones animadas vienen incluidas en scenes/, escritas para este proyecto y licenciadas con él.

Los espacios se aplican. verify se niega a pasar una hoja con un espacio sin rellenar, y un corte que caiga fuera de la tolerancia de un espacio es rechazado como SLOT_TOO_TIGHT con los límites legales más cercanos devueltos como llamadas listas para enviar. Eso es lo que permite a un agente alcanzar un ritmo que no puede ver.

Puedes escribir las tuyas propias. spd compose --kind template valida y escribe una plantilla o tarjeta de elemento creada a mano. Es deliberadamente solo CLI: el servidor MCP no puede escribir en templates/, y docs/templates.md §4 explica el razonamiento en lugar de tratarlo como un descuido.

Por qué memoria

Un montaje son mil pequeños juicios y casi todos se repiten. Cuánto tiempo mantener después de un remate. Si el relleno de este orador es ruido o personalidad. Qué tan grandes deben ser los subtítulos en un teléfono a la distancia del brazo. Una herramienta sin estado te obliga a volver a proporcionar esa información cada sesión, por lo que la "edición con IA" tan a menudo produce algo técnicamente correcto y tonalmente incorrecto.

Aquí, una decisión que tomas una vez se registra y reutiliza:

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

Ese registro vive en tu repositorio como texto revisable. Puedes leer el diff, corregir una entrada incorrecta editando una línea, y git revert un cambio que empeoró los montajes. Es un registro de cambios de comportamiento, mantenido en el mismo lugar que todo lo demás que versionas.

Dos reglas lo mantienen fiable:

• Nada duradero es escrito por el modelo. Un registro describe algo que un humano hizo: envió un render y lo mantuvo, restauró un momento que el corte eliminó. El agente puede señalar lo que sucedió; no puede componer lo que se recuerda.

• Cada escritura pasa por una puerta humana. Ninguna preferencia se aprende en silencio.

Ese bucle se ejecuta hoy. spd set, ship, keep, restore y discard añaden actos al libro mayor encadenado por hash de una party y preparan una propuesta a partir de cada uno; un acto no puede ser añadido a una cadena que no se verifica. spd review entonces pide el valor a ciegas, mostrando los límites y el corte enviado pero nunca el número, y una respuesta coincidente se convierte en un caso sellado y un findings.lock.txt regenerado. El siguiente draft resuelve contra él: el marcador abre la configuración, el libro de casos anula aquellos que un humano estableció, y la hoja registra qué bloqueo leyó.

Local primero, y completo

Un clon nuevo sin claves de API y sin cuenta en la nube produce un archivo terminado y entregado en tu propia máquina. Ese es el punto de partida, no un modo degradado.

Los servicios en la nube se pueden activar donde realmente ayuden, como una API de habla alojada para audio difícil o diarización, pero nada se vuelve obligatorio y ningún entregable depende de uno. ffmpeg hace el trabajo como un proceso hijo. Nunca se vende y nunca se enlaza.

El proyecto también se niega a adivinar sobre tu hardware. La compatibilidad con codificadores se demuestra codificando de prueba en lugar de leer una lista de características, porque las listas de características mienten. En la máquina de desarrollo ffmpeg -encoders anuncia un codificador NVIDIA que falla en tiempo de ejecución, mientras que el Intel que realmente funciona no se menciona en ninguna guía.

Qué funciona

• Una pasada de análisis, dos entregables. La transcripción y el análisis se ejecutan una vez por fuente. El máster de formato largo y los clips verticales leen los mismos resultados.

• Corte preciso a fotograma sin desviación de audio. El audio permanece en PCM hasta el mux y se codifica una vez. Las muestras entregadas son idénticas byte a byte a un ensamblaje de referencia construido en Python sobre 45 y 120 uniones. Medido, no afirmado.

• Plantillas y movimiento en una sola llamada, con una cuadrícula de ritmo contra la que el agente corta y un respaldo estático cuando el nivel de movimiento está ausente.

• Subtítulos que siguen siendo legibles. Los límites mínimos de tamaño y contraste son aplicados por el renderizador, y el texto que caería debajo de la propia interfaz de una plataforma se rechaza en lugar de dibujarse. Los glifos se forman y rasterizan mediante un analizador TrueType de stdlib puro, por lo que las impresiones son byte-reproducibles y se confirman como doradas.

• Encuadre vertical que admite incertidumbre. Cuando el sujeto no puede ser rastreado con confianza, declina autoencuadrar y dice por qué. Un recorte erróneo con confianza es peor que una negativa honesta, porque nadie revisa el que parecía correcto.

• Derechos que se sostienen. La música, los efectos y el material de archivo llevan un registro de dónde vinieron y qué permiten los términos. Una entrega se niega a ejecutarse si algún activo carece de uno.

• Negativas tipadas que llevan su propia corrección. Una negativa llega con retry_with, una lista de llamadas listas para enviar. Hay 102 códigos, cada uno con un sitio de construcción y una prueba que demuestra que es alcanzable.

Qué no funciona

Dicho claramente, porque una sección de estado que omite esto es la razón por la que la última fue inútil.

CHANGELOG.md lleva la misma lista, y se espera que ambas se mantengan sincronizadas.

Dos niveles por debajo del nivel de modelo sí funcionan. subject: "centre" es geométrico y no necesita nada. SPD_SIGHT_LOCATOR=reduce selecciona un localizador libre de pesos que encuentra el sujeto mediante sustracción de fondo de mediana temporal en Python stdlib puro, sin numpy y sin ninguna extensión compilada .

Verificado contra un detector de rostros en el máster de referencia, la mediana de ese localizador coincidió dentro del 0.1% del ancho del fotograma. En el mismo metraje luego reportó certeza 0.26 y no ajustó ninguna trayectoria, porque un orador que apenas se mueve contra un fondo estático no deja nada para que la sustracción de fondo se aferre. Ambas son la respuesta correcta: la aritmética es sólida, y el límite honesto de un nivel libre de pesos es un agujero en lugar de una suposición centrada (docs/framing.md §7). El metraje con un sujeto en movimiento se rastrea bien.

Cómo lo manejas

A través de un servidor MCP y Skills, para que cualquier asistente compatible con MCP pueda usarlo, además de una CLI que expone exactamente los mismos verbos. Ambas superficies se generan a partir de splicedeck/surface/verbs.py, y python -m checks.golden --check hace fallar la compilación si se desvían.

El servidor habla cinco revisiones de protocolo, 2024-11-05 a 2026-07-28, y responde tanto al protocolo de apretón de manos initialize como a server/discover.

Los fallos están tipificados. Una negativa lleva su propia corrección como llamadas listas para enviar en lugar de prosa que un agente tenga que interpretar, por lo que la recuperación es de un turno:

{"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"}}]}

Habilidades

Cuatro habilidades enseñan a un agente el orden de los verbos, las trampas entre verbos y cómo convertir una negativa en la siguiente llamada correcta. Se encuentran en .claude/skills/, y un clon las recoge sin necesidad de instalación alguna.

Este repositorio es también un plugin de Claude Code y su propio mercado:

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

O instala las habilidades en cualquiera de los agentes que soporta la CLI skills, incluyendo Codex, Cursor, OpenCode, Antigravity, Cline, Gemini CLI, Zed y Windsurf:

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

Ambas rutas envían solo las habilidades. No registran el servidor MCP, porque el servidor necesita una ruta absoluta del intérprete y un cwd que ni un plugin ni un instalador de habilidades pueden conocer. install.sh lo escribe por ti, y docs/mcp.md lo tiene a mano.

Cualquier otro runtime de agente lee AGENTS.md.

Diseño

La especificación está escrita antes que el código, deliberadamente.

La memoria persistente en un agente es una superficie de seguridad, no solo una funcionalidad. Cualquier cosa que un atacante pueda escribir en ella sobrevive a la conversación que la plantó. Si lees un documento, lee docs/security.md.

No objetivos

Montar una película a partir de múltiples fuentes. Generar vídeo o música. Una interfaz gráfica de línea de tiempo. Colaboración en tiempo real. Un servicio alojado. Elegir automáticamente qué momentos se convierten en clips, ya que presenta candidatos y espera a una persona.

Requisitos

Python 3.12 o más reciente, y ffmpeg 8.x en tu PATH. No se utiliza ninguna extensión compilada de Python en ninguna ruta predeterminada, por lo que no hay paso de compilación ni runtime de plataforma que instalar primero. Windows, macOS y Linux; CI cubre Ubuntu y Windows, y macOS no está probado por máquina.

El nivel de movimiento adicionalmente necesita Node y un npm install dentro de scenes/. Es opcional, y una entrega sin él recurre a marcas fijas.

Contribuciones

Las incidencias y las críticas de diseño son bienvenidas. CONTRIBUTING.md es la puerta de entrada: configuración, las comprobaciones a ejecutar, cómo añadir un verbo o un código de negativa, y las cosas que hacen que una solicitud de extracción sea rechazada independientemente de su mérito. Lee AGENTS.md primero. Las doce reglas estrictas son fundamentales, y un cambio que rompa una se rechaza solo por esa base.

Al participar, aceptas el Código de Conducta.

Seguridad

Por favor, no abras una incidencia pública para una vulnerabilidad. SECURITY.md tiene la ruta de notificación y qué está en alcance.

Licencia

Apache-2.0. Copyright 2026 Huzaifa Shoukat.