Repository files navigation

Read this in other languages:한국어,Française,Íslenska,Español,Pусский,Українська,Magyar,Português,日本語

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 inone 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): disablethe"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 thevolume 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 towithRich Presence

• Downloader: downloadsMP3directly from the interface(youtube-dl)

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

• Exponential Volume: Makes the volumesliderexponential so it's easier toselect lower volumes

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

  (seethis post if you have problemaccessing the menu after enabling this plugin and hide-menu option)

• Scrobbler: Adds scrobbling support forLast.fm andListenBrainz

• Lumia Stream: AddsLumia 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 startsplaying (interactive notificationsare available on windows)

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

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

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

• Shortcuts (& MPRIS): Allows setting global hotkeys for playback (play/pause/next/previous) +disablemedia osdby overriding media keys + enable Ctrl/CMD + F to search + enable linux mpris support formediakeys +custom hotkeysforadvanced users

• Skip Disliked Song: Skips disliked songs

• Skip Silences: Automatically skip silenced sections

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

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

• Taskbar Media Control: Control playback fromyourWindows taskbar

• TouchBar: Custom TouchBar layout for macOS

• Tuna OBS: Integration withOBS'spluginTuna

• Unobtrusive Player: Prevents the player from popping up when playing a song

• Video Quality Changer: Allows changing the video quality withabutton onthe video overlay

• Video Toggle: Addsabutton toswitch between Video/Song mode. can also optionally remove the whole video tab

• Visualizer: Different music visualizers

You can help with translation onHosted Weblate.

You can check out thelatest release to quickly find thelatest version.

Install theyoutube-music-bin package from the AUR. For AUR installation instructions, take a look atthiswiki page.

You can install the app using Homebrew (see thecask 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 theScoop package manager to install theyoutube-music package fromtheextras bucket.

scoop bucket add extrasscoop install extras/youtube-music

Alternately you can useWinget, Windows 11sofficial CLI package manager to install theth-ch.YouTubeMusic package.

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

winget install th-ch.YouTubeMusic

• Download the*.nsis.7z file foryour device architecture inrelease 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 thesame 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 inhttps://github.com/kerichdev/themes-for-ytmdesktop-player.

git clone https://github.com/th-ch/youtube-musiccd youtube-musicpnpm install --frozen-lockfilepnpm dev

Using plugins, you can:

• manipulate the app - theBrowserWindow from electron is passed to the plugin handler
• change the front by manipulating the HTML/CSS

Create a folder insrc/plugins/YOUR-PLUGIN-NAME:

• index.ts: the main file of the plugin

importstylefrom'./style.css?inline';// import style as inlineimport{createPlugin}from'@/utils';exportdefaultcreatePlugin({name:'Plugin Label',restartNeeded:true,// if value is true, ytmusic show restart dialogconfig:{enabled:false,},// your custom configstylesheets:[style],// your custom style,menu:async({ getConfig, setConfig})=>{// All *Config methods are wrapped Promise<T>constconfig=awaitgetConfig();return[{label:'menu',submenu:[1,2,3].map((value)=>({label:`value${value}`,type:'radio',checked:config.value===value,click(){setConfig({ value});},})),},];},backend:{start({ window, ipc}){window.maximize();// you can communicate with renderer pluginipc.handle('some-event',()=>{return'hello';});},// it fired when config changedonConfigChange(newConfig){/* ... */},// it fired when plugin disabledstop(context){/* ... */},},renderer:{asyncstart(context){console.log(awaitcontext.ipc.invoke('some-event'));},// Only renderer available hookonPlayerApiReady(api:YoutubePlayer,context:RendererContext){// set plugin config easilycontext.setConfig({myConfig:api.getVolume()});},onConfigChange(newConfig){/* ... */},stop(_context){/* ... */},},preload:{asyncstart({ getConfig}){constconfig=awaitgetConfig();},onConfigChange(newConfig){},stop(_context){},},});

• injecting custom CSS: create astyle.css file in the same folder then:

// index.tsimportstylefrom'./style.css?inline';// import style as inlineimport{createPlugin}from'@/utils';exportdefaultcreatePlugin({name:'Plugin Label',restartNeeded:true,// if value is true, ytmusic will show a restart dialogconfig:{enabled:false,},// your custom configstylesheets:[style],// your custom stylerenderer(){}// define renderer hook});

• If you want to change the HTML:

import{createPlugin}from'@/utils';exportdefaultcreatePlugin({name:'Plugin Label',restartNeeded:true,// if value is true, ytmusic will show the restart dialogconfig:{enabled:false,},// your custom configrenderer(){// Remove the login buttondocument.querySelector(".sign-in-link.ytmusic-nav-bar").remove();}// define renderer hook});

• communicating between the front and back: can be done using the ipcMain module from electron. Seeindex.ts file andexample insponsorblock plugin.

1. Clone the repo
2. Followthis guide to installpnpm
3. Runpnpm install --frozen-lockfile to install dependencies
4. Runpnpm build:OS

• pnpm dist:win - Windows
• pnpm dist:linux - Linux (amd64)
• pnpm dist:linux:deb-arm64 - Linux (arm64 for Debian)
• pnpm dist:linux:rpm-arm64 - Linux (arm64 for Fedora)
• pnpm dist:mac - macOS (amd64)
• pnpm dist:mac:arm64 - macOS (arm64)

Builds the app for macOS, Linux, and Windows,usingelectron-builder.

pnpm start

pnpmtest

UsesPlaywright to test the app.

MIT ©th-ch

IfHide Menu option is on - you can show the menu with thealt key (or` [backtick] if usingthe in-app-menu plugin)