vosjs/vos-cut

Cortar un take a partir de su evidencia

Estás cortando una GRABACIÓN que alguien hizo (un take de vosso: recording.webm + cursor.json + meta.json + doc.json), no grabando uno. Grabar desde un script es la skill product-video; los programas son vos-create/vos-remix.

El bucle es: ver → narrar → decidir por excepción → verificar → enviar → (el humano revisa) → volver a cortar. Cada paso nombra el verbo que lo realiza. El documento es doc.json; el contrato para sus campos y unidades está en https://vos.so/llms-full.txt. Nada de esto regraba el take de un humano, nunca: un corte no puede arreglar material de archivo, y si el material no puede soportar la petición, lo dices en la nota y te detienes.

Configuración

npm i -D @vosjs/cli   # fetch, digest, plan, frames, render, push, pull

Credenciales, en este orden, nunca impresas: VOS_API_KEY, luego la primera línea de ~/.config/vos/credentials, luego vos login (un inicio de sesión en el navegador que genera una clave para esta máquina). Las claves crean trabajo PRIVADO solamente y nunca pueden publicar. Se necesita Chromium para digest, frames y render.

0. Reglas básicas que anulan todo lo siguiente

• Nunca leas el video. Tus ojos son vos digest: digest.json, luego sheet.png, luego un recorte solo donde debas decidir. Un take de 90s tiene ~35 momentos y ~25-40k tokens de imagen si lees cada imagen; la hoja más los recortes decisivos es ~10k. El evento done imprime la estimación.
• Edita por excepción. Los planificadores (zoom, velocidad, inclinación) ya respondieron DÓNDE está cada clic, sesión de escritura, desplazamiento y pausa. plan en el resumen (digest) contiene sus intervalos y proposed nombra los que están bajo cada momento. Conserva, fusiona, elimina o reajusta esos intervalos; añade solo lo que un planificador no puede saber (qué clic solitario merece un beat, un título, un avance rápido que es aburrido pero no una pausa). Cada intervalo que tocas lleva "source": "manual". Una propuesta que ELIMINAS va a rejected ([{id, lane, in, out}], el carril y su extensión de origen) para que ningún replan, y ninguna regrabación realizada por plan --reuse, proponga ese beat de nuevo; el estudio lo escribe por sí mismo cuando un humano elimina un intervalo automático.
• Señala con una capa, no con la cámara. Cuando el corte señala a un componente (un botón, una tarjeta, un bloque de código) y el zoom magnificaría los píxeles, redibújalo como una capa html en doc.json (overlays[] con kind: "html": el marcado, el CSS en el tipo propio del producto, la caja de diseño en píxeles 1080p) colocada al lado de su sujeto, nunca sobre él. Tienes los componentes reales del producto en el repositorio; úsalos. El marcado es XML bien formado y vos validate dice lo que no se pintaría; una animación CSS se ejecuta en el reloj de pared y se rechaza en favor de anim y motion.
• Las unidades del documento, copiadas, nunca convertidas. El focus de un momento es el cx/cy de un intervalo de zoom; su rect es lo que el zoom debe contener. Las extensiones source son segundos de metraje (zoom/velocidad/inclinación/segmentos); las extensiones output son segundos renderizados (superposiciones/audio). Los valores de píxel en cualquier lugar son el error #1.
• Las ediciones humanas son sagradas. doc.manual en el resumen cuenta los intervalos que un humano decidió; un envío que toca un nodo que el humano editó desde tu base devuelve 409 como protected_conflict. Mantén sus valores a menos que la petición nombre ese nodo exacto.
• Tres rondas solo, luego un humano. Ronda = editar → validar → fotogramas → juzgar. Si no se concretará en tres, envía la mejor ronda y explica por qué.
• La petición decide; las recetas de la carpeta clasifican a continuación; estos valores predeterminados al final. Una línea de receta que los miembros recientes contradicen se considera obsoleta en tu nota, no se obedece.

1. Ver

vos fetch <vosId> --media        # un take alojado que no grabaste (doc + material de archivo en casa)
vos pull <take> --media          # un directorio de take ya vinculado a vos.so
vos folder pull <slug> --media   # los takes de un proyecto, recetas incluidas
vos plan <take> --style <seed doc.json|vosId>   # en una serie: el estilo de la semilla, por datos
vos digest <take> [--transcript whisper.json] [--style <seed>]

Lee, en este orden:

1. digest.json → take (duración, página, tiene cursor/mic), moments (id, tipo, ventanas source/output, focus, rect, activity, proposed, said), plan, doc.manual. Un take con hasCursor: false (un take de grabador de navegador) lista solo head/tail/scenes: marca el ritmo por activity, haz zoom solo donde la petición nombre un lugar, y di en la nota que el take no tenía pista de cursor.
2. sheet.png → los recortes en orden temporal, ids grabados. Esta es la película de un vistazo.
3. m<nn>.crop.png para los momentos que la petición o la receta hacen decisivos; m<nn>.full.png solo para contexto (qué página, qué sección).

Al leer un recorte: qué está enfocado (un control, un campo, contenido); qué dice (la etiqueta, el valor escrito); ¿es la consecuencia del clic visible en el siguiente fotograma del momento o en un momento scene justo después? Una scene es un salto de diferencia de fotograma (una navegación, un diálogo); mira su fotograma completo para nombrarlo.

Dos cosas que los recortes dicen que la lista de clics no: un grupo de clics cuyo rect es la mayor parte del fotograma es un ARRASTRE (apuntar, raspar, mover algo), no un objetivo; y un intervalo "inactivo" cuyo activity se mantiene por encima de ~0.1 es el video REPRODUCIÉNDOSE, no inactivo. Ninguno de los dos quiere la propuesta del planificador.

Si hay una carpeta involucrada, lee TODOS los .md en ella (propios y heredados) antes de decidir nada.

2. Narrar

Escribe 3-6 beats en tus notas de trabajo, cada uno con sus ids de momento, qué MUESTRA (de los recortes) y para qué SIRVE (de la receta, el título de la página, said, o la petición). Ejemplo:

B1 m01-m04  la galería: navegar, elegir un programa            (abierto de par en par, zoom a una tarjeta)
B2 m05-m06  Remix abre el estudio                              (la escena es la recompensa)
B3 m07-m12  perillas: cinco arrastres de deslizador en el panel de remix     (un zoom sostenido, 2× sobre el medio)
B4 m13-m14  el resultado se reproduce                          (soltar, estabilizar)

¿No vino ninguna petición con el take? Infiere una de la grabación (qué muestra, dónde se mostraría, cuánto debería durar) y ENUNCIALA en la nota de versión, para que el humano corrija la petición antes del corte cuando sea incorrecta.

Si la petición nombra un beat ("haz que la parte de exportación sea más rápida"), asigna ids de momento PRIMERO y no toques nada fuera de ellos.

3. Decidir, por excepción

Por beat, contra plan y la receta:

• Zoom. Mantén el intervalo del planificador cuando enmarca el beat; fusiona propuestas adyacentes en un intervalo sostenido cuando son un beat (un zoom por beat, nunca por clic); elimina una propuesta en un clic que no es un beat; añade un intervalo en un clic solitario que el planificador omitió cuando el recorte muestra que es el momento. Nivela desde el rect: un control pequeño quiere 1.8-2.2, un panel 1.4-1.6; cuando el objetivo es la mayor parte del ancho del fotograma, la advertencia de encuadre decide el nivel, obedécela. cx/cy = el focus del momento. Ids que acuñas: u1, u2… En una grabación de editor, haz zoom en el CARRIL donde aparece un intervalo, nunca en el lienzo que se arrastra. Suelta un zoom ANTES de un clic que navega, para que el cambio de página se reproduzca en grande.
• Velocidad. Mantén propuestas sobre escritura/pausa/desplazamiento; añade 2×-3× en un tramo cuyo activity es bajo y ningún beat necesita, o bajo grupos de arrastre; nunca sobre la recompensa de un beat, nunca sobre reproducción.
• Inclinación. Solo si el estilo de cámara tiene una (tiltStyle/la personalidad del estilo) y un beat merece puntuación. Una pose por ~5s, ±5..18°.
• Recorte. Principio y final: corta a la primera y última cosa que importa (segments), dejando ~0.5s de estabilización al final. Las pantallas de carga se cortan.
• Texto. Un título por beat que tenga algo que decir, a un ritmo (uno cada 5-10s, 2.5-4s cada uno, nunca dos a la vez), en las palabras del producto y la intención del video; tercio inferior y ≈ 0.82; segundos de SALIDA; nunca sobre el control cliqueado (validate advierte). Dale una box cuando el fondo debajo es claro (la línea de tiempo de un editor lo es), y juzga cada título en su propio instante. Un título por película es demasiado escaso para una película que explica un flujo; cero está bien solo cuando la receta o la petición dicen sin texto.
• Estilo. En una serie, vos plan --style <seed> ANTES de cortar: copia los zoomStyle/zoomParams/speedParams/tiltStyle/frame/ cursor/cam/export de la semilla y replanifica los intervalos automáticos bajo ellos. Nunca vuelvas a declarar esos números en una receta; el documento de la semilla es su hogar.

Escribe el parche como EDICIONES a doc.json, nunca una reescritura. Mantén cada campo que no entiendas.

4. Verificar

vos validate <take>                                   # limpio; LEE las advertencias de encuadre, arréglalas
vos digest <take> --no-frames                         # después de reajustar tiempos: nuevos tiempos OUTPUT, mismos fotogramas
vos frames <take> --at-moments --at-zooms --times 0,25%,50%,75%,100%
vos frames <take> --times <every caption start + 1>   # cada título en su propio fondo
vos render <take> check.webm --range a..b --draft     # el beat que más cambió

Juzga las imágenes fijas contra el bucle de calidad en https://vos.so/llms-full.txt y el estándar de la carpeta: desenfoque, cromo, cursor, legibilidad del texto, primer y último fotograma como carteles; el tiro ganador dentro de 3s; el final estabilizado; ≤1 cambio de fotograma completo por ~5s (ffmpeg -vf "select='gt(scene,0.12)'" los cuenta). Una imagen fija moment-<id> y su <id>.crop.png comparten un id: "lo que había" junto a "lo que muestra el corte".

5. Enviar

vos push <take> --label "<qué, imperativo, ≤60 caracteres>" --note "<la petición a la que cortaste; los beats con segundos de origen; lo que eliminaste y añadiste>" [--folder <slug>]

La base proviene de vos.json. 409 stale_base → vos pull, reaplicar encima, enviar de nuevo. 409 protected_conflict → mantén los valores del humano a menos que la petición nombrara ese nodo (--override <id> solo entonces). Un 400 imprime el campo y su límite. Luego GET /api/vos/<id>, sigue contentUrls.thumbnail, y MÍRALO antes de informar que está listo.

6. Volver a cortar (el humano revisó)

vos pull imprime el resumen del 'differ' de lo que cambiaron ("zoom z3: nivel 2.2→1.6; overlay c1 eliminado"). Ese es el feedback, en las propias palabras de los datos: vuelve a cortar lo que sus PALABRAS pidieron y nada de lo que sus MANOS ya arreglaron. Cuenta las rondas. "Genial" es su palabra y la única salida de una semilla.

7. Recordar (solo después de que el humano haya aprobado una semilla)

Archívalo y escribe las reglas; los números se quedan en el documento de la semilla.

vos folder create "<serie>" --desc "<para qué sirve, ≤200 caracteres>"
vos folder move <vosId> --to <slug>
vos recipe push CUT.md --folder <slug>      # aplica: takes, seed: <el vos id>
vos recipe push BRAND.md --folder <slug>    # aplica: cualquiera, seed: ninguno

Una receta se nombra en MAYÚSCULAS, como CLAUDE.md: es el archivo que la colección lee antes de cortar cualquier cosa. Lo que archivas se almacena con su raíz en mayúsculas de cualquier manera, para que el terminal y el estante estén de acuerdo.

CUT.md dice lo que un número no puede: el vocabulario de beats, qué recibe un título y qué nunca, duraciones de mantenimiento, la convención de título/final, la banda de longitud, qué saltar, y las decisiones que el humano corrigió DENTRO de la semilla (leído del 'differ'). BRAND.md: tipografía, paleta, fondo, música, la voz de cualquier texto. Miembros posteriores: tira de la carpeta, digest, planifica --style desde la semilla, corta contra CUT.md, envía --folder; una corrección que se repite en dos miembros (o una que el humano establece para todos ellos) se añade bajo ## Notas del agente, con fecha, y la regla anterior se reescribe para que coincida (vos recipe push <file> --asset <id> reemplaza en su lugar; el cuerpo anterior se conserva). Nunca reescribas las líneas del propietario en silencio.