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:
npm install
npm run devWhen 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
webRequestobserver records streaming manifests as they cross the network stack. - Native host — a Python daemon outside the sandbox that owns
ffmpeg,yt-dlpand 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
imgandvideoelements,srcsetvariants, CSS background images and lazy-loading placeholders, classifying each resource by type and dimensions. - Network observation: the
webRequestlistener 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
Refererheader through ephemeraldeclarativeNetRequestrules 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.
Double-click
operant-host.exe. A native Win32 dialog confirms registration in Chrome, Edge and Firefox automatically — no terminal, no extension ID needed.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.
{ "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
| Operation | Output | Key arguments | Use |
|---|---|---|---|
extract-mp3 | .mp3 | -vn -c:a libmp3lame -b:a 192k | Fast audio extraction |
remux-mp4 | .mp4 | -c copy -movflags +faststart | Lossless conversion |
compress | .mp4 | -c:v libx264 -crf 28 -preset veryfast | Size reduction |
resize-50 | .mp4 | -vf scale=iw*0.5:ih*0.5 | Dimension 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:audittest: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.