Documentation

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

1. Quick start

Operant is a multi-browser Manifest V3 extension. No build step is required for development.

Development

npm install
npm run dev

Alternatively, open chrome://extensions (or edge://extensions), enable Developer mode and load the unpacked extension.

2. Native host installation

The native host (native-host/operant_host.py) is the Python process that runs outside the sandbox and drives ffmpeg and yt-dlp. Chromium requires it to be registered with the system.

Windows (Chrome & Edge)

native-host\install_host.bat <extension-id>

Why a .bat wrapper?
If the manifest pointed directly at the .py file, Windows would open a visible console window. The wrapper launches pythonw.exe, keeping execution silent.

Linux / macOS

chmod +x native-host/install_host.sh
./native-host/install_host.sh <extension-id>

3. Messaging protocol

Communication uses structured stdio channels following the Chromium specification:

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

Ping / pong

{ "type": "ping" }

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

4. 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=iw0.5:ih0.5`	Dimension reduction
`hls-dash`	`.mp4`	`-c copy` (direct URL)	m3u8 / mpd assembly
`dash-merge`	`.mp4`	`-c copy` (video + audio)	Merging split tracks

5. Testing

Deterministic suites run with Puppeteer and Chrome for Testing:

# 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

# Side panel visual audit
npm run test:audit