Home

A Playa Named Gus

A Playa Named Gus is an Apple-first, multiplatform Jellyfin client for iOS, iPadOS, tvOS, visionOS, and macOS, plus a watchOS companion app. The project goal is one native SwiftUI app that feels first-party on every Apple platform while staying small, reviewable, and dependency-light.

Bundle identifier: dev.ericslutz.gus. Named for Psych.

Project Principles

• Prefer Apple and system frameworks over custom or third-party runtime code.
• Keep runtime dependencies to jellyfin-sdk-swift, plus the Readium toolkit on iOS/iPadOS only for in-app EPUB reading (no system API renders EPUB — see ADR 0009). Do not add others without an explicit ADR.
• Use SwiftUI, Observation, AVKit, Security, MediaPlayer, URLSession, FileManager, OSLog, and String Catalogs instead of custom equivalents.
• Isolate platform differences in Sources/Platform or narrowly scoped guarded modifiers.
• Keep the repository README concise; use this wiki and Documentation/ for deeper project documentation.

Current Status

A Playa Named Gus covers the full Jellyfin client flow and a broad feature set:

• Connect to a Jellyfin server, including user-initiated local discovery.
• Sign in with credentials or Quick Connect, with multi-server / multi-user switching.
• Browse home sections, libraries, search results, item details, and series seasons/episodes.
• Play video through AVKit with direct play at original quality where the device's hardware supports it (HEVC/HDR/surround preserved), Now Playing metadata, chapters, track selection, episode auto-play, a streaming-quality setting, and AirPlay/PiP surfaces where supported.
• Play music and audiobooks through a dedicated audio engine (queue, shuffle/repeat, playback speed, chapters).
• Browse photo libraries, Live TV / DVR, and book libraries (in-app EPUB reading on iOS/iPadOS).
• Use background-capable offline downloads on iOS, iPadOS, macOS, and visionOS.
• Enter the visionOS Gus Cinema immersive playback space, including SBS/TAB and MV-HEVC stereo.
• Drive playback from a watchOS companion (remote control, quick resume, browse, on-watch audio).
• Integrate with the system via deep links, Handoff, Core Spotlight, Siri/App Intents, a content-aware tvOS Top Shelf, and an iOS CarPlay audio surface.
• Family-safety content gating tied to the Declared Age Range.

App Store readiness work is in progress: the privacy manifest is bundled and the readiness packet is drafted, but App Store Connect setup, signing/archive validation, screenshots, TestFlight, and submission are not complete.

Community questions, ideas, and feedback live in GitHub Discussions.

Wiki Pages

• Getting Started
• Features and Platforms
• Architecture
• Roadmap
• Testing and Verification
• App Store Readiness
• Contributing

Source Documents

The source repository remains the authority for implementation details:

• README.md - compact project summary and build commands.
• AGENTS.md / CLAUDE.md - maintainer and agent working context.
• Documentation/ROADMAP.md - milestone plan to App Store submission.
• Documentation/adr/ - accepted architecture decisions (ADR 0001–0010).
• Documentation/AppStore/ - App Store readiness packet.
• Documentation/watchos-brief.md, family-safety-brief.md, and visionos-3d-playback-plan.md - feature briefs and acceptance artifacts.