¿Qué hace llvideo?
No puedes ver videos. Un modelo nativo de video sí puede. Esta habilidad lo coloca tras una CLI, hace que devuelva evidencia estructurada en lugar de prosa, y luego te entrega fotogramas reales para que formes tu propio juicio.
Esa distinción es el punto central. Si transmites un resumen del modelo, eres un intermediario. Si razonas sobre un índice tipificado y lo confirmas contra píxeles que has visto, eres el analista.
Verificación de configuración
llvideo providers
Necesita ffmpeg en el PATH y una clave API. GEMINI_API_KEY lo maneja todo.
OPENROUTER_API_KEY cuesta aproximadamente la mitad, pero no tiene un punto de subida, por lo que
solo funciona con URLs y clips pequeños — y OpenRouter requiere $1.00 de crédito comprado antes de
aceptar cualquier solicitud de video, incluso en modelos :free.
Las claves se leen primero del entorno. Como alternativa, también lee un archivo
KEY=value en ~/.itachi-api-keys, que es solo una conveniencia para
mantener las claves fuera de tu perfil de shell — las variables de entorno son suficientes.
El bucle que debes seguir
1. Siempre comienza gratis
llvideo probe VIDEO # duración, códec, resolución, estimación de tokens — sin costo
llvideo plan VIDEO # lo que costará y cómo se manejará — sin costo
plan te indica la tasa de muestreo, si se necesita una transcodificación, el recuento de tokens
y la estimación en dólares. Léelo antes de gastar.
2. Indexa el video
llvideo index VIDEO
llvideo index VIDEO --json # para analizar
llvideo index VIDEO --verify 3 # cuando el texto en pantalla importa — ver más abajo
Devuelve escenas con marcas de tiempo, texto en pantalla, acciones, diálogos, momentos clave y una
lista explícita de incertidumbres. También escribe una hoja de contacto.
3. MIRA LA HOJA DE CONTACTO. Este paso no es opcional.
La salida de index termina con una ruta. Lee esa imagen con tu propia visión antes de responder
al usuario. Es una imagen que cubre toda la línea de tiempo por aproximadamente 600–1,600
tokens. Eres barato para fundamentar y caro para equivocarte.
Todo lo que afirmes debe ser:
- algo que viste tú mismo en un fotograma,
- una medición de ffmpeg, o
- una cita de la transcripción.
Cualquier otra cosa debe atribuirse: "el índice informa…". Nunca transformes la suposición de un modelo en tu propia voz.
4. Profundiza donde importa
llvideo clip VIDEO --start 02:10 --end 02:40 --fps 4 -q "¿el logotipo se anima limpiamente?"
llvideo stills VIDEO --at 02:14,02:19 --width 1920 # resolución completa, míralos tú mismo
llvideo sheet VIDEO --at 01:00,01:05,01:10 --tile 768 --cols 2 # texto de interfaz denso
El recorte es preciso al fotograma y cuesta unos cientos de tokens. Úsalo libremente.
La mejor vista para entender — timeline
llvideo timeline VIDEO
llvideo timeline VIDEO --transcribe # sincronización palabra exacta del habla
index devuelve escenas, habla y eventos_audio como tres arrays separados. Cada
uno es preciso, pero nada los conecta — por lo que "un primer plano del tablero" y "dice que
el rango está mal" están en listas diferentes, y el hecho de que ocurran al mismo
momento queda para que tú lo reconstruyas.
Esa coocurrencia es el contexto. Un plano significa algo diferente dependiendo de
lo que se dice sobre él. timeline entrelaza todo en una sola pista:
00:10-00:18 (8.0s) *CLAVE*
plano primer plano del conductor
ve La cámara vuelve al conductor mientras una gasolinera iluminada pasa por la ventana
hace El vehículo pasa bajo el toldo iluminado
dice "La gasolinera aparece a los nueve segundos del clip."
oye Zumbido ambiental bajo del interior del coche
por qué El toldo de la gasolinera pasa directamente detrás del conductor
Usa esto sobre index siempre que la pregunta sea sobre el significado en lugar del inventario.
--transcribe fusiona una transcripción local a nivel de palabra en lugar del habla del modelo.
Las marcas de tiempo de audio del modelo se desvían aproximadamente un segundo, lo que es suficiente para
asignar una línea al plano equivocado en un corte rápido. El habla se asigna al compás que más se superpone, no
al primero que toca, por lo que una línea que cruza un corte aterriza donde se habló mayoritariamente.
Informa sobre la cobertura y nombra cualquier tramo de tiempo del que no se dijo nada. Una línea de tiempo con agujeros omitió algo, y decirlo es mejor que presentar un relato parcial como completo.
Las preguntas de seguimiento son gratuitas
El índice se almacena en caché durante 48 horas según la identidad del contenido y la configuración de muestreo.
Medido: una segunda timeline en el mismo video pasó de 12.5s y $0.02 a 0.4s y
nada. Haz todas las preguntas que necesites — iterar es como se construye la comprensión,
y no debería costar nada después de la primera pasada. --no-cache fuerza una ejecución nueva.
Reparando lo que encontraste — fix
La mayoría de los hallazgos de auditoría no necesitan regenerarse. Volumen incorrecto, un pico recortado, un fotograma negro al principio o al final — esas son operaciones deterministas de ffmpeg que no cuestan nada y no pueden alucinar.
llvideo audit render.mp4 # encuéntralo
llvideo fix render.mp4 # repáralo -> render_fixed.mp4
Reparado automáticamente: volumen integrado (loudnorm de dos pasos a −14 LUFS),
recorte de pico verdadero (mantenido a −1.0 dBFS), y fotogramas negros o blancos del primero o último — recortados
midiendo dónde termina realmente el negro, no asumiendo un recuento de fotogramas.
Deliberadamente NO reparados, cada uno con una razón indicada:
| hallazgo | por qué no |
|---|---|
| espacio negro a mitad de la línea de tiempo | una decisión de edición, no un defecto que eliminar silenciosamente |
| congelamiento | un fotograma mantenido puede ser intencional — acórtalo en la línea de tiempo |
| baja resolución | escalar inventa detalles que nunca se capturaron |
| margen de seguridad | el diseño es una elección de composición; mueve el elemento, no recortes |
| duración / relación de aspecto | se establece al renderizar; recortar para ajustarse cortaría contenido |
fix vuelve a auditar después e informa conteos de antes/después, porque afirmar que una
reparación funcionó sin volver a medir es el hábito que esta herramienta existe para romper. Medido
en una renderización deliberadamente rota: 5 mayores + 1 menor se convirtieron en 1 mayor + 1 menor, y los
dos restantes fueron los dos que necesitan una decisión humana.
Nunca sobrescribe la fuente. La salida va a <nombre>_fixed.mp4 a menos que pases --out.
Generando clips complementarios — gen
Clips cortos que se insertan en una línea de tiempo construida en otro lugar: un plano general, material de relleno, textura, un logotipo animado. No películas completas.
llvideo gen "acercamiento aéreo lento sobre un bosque de pinos neblinoso al amanecer" --seconds 5
llvideo gen "logotipo se asienta en el encuadre" --image logo.png --seconds 3 # imagen a video
llvideo gen "misma escena, tonalidad más fría" --video clip.mp4 --seconds 5 # video a video
llvideo gen-image "tarjeta de título de madera envejecida" --out title.png
Se ejecuta en Grok Imagine a través de tu XAI_API_KEY existente. Ten en cuenta que es xAI Grok,
no Groq — empresas diferentes. 1 a 15 segundos en pasos de un segundo, lo que es más
flexible que los fijos 4/6/8 de Veo.
| resolución | costo medido |
|---|---|
| 480p | $0.05/s |
| 720p | $0.07/s |
| 1080p | ~$0.11/s (extrapolado, no medido) |
Esas tarifas provienen del campo de uso de la propia API en trabajos reales, no de la documentación.
Cualquier cosa superior a $1.00 necesita --yes.
Cada clip se audita a su llegada, y eso no es decoración. Los propios valores predeterminados de Grok
producen 848x480 a aproximadamente -21 LUFS — ambos señalados por el auditor. gen por defecto usa
720p por esa razón. Luego míralo tú mismo:
llvideo sheet clip.mp4
--audio cambia a grok-imagine-video-1.5, que genera una banda sonora.
El audio generado tiende a salir bajo; espera un hallazgo de volumen y normaliza en
postproducción si el clip va a ir junto a otro material.
Auditando un video que HICISTE — spec + --from-project
Este es el bucle completo. HyperFrames, brag y Remotion ya saben lo que pretendían construir, así que nadie debería escribir una especificación de intención manualmente:
llvideo audit render.mp4 --from-project ./my-hyperframes-project
llvideo audit brag-output/brag.mp4 --from-project ./brag-output
llvideo audit out.mp4 --from-project ./my-remotion-project
O extrae la especificación por sí sola para inspeccionarla o editarla:
llvideo spec ./project --out intent.json
De dónde proviene la intención y cuánto confiar en ella:
| Fuente | Qué se extrae | Confianza |
|---|---|---|
HyperFrames index.html | inicio/fin de escena de data-start / data-duration, texto en pantalla del DOM | exacta |
HyperFrames STORYBOARD.md | tipo de transición y duración por fotograma (transition_in) | intención del autor |
| brag | lee el proyecto HyperFrames que construye bajo composition/; coteja el recuento de escenas de brag-plan.md y el total | exacta + cotejo |
Remotion .tsx | <Sequence from= durationInFrames=> ÷ fps; <TransitionSeries.Transition presentation=> | exacta para valores literales y N * fps; los valores calculados se OMITEN, no se adivinan |
Cualquier cosa que no pueda leerse estáticamente se informa como una nota en lugar de asumirse —
una duración springTiming o un from={computeIt()} se marca y se excluye.
Por qué existe esto. HyperFrames check valida la línea de tiempo de la composición buscada en
Chrome sin interfaz gráfica. La puerta de entrega de brag se detiene en las capturas previas al renderizado. Remotion no tiene
una puerta equivalente en absoluto. Ninguno de ellos mira el MP4 exportado, por lo que un error del codificador,
una renderización obsoleta o fotogramas perdidos en la exportación se envían sin ser notados. Ese vacío es lo que
esto llena — y es por lo que vale la pena ejecutar audit incluso cuando las comprobaciones propias del proyecto
pasan.
Un fundido a negro que la especificación solicitó no se informa como un defecto de fotograma negro. Solo el negro no declarado es un hallazgo.
Transiciones, cámara y ritmo — craft
Para preguntas como "cómo es este corte", "qué transiciones se usan", "analiza la edición", "qué está
haciendo la cámara", "por qué se siente rápido" — usa craft, no index.
llvideo craft VIDEO
llvideo craft VIDEO -q "¿el corte en 00:14 cae en el compás?"
index muestrea todo el video a 1 fps, lo que está bien para qué sucede e inútil
para cómo está editado: un corte directo ocupa un solo fotograma, por lo que a 1 fps ves los planos
a ambos lados y nunca la transición. craft funciona de manera diferente:
- Una pasada local gratuita puntúa cada fotograma y encuentra candidatos de transición. Esto capta transiciones suaves que un detector normal no puede — un fundido encadenado de 1 segundo alcanza un pico alrededor de 0.025, donde la detección de escena se activa en 0.12.
- Luego, cada candidato se reexamina a 8 fps en una ventana estrecha, para que el modelo vea la transición ocurrir fotograma a fotograma.
- El brillo a través de cada ventana se mide con ffmpeg, que es lo que separa un fundido a negro de un fundido encadenado. Sin eso, el modelo llama fundido a negro a un fundido encadenado; con eso, es correcto.
Devuelve lista de planos (tamaño, movimiento de cámara, composición), lista de transiciones (tipo, duración exacta, por qué el corte funciona allí), estadísticas de ritmo, color e iluminación.
Verificado contra un video con transiciones conocidas — 4/4 tipos correctos, duraciones dentro de 0.2s:
| construido | detectado |
|---|---|
| corte directo, instantáneo | hard_cut, instantáneo |
| fundido encadenado, 1.0s | crossfade, 1.0s |
| fundido a negro, 0.6s | fade_to_black, 0.5s |
| barrido a la izquierda, 0.8s | wipe, 0.63s |
Y en una toma continua con cámara en mano que contiene un paneo rápido, informó correctamente un plano y cero transiciones en lugar de inventar un corte.
Un movimiento de cámara no es un corte. Un paneo rápido, un giro rápido o un cambio de enfoque se parecen exactamente a una
edición a bajas frecuencias de cuadro. craft está construido para distinguirlos; index no. Si una
pregunta es sobre edición, usa craft.
Banderas: --zoom-fps 12 para cortes muy rápidos · --max-windows 12 para ediciones más movidas ·
--no-zoom para saltarse la pasada cercana (más barato, mucho menos preciso).
El texto en pantalla es el modo de fallo. Tómalo en serio.
Un modelo leerá texto borroso con confianza y se equivocará. Medido en metraje real — el mismo tablero de coche con desenfoque de movimiento, preguntado tres veces:
ejecución 1: "642" "55 F" "330 mi"
ejecución 2: "23.9" "65 F" "330"
ejecución 3: "6:42" "55 F" "330 mi"
Nada en ninguna respuesta individual señala el problema. Por lo tanto, no confíes en una sola respuesta:
llvideo index VIDEO --verify 3
Esto ejecuta la consulta tres veces e informa qué lecturas son estables (idénticas cada ejecución) y cuáles son INESTABLES. Trata las lecturas inestables como "hay un display presente pero no legible". Si una lectura inestable es importante, exporta un fotograma de resolución completa y léelo tú mismo:
llvideo stills VIDEO --at 00:11 --width 1920
Usa --verify 3 siempre que la respuesta se vaya a usar en acciones: mensajes de error en una
grabación de pantalla, números en un tablero, código en pantalla, precios, nombres. Cada
ejecución adicional cuesta aproximadamente lo mismo que la primera — unos céntimos.
Auditando una renderización — audit
Después de hacer un video (Remotion, HyperFrames, brag, ffmpeg, Veo), nunca lo has visto. Compruébalo antes de enviarlo:
llvideo audit out.mp4 # solo comprobaciones gratuitas medidas
llvideo audit out.mp4 --craft # más transiciones y cámara
llvideo audit out.mp4 --spec intent.json # más una diferencia con lo que pediste
Las comprobaciones gratuitas detectan los errores que realmente se envían. Sin modelo, sin tokens, sin red:
- primer/último fotograma negro o blanco — el defecto de exportación más común, un deshajuste de uno en la línea de tiempo
- espacios negros y tramos congelados dentro del cuerpo
- volumen EBU R128 y recorte de pico verdadero, contra el objetivo de plataforma de -14 LUFS
- espacios de silencio, y "la pista de audio está efectivamente vacía"
- velocidad de fotogramas, resolución, tasa de bits declaradas vs. implícitas
- detalle brillante presionado contra el borde del fotograma (pista de margen de seguridad)
Verificado: detecta 5 de 5 defectos plantados deliberadamente, y devuelve LIMPIO con cero hallazgos en metraje profesional real. No da falsas alarmas.
Cada hallazgo indica si es medido (ffmpeg lo dijo, con el número) o juzgado (un modelo lo cree). Nunca presentes un hallazgo juzgado como un hecho.
El código de salida es 1 solo cuando hay un bloqueador, por lo que funciona como puerta de CI.
Diferencia contra la intención
Escribe lo que se suponía que era el video, luego diferencia:
{
"duration_seconds": 30,
"duration_tolerance": 0.5,
"aspect": "16:9",
"transitions": [
…
[truncado por traducción]