Plozz

A free and open source native Apple TV app for Jellyfin or Plex servers.

Try the beta

Plozz is in public beta on TestFlight. Join the beta → to install it on your Apple TV (tvOS 17 or later) and stream from your own Jellyfin or Plex server.

Features

Servers & sign-in:

• Jellyfin and Plex — one experience over either backend; Home, detail, and playback work the same.
• Multiple servers, one library — Together or separate - you can connect multiple Jellyfin and Plex servers; Everything optionally merges together.
• Auto-discovery — finds Jellyfin servers on your LAN (UDP) automatically, with manual URL entry as a fallback.
• Remote-free sign-in — Jellyfin Quick Connect and Plex Link: enter a code, no password typing.
• Persistent session — relaunch restores your login. Tokens live in the Keychain and are never logged.

Browse & detail:

• Home — Continue Watching plus Latest / Recently Added.
• Detail pages — full-bleed backdrop, logo, overview, ratings, and a Play/Resume button.
• Series — focus-driven season tabs and an episode rail, with per-episode watched badges and "mark watched up to here."
• Trailers — plays library trailers, with a TMDb → YouTube fallback when the server has none.
• Music — browse artists and albums with a mini-player, queue, and background audio.

Playback:

• Direct play first — AVPlayer plays what it can; tricky formats (AV1, some HEVC/10-bit, image-based PGS/VOBSUB subtitles) route to an on-device engine automatically.
• Resume — position is restored and reported back to the server.
• Skip intros & credits — skip buttons appear automatically from your server's media segments.
• Track selection — audio and subtitles when available.
• Caption customization — font, size, color, opacity, background, and edge style.

Appearance:

• Themes & display size — System, Dark, OLED, and Light, plus adjustable interface sizing.
• Night mode — highly adjustable settings to warm and dim the display automatically to protect your circadian rhythm
• Profiles — all settings are per-profile, allowing you to customize the experience to your own preferences while grandma can do as she pleases

Architecture

Plozz is a Swift Package with one library per concern, consumed by a thin tvOS app target generated with XcodeGen.

Module	Responsibility
CoreModels	Domain models, AppError, LoadState, caption settings, and the MediaProvider protocol (the provider abstraction).
CoreNetworking	HTTPClient, Endpoint, URL normalization, and a secret-safe logger (PlozzLog).
CoreUI	Shared focusable components, theme, image cache, content-state views.
ProviderJellyfin	Jellyfin REST client, DTOs, device profile, and a MediaProvider implementation.
ProviderPlex	Plex client, DTOs, PIN/auth, connection resolver/selector, and a MediaProvider implementation.
ProviderTrailers	Synthetic MediaProvider for online (YouTube) trailers, with stream extraction via YouTubeKit.
MetadataKit	Keyless-first artwork & metadata enrichment (AniList, Kitsu, TVmaze, Deezer, MusicBrainz/CAA, Wikidata/Wikipedia) routed by content type with a persistent on-disk cache. Optional maintainer-hosted TMDb tier.
RatingsService	External ratings enrichment (OMDb optional key, keyless AniList) with on-disk cache.
TraktService	Optional Trakt OAuth, scrobbling, and watched/sync helpers.
TopShelfKit	Domain-to-snapshot mapping for the Top Shelf extension; writes to the shared App Group container.
FeatureDiscovery	LAN (UDP) discovery, server validation, server-picker UI, last-server persistence.
FeatureAuth	Quick Connect, Plex Link, password sign-in, the explicit session state machine, Keychain-backed account/session stores.
FeatureHome	Home rows, item detail, series/season experience, online trailer fallback.
FeaturePlayback	AVPlayer view model/view, engine routing, resume reporting, caption style rules, idle-sleep handling, diagnostics overlay.
FeatureSearch	Search view & view model, deduplication, search policy.
FeatureSettings	Settings (profiles, integrations, server, caption customization, preference detail).
FeatureProfiles	Profile picker, editor, avatar/photo capture (household "Who's watching?").
FeatureMusic	Music browsing, mini-player, queue/now-playing, background audio.
AppShell	App state wiring, root navigation, profile selection, provider/registry composition.

Each module's README.md documents its responsibility, public surface, and invariants. Everything above the provider layer talks to the MediaProvider abstraction rather than a specific backend, so Jellyfin and Plex are each just a conformer — adding another backend means one new conformer, no feature rewrites.

Building & running

Requirements

• macOS with Xcode 16+ (tvOS 17.0 deployment target)
• XcodeGen: brew install xcodegen

Generate the project and run

xcodegen generate
open Plozz.xcodeproj
# Select the "Plozz" scheme and an Apple TV simulator, then Run.

Run the unit tests

swift test

The logic modules are platform-portable, so swift test runs on any Swift toolchain — no simulator. UI modules compile out behind #if canImport(...) guards and are covered by the tvOS simulator/app build instead. CI runs swift test on Linux and an xcodebuild tvOS build on macOS.

Performance debugging

If the app feels laggy or you see blank artwork / memory crashes on device, see docs/performance-debugging.md — an on-device playbook using the watchdog and Instruments (xctrace).

Releasing to TestFlight

Distribution is automated with fastlane (App Store Connect API key auth). Drop a gitignored .env.fastlane with ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_PATH (see .env.fastlane.example), then:

fastlane beta --env fastlane    # build + upload to TestFlight
fastlane build --env fastlane   # archive a signed .ipa locally, no upload
fastlane release --env fastlane # build + upload to the App Store

Versioning (project.yml): bump the marketing version (CFBundleShortVersionString, e.g. 0.1 → 0.2) by hand; the build number is auto-incremented from the latest TestFlight build at archive time — never edit it manually.

tvOS Brand Assets (app icon + Top Shelf images) live under App/Resources/Assets.xcassets/…brandassets and are required for any upload. The current art is a placeholder — replace it before a public App Store release.

Roadmap

• Overseerr integration (request media).
• iOS and/or iPadOS app depending on demand

Donate

Plozz is free and open source, with no paywall, ads, or obligation. If it's useful to you, donations toward upkeep are welcome — and not donating is completely fine.

Donate via GitHub Sponsors — one-time or recurring.

Credits & attribution

Plozz is an unofficial client and is not affiliated with, endorsed, or certified by any of the services below.

• AetherEngine — on-device playback engine (FFmpeg demux → VideoToolbox decode) by Vincent Herbst, LGPL-3.0 with an App Store exception. superuser404notfound/AetherEngine. Its bundled FFmpeg is a decode-only, LGPL-3.0 build (see NOTICE.md).

• The Movie Database (TMDB) — some artwork and metadata is provided by the TMDB API. This product uses the TMDB API but is not endorsed or certified by TMDB. TMDB's marks and logos are trademarks of TMDB.

  

• OMDb API — optional IMDb ratings enrichment (requires your own OMDb key).

• AniList — keyless community scores for anime titles.

• Plex and Jellyfin — the media servers Plozz connects to. All library content, artwork, and ratings shown in the app are supplied by your own server. "Plex" and "Jellyfin" are trademarks of their respective owners.

License

GPL-3.0 (with an App Store Exception) © 2026 Brandon Moore