Back to KlipVault

Extension Setup Guide

This guide walks you through installing three small pieces of free software that work together to let you download HLS streams like Twitch VODs, livestreams, and segmented videos directly to your computer.

Everything runs locally on your machine. No files are uploaded to any server.

Twitch & Livestreams

Download Twitch VODs, livestream replays, and any HLS / .m3u8 video.

Local & Private

All processing happens on your computer. Nothing leaves your machine.

Works Everywhere

Any site yt-dlp supports — Vimeo, Instagram, Reddit, and more.

What You Will Install

  1. Python — a free programming environment that runs the installer script. Most Mac and Linux computers already have this.
  2. yt-dlp — a free, open-source video downloader. This is the actual engine that fetches and saves the video files.
  3. KlipVault Browser Extension — the button that appears in your browser toolbar and talks to the other tools.
  4. KlipVault Native Host — a tiny bridge file that lets the extension communicate with yt-dlp on your computer.
1

Install Python (if you don't already have it)

Python is required to run the native host installer. Most Mac and Linux computers already have it installed. If you are not sure, you probably need to install it on Windows.

Download Python for Windows

python.org — click the yellow button

Download Python for Mac

python.org — click the macOS installer

Windows users: Download the installer, open it, and check the box that says "Add Python to PATH" at the bottom of the first screen. Then clickInstall Now. You may need to restart your computer when it finishes.

Mac users: Open the downloaded .pkg file and follow the prompts. You will likely need to enter your computer password.

Linux users: Python is almost certainly already installed. You can check by opening a terminal and typing python3 --version.

2

Download yt-dlp (the video downloader engine)

yt-dlp is the free, open-source tool that actually downloads the video files. You need to download the correct version for your operating system and place it somewhere your computer can find it.

Download yt-dlp for Windows

yt-dlp.exe — about 15 MB

Download yt-dlp for Mac

Standalone binary

Download yt-dlp for Linux

Standalone binary

Windows — Where to put the file:

  1. Create a new folder called C:\yt-dlp on your computer.
  2. Move the downloaded yt-dlp.exe file into that folder.
  3. Press the Windows key, type "environment variables", and open"Edit the system environment variables".
  4. Click the "Environment Variables" button at the bottom.
  5. In the top list, find "Path", click it, then click "Edit".
  6. Click "New" and type C:\yt-dlp, then click OK on all windows.
  7. Restart your computer so the change takes effect.

Mac — Where to put the file:

  1. Open the Finder, press Cmd + Shift + G.
  2. Type /usr/local/bin and press Enter.
  3. Drag the downloaded yt-dlp_macos file into this folder.
  4. Right-click the file, choose "Get Info", and rename it to just yt-dlp.
  5. You may need to grant permission the first time you run it. Go to System Settings → Privacy & Security and approve it if prompted.

Linux — Where to put the file:

  1. Open your file manager as administrator (or use the terminal).
  2. Move the downloaded yt-dlp file to /usr/local/bin/.
  3. Right-click the file, choose Properties → Permissions, and check "Allow executing file as program".

Alternatively, most Linux distributions can install it through the package manager: open a terminal and run sudo apt install yt-dlp (Ubuntu/Debian) or sudo pacman -S yt-dlp (Arch).

3

Install the KlipVault Browser Extension

The extension is a small file that adds a KlipVault button to your browser toolbar. Firefox users can install directly from the Firefox Add-ons store. Chrome / Edge / Brave users install manually in "developer mode" — it's completely safe and the extension only communicates with KlipVault and your local yt-dlp installation.

Download Extension for Chrome

klipvault-extension-chrome-v1.2.7.zip

Install Extension for Firefox

Firefox Add-ons Store — official Mozilla release

Chrome / Edge / Brave Installation:

  1. Download the Chrome zip file above.
  2. Right-click the downloaded zip file and choose "Extract All...". Extract it to a folder you will keep permanently (for example, Documents\KlipVault-Extension). Do not delete this folder — Chrome loads the extension from it.
  3. Open Chrome and type chrome://extensions into the address bar, then press Enter.
  4. In the top-right corner, toggle the switch labeled "Developer mode" to the ON position.
  5. Three new buttons will appear at the top left. Click "Load unpacked".
  6. A file picker opens. Navigate to the folder you extracted in step 2 and select it. Click Select Folder.
  7. The KlipVault extension will now appear in your list. You should see a small puzzle-piece icon in your browser toolbar near the top right. If you do not see it, click the puzzle-piece icon in Chrome's toolbar and pin KlipVault so it stays visible.

Firefox Installation:

  1. Click the "Install Extension for Firefox" button above — it opens the KlipVault page on the Firefox Add-ons store.
  2. Click the "Add to Firefox" button on the store page.
  3. A popup will appear asking you to confirm the permissions. Click "Add".
  4. The KlipVault puzzle-piece icon will appear in your browser toolbar. If you don't see it, click the puzzle-piece icon in Firefox's toolbar and pin KlipVault.
  5. That's it — the extension is now permanently installed and will persist across Firefox restarts.
4

Install the KlipVault Native Host

The native host is a tiny bridge file that lets the KlipVault extension talk to yt-dlp on your computer. It only runs when you start a download — it does not run in the background.

Download Native Host

klipvault-native-host.zip — source code with installer

Windows Installation:

  1. Download the zip file above.
  2. Right-click the zip and choose "Extract All...". Extract it to a folder like Documents\klipvault-native-host.
  3. Open the extracted folder. You will see several files including install.py.
  4. Find your extension ID: Open Chrome, go to chrome://extensions/, find "KlipVault Video Downloader," and copy the long ID string underneath it (looks like nejkkeckaagccbhlobjmjejnnlopiecf).
  5. Right-click on install.py and choose "Open with" → "Python". If you do not see Python, you may need to install it first (see Step 1).
  6. The installer will auto-detect your extension ID. If it cannot, open a terminal (PowerShell or Command Prompt), navigate to the extracted folder, and run: python install.py --extension-id YOUR_ID_HERE
  7. A black window (command prompt) will open, run for a few seconds, then close. If you see any errors, read the message carefully — it usually means yt-dlp is not in your PATH yet (see Step 2).
  8. Restart your browser completely — close all Chrome windows and open it again. Simply closing one tab is not enough.

Mac Installation:

  1. Download the zip file above.
  2. Double-click the zip to extract it. A folder called klipvault-native-host will appear.
  3. Open the Terminal app (press Cmd + Space, type "Terminal", press Enter).
  4. Type cd Downloads/klipvault-native-host and press Enter. If you extracted it somewhere else, navigate to that folder instead.
  5. Type python3 install.py and press Enter.
  6. The installer will report what it did. If it says "Success," you are done.
  7. Quit Chrome completely (Cmd + Q) and reopen it.

Linux Installation:

  1. Download the zip file above.
  2. Extract the zip using your file manager.
  3. Open a terminal and navigate to the extracted folder.
  4. Run python3 install.py.
  5. The installer will detect your browser and install the manifest automatically.
  6. Restart your browser completely.

How to Tell It Is Working

  1. Click the KlipVault puzzle-piece icon in your browser toolbar. A small popup will open.
  2. In the top-right corner of the popup, look for a small status indicator. If it says something like "Native host connected" or shows a green dot, the bridge is working.
  3. Go to KlipVault and paste a Twitch VOD URL, such as https://www.twitch.tv/videos/2768136341
  4. Select a format and click Get Download Link.
  5. You should see a card that says "HLS Stream Detected" with a button labeled "Open in Extension". Click it.
  6. The extension popup should open and the download should start automatically. You will see progress updates inside the popup.
  7. When finished, the video file will be in your computer's Downloads folder.

Common Problems & How to Fix Them

"yt-dlp not found" even though install.py found it

This usually means the native host manifest has the wrong extension ID. Chrome silently rejects connections when allowed_origins doesn't match. Re-run install.py — it now auto-detects your extension ID. If that fails, run: python install.py --extension-id YOUR_ID_HERE

"Native host not found" when I click Open in Extension

The bridge file is not registered with your browser. Re-run install.py (Step 4) and then fully quit and reopen your browser — not just close the window, but right-click the browser icon and choose Quit / Exit.

"yt-dlp not found" error during install

yt-dlp is not in your system PATH. Go back to Step 2 and make sure you placed yt-dlp in a folder that is listed in your PATH environment variable. On Windows, restarting your computer after editing PATH is required.

The download starts but fails or produces a broken file

Make sure you are using the latest version of yt-dlp. Download it again from the link in Step 2 and replace your old copy. Some streaming sites change their formats frequently.

Nothing happens when I click Open in Extension

Open the browser's developer console (press F12, then click the Console tab) and look for red error messages. If you see errors mentioning 'klipvault_host', the native host is not installed correctly. Re-run Step 4.

Firefox: the extension disappears when I restart Firefox

Firefox temporary add-ons are intentionally unloaded on restart. This is normal until the extension is officially published on the Firefox Add-ons store (coming soon). For now, you will need to reload it via about:debugging each time you restart Firefox.

Mac: 'cannot be opened because the developer cannot be verified'

This is macOS Gatekeeper. Go to System Settings → Privacy & Security, scroll down, and click 'Allow Anyway' next to the yt-dlp or install.py entry. Then try again.

Still Stuck?

If you have followed all the steps above and something is still not working, you can open an issue on GitHub and we will help you.

Open an Issue on GitHub
Back to KlipVault