Twizz

A free, open-source Apple TV app for watching Twitch with a fast, chat-first viewing experience and native external emote support.

Features

Sign in & navigation:

• Sign in with Twitch using the Device Code flow (approve on your phone or browser); tokens are stored securely and refresh automatically.
• Four tabs: Home, Browse, Search, and Settings.

Home & discovery:

• Home shows the channels you follow that are live now, plus recommendations.
• Optional personalized recommendations built from on-device watch history and your followed categories — or anonymous trending when you're signed out or have it turned off.
• Browse top categories and the live streams within them.
• Search channels and categories with live results.
• Channel pages with top clips, past broadcasts (VODs), and similar channels.
• Apple TV Top Shelf surfaces your live follows and recommendations on the tvOS home screen.

Playback:

• Live playback on real Apple TV hardware, with a side-by-side layout: video on the left, chat pane on the right.
• Quality picker with persistence (Auto + explicit qualities), ordered highest-to-lowest.
• Low-latency mode (on by default) that closes most of the gap to the live edge.
• Stream rewind (DVR): seek back within the live window.
• Audio-only mode with a reactive audio visualizer — handy for music, just-chatting, or background listening.
• Custom bottom overlay controls built for the tvOS focus engine.
• Sleep timer tucked inside the quality menu (timed or "end of stream") with a "still watching?" check, an animated starry "Sleeping" screen, and one-press resume that snaps back to the live edge.
• VOD and clip playback from channel pages; VODs include synced chat replay and variable speed (0.5×–2×).
• Optional diagnostics overlay for latency and buffer stats.

Chat:

• Anonymous read via Twitch IRC over WebSocket, with auto-reconnect.
• Send messages when signed in.
• Twitch badges (global + channel-specific) and cheermotes (bits).
• Emotes: Twitch native (incl. channel/sub), 7TV, BTTV, and FFZ (global + channel), including animated emotes.
• Extensive chat appearance controls: text and emote size, font (including OpenDyslexic), spacing, width, and layout (side / overlay / glass).
• Incoming and outgoing raid banners.
• Live polls, predictions, hype trains, and creator goals surfaced as passive, display-only overlays.
• "Just went live" toast for followed channels, with one tap to switch over.
• Experimental: merge a YouTube live chat into the Twitch chat pane.

Appearance:

• Themes: System, Dark, OLED, and Light.
• Adjustable stream-card sizes and a stream-language filter.

Tech Stack

• Swift / SwiftUI targeting tvOS.
• AVPlayer-backed playback with custom overlay controls and an in-process low-latency HLS proxy.
• Twitch EventSub / Hermes for real-time raids, polls, predictions, and live events.
• A Top Shelf app extension for the tvOS home screen.
• XcodeGen project generation (project.yml is source of truth).

Build & Run

Prerequisites:

• macOS with Xcode installed.
• Homebrew tools:

brew install xcodegen xcbeautify xcode-build-server

Generate the project:

xcodegen generate

Build:

xcodebuild \
	-project Twizz.xcodeproj \
	-scheme Twizz \
	-configuration Debug \
	-destination 'generic/platform=tvOS Simulator' \
	build | xcbeautify

For real Apple TV deployment, use a valid signing team and a device destination.

Twitch Auth Setup (No Committed Secrets)

Twitch device auth still needs a Twitch app client_id, but you do not need to commit it to this repo.

1. Copy Config/TwitchSecrets.xcconfig.local.example to Config/TwitchSecrets.xcconfig.local.
2. Set your value:

TWITCH_CLIENT_ID = your_real_client_id

Important:

• Do not use Twitch's public web client ID (for example kimne78kx3ncx6brgo4mv6wki5h1ko).
• If you do, the consent page will show "Twilight" and followed-channel APIs may fail.
• Create your own Twitch app in the Twitch Developer Console and use that Client ID.

Config/TwitchSecrets.xcconfig.local is gitignored (*.xcconfig.local), so your ID stays local.

Working in git worktrees

Because the secrets file is gitignored, it does not exist in freshly created worktrees. After making a new worktree, run the bootstrap helper from inside it:

./tools/bootstrap-worktree.sh

This copies Config/TwitchSecrets.xcconfig.local from your primary checkout and regenerates the Xcode project. Without it, builds fail with "Missing Twitch client ID".

On Apple TV, sign-in uses Twitch Device Code flow: start sign-in on TV, then complete approval on your phone/browser (including the Twitch mobile app browser flow) using the shown code/link.

How Playback Works

Apple TV has no official Twitch playback SDK. Twizz resolves playback via Twitch GraphQL PlaybackAccessToken and Usher HLS playlists, similar in spirit to open-source clients like Streamlink and Frosty.

This project is non-commercial and ad-respecting.

Not Supported: Auto-Redeeming Channel Points

Twizz won't auto-claim channel points (the way the 7TV/FFZ browser extensions do). Twitch's official login that Twizz uses isn't accepted by the private API that claims points — that API only trusts a real twitch.tv web-session login. Supporting it would mean adding a second login where you type your Twitch password into the app and storing a full-account session token, plus fighting Twitch's anti-bot checks. It's also against Twitch's Terms of Service. Not worth the security risk and fragility, so we're not doing it.

Not Supported: Follow / Unfollow Actions

Twizz can show who you follow, but Twitch now blocks follow/unfollow mutations from this app context with integrity checks. Because of that Twitch-side restriction, Twizz does not expose follow/unfollow controls — use the official Twitch app or website to change follows.

Ideas & Improvements

A running list of things we're considering but haven't built yet:

• Multi-view & Picture-in-Picture — watch two streams at once, or shrink the player to a corner while you browse for the next channel.
• SharePlay watch-together — sync playback (and a shared reaction layer) over FaceTime; a social differentiator unique to the Apple ecosystem.
• Moderator mode — timeout / ban / delete and a mod-action log from the couch for users who mod.
• Chat keyword highlights + mention ping — client-side highlighting for keywords and your username in busy chats.
• Freeze-chat-on-focus — pause autoscroll while you're reading so it doesn't fight you.
• Siri & deep search — "Play channel on Twizz" and system-Search results that jump straight into playback.
• Per-channel memory — remember preferred quality, chat width, and audio-only state per channel.
• Deeper accessibility — VoiceOver labels for chat lines and cards, and a captions toggle where available.

Donate

Twizz is free and open source, and it always will be. There's no paywall, no ads, and no obligation to give anything.

If the app has been useful to you and you'd like to chip in toward its upkeep — things like the Apple Developer Program fee and time spent maintaining it — donations are welcome and genuinely appreciated. Anything is plenty, and not donating is completely fine too.

Donate via GitHub Sponsors — one-time or recurring, whatever suits you.

License

MIT © 2026 thatcube

Not affiliated with or endorsed by Twitch Interactive, Inc.