TuneShift

TuneShift is a Chrome and Firefox extension for musicians, vocalists, producers, and practice-heavy listeners who need quick pitch and playback control on YouTube.

It lets you shift YouTube audio by semitones and adjust playback speed from a compact popup, without leaving the video page or reaching for a separate audio tool.

Preview

Dark mode	Light mode

What It Does

• Shift YouTube audio up or down in semitone steps.
• Change playback speed with presets from 0.5x up to 2x.
• Keep pitch and playback controls in one focused extension popup.
• Start the audio pipeline automatically when pitch or speed moves away from default.
• Reset pitch and speed back to normal with one button.
• Switch between dark and light popup themes.
• Run only on YouTube pages.

Why TuneShift Exists

YouTube is one of the easiest places to find songs, lessons, backing tracks, live versions, covers, and practice references. But practicing with YouTube often means the track is in the wrong key, too fast, or too slow.

TuneShift keeps those controls close:

• Transpose a song into your vocal range.
• Practice a solo at a slower speed.
• Match a track to your instrument tuning.
• Speed up or slow down lessons without opening another app.
• Make quick adjustments while the video keeps playing.

Current Status

TuneShift is available on the Chrome Web Store and Firefox Add-ons. Chrome and Firefox builds can also be loaded manually for development.

Project website: tuneshift.207146.xyz

The core popup, YouTube content script, background messaging, playback speed controls, semitone state handling, icons, and automated tests are in place. Audio quality and browser behavior can still vary depending on the video, tab state, and Chrome audio pipeline.

Install

Install from your browser's official extension marketplace:

• Add TuneShift to Chrome
• Add TuneShift to Firefox

Installation For Development

1. Clone this repository.
2. Install dependencies with npm ci.
3. Generate both browser builds with npm run build.

Chrome

1. Open chrome://extensions.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select dist/chrome.
5. Open a YouTube video and click the TuneShift extension icon.

Firefox

1. Open about:debugging.
2. Select This Firefox.
3. Click Load Temporary Add-on.
4. Select dist/firefox/manifest.json.
5. Open a YouTube video and click the TuneShift extension icon.

The temporary Firefox installation is removed when Firefox closes. You can alternatively run npm run dev:firefox to build TuneShift and launch it in a temporary Firefox profile.

The files under extension/ are shared source files. Browser-loadable extension roots are generated under dist/; do not load extension/ directly.

Store Packaging

Generate store-ready archives with:

npm run package:chrome
npm run package:firefox

Archives are written below web-ext-artifacts/chrome/ and web-ext-artifacts/firefox/. These generated directories are intentionally ignored by Git.

Each archive contains files like this at its root:

manifest.json
background.js
content.js
popup.html
popup.js
assets/
lib/
pitch/

Do not upload the repository root or the extension/ source folder. Both stores expect the generated manifest.json at the archive root.

For Firefox validation and AMO submission details, see docs/firefox.md.

Permissions

TuneShift keeps permissions intentionally narrow:

"permissions": ["activeTab"],
"host_permissions": ["https://www.youtube.com/*"]

These are used so the popup can work with the active YouTube tab and the content script can run on YouTube pages. TuneShift does not request broad access such as bookmarks, context menus, all URLs, storage, or scripting injection permissions.

Project Structure

extension/
  manifest.base.json
  manifests/
    chrome.json
    firefox.json
  background.js
  content.js
  popup.html
  popup.js
  assets/
    fonts/
    icons/
  lib/
    tuneshift-core.js
    tuneshift-audio-engine.js
    tuneshift-stream-source.js
  pitch/
    worklet/

scripts/
  build-extension.js

tests/
  build-extension.test.js
  background.test.js
  popup.test.js
  tuneshift-audio-engine.test.js
  tuneshift-core.test.js
  tuneshift-stream-source.test.js

docs/
  firefox.md

dist/                       # generated and ignored
  chrome/
  firefox/

web-ext-artifacts/          # generated and ignored
  chrome/
  firefox/

Development

The build step copies shared extension files and combines manifest.base.json with the selected browser manifest. It does not bundle, transpile, or minify runtime code.

Install test dependencies:

npm install

Run tests:

npm test

Run coverage:

npm run test:coverage

Build one browser:

npm run build:chrome
npm run build:firefox

Validate the Firefox build with Mozilla's extension linter:

npm run lint:firefox

Tech Notes

• Manifest V3 extension with separate Chrome and Firefox background declarations.
• Chrome runs background.js as a service worker; Firefox runs the shared core and background files as non-persistent background scripts.
• Popup UI uses plain HTML, CSS, and JavaScript.
• Shared state helpers live in extension/lib/tuneshift-core.js.
• Background script owns per-tab extension state.
• Content script connects the popup/background state to the YouTube page.
• Pitch processing is handled through the bundled SoundTouch worklet files.
• Tests run with Vitest and jsdom.

Limitations

• TuneShift is currently focused on YouTube.
• Real-time pitch shifting can introduce artifacts depending on the source audio and playback settings.
• Some YouTube page transitions may require reopening the popup or refreshing extension state.
• This is not intended to replace a DAW or professional pitch correction workflow.

License

TuneShift is released under the MIT License.

TuneShift's data practices are described in PRIVACY.md.

This project includes third-party SoundTouch license files under extension/pitch/ and extension/pitch/worklet/.

Project license information is available in LICENSE.