FloatNative

A modern, native iOS/tvOS client for Floatplane with liquid glass UI design, background audio playback, playlists, enhanced LTT search, Picture-in-Picture support, and more.

Features:

• Clean, streamlined, native iOS design
• Watch Later and Playlists (through supplementary API)
• "Enhanced LTT Search" (through supplementary API)
• Token login and QR code token login (to workaround the shut down V2 auth)
• Native Picture-in-Picture support
• Background play
• Video download
• Tappable timestamps in video description
• Light/Dark mode
• iPad styles/support
• Full-featured tvOS app from same codebase
  • Long press menu
  • Custom player controls
• Screen stays awake during playback
• Pretty icon that supports clear/tinted variants
• Watch progress is saved very regularly
• Displays watch progress

Architecture

FloatNative uses a dual-API approach:

• Floatplane API Official 1st party API for accessing Floatplane content (videos, posts, creators, subscriptions)
• Companion API (packages/api) - Custom Cloudflare Worker providing enhanced features:
  • Watch Later and custom playlists
  • Enhanced LTT content search

For the Companion API documentation, see its readme here.

The iOS app integrates with both APIs: auto-generated Swift models from the community-maintained Floatplane API spec for content delivery, and a custom client for companion features.

Repository Structure

This is a pnpm monorepo containing a native iOS application and a Cloudflare Worker API.

floatnative/
├── packages/
│   └── api/              # Companion API (Cloudflare Worker)
│   └── openapi/          # Community-maintained OpenAPI spec for API file generation
│
└── apps/
    └── ios/              # Native iOS app (SwiftUI)
    └── android/          # Placeholder for native Android app (Kotlin)

Package Details

packages/api

Cloudflare Worker providing companion features for the FloatNative iOS app.

• Tech: TypeScript, Cloudflare Workers, Hono, Drizzle ORM, D1 Database
• Features: Watch Later, Playlists, Enhanced LTT Search
• Deploy: pnpm api:deploy

apps/ios

Native iOS application built with SwiftUI.

• Requirements: Xcode 16.4+, iOS 18.5+, Swift 5.0
• Platforms: iOS, tvOS
• API Integration:
  • Auto-generated models from community FloatplaneAPI specification
  • Custom Companion API client for enhanced features
  • Secure credential storage via iOS Keychain

Getting Started

Prerequisites

• Node.js 18+
• pnpm 8+
• Xcode 16.4+ (for iOS development)

Setup

1. Clone the repository

2. Install dependencies:

   pnpm install

3. Open the iOS project in Xcode:

   open apps/ios/FloatNative.xcodeproj

Development Workflow

API Development

Start local development server:

pnpm api:dev

Stream live logs from deployed worker:

pnpm api:tail

Deploy to Cloudflare:

pnpm api:deploy

Database Management

Generate database migrations:

pnpm api:db:generate

Run migrations locally:

pnpm api:db:migrate:local

Run migrations on production:

pnpm api:db:migrate:remote

OpenAPI Model Generation

The monorepo uses a centralized OpenAPI specification in packages/openapi/ to generate type-safe API models for iOS (and future Android).

Specification Source: Community-maintained FloatplaneAPI

Available Commands:

Generate Swift models for iOS:

pnpm openapi:generate:swift

Generate Kotlin models for Android (placeholder):

pnpm openapi:generate:kotlin

Generate all platform models:

pnpm openapi:generate:all

Update OpenAPI spec from upstream:

pnpm openapi:update-spec

How it works:

• Spec stored in packages/openapi/floatplane-openapi-specification.json
• Generation script in packages/openapi/scripts/generate-swift.sh
• Models output to apps/ios/FloatNative/Models/Generated/
• Selective copying: only includes models actually used by the app
• Automatic dependency resolution
• Post-processing fixes for known generator bugs

For more details, see packages/openapi/README.md.

iOS Development

Open apps/ios/FloatNative.xcodeproj in Xcode and build/run the project.

Note: API models are auto-generated from OpenAPI spec. See "OpenAPI Model Generation" section above to regenerate models when needed. The app also maintains custom model wrappers in apps/ios/FloatNative/Models/ for fields not covered by the OpenAPI spec (e.g., selfUserInteraction).

Authentication & DPoP

This application implements DPoP (Demonstrating Proof-of-Possession) to secure OAuth tokens. This binds access tokens to a private key stored in the device's Secure Enclave/Keychain, preventing token replay attacks if intercepted.

Video Playback Strategy

The native iOS video player (AVPlayer) does not natively support DPoP because it cannot sign individual HLS segment requests. We solve this using a Manifest Interception strategy via AVAssetResourceLoaderDelegate:

1. Custom Scheme: The player is initialized with a custom scheme (floatnative://) to force all requests through our VideoResourceLoader.
2. Manifest Rewrite: We intercept the Master Playlist download, rewrite the #EXT-X-KEY URIs to keep them within our custom scheme, but rewrite all Segment (.ts/.m4s) URIs to absolute https:// URLs.
3. Hybrid Execution:
   • Keys: Are loaded by our code, signed with a fresh DPoP proof, and returned to the player.
   • Segments: Are loaded natively by AVPlayer over standard HTTPS (bypassing DPoP), which aligns with the backend's design that segment requests do not require session-bound authentication.

🙏 Acknowledgments

• The Community-maintained FloatplaneAPI
• Hydravion-AndroidTV for providing a great basis of code to draw inspiration and reverse-engineering from
• Wasserflug-tvOS for providing a great basis of code to draw inspiration and reverse-engineering from (and for giving my wife and I a convenient tvOS app we use every day)
• The Apple Docs MCP server
• Claude Code (why hide it)
• The Floatplane team for all their incredible work building this great service and putting up with nerds like me 👏

License

MIT License - see LICENSE for details.

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