Kinrox
Kinrox is a minimalist video player for macOS with a native iPhone remote.
Open a movie on your Mac and control it from the couch over your local network.
No cloud, user accounts, analytics, or telemetry.
Features
- Local video playback, including MP4 and MKV, powered by libmpv, OpenGL,
and VideoToolbox hardware acceleration.
- Glass controls, keyboard shortcuts, native fullscreen, and drag-and-drop.
- Recent files, naturally sorted folder playlists, and automatic next-file playback.
- Mac audio/subtitle selection, recursive discovery of external tracks, folder search,
and remembered preferences for the next episode.
- System media keys and Now Playing integration.
- Mac update reminders through Sparkle 2 (from 0.3.0): a banner on
the welcome screen and a pill on pause. Scheduled checks read the public HTTPS
appcast daily without unique identifiers or a system profile; updates download
when the user chooses to install them.
- iPhone discovery over Bonjour, six-digit PIN pairing, encrypted commands,
Keychain token storage, and reconnection.
- Remote playback, seeking, volume, fullscreen, and recent-file controls.
- Matrix screensaver on Mac, with controls in companion builds that support screensavers:
falling green code, movie pause on activation, and Esc to exit.
- Shared localization in 30 languages with English fallback.
Project Status
The Mac player and real iPhone remote are implemented through M5. The current
standalone Mac release is 0.3.0, for Apple Silicon and macOS 14+:
download the DMG
or read the release notes.
The installer bundles libmpv and its dependencies, is Developer ID signed, and
is notarized by Apple. Homebrew is only needed for the default development setup.
Users of Mac 0.2.0 or earlier install 0.3.0 manually once to enable future update reminders.
The iPhone App Store release remains separate; the remote can be built from source.
The kinrox-cli executable is a stub; its implementation is an
optional task. Network streams,
custom playlists, and playback position memory are outside the initial scope.
Architecture and roadmap are in AGENTS.md.
The player also updates the current folder playlist as videos appear
or disappear, including Next/Previous availability on the iPhone. Temporary download suffixes (.part, .crdownload, .!qB)
are excluded until renamed to a video filename. If a downloader writes directly
to the final filename, Kinrox cannot determine whether that download is complete.
A video arriving after the final EOF check enables Next without starting playback.
Requirements
Requires Xcode 26.5, Swift 6, and XcodeGen 2.46.0 or newer. Minimum deployment
targets — macOS 14 and iOS 17. Builds target arm64.
Player requires libmpv and headers in /opt/homebrew, test media requires ffmpeg.
Scripts do not install dependencies automatically. Current Homebrew libmpv is built for macOS 26.
Distribution instead uses pinned portable libraries; see the
release runbook. Runtime testing in this session
was on macOS 26.5.2; minimum-version checks cover every bundled Mach-O library.
Install the command-line dependencies if they are not already available:
brew install xcodegen mpv pkg-config ffmpeg
Xcode must be installed and selected as the active developer directory.
Mac remote pairing requires Apple Development signing with a matching macOS
provisioning profile. An iOS simulator build does not require a developer team;
installation on a physical iPhone requires device signing.
Build and Tests
After cloning, create your local signing configuration if it does not exist:
cp -n Config/Signing.local.xcconfig.example Config/Signing.local.xcconfig
Set your own team and bundle identifier prefix in that file, and configure the
Mac provisioning profile per the
signing runbook.
Then, from the project root, run sequentially:
./Scripts/check-env.sh
./Scripts/generate.sh
bash Scripts/make-test-media.sh
swift test --package-path Packages/RemoteProtocol
xcodebuild -workspace Kinrox.xcworkspace -scheme PlayerMac \
-configuration Debug -destination 'platform=macOS,arch=arm64' \
-derivedDataPath DerivedData build test
xcodebuild -workspace Kinrox.xcworkspace -scheme RemoteiOS \
-destination 'platform=iOS Simulator,name=iPhone 17' \
-derivedDataPath DerivedData build test
If iPhone 17 is unavailable, choose an installed simulator from
xcrun simctl list devices available and update the destination.
The package tests can run independently of app signing. Local transport tests
require local network access. Playback tests use synthetic media with Kinrox's
volume set to zero; do not change the Mac system volume for testing.
Launching the player:
open DerivedData/Build/Products/Debug/Kinrox.app
Open a video via ⌘O, drag it into the window, or drop onto the Dock icon.
Keybindings: Space — pause, ←/→ — 5s, ⇧←/⇧→ — 30s, ↑/↓ — volume,
⌘←/⌘→ — adjacent file in folder, F or double-click — fullscreen.
Use the caption-bubble button or the Audio / Subtitles menus to select tracks.
Choose Screensaver → Matrix to show falling code over the player. A playing
movie pauses first. The exit hint disappears after three seconds; Esc exits
Matrix while preserving the movie's paused position and fullscreen state.
The iPhone remote has a Screensavers section with start/stop controls.
See screensaver verification.
⌃⌘A and ⌃⌘S cycle audio and subtitles. All files in folder shows external
tracks from every nested folder, including unmatched files and other episodes.
Choose a common search folder when audio and subtitles are outside the video's folder.
To launch with a file argument:
open -n DerivedData/Build/Products/Debug/Kinrox.app --args /full/path/to/video.mkv
Closing the window tears down the player; ⌘O creates a new window.
To run the remote, open Kinrox.xcworkspace, select scheme RemoteiOS
and simulator iPhone 17, and click Run. Player scheme is PlayerMac,
built application is Kinrox.app.
Standard remote launch searches for Macs on the local network. Enable "Remote" in Kinrox
Mac settings, allow local network access on iPhone, select the Mac, and enter the code
from its screen. Subsequent launches authenticate via Keychain token.
Demo mode without Mac is available in remote settings via "Try demo without Mac" button
or launch argument -KinroxDemo; real pairings are unavailable in demo.
Debug argument -KinroxScreen pairing|remote|recents functions only alongside
-KinroxDemo. Network errors never switch the app into demo mode.
Installation and tests on a physical iPhone — per runbook.
Generated .xcodeproj files are git-ignored. After modifying project.yml,
rerun ./Scripts/generate.sh. Common configuration is in
Config/Shared.xcconfig: Swift 6, complete strict concurrency, and OS versions.
App Intents metadata extraction is disabled as no intents are present.
Since M4.4, Mac requires Apple Development signing and a macOS provisioning profile for Data Protection
Keychain. For iOS simulator, a developer team is not required. Personal template is
Config/Signing.local.xcconfig.example; file Signing.local.xcconfig is git-ignored.
Platform signing configurations are defined in Config/PlayerMac.xcconfig and
Config/RemoteiOS.xcconfig, including shared and local configs.
For custom Bundle IDs, specify KINROX_BUNDLE_ID_PREFIX in personal config;
app and test suffixes remain intact, common PRODUCT_BUNDLE_IDENTIFIER is not required.
Config/MPV.xcconfig is linked to Mac project; MPVKit resides inside PlayerMac.
The verified development setup uses mpv 0.41.0. pkg-config --modversion mpv
reports 2.5.0 — libmpv client API version. Development headers reside in
/opt/homebrew/include/mpv. Library validation is disabled for development with
Homebrew dylibs. Distribution uses pinned libraries, signs every dylib with the
same Developer ID, and keeps library validation enabled. See the
release runbook.
Design
All design work is done in Figma file
Kinrox — Design:
01 · UI v1 — Player & Remote
and 02 · M4 — Connection & states.
Mac track selection follows 04 · Tracks — Audio & subtitles.
Tokens from the file live in Shared/Design/KinroxTheme.swift and Resources/Branding.xcassets.
Logo and Icons
Master logo is stored in
Resources/Branding.xcassets/KinroxLogo.imageset/kinrox-logo.png.
Shared catalog is included in both applications; asset KinroxLogo is used
on player and remote splash screens.
App icons are in Resources/Assets.xcassets/AppIcon.appiconset
inside each application. For macOS, sizes 16–1024 pixels are provided;
for iOS — an opaque 1024×1024 PNG from which Xcode generates required assets.
PNGs were downscaled from source via sips -z <size> <size> <source> --out <file>.
Both project.yml specify AppIcon via ASSETCATALOG_COMPILER_APPICON_NAME.
Localization
Both apps support 30 locales and follow the system app-language preference, with English as fallback. Translations are shared in Resources/Localization.
See supported languages and verification.
Run python3 Scripts/check-localization.py after changing user-facing strings.
Code Style
Format touched Swift files; verify entire tree:
xcrun swift-format lint --strict --recursive PlayerMac RemoteiOS Packages Shared
Contributing and Security
See CONTRIBUTING.md for setup, scope, and validation guidance.
The master project specification and agent workflow are in AGENTS.md.
For sensitive vulnerability reports, follow SECURITY.md.
Keep signing settings, certificates, private keys, .env files, generated
projects, and build artifacts out of commits. The repository includes a signing
template; each developer supplies their own ignored local configuration.
Landing Site
site/ holds the GitHub Pages landing in English and Russian: plain HTML and CSS,
no build step, no analytics. It also includes privacy
and support pages linked from the landing and iPhone app.
Preview locally:
python3 -m http.server 8080 --directory site
Workflow .github/workflows/pages.yml deploys it on every push to main that touches site/
(enable Settings → Pages → Source: GitHub Actions once). Refresh remote screenshots with
./Scripts/capture-landing-screenshots.sh after building RemoteiOS for a booted simulator.
Details — site/README.md.
Runbooks
Repeatable runbooks are organized in docs/runbooks:
License
Kinrox is open source under GNU GPL v3
(GPL-3.0-only). The license applies to player, remote, shared packages,
and scripts. Full text in LICENSE.
Third-party libraries retain their respective licenses.
