jellyfin-plugin-floatplane/doc/research/reference-sources/fn_README.md

FloatNative

A modern, native client for Floatplane — built from scratch for iPhone, iPad, Apple TV, Android phone, Android TV, and Fire TV.

Highlights

• Native everywhere. SwiftUI on Apple platforms, Jetpack Compose on Android. Not a wrapped web view.
• Closed captions on every platform, with system-styling support.
• Picture-in-picture and background audio on iPhone, iPad, and Android.
• Watch Later, custom Playlists, and Enhanced LTT search via a companion API.
• Simple Floatplane OAuth login — sign in with your Floatplane account through Floatplane's official OAuth flow; tokens are DPoP-bound to a private key in the device Keychain / Keystore so they can't be replayed if intercepted.
• Player polish: sleep timer, force-landscape, screen-stay-awake, playback-speed memory, tappable timestamps in descriptions, watch-progress restore, multi-part post support.
• TV-first TV apps for tvOS, Android TV, and Fire TV — not phone apps stretched onto a 65" screen.

Repository layout

This is a pnpm + Gradle monorepo.

floatnative/
├── apps/
│   ├── ios/               # SwiftUI app — iOS, iPadOS, tvOS
│   ├── android/           # Jetpack Compose app — Android phone, Android TV, Fire TV
│   └── chrome-extension/  # Companion extension for Floatplane playlists in the web UI
│
├── packages/
│   ├── api/               # Companion API — original Cloudflare Workers (TS, Hono, D1)
│   ├── api-go/            # Companion API — Go reimplementation for self-hosting (chi, Postgres)
│   └── openapi/           # Community-maintained OpenAPI spec + Swift/Kotlin model generation
│
└── tools/
    └── floatcli/          # Diagnostic CLI that mirrors what the apps do, for reproducing bugs

Getting started

iOS / iPadOS / tvOS

pnpm install
open apps/ios/FloatNative.xcodeproj

Requirements: Xcode 16.4+, iOS 17+ / tvOS 17+.

Android / Android TV / Fire TV

Open apps/android/ in Android Studio (Hedgehog or newer) and let Gradle sync. Min SDK 26, target SDK 36.

Companion API

pnpm api:dev           # Cloudflare Workers local dev
pnpm api:deploy        # ship to Cloudflare

For the Go variant (self-hosting on a Linux box with Postgres), see packages/api-go/README.md.

Regenerate API models

pnpm openapi:generate:swift    # iOS models
pnpm openapi:generate:kotlin   # Android models
pnpm openapi:generate:all      # both
pnpm openapi:update-spec       # pull latest community spec

Spec and generation scripts live in packages/openapi/.

Authentication & DPoP

Floatplane's V2 auth uses DPoP (Demonstrating Proof-of-Possession) to bind OAuth tokens to a device-held private key, so intercepted tokens can't be replayed elsewhere.

Both apps store the DPoP key in the platform's secure enclave (iOS Keychain, Android Keystore) and sign every request with a fresh proof. For HLS playback — where neither AVPlayer nor ExoPlayer can sign individual segment requests — we use a manifest interception strategy: a custom resource loader signs the master playlist and key requests with DPoP, then rewrites segment URIs to absolute https:// so the player streams them natively without DPoP. The backend is designed around this split: keys require session-bound auth, segments don't.

Acknowledgments

• The community-maintained FloatplaneAPI spec
• Hydravion-AndroidTV — invaluable as a reverse-engineering reference
• Wasserflug-tvOS — a great tvOS client my wife and I used every day for years, and a strong codebase to learn from
• apple-docs MCP
• Claude Code (why hide it)
• The Floatplane team — for building a service worth writing a client for, and for putting up with nerds like me

License

MIT — see LICENSE.

This is an unofficial third-party client and is not affiliated with Floatplane Media Inc.