OpenYTClipper

Chrome extension + native helper that adds clipping controls directly under every YouTube video and downloads the requested segment via yt-dlp + ffmpeg.

Workflow

1. Use the Use current time buttons to populate start/end.
2. Adjust the clip name or timestamps manually (supports HH:MM:SS.mmm).
3. Click Download clip. The background script forwards the request to native_helper.py via Chrome Native Messaging.
4. The helper downloads + trims using yt-dlp and saves the media + JSON metadata to ~/Downloads/YouTube Clips (folder is auto-created).
5. Once complete, click Reveal clip to show it in Finder/Explorer (delegated to the helper).

Repository Layout

• extension/ – Manifest v3 extension (content script UI + background service worker).
• helper/native_helper.py – Native messaging helper that calls yt-dlp and trims the requested range.
• helper/yt_snippet_helper.json – Native messaging host manifest template (installer fills in the helper path + extension ID).
• helper/install_helper.py – Optional installer script to verify dependencies and copy the host manifest.
• plan.md – High-level implementation rationale.

Prerequisites

• Chrome/Chromium 114+ (Manifest v3 compatible).
• macOS/Linux/Windows with Python 3.9+, yt-dlp, and ffmpeg in PATH.

Install helper dependencies:

cd helper
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Verify that ffmpeg is available (e.g., via Homebrew brew install ffmpeg).

Extension ID & Native Host Registration

The repository no longer checks in a private RSA key. This keeps the signed extension ID private (as required for security) and lets each distribution define its own ID:

1. Load the unpacked extension via chrome://extensions.
2. Copy the ID that Chrome assigns (e.g. abc123...) from the card’s ID field.
3. Run the installer with that ID so the native host only accepts messages from your build:

python3 helper/install_helper.py --extension-id <your-extension-id>

When the project is published to the Chrome Web Store, its official extension ID can be documented in the release notes, and users should pass that ID to the installer. Until then, each developer repeats the steps above after loading the extension locally.

The installer script:

• Verifies python3, yt-dlp, and ffmpeg exist in PATH.
• Writes the host manifest to the Chrome/Chromium native messaging directory (platform-aware).
• Ensures native_helper.py is executable.
• On Windows, writes the HKEY_CURRENT_USER\SOFTWARE\{Google\Chrome|Chromium}\NativeMessagingHosts\yt_snippet_helper registry entry so Chrome actually discovers the manifest.
• If yt-dlp / ffmpeg live in a common Homebrew location (e.g., /opt/homebrew/bin) but aren’t on your PATH, the script will still detect them and print a reminder to export that directory.

Useful flags:

• --chrome-channel chromium installs into the Chromium profile paths.
• --dry-run prints the manifest without writing.
• --skip-dependency-check skips verifying yt-dlp/ffmpeg (useful if they’re installed but not on the current PATH).

Linux: the manifest is placed in ${XDG_CONFIG_HOME:-~/.config}/google-chrome/NativeMessagingHosts/.
Windows: the installer records the manifest path under HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts (Chrome docs).

Loading the Extension

1. Run pnpm/vite is not required – this is pure JS/CSS.
2. Open chrome://extensions, toggle Developer mode, and click Load unpacked.
3. Select the extension/ directory from this repo. Chrome will assign an ID (shown on the card); copy it for the installer step.
4. Navigate to any youtube.com/watch page. A “Clip Recorder” panel should appear under the video player.

Troubleshooting

• “Native helper not found” – confirm that the host manifest exists in the Chrome Native Messaging directory and that the path is correct.
• yt-dlp errors – run the same command manually (printed in helper logs) to validate network/DRM limitations.
• Permission errors – the extension requires nativeMessaging, downloads, and host permission for https://www.youtube.com/* per manifest.json.
• Helper not registering – rerun python3 helper/install_helper.py --extension-id <your-extension-id> and restart Chrome.

License

This project is released under the MIT License.