https://github.com/ytmd-devs/ytmd
YouTube Music Desktop App bundled with custom plugins
https://github.com/ytmd-devs/ytmd
adblocker desktop-app electron linux mac macosx music music-player music-player-application node windows youtube youtube-music youtube-music-player youtube-player youtube-playlist
Last synced: 13 days ago
JSON representation
YouTube Music Desktop App bundled with custom plugins
- Host: GitHub
- URL: https://github.com/ytmd-devs/ytmd
- Owner: ytmd-devs
- License: mit
- Created: 2019-04-19T18:14:40.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-09-21T08:02:12.000Z (14 days ago)
- Last Synced: 2025-09-21T10:05:15.464Z (14 days ago)
- Topics: adblocker, desktop-app, electron, linux, mac, macosx, music, music-player, music-player-application, node, windows, youtube, youtube-music, youtube-music-player, youtube-player, youtube-playlist
- Language: TypeScript
- Homepage:
- Size: 18.7 MB
- Stars: 28,117
- Watchers: 148
- Forks: 1,578
- Open Issues: 491
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: license
Awesome Lists containing this project
- awesome - ytmd-devs/ytmd - YouTube Music Desktop App bundled with custom plugins (TypeScript)
- awesome-mac - ytmd-devs/ytmd
- awesome - ytmd-devs/ytmd - YouTube Music Desktop App bundled with custom plugins (TypeScript)
- awesome - ytmd-devs/ytmd - YouTube Music Desktop App bundled with custom plugins (TypeScript)
README
# YTMD
[](https://github.com/th-ch/youtube-music/releases/)
[](https://github.com/th-ch/youtube-music/blob/master/license)
[](https://github.com/th-ch/youtube-music/blob/master/eslint.config.mjs)
[](https://GitHub.com/th-ch/youtube-music/releases/)
[](https://GitHub.com/th-ch/youtube-music/releases/)
[](https://aur.archlinux.org/packages/youtube-music-bin)
[](https://snyk.io/test/github/th-ch/youtube-music)
- Native look & feel extension, aims at keeping the original interface
one click
## Content
- [Features](#features)
- [Translation](#translation)
- [Download](#download)
- [Arch Linux](#arch-linux)
- [MacOS](#macos)
- [Windows](#windows)
- [How to install without a network connection? (in Windows)](#how-to-install-without-a-network-connection-in-windows)
- [Themes](#themes)
- [Dev](#dev)
- [Build your own plugins](#build-your-own-plugins)
- [Creating a plugin](#creating-a-plugin)
- [Common use cases](#common-use-cases)
- [Build](#build)
- [Production Preview](#production-preview)
- [Tests](#tests)
- [License](#license)
- [FAQ](#faq)
## Translation
You can help with translation on [Hosted Weblate](https://hosted.weblate.org/projects/youtube-music/).
## Download
You can check out the [latest release](https://github.com/th-ch/youtube-music/releases/latest) to quickly find the
latest version.
### Arch Linux
Install the [`youtube-music-bin`](https://aur.archlinux.org/packages/youtube-music-bin) package from the AUR. For AUR installation instructions, take a look at
this [wiki page](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages).
### macOS
You can install the app using Homebrew (see the [cask definition](https://github.com/th-ch/homebrew-youtube-music)):
```bash
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:
```bash
/usr/bin/xattr -cr /Applications/YouTube\ Music.app
```
### Windows
You can use the [Scoop package manager](https://scoop.sh) to install the `youtube-music` package from
the [`extras` bucket](https://github.com/ScoopInstaller/Extras).
```bash
scoop bucket add extras
scoop install extras/youtube-music
```
Alternately you can use [Winget](https://learn.microsoft.com/en-us/windows/package-manager/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).*
```bash
winget install th-ch.YouTubeMusic
```
#### How to install without a network connection? (in Windows)
- Download the `*.nsis.7z` file for _your device architecture_ in [release page](https://github.com/th-ch/youtube-music/releases/latest).
- `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.
## Themes
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.
## Dev
```bash
git clone https://github.com/th-ch/youtube-music
cd youtube-music
pnpm install --frozen-lockfile
pnpm dev
```
## Build your own plugins
Using plugins, you can:
- manipulate the app - the `BrowserWindow` from electron is passed to the plugin handler
- change the front by manipulating the HTML/CSS
### Creating a plugin
Create a folder in `src/plugins/YOUR-PLUGIN-NAME`:
- `index.ts`: the main file of the plugin
```typescript
import style from './style.css?inline'; // import style as inline
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, ytmusic show restart dialog
config: {
enabled: false,
}, // your custom config
stylesheets: [style], // your custom style,
menu: async ({ getConfig, setConfig }) => {
// All *Config methods are wrapped Promise
const config = await getConfig();
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 plugin
ipc.handle('some-event', () => {
return 'hello';
});
},
// it fired when config changed
onConfigChange(newConfig) { /* ... */ },
// it fired when plugin disabled
stop(context) { /* ... */ },
},
renderer: {
async start(context) {
console.log(await context.ipc.invoke('some-event'));
},
// Only renderer available hook
onPlayerApiReady(api: YoutubePlayer, context: RendererContext) {
// set plugin config easily
context.setConfig({ myConfig: api.getVolume() });
},
onConfigChange(newConfig) { /* ... */ },
stop(_context) { /* ... */ },
},
preload: {
async start({ getConfig }) {
const config = await getConfig();
},
onConfigChange(newConfig) {},
stop(_context) {},
},
});
```
### Common use cases
- injecting custom CSS: create a `style.css` file in the same folder then:
```typescript
// index.ts
import style from './style.css?inline'; // import style as inline
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, ytmusic will show a restart dialog
config: {
enabled: false,
}, // your custom config
stylesheets: [style], // your custom style
renderer() {} // define renderer hook
});
```
- If you want to change the HTML:
```typescript
import { createPlugin } from '@/utils';
export default createPlugin({
name: 'Plugin Label',
restartNeeded: true, // if value is true, ytmusic will show the restart dialog
config: {
enabled: false,
}, // your custom config
renderer() {
console.log('hello from renderer');
} // define renderer hook
});
```
- communicating between the front and back: can be done using the ipcMain module from electron. See `index.ts` file and
example in `sponsorblock` plugin.
## Build
1. Clone the repo
2. Follow [this guide](https://pnpm.io/installation) to install `pnpm`
3. Run `pnpm install --frozen-lockfile` to install dependencies
4. Run `pnpm 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,
using [electron-builder](https://github.com/electron-userland/electron-builder).
## Production Preview
```bash
pnpm start
```
## Tests
```bash
pnpm test
```
Uses [Playwright](https://playwright.dev/) to test the app.
## License
MIT © [th-ch](https://github.com/th-ch/youtube-music)
## FAQ
### Why apps menu isn't showing up?
If `Hide Menu` option is on - you can show the menu with the alt key (or \` [backtick] if using
the in-app-menu plugin)