Documentación

Instala la extensión, registra el host de Native Messaging y verifica la cadena de herramientas.

1. Inicio rápido

Operant es una extensión Manifest V3 para navegadores Chromium (Chrome, Edge, Brave o cualquier otro build de Chromium con soporte de side panel). No hay paso de build: el árbol de fuentes es la extensión cargable.

Carga descomprimida: abre chrome://extensions, activa el modo desarrollador, pulsa Cargar descomprimida y selecciona la carpeta operant. Fija la extensión desde el menú de la pieza y abre su side panel desde el icono fijado.

Zip de la release: descarga el zip, descomprímelo y sigue el mismo flujo; el archivo es la extensión descomprimida, lista para cargar.

Desarrollo:

Desarrollo
npm install
npm run dev

Si cambias el host nativo, recarga la extensión para que el nuevo registro surta efecto. La extensión funciona por sí sola; el host solo es necesario para procesar con ffmpeg y yt-dlp.

2. Arquitectura

Operant reparte su trabajo en tres capas desacopladas. Cada capa habla únicamente con sus vecinas a través de un canal bien definido, lo que mantiene la UI fluida, la interceptación dirigida por eventos y el procesamiento pesado en nativo.

  • Side panel (UI) — JavaScript vanilla, renderizado bajo demanda. Lista los medios detectados, gestiona la cola de descargas y expone la consola ffmpeg/yt-dlp. No contiene lógica de captura ni de procesado.
  • Service worker y motor de contenido — el núcleo dirigido por eventos. Un escáner DOM descubre medios en la pestaña activa mientras un observador webRequest registra los manifiestos de streaming cuando cruzan la pila de red.
  • Host nativo — un daemon en Python fuera del sandbox que posee ffmpeg, yt-dlp y el acceso al sistema de archivos que el navegador no puede tener.

El panel nunca habla con el host directamente: las peticiones viajan por el service worker mediante puertos chrome.runtime, y el worker las reenvía por el canal de Native Messaging. El camino de vuelta — progreso y salida de consola — sigue la misma ruta, así que cada mensaje tiene exactamente un propietario.

3. Captura de medios

La detección corre en dos planos complementarios, de modo que los medios se encuentran tanto si viven en el marcado como si solo cruzan la red:

  • Escaneo DOM: el content script inspecciona la pestaña activa buscando elementos img y video, variantes srcset, imágenes de fondo CSS y placeholders de lazy loading, clasificando cada recurso por tipo y dimensiones.
  • Observación de red: el listener webRequest inspecciona cabeceras de respuesta y marca manifiestos HLS (.m3u8), DASH (.mpd) y segmentos de media en el momento en que aparecen; los streams que nunca tocan el DOM también se detectan.

Cada hallazgo se reduce al mínimo que el panel necesita — URL, tipo de medio, dimensiones — y se conserva en la memoria volátil de la pestaña más chrome.storage.session para mantener el panel sincronizado. Nada se escribe en disco y el metadata muere con la sesión.

4. Descargas

El motor de cola obtiene los recursos detectados con peticiones directas y paralelas, reportando progreso en vivo por archivo al panel.

  • Inyección de Referer: los recursos protegidos contra hotlinking reciben el Referer real de la página mediante reglas efímeras de declarativeNetRequest que existen solo durante la transferencia y se eliminan inmediatamente después.
  • Exportación por lotes: varias selecciones se empaquetan en un único ZIP en memoria (JSZip) — sin archivos temporales en disco.
  • Salida: todo lo que descargas aterriza en ~/Downloads/Operant/.

5. Companion (Rust)

El companion (operant-host.exe) es un binario Rust standalone — sin Python, sin runtime, sin paquetes pip. Corre fuera del sandbox y controla ffmpeg y yt-dlp. El ejecutable de 2–3 MB es autocontenido y se incluye en la release.

Autoregistro en Windows
Haz doble clic sobre operant-host.exe. Un diálogo Win32 nativo confirma el registro en Chrome, Edge y Firefox automáticamente — sin terminal ni ID de extensión.
Linux / macOS
chmod +x operant-host
./operant-host --register <extension-id>

Registro: el companion escribe un manifiesto de Native Messaging que apunta a sí mismo y permite exactamente un ID de extensión — el tuyo — y lo registra donde Chromium espera encontrarlo (el registro de Windows; los directorios de native-messaging en Linux y macOS). El companion rechaza mensajes de cualquier otro origen.

Binarios gestionados: ffmpeg y yt-dlp se descargan bajo demanda desde sus repositorios oficiales de releases al directorio bin propio del companion, aislado de cualquier cosa en tu PATH: %LOCALAPPDATA%\Operant\bin\ en Windows, ~/Operant/bin/ en el resto. Borrar ese directorio y desregistrar el companion elimina cualquier rastro.

6. Protocolo de mensajería

La comunicación usa canales stdio estructurados según la especificación de Native Messaging de Chromium:

  • Prefijo de longitud: entero sin signo de 4 bytes en little endian (uint32).
  • Cuerpo del mensaje: JSON codificado en UTF-8, un objeto por mensaje.

El handshake sirve a la vez de inventario de la cadena de herramientas: el host informa de qué herramientas están presentes y en qué versión, de modo que la UI puede degradar con elegancia si falta algo.

Ping / pong
{ "type": "ping" }

{
  "type": "pong",
  "tools": {
    "ytDlp": { "installed": true, "version": "2026.03.11", "source": "app" },
    "ffmpeg": { "installed": true, "version": "7.1", "source": "app" }
  }
}

Más allá del handshake, cada petición lleva un identificador de acción y sus parámetros; el host responde con estado estructurado, y los trabajos largos emiten actualizaciones de progreso que el panel pinta en vivo. Todo el tráfico se queda en stdio — sin sockets, sin HTTP, sin logs en disco.

7. Operaciones ffmpeg

OperaciónSalidaArgumentos claveUso
extract-mp3.mp3-vn -c:a libmp3lame -b:a 192kExtracción rápida de audio
remux-mp4.mp4-c copy -movflags +faststartConversión sin pérdida
compress.mp4-c:v libx264 -crf 28 -preset veryfastReducción de tamaño
resize-50.mp4-vf scale=iw*0.5:ih*0.5Reducción dimensional
hls-dash.mp4-c copy (URL directa)Ensamblado m3u8 / mpd
dash-merge.mp4-c copy (vídeo + audio)Fusión de pistas separadas

Copias vs transcodificaciones: las operaciones de remux y fusión nunca recodifican (-c copy) — corren a velocidad de disco y no pierden calidad. Compress y resize recodifican con x264 a CRF 28, un intercambio deliberado de velocidad por tamaño.

Validación de streams: los segmentos fMP4 concatenados se validan (cajas ftyp, moov, moof) antes de escribir nada en disco, así que una captura interrumpida nunca produce un archivo corrupto.

8. Testing

Las suites corren con Puppeteer sobre Chrome for Testing. El set local es totalmente determinista — sin inestabilidad de red.

# 10 casos deterministas locales (galerías, lazy loading, HLS local, shadow DOM)
npm run test:verify

# + 5 casos contra sitios públicos reales
npm run test:verify:public

# Tests unitarios del companion Rust
npm run host:test

# Auditoría visual del side panel
npm run test:audit

test:verify cubre de la captura a la descarga sobre fixtures autocontenidos: galerías de imágenes, assets con lazy loading, un servidor HLS local y contenido dentro de shadow roots. test:verify:public añade páginas reales al set. host:test ejecuta 11 tests unitarios deterministas contra el companion Rust. test:audit renderiza las vistas del side panel y las audita visualmente.

9. Estado

Esto es donde está el proyecto:

  • Completado: Núcleo de medios: escaneo DOM, sniffing HLS/DASH, descargas paralelas y exportación ZIP en memoria.
  • Completado: Companion Rust y ffmpeg: binario Rust standalone, binarios gestionados de ffmpeg/yt-dlp, pipelines de remux y fusión.
  • En desarrollo: Agent deck: análisis del árbol de accesibilidad y navegación autónoma con Browser-Use y LLMs locales, orquestados desde el companion.