Skip to content

About

A SwiftUI YouTube iOS client

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

228 Commits

Folders and files

Repository files navigation

Better-YouTube

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.

Features

  • 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 Downloads folder, 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

Getting started

Requires Xcode 27+, iOS 26+ / macOS 26+ / watchOS 26+.

  1. Copy BetterYouTube/Config/Local.xcconfig.example to Local.xcconfig and put your Team ID in it. A free Apple account works; with one, also set BY_BUNDLE_ID to a bundle ID of your own.
  2. Open BetterYouTube/BetterYouTube.xcodeproj and run on a simulator, a device or My Mac.
  3. Connect YouTube, either way (or both — the key then handles public requests):
  4. 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

What your Apple account unlocks

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.

Open YouTube links in the app

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.

Downloads

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.

Limits

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

Development

Before pushing directly to main, run the full checks on a Mac with Xcode:

scripts/check-all.sh

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

About

A SwiftUI YouTube iOS client

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages