mixmusic README

The project's README from github.com/fzn0x/mixmusic. As one markdown file: README.md.

English · हिन्दी · 简体中文 · Bahasa Indonesia · اردو · Hausa · Português (Brasil) · বাংলা · Русский · አማርኛ

MixMusic's icon: two pink rings and a play button on black

MixMusic

One player for YouTube Music and Spotify.

YouTube Music and Spotify client for macOS, Windows and Linux. YouTube Music works with no account. One search, one queue, mixed playlists, synced lyrics, themes and plugins.

CI Website Latest release Downloads Go Reference Go version Listed on Awesome MyGo macOS, Windows and Linux MIT or GPL-3.0

Website · Download · Docs · Changelog

MixMusic 0.5.9 in its default look, the Blend layout with the Mix theme, standing upright on a dark stage and facing you: now playing アイドル by YOASOBI in the middle, outlined in pink, with romaji under each line of its lyrics and the mini player in front of it; a search on the left and the library's mixes on the right

Why MixMusic

If your music is split between YouTube Music and Spotify, you usually need two apps, with two searches, two queues and two libraries. MixMusic puts both services in one player:

Features

Search and play

Your library

Spotify, three ways

Sound

On your desktop

Make it yours

A look around

MixMusic's pages in the Blend layout, standing upright on a dark stage and facing you: now playing アイドル by YOASOBI in the middle, outlined in pink, each line of its lyrics with romaji and an English translation under it; the album THE BOOK 3 on the left and a followed podcast's page on the right

Listen. In the middle, now playing アイドル by YOASOBI: each line lights up as it's sung, with romaji and a translation under it. On the left, an album; on the right, a podcast you follow.

More of MixMusic, standing upright on a dark stage and facing you: Settings › Appearance with the four layouts in the middle, outlined in pink; a Material theme coloured by the cover that plays on the left, and the marketplace's community themes on the right

Make it yours. In the middle, the four layouts: Blend, the default, Expressive, Crate and Tiles, under the themes. On the left, a Material theme that takes its colours from the cover that plays. On the right, community themes in the marketplace.

Install

Download the file for your system from the latest release:

System Download
macOS 12 and later (Apple silicon and Intel) mixmusic-<version>-macos-universal.dmg
Windows 10 and 11 (x64, Arm), installer mixmusic-<version>-windows-<arch>-setup.exe
Windows, portable, no installation mixmusic-<version>-windows-<arch>-portable.zip
Debian, Ubuntu and derivatives mixmusic-<version>-linux-<arch>.deb
Fedora, openSUSE and derivatives mixmusic-<version>-linux-<arch>.rpm
Arch Linux and derivatives (coming soon) mixmusic-bin on the AUR: yay -S mixmusic-bin
Any Linux, one file mixmusic-<version>-linux-<arch>.AppImage
Any Linux, sandboxed (Flatpak) mixmusic-<version>-linux-<arch>.flatpak
Any Linux, in your home folder mixmusic-<version>-linux-<arch>.tar.gz, with install.sh

<arch> is amd64 for x64 and arm64 for Arm. Each release lists SHA256SUMS to check the downloads with. You don't need the files named update-…, ….delta, mixmusic-<version>-macos-… or -windows-<arch>.tar.gz: installed apps update from them.

The installers, the portable zip and the Linux archive update themselves. The .deb, the .rpm, the AppImage and the Flatpak can't replace their own files, so MixMusic tells you when a new version is out and downloads it for you. The AUR's mixmusic-bin updates with the rest of your system. For the portable zip, unpack it anywhere and open MixMusic.exe. For the AppImage, make it executable (chmod +x) and open it. For the Flatpak, open it with your software center, or run flatpak install ./mixmusic-<version>-linux-<arch>.flatpak; the first time, Flatpak fetches the GNOME runtime from Flathub.

On a Mac, Homebrew installs MixMusic too, and brew upgrade updates it:

brew install --cask fzn0x/tap/mixmusic

The first launch

The Flatpak

The Flatpak runs MixMusic in a sandbox, which sees the network, the sound server, the display and the GPU, and none of your home folder. MixMusic keeps its settings and library in ~/.var/app/io.github.fzn0x.mixmusic, apart from a .deb, .rpm, AppImage or archive copy, and both can run at once. To bring a copy's settings and library over, quit both, then copy settings.json, library.json, queue.json, positions.json and the addons and mix-covers folders from ~/.config/MixMusic into ~/.var/app/io.github.fzn0x.mixmusic/config/MixMusic. Quit both first: a running MixMusic keeps library.json and most other files in memory and writes over a copied one at its next save. Then sign in to your accounts again: sign-ins stay in the other copy's keyring. The data and privacy page says what each file holds.

In the Flatpak, start at login goes through your desktop, which may ask you first, and a yt-dlp of your own must be in ~/.var/app/io.github.fzn0x.mixmusic, as the sandbox sees no other folder. A Discord app that isn't a Flatpak shows what plays only if it was running when MixMusic started, until it restarts; Discord as a Flatpak works either way. The Flatpak is new: tell us in an issue how it runs on your desktop.

Accounts (all optional)

Something not working? docs/troubleshooting.md covers the common problems and the known issues.

Build from source

You need Go 1.27.3 or later, Bun 1.2 or later, which runs MyGo's command line, and Git. MyGo needs no C compiler, so any system builds MixMusic for every system.

Windows

winget install GoLang.Go
winget install Oven-sh.Bun
winget install Git.Git

Open a new terminal, then:

git clone https://github.com/fzn0x/mixmusic
cd mixmusic
bun install
bun run dev

Signing in and Spotify playback need the WebView2 Runtime, which Windows 11 includes. On Windows 10, install it from Microsoft.

macOS

With Homebrew:

brew install go oven-sh/bun/bun
git clone https://github.com/fzn0x/mixmusic
cd mixmusic
bun install
bun run dev

Linux

Install Go from go.dev/dl (distribution packages are often older than 1.27.3), then Bun and the libraries MixMusic runs with:

curl -fsSL https://bun.sh/install | bash
# Debian and Ubuntu
sudo apt install git libgtk-3-0 libpulse0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 libsecret-1-0
# Fedora
sudo dnf install git gtk3 pulseaudio-libs webkit2gtk4.1 libayatana-appindicator-gtk3 libsecret

Then:

git clone https://github.com/fzn0x/mixmusic
cd mixmusic
bun install
bun run dev

Nix

With Nix, nix develop gives you the tools releases are built with, at the versions flake.lock pins: Go, Bun, NSIS, GoReleaser and Zola. nix build builds MixMusic for Linux from source, into result/.

Develop

bun run dev builds the app, starts it, and rebuilds it as you edit. Its data stays apart from an installed MixMusic, under the name MixMusic Dev.

bun run build:plugins          # the plugins' JavaScript, from their TypeScript
go test ./...                  # the app's tests
bun run typecheck              # the plugin SDK and the community's plugins
go run ./tools/registry -check # the community registry
bun run build                  # the packaged app for this system, in build/
bun run build -- -platform windows/amd64,linux/amd64,linux/arm64

In the Nix shell, build Linux downloads with .github/scripts/build.sh linux/amd64,linux/arm64, as releases do. A plain bun run build there makes a Linux program that asks for Nix's own loader, and it starts only on NixOS. go run ./tools/elfloader build/linux-amd64 checks a build.

The website is in site/, built with Zola, and the guides in docs/ are its /docs/ pages. go run ./tools/sitedocs && zola --root site serve previews it. Releases are built in the Nix shell and published by GoReleaser (.goreleaser.yaml).

docs/architecture explains how the parts fit together.

Layout

The app is the root package, with the packages of internal/ under it. The packages outside internal/ are for anyone to import, and documented on pkg.go.dev.

*.go                 the app and its windows: the pages, the player bar, the
                     mini player, the tray, media keys, deep links
fonts/               the typefaces the windows draw with
internal/app         the services the windows call, and the desktop integration
internal/player      the queue, played by the audio engine or on Spotify's devices
internal/audio       MixMusic's audio engine, and the system's audio output
internal/plugins     plugins, each in a JavaScript engine of its own
internal/youtube     YouTube Music's catalog, and your account there
internal/spotify     the Spotify Web API, its sign-in and Spotify Connect
internal/stream      audio streams, from YouTube or yt-dlp, opened for the engine
internal/match       Spotify tracks matched to their YouTube Music recordings
internal/romaji      Japanese lyrics in romaji, kanji read by kagome
internal/library     liked and disliked songs, mixes, history and stats
internal/lastfm      scrobbling to Last.fm
internal/discord     what plays, on your Discord profile
internal/diag        the log, without secrets, and the reports of crashes
internal/addons      themes and plugins, and the community registry
builtin/themes       the themes MixMusic ships with
public/              the page of Spotify's player, on Windows
sdk/                 the types of the plugin API
community/           community themes and plugins, and their registry

The packages you can import:

opus/                an Opus decoder in pure Go, a port of libopus's
aac/                 an AAC-LC decoder in pure Go
ac3/                 an AC-3 and E-AC-3 decoder in pure Go, written from ATSC A/52
webm/                the audio of WebM files: packets, times and seeking
mp4/                 the audio of MP4 files: packets, times and seeking
resample/            sample rate conversion, with Kaiser-windowed sincs
lyrics/              synced lyrics from Better Lyrics, Unison and LRCLIB, and translations
brand/               MixMusic's logo, for code that draws it

Community

Anyone can install community themes and plugins from the marketplace, the store icon in the sidebar, and you can add yours.

Make a theme

A theme is a theme.json file that sets colors, fonts and corners, which show in the layout the user chose. docs/themes.md lists every token and shows a complete theme. To try yours, put its folder in the themes folder (Settings › Appearance › open themes folder) and choose it in Settings › Appearance.

Make a plugin

A plugin is a small module, written in TypeScript or JavaScript, that adds pages, commands, track actions and widgets. docs/plugins.md documents the API, with its types for your editor. The community's sleep timer and spectrum are working examples.

Share it

  1. Fork this repository.
  2. Add one folder: community/themes/<id>/ for a theme, or community/plugins/<id>/ for a plugin, with its plugin.json and its index.ts.
  3. Run bun run build:plugins, go run ./tools/registry and go run ./tools/registry -check.
  4. Open a pull request.

Once it is merged, CI publishes it to the registry branch, and it shows up in everyone's marketplace. community/README.md has the details.

Privacy

MixMusic has no account, server, analytics or telemetry of its own. It talks to:

What it keeps on your computer:

The library's history page clears what you played, Settings › Playback clears the cache and the covers, and signing out of a service deletes its sign-in.

On Windows, the visualizer hears the audio of Spotify playing on this computer, in MixMusic or in the Spotify app, through Windows' process loopback, which hears only that app. On macOS 14.2 and later, it hears Spotify playing in MixMusic through a process tap, once you allow it, as macOS asks. It analyzes the audio in memory and never records or sends it.

Credits

MixMusic is built on these projects:

Contributing

Fixes, features, themes, plugins and bug reports are all welcome.

CONTRIBUTORS.md thanks the people whose code, ideas and reports shaped MixMusic.

License

MixMusic is dual-licensed: use it under the MIT license or the GNU General Public License, version 3, whichever you prefer. Contributions are accepted under both. The typefaces in fonts are under the SIL Open Font License: Selawik's, Quicksand's, Roboto Flex's and Archivo's. The Opus decoder is a port of libopus, under its BSD license, the AAC decoder derives from SharpJaad, under its MIT license, and the HCT color science is a port of Material Color Utilities, under its Apache license.

MixMusic is not affiliated with, endorsed by or sponsored by Spotify or Google. It plays what these services offer their users, through the services' own interfaces; use it as their terms allow. Spotify and YouTube Music are trademarks of their owners.

mixmusic (fzn0x/mixmusic)

Searching Database…

What is this?MixMusic is a native desktop player that plays YouTube Music and Spotify in one app, with one search, one queue and one library, on macOS, Windows and Linux.
Is it a web app or a native program?It is a native program written in Go that draws its own windows on the GPU, with no browser inside, so it stays small.
Do I need an account or extra software?No: YouTube Music works with no account, and Spotify sign-in is optional. Linux needs GTK 3 plus PulseAudio or ALSA, and Windows 10 needs the WebView2 Runtime, which Windows 11 already includes.
Does Spotify playback work for every account?Playing Spotify inside MixMusic needs Spotify Premium and works only on Windows and macOS. Without Premium, Spotify tracks can still play through their YouTube Music recording.
Does it send my data to a server of its own?No: MixMusic has no account, server, analytics or telemetry of its own. Sign-ins are kept encrypted, and Last.fm and Discord are optional integrations.
Can I customize how it looks?Yes: four layouts (Blend, Expressive, Crate, Tiles), fourteen built-in themes, community themes from a marketplace, and an accent color taken from the playing cover.
Can I change keyboard shortcuts and add plugins?Yes: any command can get your own key, a command palette opens with Ctrl K, and plugins can add pages, commands, track actions and widgets through a typed API.
Why put YouTube Music and Spotify in one app?If your music is split between both, one search, one queue and mixed playlists save you from juggling two apps with separate searches and libraries.
Does it keep running in the background?It offers tray controls, track notifications, start at login, and global shortcuts that work whichever window is in front, plus media keys on all three systems.
Creator
fzn0x
Size
66.3 MB
Stars
463
Age
1mo
Commits · 90 Days