Labstream

Labstream is a native Apple-platform media client for your own Plex, Jellyfin, or Emby server.

The app does not bundle or sell media. A separate optional project-operated review/demo service hosts licensed sample content; see the Privacy Policy. It connects only to servers you choose, and offline downloads are for media you are authorized to access and download under the applicable server/service terms.

The repository contains native targets for Apple Vision Pro, iPhone/iPad, Apple TV, and Mac. The visionOS target owns the spatial shell and Cinema experience, LabstreamMobile is one universal iPhone/iPad target, LabstreamTV is a streaming-only TV target, and LabstreamMac is the native Mac target. They share the SwiftUI app core, custom AVFoundation player, and PMSKit backend layer while owning platform-specific shells, input, and system integration.

Distribution status: Labstream is publicly distributed as source for local builds. The repository records invitation-only internal TestFlight binaries, but there is no public App Store release. It also records staged product metadata and initial privacy-safe screenshots. Platform versions remain pre-release until their individual hardware, review-access, storefront, and App Review gates pass. The release and App Store status page is the source of truth for exact source versions, processed builds, and open gates.

Development status: This is an active, pre-release project rather than a compatibility promise. Plex, Jellyfin, and Emby paths are implemented, but backend, server-version, media, and platform combinations do not all have equal live-device validation. Expect incomplete behavior and regressions while platform parity, hardware validation, performance measurement, and release acceptance remain ongoing work.

Contents

• Features
• Supported backends
• Platform status
• Tech stack
• Quick start
• Project structure
• Documentation
• Contributing
• Privacy and bug reports
• License

Features

These are implemented product areas, not a claim that every item is complete on every platform and backend. See the platform and backend status tables below for the current support boundaries.

Playback

• Custom AVFoundation player surface shared across visionOS, iOS/iPadOS, tvOS, and macOS.
• Original (Direct Stream) attempts copy or direct-stream paths where viable.
• Explicit quality rungs request capped server streams when needed.
• Resume, seek, retry, subtitles, chapters, playback speed, buffering state, and Stats for Nerds.
• On visionOS, Cinema mode expands playback into an app-owned immersive surface with the same transport controls.
• Watch progress, mark-watched behavior, Up Next, and episode autoplay.

Libraries and search

• Home, library, search, and detail surfaces for personal media.
• TV hierarchy navigation from show to season to episode.
• Music browsing and playback for supported backend music libraries.
• Backend-aware sign-in and server/session restore.

Downloads and offline

Downloads and offline playback are available on visionOS, iOS/iPadOS, and macOS. The tvOS target deliberately omits the complete download capability and Offline product surface.

• Offline downloads with metadata, poster/side-asset support, integrity checks, and route-specific recovery: static/original and server-prepared static files use checkpoints, while live remux/transcode streams reconcile safely but may need retry/restart after interruption.
• Direct original downloads only when Labstream expects the file to be locally playable.
• Server-prepared or server-rendered compatible files when the original is not a safe offline target.

Privacy and diagnostics

• Canonical app builds store tokens and server credentials in Keychain. The Plex account token is the one synchronizable Keychain item; per-device client identity, Jellyfin/Emby tokens, and server selection remain device-local. Per-worktree Mac development builds use isolated, backup-excluded credential files instead.
• Diagnostic logging is off by default and local-only. When enabled, events are kept in a bounded in-memory ring and small rotating redacted files; reports leave the device only after a user action.
• Built-in bug-report diagnostics redact tokens, client identifiers, hostnames/IPs, full URLs, usernames, library paths, filenames, and media titles.

Supported backends

Backend	Sign-in	Core support
Plex	Plex PIN/OAuth and server discovery	Implemented across browse, search, playback, progress, music, and downloads/offline; primary live-test backend.
Jellyfin	Server URL plus username (password optional) or Quick Connect	Browse, search, playback, progress, music, and downloads/offline paths are implemented; live coverage varies by server and media.
Emby	Emby Connect PIN or manual server URL plus username/password	Browse, search, playback, progress, music, and downloads/offline paths are implemented; live coverage varies by server and media.

Labstream is unofficial and independent. It is not affiliated with, endorsed by, sponsored by, or officially supported by Plex, the Jellyfin project, or Emby Media.

Platform status

Platform	Target / scheme	Current status
Apple Vision Pro / visionOS 26	Labstream	Spatial release candidate with the app-owned immersive Cinema surface. Physical-headset and release acceptance remain open.
iPhone / iOS 26.1+	LabstreamMobile	Native compact-width release candidate. Local simulator and signed-device builds are supported; physical/TestFlight acceptance remains open.
iPad / iPadOS 26.1+	LabstreamMobile	The same universal release-candidate binary, using the regular-width sidebar layout. Physical/TestFlight acceptance remains open.
Apple TV / tvOS 26+	LabstreamTV	Native streaming-only release candidate with a ten-foot shell and custom Siri Remote player interactions. Downloads and Offline are absent; physical-device, accessibility, system-integration, and release acceptance remain open.
Mac / macOS 26	LabstreamMac	Native release candidate with shared sign-in, playback, media-key, and background-download code. App Store signing, sandbox behavior, and live Mac acceptance remain open release gates.

Tech stack

• SwiftUI app shells targeting visionOS 26, iOS/iPadOS 26.1+, tvOS 26+, and macOS 26.
• Swift 6 with strict concurrency.
• Custom AVFoundation playback and offline playback paths.
• PMSKit, a local Swift package for Plex/Jellyfin/Emby request builders, models, diagnostics primitives, policy state machines, and narrow reusable networking/storage infrastructure.
• MkDocs Material documentation built from the checked-in docs/ source.

Quick start

Requirements

• macOS with Xcode 27 plus the SDK/runtime for each target being built: visionOS 26, iOS/iPadOS 26.1+, or tvOS 26+.
• A compatible simulator runtime for visionOS, iPhone/iPad, or Apple TV work, or paired physical hardware for the device acceptance being performed.
• Python 3.11+ and uv for documentation and repository tooling checks.
• A Plex, Jellyfin, or Emby server you control or have permission to access.

LabstreamMac builds directly for an Apple-silicon Mac running macOS 26; it has no simulator lane.

Build and smoke

docs/DEVELOPMENT.md is the canonical executable workflow:

• Before the first visionOS build or linked visionOS worktree, select or create and record the initial visionOS simulator. Mobile-only and tvOS-only work do not require this bootstrap.
• Build the primary Labstream visionOS scheme, the universal LabstreamMobile iPhone/iPad scheme, or the LabstreamTV Apple TV scheme.
• Complete the exact-product install, observable launch/log/screenshot smoke, and simulator shutdown.
• Run the core validation commands and clean up any linked-worktree simulators.

Physical devices and Mac

• Apple Vision Pro: complete the first-use pairing, Developer Mode, Xcode account/signing, install, and launch procedure.
• iPhone/iPad: use the canonical signed hardware install procedure.
• Apple TV: simulator procedures are documented today; physical Apple TV deployment and acceptance remain open release gates in the tvOS target guide.
• Mac: use the host validation procedure.

All four production targets use org.labstream.Labstream. The Mac host helper defaults to a per-worktree development bundle identifier so local builds do not collide; see the macOS target guide.

Project structure

Labstream/
├── Labstream/             # app-owned source, split by capability and platform ownership
│   ├── Shared/            # universal app core, backend facades, player, music, and shared UI
│   ├── Capabilities/
│   │   └── Downloads/ # visionOS, mobile, and Mac offline engine/UI; absent from tvOS
│   └── Platforms/
│       ├── visionOS/      # vision app entry point, Cinema, scoped system media, SharePlay
│       ├── Mobile/        # universal iPhone/iPad entry point and mobile player integration
│       ├── macOS/         # single-window Mac entry point and desktop player integration
│       └── tvOS/          # streaming-only TV entry point and Debug fixture ownership
├── PMSKit/                # reusable requests, models, policies, infrastructure, and tests
├── docs/                  # current docs plus plans, research, evidence, and archive lanes
├── scripts/               # local validation, simulator, deploy, and probe helpers
└── .woodpecker/           # portable CI definitions

Documentation

• Documentation source and local site build: docs/
• User guide: support, bug reporting, privacy, and release/App Store status
• Contributor guide: contributing, development setup, testing strategy, and playback troubleshooting
• Platform guides: iOS/iPadOS, tvOS, and macOS
• Architecture: overview, code map, backends, playback, downloads/offline, music, persistence, system integration, and diagnostics/privacy
• Validation: private media corpus, App Store screenshots, compile performance, and manual validation checklist

Public pages at the top of docs/ describe the current app. Internal documents use explicit unpublished lanes: active implementation plans and acceptance journals in docs/plans/, unresolved investigations in docs/research/, immutable audit/profiling observations in docs/evidence/, and completed or superseded context in docs/archive/. The repository-root TESTING-CHECKLIST.md is the deliberate operational exception and remains the current manual validation matrix.

Contributing

Start with docs/CONTRIBUTING.md. In short:

• keep backend-specific wire behavior explicit;
• put reusable request, model, and policy decisions in PMSKit, keeping its few effectful networking/storage utilities narrow and injectable;
• keep SwiftUI, AVPlayer ownership, target lifecycle, background-session delegation, Keychain, and app persistence in the app target;
• never commit tokens, server URLs, private IPs, media titles, local signing files, or diagnostic artifacts.

For a quick module size readout, run:

scripts/loc.sh

Privacy and bug reports

Labstream does not send analytics, diagnostics, or media-server data to the developer. If something breaks, the app can generate a local redacted diagnostic report that you review before posting to GitHub.

• Bug guide: docs/REPORTING-BUGS.md
• Bug form: https://github.com/jlipworth/Labstream/issues/new?template=bug_report.yml
• Privacy policy: PRIVACY.md
• Security reports: SECURITY.md — vulnerabilities must use the private route
• Community conduct: CODE_OF_CONDUCT.md

License

Labstream is licensed under the GNU General Public License v3.0. See LICENSE for the full text. Third-party package licenses and required notices are bundled under Labstream/Shared/Resources/ThirdPartyNotices.

The project also carries a GPLv3 section 7 additional permission for linking and distributing the visionOS, iOS/iPadOS, tvOS, and macOS applications through Apple App Store and TestFlight paths. See APP-STORE-EXCEPTION.md for its exact scope.

Copyright (C) 2026 Jonathan Lipworth