Local Media Helper

Local Media Helper is a small local companion program that handles high-quality video work the Chrome extension cannot do on its own. Many platforms deliver high-quality video as a separate video-only track and audio-only track (DASH), and a browser extension alone cannot merge the two. The helper merges them into a single MP4 locally and hands the result back to the Chrome extension.

It ships as a standalone Rust CLI rather than being bundled into the desktop app. Media downloading itself is still done by Chrome with your browser session — the helper only muxes.

When Do You Need It?

TikTok clips (sometimes required)

• Many TikTok videos are delivered as separate audio/video streams. Saving those with Clip to Obsidian requires the helper. Without it, the popup stops with a "This TikTok video needs the Local Media Helper" message.
• Progressive (single-file) videos clip fine without the helper.

Facebook reel clips (optional)

• Facebook reels with split audio/video save as a single MP4 with sound when the helper is available. Without it, the clip still completes but saves a video-only (silent) file.

Instagram → Immich high-quality uploads (optional)

• When you want to preserve maximum video quality while uploading Instagram saved posts, my posts, or a profile grid to Immich
• When Instagram serves high quality only as video-only/audio-only sidecars and offers just a lower-quality progressive video as fallback
• When your Immich server runs on light hardware like a Raspberry Pi and you don't want to install Social Archiver-specific processing tools on it

Immich uploads keep working without the helper (lower-quality fallback).

Install

On macOS, download the Local Media Helper .pkg installer and double-click to install. The installer registers the helper app, a login startup item, and Chrome pairing support together.

After installing, click Pair Local Helper in the Chrome extension Options. Manual token copying is not needed in the normal install flow.

Opening the helper app directly does not run an installation — it shows the current running state and next steps.

Development Run

Run straight from source:

cd local-media-helper
cargo run -- serve --token local-test-token

Default address:

http://127.0.0.1:8787

Install locally:

cd local-media-helper
cargo install --path .
social-archiver-local-media-helper serve --token local-test-token

If you omit --token, the helper generates a temporary pairing token and prints it to the terminal. Development runs may require ffmpeg.

macOS:

brew install ffmpeg

Debian/Ubuntu:

sudo apt install ffmpeg

On Windows, use scoop install ffmpeg or an official ffmpeg build.

Chrome Extension Settings

Set the following in the Chrome extension options:

Local Media Helper URL: http://127.0.0.1:8787
Pairing Token: set automatically by the Pair Local Helper button
Use local helper: on
Prefer helper for high-quality Immich videos: on

When saving, Chrome may ask for the http://127.0.0.1:8787/* permission. You must allow it so the extension can send /health and /media/dash-mux requests to the helper.

Building a Local Package

For developers building a test binary:

cd local-media-helper
./scripts/package-local.sh

Output is created under local-media-helper/dist/. At the MVP stage this is not a signed/notarized app package, so OS-specific security warnings and the install flow should be validated separately before distribution.

Security Boundaries

• The helper binds to 127.0.0.1 only by default.
• /media/dash-mux requires a bearer token.
• The helper never receives Instagram cookies, Immich API keys, or Social Archiver tokens.
• The helper does not run arbitrary shell commands — only the fixed ffmpeg mux command.
• It processes one mux job at a time.

Troubleshooting

Connection check fails

Confirm the helper is running and that the URL and token match the extension settings. If you started it on a different port, update the URL in the extension settings too.

ffmpeg not found

If ffmpeg is not on your PATH, pass the path explicitly:

social-archiver-local-media-helper serve --token local-test-token --ffmpeg /path/to/ffmpeg

Video uploaded as fallback

This can be expected behavior. If the helper fails or the progressive video is judged good enough, the Chrome extension uploads the existing browser-ready video to Immich.

TikTok clip asks for the helper

That TikTok video is delivered as separate audio/video streams. Install the helper, enable it in extension Settings, then clip again. A vault folder must also be selected in extension Settings — TikTok clips write the merged video file directly into your vault.

Next Steps

• Chrome Extension
• Video Downloads