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).

1. Download QTube-Music-<version>.dmg from Releases.

2. Open it and drag QTube Music to Applications.

3. 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.