CineLark

CineLark is a TV-first media library client for macOS. It presents a focused, remote-friendly browsing experience and delegates playback to IINA/mpv through an optional thin bridge plugin.

Status: pre-alpha; the native macOS UHDNow vertical slice is now implemented.

Product family

• CineLark — a native Swift/SwiftUI macOS client and system coordinator.
• CineLark Remote — a future Flutter companion for iOS and Android; the Mac app remains fully usable without it.
• CineLark IINA Bridge — a provider-neutral IINA plugin for playback control and telemetry.

All components live in this repository so shared contracts can evolve atomically.

Architecture

Flutter Remote (iOS / Android)
             │ paired TLS protocol
             ▼
      CineLark for Mac ◀──▶ Media Provider (UHDNow first)
   Swift · SwiftUI · AppKit
             │ child process / stdio
             ▼
   bundled Rust Bridge Helper
             │ loopback-only local protocol
             ▼
  thin IINA JS Plugin → IINA → mpv

IINA owns decoding, HDR, audio tracks, subtitles, and presentation. CineLark owns discovery, provider credentials, resume decisions, and progress updates. The bridge never receives provider account credentials.

Repository layout

apps/macos/       native Swift/SwiftUI macOS app
apps/remote/      future Flutter app for iOS and Android
packages/apple/   local Swift package and provider/bridge targets
packages/rust/    bundled, runtime-free bridge helper
plugins/iina/     thin IINA JavaScript adapter
specs/            cross-language contracts and external API observations
shared/           generated-code policy, design tokens, and brand assets
fixtures/         synthetic, redacted test fixtures only
docs/             product, architecture, integration, and decision records

Install

CineLark requires macOS 14 or later and uses an existing IINA installation:

brew install --cask samsonlab/cinelark/cinelark

If IINA is not installed yet:

brew install --cask iina

Tagged releases use a stable project-controlled self-signed identity rather than Apple notarization. The Cask pins the DMG by SHA-256 and removes quarantine after installation. The IINA plugin is installed explicitly on first playback.

Development

open apps/macos/CineLark.xcodeproj
swift test --package-path packages/apple/CineLarkKit

See apps/macos/README.md for implemented capabilities and build details.

Specifications

Start with docs/README.md.

• Product specification
• Architecture
• Implementation plan
• Media provider interface
• Metadata cache
• Playback bridge protocol
• Rust bridge helper
• Remote protocol
• Homebrew distribution decision
• Observed UHDNow API
• Verified IINA plugin capabilities

Security

Do not commit HAR files, extracted captures, credentials, cookies, access tokens, signed playback URLs, or real account data. See SECURITY.md.

License

No license has been selected yet. Until one is added, all rights are reserved.