Youtube-Keystrokes-Blocker

From the README

Keystrokes Blocker for YouTube

Block distracting YouTube keyboard shortcuts while keeping the ones you need — available as a native browser extension and a userscript.

Features

Fine-grained control — individually toggle each YouTube hotkey. Enable only what you need, block everything else.

30+ hotkeys covered:

• Number keys (0–9) — jump to timeline percentage
• Spacebar — play/pause
• Arrow keys — seek (±5 s) and volume (±5%)
• Ctrl + Left/Right — chapter navigation
• F — fullscreen, M — mute, K — alternate play/pause
• J / L — seek ±10 s, T — theatre mode, C — captions, I — miniplayer
• Shift + < / > — playback speed, Period/Comma — frame-by-frame
• Home / End — jump to start/end

Smart text detection — blocking is automatically suspended when you type in search, comments, or any other input field.

Persistent settings — stored in chrome.storage.sync (extension) or the userscript manager (userscript). No external servers, no accounts.

Two install paths — native browser extension (Chrome, Firefox, Edge) or userscript (Tampermonkey, Violentmonkey, Greasemonkey).

Installation

Browser Extension

Chrome and Edge

1. Download youtube-hotkeys-blocker-v5.0.0-chrome.zip from GitHub Releases
2. Unzip to a permanent folder
3. Open chrome://extensions/ (Chrome) or edge://extensions/ (Edge)
4. Enable Developer Mode
5. Click Load unpacked and select the unzipped folder

Firefox

1. Download youtube-hotkeys-blocker-v5.0.0-firefox.zip from GitHub Releases
2. Open about:debugging#/runtime/this-firefox
3. Click Load Temporary Add-on… and select the .zip

Temporary add-ons are removed when Firefox closes. For a permanent install, wait for the AMO listing or self-sign the extension.

Userscript

1. Install Tampermonkey (recommended), Violentmonkey, or Greasemonkey
2. Install from Greasy Fork (auto-updates) or click the direct GitHub link

Usage

Open any YouTube video. A Hotkeys button appears in the actions bar below the video (next to Like, Share, Clip). Click it to open the settings panel.

Extension users also have a toolbar popup (click the extension icon) and a full options page (gear icon in the popup). All three surfaces stay in sync — any change in one is reflected in the others immediately.

Keyboard shortcut: Alt+Shift+H (Windows/Linux) or Cmd+Shift+H (Mac) opens the popup from any YouTube page.

Default configuration

Settings Reference

All settings are flat keys in chrome.storage.sync (extension) or GM_setValue storage (userscript).

How It Works

1. Content script runs at document_start on www.youtube.com
2. Early navigation listeners are registered synchronously — before storage loads
3. chrome.storage.sync settings are loaded asynchronously
4. Any yt-navigate-finish / yt-page-data-updated events that fired during loading are replayed once storage resolves — this is what makes the button appear on the first page load without a reload
5. On each /watch navigation, tryInjectButton() injects the Hotkeys button into YouTube's actions bar
6. Key events are intercepted; blocked keys get preventDefault() + stopImmediatePropagation()
7. Blocking is skipped when focus is in any <input>, <textarea>, or contentEditable element

The browser extension is assembled from src/gm-shims.js (shim layer) + disable-yt-hotkeys.user.js (hotkey logic) by scripts/build.js. The userscript is self-contained.

Development

Project Structure

Youtube-Keystrokes-Blocker/
├── disable-yt-hotkeys.user.js    # Userscript (master source for hotkey logic)
├── src/
│   ├── gm-shims.js               # Extension shim layer — assembles into content.js
│   ├── content.js                # Generated — do not edit directly
│   ├── content.css               # Styles injected by the content script
│   ├── background.js             # MV3 service worker (seeds default settings)
│   ├── manifests/
│   │   ├── manifest.chrome.json  # Chrome / Edge manifest
│   │   └── manifest.firefox.json # Firefox manifest
│   ├── popup/                    # Toolbar popup UI
│   ├── options/                  # Full options page UI
│   └── icons/                    # SVG source icon
├── scripts/
│   ├── build.js                  # Build script (version validation, assembly, zip, AMO lint)
│   └── update-version.js         # Version bumper
├── release/                      # Build artifacts — git-ignored
│   └── <version>/
│       ├── youtube-hotkeys-blocker-v<ver>-chrome.zip
│       ├── youtube-hotkeys-blocker-v<ver>-firefox.zip
│       └── youtube-hotkeys-blocker-v<ver>-userscript.user.js
└── .github/
    └── workflows/
        └── release.yml           # Builds and publishes GitHub Release on tag push

Build Commands

# Build both browsers (production — includes Firefox AMO lint)
npm run build

# Single browser
npm run build:chrome
npm run build:firefox

# Dev build — no zip, no lint, loads as unpacked extension
npm run dev
npm run dev:chrome
npm run dev:firefox

# Version management
npm run version:patch   # 5.0.0 → 5.0.1
npm run version:minor   # 5.0.0 → 5.1.0
npm run version:major   # 5.0.0 → 6.0.0

# Clean build directory
npm run clean

Artifacts land in release/<version>/. See docs/DEVELOPMENT.md for the full workflow.

Release

git add -A && git commit -m "feat: description"
npm run version:minor
git add -A && git commit -m "chore: bump version to x.y.z"
git tag vx.y.z
git push && git push --tags

Pushing a v* tag triggers GitHub Actions, which builds both extensions, runs web-ext lint, verifies the three artifacts, and creates a GitHub Release with them attached.

Troubleshooting

Extension not working — verify it is enabled at chrome://extensions/ or about:addons, then reload the YouTube tab.

Hotkeys button didn't appear — this was a first-load bug fixed in v5.0.0. If still happening, confirm you have the latest version and check the extension is enabled.

Settings not saving — confirm the storage permission is granted. Inspect storage in the browser console on a YouTube tab: chrome.storage.sync.get(null, console.log).

Userscript not working — make sure the script is enabled in your manager's dashboard and that no other extension intercepts keyboard events first.

License

Licensed under the Apache License 2.0 — see LICENSE.md.

Contributing

1. Fork the repository
2. Make your changes in disable-yt-hotkeys.user.js (hotkey logic) or src/ (extension-specific)
3. Run npm run build and verify 0 errors, 0 warnings
4. Open a pull request

Bug reports and feature requests: GitHub Issues

Links

Created and maintained by VKrishna04 · Life Experimentalist

If you find this useful, please star the repository.