An unofficial YouTube client for iPhone, iPad, Mac, Apple Watch and CarPlay, built with SwiftUI to feel like a first-party Apple app. One target builds iOS and macOS (native, not Catalyst); a separate Watch app handles library, search and offline audio.
- Home — For You (YouTube's charts for the categories you watch, mixed with new uploads from your most-watched channels), Subscriptions, and your real YouTube home feed with an optional youtube.com session
- Search — filters, recent searches, free suggestions; pasting a YouTube link opens it
- Playback — the official YouTube embed under native controls: chapters, captions, quality, speed, Picture in Picture, full screen, sleep timer, resume where you left off
- Library — subscriptions, playlists and likes from your Google account; favorites, Watch Later and history synced through iCloud
- Downloads — real files in a
Downloadsfolder, played offline anywhere they appear in the app - Background playback — keeps playing when the iPhone locks, with lock-screen controls
- YouTube links — a Safari extension opens videos, channels and playlists in the app on iOS and Mac
- Shortcuts, Siri, Spotlight and Handoff
- Demo mode — real videos, no account or key needed (
betteryoutube://demo) - English and French everywhere
Requires Xcode 27+, iOS 26+ / macOS 26+ / watchOS 26+.
- Copy
BetterYouTube/Config/Local.xcconfig.exampletoLocal.xcconfigand put your Team ID in it. A free Apple account works; with one, also setBY_BUNDLE_IDto a bundle ID of your own. - Open
BetterYouTube/BetterYouTube.xcodeprojand run on a simulator, a device or My Mac. - Connect YouTube, either way (or both — the key then handles public requests):
- Google sign-in (recommended): in the Google Cloud Console, enable the YouTube Data API v3 and create an OAuth client ID of type iOS with your bundle ID (it works for the Mac too). Paste the client ID in the app and sign in.
- API key: create one for public browsing without an account.
- Optional: Settings → YouTube Home signs in to youtube.com for your real home feed and Watch Later.
Avoid the weekly sign-in. While the OAuth app is in Testing, Google expires tokens after 7 days (and only accounts listed as test users can sign in). To publish it, fill the Branding page with the project's own pages — leave the logo empty — then click Publish app under Audience. No verification is needed for personal use; pass the "unverified app" screen via Advanced. On the consent screen, tick the YouTube permission, or the sign-in is refused.
| Branding field | Value |
|---|---|
| Home page | https://atomtoto.github.io/Better-YouTube/ |
| Privacy policy | https://atomtoto.github.io/Better-YouTube/privacy.html |
| Terms of service | https://atomtoto.github.io/Better-YouTube/terms.html |
| Authorized domain | atomtoto.github.io |
| Team | iCloud sync | CarPlay |
|---|---|---|
| Free (Personal Team) | no — builds expire after 7 days | no |
| Paid | yes, detected automatically | no |
| Paid, CarPlay entitlements granted by Apple | yes | BY_CARPLAY = YES in Local.xcconfig |
For iCloud, deploy the CloudKit schema to production in the CloudKit Console before shipping a TestFlight or App Store build.
Enable Better YouTube in Safari’s extension settings and allow access to youtube.com and
youtu.be (on iOS: Settings → Apps → Safari → Extensions; on Mac: Safari → Settings → Extensions).
Links that reach Safari can then open in the app, including their timestamps. Safari may ask for
confirmation; an Open in Better YouTube button remains on the page if automatic opening is
blocked. The extension menu lets you turn automatic opening off.
This cannot override YouTube’s universal links or intercept links handled by another browser or the YouTube app. For those, create a shortcut using Open YouTube Link, enable Show in Share Sheet, and share the link to it.
By default, videos are downloaded and assembled on the device with
YouTubeKit — nothing to install. You can instead point
Settings → Downloads at your own server: resolver/ is a small yt-dlp
resolver to run at home with docker compose up -d.
- The public API has no Watch Later, history, home feed or related videos. The optional youtube.com session fills that gap by reading YouTube's website — outside YouTube's terms and liable to break. Nothing runs until you sign in there.
- Quota: 10,000 units a day; a search costs 100, most reads 1. Settings shows what is left.
- Passkeys don't work for the youtube.com sign-in (no WebAuthn in
WKWebView): use a password. - Downloading videos is outside YouTube's terms too; playback itself stays on the official embed.
Before pushing directly to main, run the full checks on a Mac with Xcode:
scripts/check-all.shThis runs Safari extension tests, offline resolver tests, macOS Swift tests, then the French
localization check (which uses Xcode to extract strings). Live download tests remain opt-in.
GitHub Actions runs scripts/check-all.sh --portable on Linux for pushes and pull requests to
main, covering the extension and resolver.
scripts/build-demo-catalog.py rebuilds the demo catalogue.
Conventions, design decisions and on-device checks are in DEVELOPMENT.md.
Unofficial client; not affiliated with YouTube or Google.