Documentation

Install the extension, register the native messaging host and verify the toolchain.

1. Quick start

Operant is a Manifest V3 extension for Chromium browsers (Chrome, Edge, Brave or any other Chromium build with side panel support). There is no build step: the source tree is the loadable extension.

Load unpacked: open chrome://extensions, enable Developer mode, press Load unpacked and select the operant folder. Pin the extension from the puzzle-piece menu and open its side panel from the pinned icon.

Release zip: download the zip, unpack it and follow the same flow — the archive is the unpacked extension, ready to load.

Development:

Development
npm install
npm run dev

When you change the native host, reload the extension so the new registration takes effect. The extension works standalone; the host is only required for ffmpeg and yt-dlp processing.

2. Architecture

Operant splits its work across three decoupled layers. Each layer only talks to its neighbours through a well-defined channel, which keeps the UI responsive, the interception event-driven and the heavy processing native.

  • Side panel (UI) — vanilla JavaScript, rendered on demand. Lists detected media, drives the download queue and exposes the ffmpeg/yt-dlp console. It holds no capture or processing logic.
  • Service worker and content engine — the event-driven core. A DOM scanner discovers media in the active tab while a webRequest observer records streaming manifests as they cross the network stack.
  • Native host — a Python daemon outside the sandbox that owns ffmpeg, yt-dlp and the file system access the browser cannot have.

The panel never talks to the host directly: requests travel through the service worker over chrome.runtime ports, and the worker forwards them over the native messaging channel. The reverse path — progress and console output — follows the same route, so every message has exactly one owner.

3. Media capture

Detection runs on two complementary planes, so media is found whether it lives in the markup or only crosses the network:

  • DOM scan: the content script inspects the active tab for img and video elements, srcset variants, CSS background images and lazy-loading placeholders, classifying each resource by type and dimensions.
  • Network observation: the webRequest listener inspects response headers and flags HLS manifests (.m3u8), DASH manifests (.mpd) and media segments the moment they appear — streams that never touch the DOM are still detected.

Every finding is reduced to the minimum the panel needs — URL, media type, dimensions — and is kept in the tab's volatile memory plus chrome.storage.session so the panel stays in sync. Nothing is written to disk and the metadata dies with the session.

4. Downloads

The queue engine fetches detected resources with direct, parallel requests, reporting live progress per file back to the panel.

  • Referer injection: resources protected against hotlinking receive the page's real Referer header through ephemeral declarativeNetRequest rules that exist only for the duration of the transfer and are removed immediately afterwards.
  • Batch export: multiple selections are packaged into a single ZIP in memory (JSZip) — no temporary files touch the disk.
  • Output: everything you download lands in ~/Downloads/Operant/.

5. Companion (Rust)

The companion (operant-host.exe) is a standalone Rust binary — no Python, no runtime, no pip packages. It runs outside the sandbox and drives ffmpeg and yt-dlp. The single 2–3 MB executable is self-contained and ships as part of the release.

Self-registration on Windows
Double-click operant-host.exe. A native Win32 dialog confirms registration in Chrome, Edge and Firefox automatically — no terminal, no extension ID needed.
Linux / macOS
chmod +x operant-host
./operant-host --register <extension-id>

Registration: the companion writes a native messaging manifest that points at itself and allows exactly one extension ID — yours — then registers it where Chromium expects it (the Windows registry; the platform native-messaging directories on Linux and macOS). The companion refuses messages from any other origin.

Managed binaries: ffmpeg and yt-dlp are downloaded on demand from their official release repositories into the companion's own bin directory, isolated from anything in your PATH: %LOCALAPPDATA%\Operant\bin\ on Windows, ~/Operant/bin/ elsewhere. Deleting that directory and unregistering the companion removes every trace.

6. Messaging protocol

Communication uses structured stdio channels following the Chromium native messaging specification:

  • Length prefix: 4-byte unsigned integer, little endian (uint32).
  • Message body: UTF-8 encoded JSON, one object per message.

The handshake doubles as a toolchain inventory: the host reports which tools are present and at which version, so the UI can degrade gracefully when something is missing.

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

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

Beyond the handshake, every request carries an action identifier and its parameters; the host answers with structured status, and long-running jobs emit progress updates the panel renders live. All traffic stays on stdio — no sockets, no HTTP, no disk logs.

7. ffmpeg operations

OperationOutputKey argumentsUse
extract-mp3.mp3-vn -c:a libmp3lame -b:a 192kFast audio extraction
remux-mp4.mp4-c copy -movflags +faststartLossless conversion
compress.mp4-c:v libx264 -crf 28 -preset veryfastSize reduction
resize-50.mp4-vf scale=iw*0.5:ih*0.5Dimension reduction
hls-dash.mp4-c copy (direct URL)m3u8 / mpd assembly
dash-merge.mp4-c copy (video + audio)Merging split tracks

Copies vs transcodes: remux and merge operations never re-encode (-c copy) — they run at disk speed and lose no quality. Compress and resize re-encode with x264 at CRF 28, a deliberate speed-for-size trade-off.

Stream validation: concatenated fMP4 segments are validated (ftyp, moov, moof boxes) before anything is written to disk, so an interrupted capture never produces a corrupt file.

8. Testing

Suites run with Puppeteer against Chrome for Testing. The local set is fully deterministic — no network flakiness.

# 10 local deterministic cases (galleries, lazy loading, local HLS, shadow DOM)
npm run test:verify

# + 5 cases against live public sites
npm run test:verify:public

# Rust companion unit tests
npm run host:test

# Side panel visual audit
npm run test:audit

test:verify covers capture through download on self-contained fixtures: image galleries, lazy-loaded assets, a local HLS server and content inside shadow roots. test:verify:public adds real-world pages to the set. host:test runs 11 deterministic unit tests against the Rust companion. test:audit renders the side panel views and audits them visually.

9. Status

This is where the project stands:

  • Shipped: Media core: DOM scanning, HLS/DASH sniffing, parallel downloads, in-memory ZIP export.
  • Shipped: Rust companion & ffmpeg: standalone Rust binary, managed ffmpeg/yt-dlp binaries, remux and merge pipelines.
  • In development: Agent deck: accessibility-tree analysis and autonomous navigation via Browser-Use and local LLMs, dispatched through the companion.