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
docs-ai/          curated feature plans, implementation outcomes, and runbooks

Install

CineLark requires macOS 26 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 are archived and exported on the maintainer Mac with Xcode Automatic Signing. The current Apple Development export is not Developer ID notarized, so 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.

Durable implementation rationale and feature evolution live in docs-ai/README.md. Repository-local agent skills are maintained once under .claude/skills/ and exposed to Codex through .codex/skills.

• Product specification
• Architecture
• Implementation plan
• Media provider interface
• Metadata cache
• Playback bridge protocol
• Rust bridge helper
• Remote protocol
• Homebrew distribution decision
• Sparkle update decision
• Local automatic release-signing 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.