Getting Started

Getting Started

This page is for contributors setting up A Playa Named Gus locally.

Requirements

• macOS with a modern Xcode install (Xcode 26.5 baseline) that supports the iOS, tvOS, visionOS, macOS, and watchOS SDKs.
• Xcode command line tools selected with xcode-select.
• XcodeGen installed locally.
• A Jellyfin server for manual smoke testing (or the bundled demo server — see below).

Deployment targets: iOS 18.0, tvOS 18.0, visionOS 2.0, macOS 15.0, watchOS 11.0.

Install XcodeGen once:

brew install xcodegen

Clone and Generate the Project

git clone https://github.com/eslutz/A-Playa-Named-Gus.git
cd 'A Playa Named Gus'
xcodegen generate

A Playa Named Gus.xcodeproj is generated output and is intentionally not committed. The source of truth is project.yml.

Run xcodegen generate after adding, removing, or renaming source/resource files. XcodeGen globs the file tree when the project is generated, so new files are invisible to xcodebuild until regeneration.

Resolve Packages

xcodebuild -resolvePackageDependencies -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus'

Runtime dependencies are jellyfin-sdk-swift and — on iOS/iPadOS only — the Readium toolkit for in-app EPUB reading (ADR 0009). XcodeGen is a build-time dev tool, not a shipped dependency.

Build

First list the destinations installed on the current machine:

xcodebuild -showdestinations -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus'

Example build commands (names match a stock Xcode 26.5 install — verify with -showdestinations, as simulator names drift between Xcode versions):

xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=iOS Simulator,name=iPhone 17' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=iOS Simulator,name=iPad Pro 11-inch (M5)' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=tvOS Simulator,name=Apple TV 4K (3rd generation)' build
xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=macOS' build

For visionOS, target by simulator ID because more than one "Apple Vision Pro" simulator can exist:

xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'A Playa Named Gus' -destination 'platform=visionOS Simulator,id=<UUID>' build

Build the watchOS companion with its own scheme:

xcodebuild -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus watchOS' -destination 'generic/platform=watchOS Simulator' build

Run Tests

The A Playa Named Gus scheme is build-only. Use the per-platform test schemes for the test action. The Gus <platform> Unit Tests schemes run the Swift Testing bundles only (these are the CI lanes); the Gus <platform> Tests schemes also run the narrow launch UI tests.

xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus iOS Unit Tests' -destination 'platform=iOS Simulator,name=iPhone 17'
xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus tvOS Unit Tests' -destination 'platform=tvOS Simulator,name=Apple TV 4K (3rd generation)'
xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus macOS Unit Tests' -destination 'platform=macOS'
xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus visionOS Unit Tests' -destination 'platform=visionOS Simulator,id=<UUID>'

Run a single Swift Testing test with:

xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus iOS Unit Tests' -destination 'platform=iOS Simulator,name=iPhone 17' -only-testing:GusTests/<Suite>/<test>

If Swift Testing selector matching is uncertain, run the whole GusTests target:

xcodebuild test -project 'A Playa Named Gus.xcodeproj' -scheme 'Gus iOS Unit Tests' -destination 'platform=iOS Simulator,name=iPhone 17' -only-testing:GusTests

Format and Validate Strings

Scripts/format.sh
swiftformat Sources Tests --lint
jq empty Resources/Localizable.xcstrings

Demo Server

Scripts/demo-server.sh runs a local Jellyfin container over the rights-cleared sample_media/ folder (git-ignored). Debug builds sign straight in via the --gus-demo-server launch argument or the Connect screen's demo button. See Documentation/AppStore/demo-server.md.

Manual Smoke Test

Use a real or demo Jellyfin server and verify:

• Connect to a server.
• Sign in or use Quick Connect.
• Browse Home, Search, Library, Item Detail, Settings, and Downloads.
• Start video playback; play a song or audiobook through the audio player.
• Verify track selection, chapters, next-up prompt, Now Playing, AirPlay, and PiP where the platform supports them.
• Verify direct play of a compatible file (HEVC/HDR/surround preserved) and instant audio/subtitle switching on it; verify a text-subtitle selection on an incompatible file triggers a transcode with subtitles in the manifest.
• Let an episode reach its natural end: it should auto-play the next episode (Settings → Playback toggle) or close the player.
• Change Settings → Playback → Streaming Quality and confirm a lower cap forces a transcode.
• On macOS, confirm video opens in its own resizable player window (green-button fullscreen works).
• On non-tvOS platforms, start, pause, resume, delete, and play from an offline download.
• On visionOS, enter Gus Cinema and test spatial/stereo fallback behavior where device support exists.

When locating a built .app, scope find to the correct product directory such as Debug-iphonesimulator or Debug-appletvsimulator. A broad find build can return another platform's product and cause simulator install failures.

Useful Source Links

• Architecture
• Testing and Verification
• AGENTS.md
• Documentation/ROADMAP.md