YTubic

本页保存的是公开项目资料快照，阅读过程不需要连接 GitHub。

YTubic

A fast, responsive YouTube Music desktop client for Windows, Linux, and macOS.

Built as a reaction to the sluggish webview-wrapper experience — YTubic talks to YouTube’s InnerTube API directly, renders its own UI, and caches aggressively, so navigation and playback feel instant.

图片：YTubic — artist page with the player and synced lyrics

Features

• Fast and responsive UI — instant navigation with prefetch and aggressive caching; no page reloads, no spinners on every click
• Flexible player layouts — dock the player at the bottom or as a right-side panel
• Floating player widget — pop the player out into a compact always-on-top window
• Synced lyrics — line-by-line synced lyrics from multiple providers (LRCLIB, Musixmatch, Genius)
• Hi-res cover art — upgrades album covers to high-resolution studio art when available
• Full library support — your playlists, likes, albums and artists; search with filters; radio/autoplay queues
• Desktop integration — media keys and system media controls, tray/menu-bar icon, single instance
• Auto-updates — the app updates itself from GitHub Releases, and keeps its yt-dlp copy fresh automatically

Disclaimer: YTubic is an unofficial client. It is not affiliated with, endorsed by, or sponsored by Google or YouTube. “YouTube” and “YouTube Music” are trademarks of Google LLC. The app streams audio through yt-dlp and may stop working at any time if YouTube changes its internals. Use at your own risk.

Install

Download the latest installer from the Releases page and run it.

• Windows 10/11: run the .exe NSIS installer. Pick the x64 build, or the arm64 one on a Windows on ARM device.
• macOS 10.15+ (beta): open the universal .dmg; the same build supports Apple Silicon and Intel. Login cookies are encrypted with a Keychain-backed key.
• Linux (beta): install the .deb or .rpm, or run the .AppImage. Playback requires WebKitGTK 4.1, GTK 3 and the GStreamer base, good and libav plugins. Signing in also requires a desktop Secret Service provider such as GNOME Keyring or a compatible KWallet setup.
• On first launch the app downloads its own copy of yt-dlp (~12 MB) into its data folder and keeps it updated automatically.
• Signing in is optional: browse and playback work anonymously; sign in to get your library, likes, and playlists.

Linux and macOS builds are in beta. They are compiled and unit-tested in CI, but get far less real-world testing than the Windows build. If something breaks, please open an issue — or use the in-app reporter (⋯ menu → Report an issue), which attaches your app version and OS automatically.

FAQ

Windows says “Windows protected your PC” (SmartScreen). The installer is not code-signed (certificates are expensive for a free open-source project). Click “More info” → “Run anyway”. The source code is public — you can audit it or build it yourself.

macOS says YTubic can’t be opened or is from an unidentified developer. Release builds are ad-hoc signed until Developer ID credentials are configured, so they are not notarized. Open System Settings → Privacy & Security and choose Open Anyway, or right-click YTubic in Applications and choose Open. As a last resort, clear the downloaded quarantine attribute:

xattr -cr /Applications/YTubic.app

My antivirus flags the app / yt-dlp. yt-dlp is a widely-used open-source downloader that some AV vendors false-positive on. The binary is downloaded directly from yt-dlp’s official GitHub releases.

Will Google ban my account for using this? Browsing/search/library requests look identical to the official web app, and audio streaming is fully anonymous (never tied to your account). There are no known cases of accounts being banned for third-party players — but no guarantees; see the disclaimer above.

Playback suddenly stopped working. YouTube periodically changes its streaming internals. yt-dlp usually ships a fix within days, and the app picks it up automatically (it self-updates its yt-dlp copy every ~3 days). Restarting the app forces the check.

Stack

• Shell: Tauri 2 (Rust backend, system webview — WebView2 on Windows, WebKitGTK on Linux, WKWebView on macOS)
• Frontend: React 19 + TypeScript
• Build: Vite 7
• Styling: Tailwind CSS v4
• Components: shadcn/ui (new-york style, neutral base, YouTube red accent)
• Routing: TanStack Router (file-based, type-safe, prefetch on intent)
• Data: TanStack Query
• Client state: Zustand
• Icons: lucide-react

Dev

pnpm install
pnpm tauri dev

Frontend-only dev (no Tauri window): pnpm dev.

Quality checks

pnpm test         # vitest unit tests (pure parsers/matchers)
pnpm lint         # eslint
pnpm format       # prettier --write
pnpm build        # tsc + vite production build

CI (.github/workflows/ci.yml) runs typecheck, lint, tests, build and Rust tests on Windows, Linux, and macOS for every push / PR.

Project layout

src/
├── routes/              # TanStack Router file-based routes
├── components/
│   ├── ui/              # shadcn primitives
│   ├── layout/          # AppShell, sidebar, topbar, player bar, floating player, lyrics
│   └── shared/          # Track list/rows, cards, shelves, context menus
├── lib/
│   ├── innertube/        # Raw InnerTube client + parsers
│   ├── lyrics/          # LRCLIB / Musixmatch / Genius sources + LRC parser
│   ├── store/           # Zustand stores
│   ├── audio-engine.ts  # Playback engine
│   ├── stream.ts        # Stream URL resolver (localhost proxy)
│   └── utils.ts         # cn() and friends
└── hooks/
src-tauri/               # Rust backend (axum stream proxy, cookies, tray)

Credits

• yt-dlp — audio streaming
• LRCLIB — synced lyrics
• Musixmatch and Genius — lyrics sources
• Tauri, shadcn/ui, TanStack, and the rest of the stack above

License

GPL-3.0 — free to use, modify, and redistribute; derivative works must stay open source under the same license.