QTube Music
A native macOS app for YouTube Music, built around the song that's playing: a full-screen Stage, word-synced
lyrics with translation, and Song ⇄ Video at the same moment. It's music only. No Shorts, no podcasts, no
comments, no feeds.
QTube Music is an unofficial client. It isn't made, endorsed or supported by Google or YouTube. You need a
YouTube Music account to see your library. You can browse and play without one, with ads, the same as on the web.
Why QTube Music?
The inspiration is NetEase Cloud Music. Its player is the best I've used: lyrics that light up word by word with
a translation under each line, a full-screen player with a spinning record, and lyrics on the desktop. I wanted that
for YouTube Music, and none of the YouTube Music apps on the Mac comes close. Here's what each one is missing
(tried hands-on and read through their code in October 2026):
- The YouTube Music website. There's no Mac app at all. The library loads as you scroll, so you can't sort it or
jump to a letter, and the queue is hard to find. Lyrics are never word by word, and there's no translation.
- Electron wrappers such as th-ch's YouTube Music. They put the website in a window and run a whole copy of
Chrome underneath it. You get the website's interface, and every gap the website has.
- Kaset. No full-screen player. The music video button is greyed out for most songs, and there's no way to switch
between a song and its video. Tracks sometimes stop instead of moving on (issues #280, #409), it can show up twice
in Now Playing (#457), and a single click plays a song instead of selecting it (#446).
- YTubic. Premium accounts only. Its Song/Video switch only swaps the audio; you never see a video. Lyrics go line
by line, with no translation. Every track starts a separate yt-dlp process, so there's no gapless playback, and it
breaks when YouTube changes something.
- JustAnotherMusicClient. No full-screen player and no music videos. It plays through a hidden YouTube player, so
some songs just fail with an error. On my Mac it used about 100% CPU and 800 MB of memory while paused. The window
buttons sit on the right, Windows-style, and ⌘Space for search clashes with Spotlight.
QTube Music has all of it: a full-screen player with five backgrounds, lyrics that light up word by word with a
translation under each line, real music videos you can switch to without losing your place, desktop lyrics and a
mini player. It's built in SwiftUI and AppKit, idles under 1% CPU and uses about 4–5% while playing
(measurements), and works with free accounts.
What it does
- A real Mac app. SwiftUI and AppKit, with system controls, menus, shortcuts, Liquid Glass on macOS 26, light
and dark modes, and English and Simplified Chinese.
- The Stage. A full-screen now-playing view with three layouts and five backgrounds: blurred cover, cover,
vinyl, the music video, and an audio-reactive visualizer.
- Lyrics that keep up. Word-by-word karaoke where the source has it. You can scroll back and jump to the
current line, and set the timing offset. Sources are YouTube Music, LRCLIB and the AMLL TTML DB; NetEase, Kugou
and QQ Music are opt-in. Wrong lyrics? Pick another version in Lyrics Source, report it, or turn lyrics off for
that song; the app remembers.
- Translation on your Mac. The Translation framework, or Apple Intelligence on macOS 26. Chinese lyrics show in
Simplified or Traditional characters, whichever you pick.
- Song ⇄ Video. Switch between the song and its music video without losing your place. Picture in Picture
works too.
- Playback speed. 0.5× to 2× with the pitch kept (Controls › Playback Speed, ⌥⌘. and ⌥⌘,). Lyrics, Now
Playing and scrobbles follow the speed; ads still play at 1×.
- Your library. Home, Explore, Liked songs, playlists and history, in sortable, filterable tables, plus a
docked Now Playing and Queue panel. Likes, playlists (new, renamed, reordered, songs added or removed),
subscriptions and saved albums sync with your YouTube Music account, brand accounts included. Music you uploaded
to YouTube Music has its own Uploads page (songs, albums, artists).
- The rest of the Mac. Media keys, Control Center, AirPlay, a mini player, a menu bar player, desktop lyrics,
Shortcuts and AppleScript. Optional global shortcuts (Settings › Shortcuts) play, skip, like and show the players
from any app, with no Accessibility permission.
- Song colours. The app takes its accent colour from the cover art. You can switch back to the system accent
in Settings.
- Scrobbling. Last.fm and ListenBrainz (or a ListenBrainz-compatible server such as Maloja): paste your
ListenBrainz token and click Connect. Plays wait offline and go out later. Both are off until you turn them on.
Install
You need macOS 15 Sequoia or later, on Apple silicon or Intel (the app is universal; it's tested on Apple
silicon).
-
Download QTube-Music-<version>.dmg from Releases.
-
Open it and drag QTube Music to Applications.
-
The app isn't notarized yet: I don't have an Apple Developer ID. The first time you open it, macOS says it
can't check it. Click Done, go to System Settings › Privacy & Security, scroll down and click
Open Anyway. Or, in Terminal:
xattr -dr com.apple.quarantine "/Applications/QTube Music.app"
From 0.4.0 the app updates itself: it checks once a day and shows what's new (QTube Music › Check for
Updates… checks now; Settings › General › Updates can install updates in the background). Updates are verified
with the release's signing key. Coming from 0.3.0 or earlier, download 0.4.0 once by hand; macOS then asks one last
time for the old Keychain item, so your sign-in can move to its new place.
Sign-in and privacy
- Signing in happens in a Google sign-in window inside the app: a private page, deleted afterwards, with the
address and a lock above it (click the lock for Google's certificate; a page that isn't Google's gets a warning).
QTube Music keeps only Google's sign-in cookies, in a private file on this Mac
(
~/Library/Application Support/com.roderickqiu.qtube/Private/), which only your user account can open and Time
Machine skips. It never sees or stores your password, and never writes the cookies anywhere else. This is how
Firefox keeps cookies, and it has the same limit: other programs you run could read that file without asking. The
Keychain would make them ask, but without a paid Apple Developer ID it also asks for your Mac password after every
update.
- Passkeys and security keys only work in apps Apple approves as web browsers, so the sign-in window hides them
and Google offers your password with a phone prompt, a code or "Try another way" instead. If your account has only
passkeys or uses Advanced Protection, use Settings › Account › Import Session: sign in to YouTube Music in
Firefox (in a profile you won't use for YouTube afterwards) or export a
cookies.txt from a private window and close
it, then import. Only the Google sign-in cookies are taken. Chrome and Safari can't be imported.
- Signing out deletes that file's session and also ends it at Google, so it leaves your account's
device list. Settings › Account links to that list (Your Devices…).
- What goes where. Browsing and playback talk to YouTube Music, as the web player does, so your plays show up in
your YouTube Music history. Searches are always sent signed out, so they don't land in your search history.
Lyrics come from LRCLIB, the AMLL TTML DB on GitHub, YouTube Music, and NetEase, Kugou and QQ Music only if you
turn on Unofficial sources. Last.fm and ListenBrainz scrobbling and Discord status are off until you turn them on
with your own keys or token.
- Likes and playlists sync. Signed in, likes, playlist changes (new, renamed, reordered, deleted playlists,
songs added or removed), subscriptions and albums you add to your library change your YouTube Music account, one
change at a time. Turn off Settings › Account › Sync likes and playlists to YouTube Music to keep them on this
Mac only. Brand accounts (channels) can be switched in Settings › Account or the Account menu.
- No analytics. No tracking, no telemetry, no crash reporting service. Translation runs on your Mac.
- Update checks. Once a day the app downloads a small update feed from this repository's GitHub Releases. It
sends no system profile, and Settings › General › Updates turns the checks off.
The native engine (experimental)
By default every account plays through YouTube's own web player, inside the app. With YouTube Music Premium
you can turn on Settings › Playback › Native engine (Experimental). It plays the audio with Apple's audio
engine, which gives you gapless playback, crossfade and a 10-band equalizer.
Please read this first:
- It fetches the audio streams directly. That isn't how YouTube's Terms of Service want their service used. You
use it at your own risk.
- It depends on how YouTube serves streams today, and YouTube changes that often. When something breaks, the app
quietly falls back to the web player until a fix ships.
- Plays through the native engine don't appear in your YouTube Music history.
- Music videos always play through the web player.
Feedback
Something wrong? Help › Report a Problem… opens a prefilled GitHub issue in your browser with what you write
and, if you leave it on, the app's diagnostics: versions, playback state, settings and this session's log, with
cookies, keys, email addresses, account names and your Mac's user name taken out. Show Diagnostics shows the
exact text first, and nothing is sent until you submit the issue yourself.
Build from source
You need Xcode 27 (Swift 6.4). The app it builds runs on macOS 15 or later.
git clone https://github.com/RoderickQiu/qtube-music.git
cd qtube-music
QT_CONFIG=release Scripts/build-app.sh # → .build/apps/QTube Music.app
swift test --disable-xctest
Always run the bundled app that build-app.sh makes, not swift run. The bundle carries the resources and the
macOS 26 look. Architecture, dev tools and launch arguments are covered in
docs/development.md and docs/architecture.md.
Licence
Made by Tianrun Qiu. QTube Music is licensed under the Mozilla Public License 2.0. It uses Sparkle, SwiftyOpenCC, OpenCC
and yt-dlp's EJS solver; their licences are in THIRD_PARTY_NOTICES.md. YouTube and
YouTube Music are trademarks of Google LLC. Song titles, artwork and lyrics belong to their owners.
