Read this in other languages: 🇰🇷, 🇫🇷, 🇮🇸, 🇨🇱 🇪🇸, 🇷🇺, 🇭🇺

Electron wrapper around YouTube Music featuring:

• Native look & feel, aims at keeping the original interface
• Framework for custom plugins: change YouTube Music to your needs (style, content, features), enable/disable plugins in one click

Player Screen (album color theme & ambient light)

• Features
• Available plugins
• Translation
• Download
  • Arch Linux
  • MacOS
  • Windows
    • How to install without a network connection? (in Windows)
• Themes
• Dev
• Build your own plugins
  • Creating a plugin
  • Common use cases
• Build
• Production Preview
• Tests
• License
• FAQ

• Auto confirm when paused (Always Enabled): disable the "Continue Watching?" popup that pause music after a certain time

• And more ...

• Ad Blocker: Block all ads and tracking out of the box

• Album Actions: Adds Undislike, Dislike, Like, and Unlike buttons to apply this to all songs in a playlist or album

• Album Color Theme: Applies a dynamic theme and visual effects based on the album color palette

• Ambient Mode: Applies a lighting effect by casting gentle colors from the video, into your screen’s background

• Audio Compressor: Apply compression to audio (lowers the volume of the loudest parts of the signal and raises the volume of the softest parts)

• Blur Navigation Bar: makes navigation bar transparent and blurry

• Bypass Age Restrictions: bypass YouTube's age verification

• Captions Selector: Enable captions

• Compact Sidebar: Always set the sidebar in compact mode

• Crossfade: Crossfade between songs

• Disable Autoplay: Makes every song start in "paused" mode

• Discord Rich Presence: Show your friends what you listen to with Rich Presence

• Downloader: downloads MP3 directly from the interface (youtube-dl)

• Equalizer: add filters to boost or cut specific range of frequencies (e.g. bass booster)

• Exponential Volume: Makes the volume slider exponential so it's easier to select lower volumes

• In-App Menu: gives bars a fancy, dark look

  (see this post if you have problem accessing the menu after enabling this plugin and hide-menu option)

• Scrobbler: Adds scrobbling support for Last.fm and ListenBrainz

• Lumia Stream: Adds Lumia Stream support

• Lyrics Genius: Adds lyrics support for most songs

• Music Together: Share a playlist with others. When the host plays a song, everyone else will hear the same song

• Navigation: Next/Back navigation arrows directly integrated in the interface, like in your favorite browser

• No Google Login: Remove Google login buttons and links from the interface

• Notifications: Display a notification when a song starts playing (interactive notifications are available on windows)

• Picture-in-picture: allows to switch the app to picture-in-picture mode

• Playback Speed: Listen fast, listen slow! Adds a slider that controls song speed

• Precise Volume: Control the volume precisely using mousewheel/hotkeys, with a custom hud and customizable volume steps

• Shortcuts (& MPRIS): Allows setting global hotkeys for playback (play/pause/next/previous) + disable media osd by overriding media keys + enable Ctrl/CMD + F to search + enable linux mpris support for mediakeys + custom hotkeys for advanced users

• Skip Disliked Song: Skips disliked songs

• Skip Silences: Automatically skip silenced sections

• SponsorBlock: Automatically Skips non-music parts like intro/outro or parts of music videos where the song isn't playing

• Synced Lyrics: Provides synced lyrics to songs, using providers like LRClib.

• Taskbar Media Control: Control playback from your Windows taskbar

• TouchBar: Custom TouchBar layout for macOS

• Tuna OBS: Integration with OBS's plugin Tuna

• Video Quality Changer: Allows changing the video quality with a button on the video overlay

• Video Toggle: Adds a button to switch between Video/Song mode. can also optionally remove the whole video tab

• Visualizer: Different music visualizers

You can help with translation on Hosted Weblate.

You can check out the latest release to quickly find the latest version.

Install the youtube-music-bin package from the AUR. For AUR installation instructions, take a look at this wiki page.

You can install the app using Homebrew (see the cask definition):

brew install th-ch/youtube-music/youtube-music

If you install the app manually and get an error "is damaged and can’t be opened." when launching the app, run the following in the Terminal:

/usr/bin/xattr -cr /Applications/YouTube\ Music.app

You can use the Scoop package manager to install the youtube-music package from the extras bucket.

scoop bucket add extras
scoop install extras/youtube-music

Alternately you can use Winget, Windows 11s official CLI package manager to install the th-ch.YouTubeMusic package.

Note: Microsoft Defender SmartScreen might block the installation since it is from an "unknown publisher". This is also true for the manual installation when trying to run the executable(.exe) after a manual download here on github (same file).

winget install th-ch.YouTubeMusic

• Download the *.nsis.7z file for your device architecture in release page.
  • x64 for 64-bit Windows
  • ia32 for 32-bit Windows
  • arm64 for ARM64 Windows
• Download installer in release page. (*-Setup.exe)
• Place them in the same directory.
• Run the installer.

You can load CSS files to change the look of the application (Options > Visual Tweaks > Themes).

Some predefined themes are available in https://github.com/kerichdev/themes-for-ytmdesktop-player.

git clone https://github.com/th-ch/youtube-music
cd youtube-music
pnpm install --frozen-lockfile
pnpm dev

This guide provides detailed instructions on creating, configuring, and debugging plugins for YouTube Music.

1. Introduction
2. Creating a Plugin
3. Plugin Configuration Options
4. Example Plugins
5. Debugging Plugins
6. Contributing

Plugins extend the functionality of YouTube Music by modifying the UI, adding new features, or integrating with external services. This guide explains how to create and manage plugins effectively.

To create a plugin, follow these steps:

1. Import the createPlugin utility from the YouTube Music plugin system.
2. Define the plugin configuration, including metadata, styles, and functionality.
3. Export the plugin so that it can be registered by the application.

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Sample Plugin',
  restartNeeded: false,
  config: {
    enabled: true,
  },
  start() {
    console.log('Sample Plugin Activated');
  },
  stop() {
    console.log('Sample Plugin Deactivated');
  }
});

Each plugin supports various configuration options. The table below explains their usage:

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Dark Mode',
  restartNeeded: false,
  stylesheets: [
    `body { background-color: black !important; color: white !important; }`
  ],
});

import { createPlugin } from '@/utils';

export default createPlugin({
  name: 'Custom Menu',
  restartNeeded: false,
  menu: {
    label: 'My Plugin',
    submenu: [
      { label: 'Option 1', click() { console.log('Clicked Option 1'); } },
      { label: 'Option 2', click() { console.log('Clicked Option 2'); } }
    ]
  }
});

To debug plugins effectively:

1. Use console.log() to output messages for debugging.
2. Inspect the DevTools Console by pressing Ctrl + Shift + I in the app.
3. Check for errors in the logs under renderer processes.
4. Disable conflicting plugins if unexpected behavior occurs.

Example:

start() {
  console.log('Debugging Plugin: Activated');
}

To contribute your plugin improvements:

1. Fork the repository.
2. Navigate to the docs or README.md file.
3. Apply your documentation updates.
4. Submit a Pull Request with a clear title and description.

Example PR Title: "Improved Plugin Documentation - Added examples, explanations, and debugging guide."

pnpm start

pnpm test

Uses Playwright to test the app.

MIT © th-ch

If Hide Menu option is on - you can show the menu with the alt key (or ` [backtick] if using the in-app-menu plugin)