Port Kaleido Desktop to macOS

macOS (Apple silicon) now plays, browses and updates like Windows:

- Video: libmpv's render API draws into a CAOpenGLLayer beneath the
  WKWebView, with the miniplayer rectangle, HDR passthrough through
  extended dynamic range (PQ/BT.2020) and display-sleep prevention.
- Window: native traffic lights on the top bar's centre line, hidden
  with the player's controls; the page's caption buttons are Windows-only.
- Interface: macOS shortcut labels (⌘K, ⌘[, ⌃⌘F), Plex identifies the
  player as a Mac, and header values are kept ASCII (Mac computer names
  usually contain a curly apostrophe).
- The window appears without waiting for an animation frame, which
  WKWebView doesn't run in a hidden window.
- Credentials: release builds use the Keychain and are signed with a
  lasting self-signed certificate so access survives updates; debug
  builds keep tokens in a private file to avoid prompts on every rebuild.
- Bundling: scripts/fetch-libmpv.sh makes Homebrew's libmpv and its
  libraries self-contained; scripts/build.sh builds the .app, .dmg and
  signed update archive.

Releases now carry both platforms: publish-release.mjs uploads each
machine's build into one release, and update-manifest.mjs writes the
feed from that release's assets, refusing while a platform is missing.

The updater uses a new signing key (public key in tauri.conf.json), so
existing installs must be reinstalled once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Elijah Kuntz 2026-11-02 15:14:40 -07:00
parent a3c05e9062
commit 7d0803481b
39 changed files with 1191 additions and 230 deletions

View file

@ -35,21 +35,34 @@ updates/latest.json Signed update feed for every platform
`src-tauri/src/platform/mod.rs` selects one of `windows.rs`, `macos.rs` or `linux.rs`.
Each exposes the same items:
| Item | Windows implementation |
| --- | --- |
| `VideoSurface` | mpv renders with `d3d11-output-mode=composition`; its swapchain (`display-swapchain`) is set as the content of a DirectComposition visual targeted at the window with `topmost = false`, i.e. behind the web view's child windows. For the miniplayer the visual is offset and mpv's composition size shrunk to a corner rectangle (`player_rect`). |
| `MPV_LIBRARIES` | `libmpv-2.dll` |
| `hold_awake` | `SetThreadExecutionState` while video plays |
| Item | Windows | macOS |
| --- | --- | --- |
| `VideoSurface` | mpv renders with `d3d11-output-mode=composition`; its swapchain (`display-swapchain`) is set as the content of a DirectComposition visual targeted at the window with `topmost = false`, i.e. behind the web view's child windows. For the miniplayer the visual is offset and mpv's composition size shrunk to a corner rectangle (`player_rect`). | mpv's render API (`vo=libmpv`, OpenGL) draws into a `CAOpenGLLayer` hosted by a view inserted beneath the WKWebView, whose background is turned off (`drawsBackground`). `start` creates the render context once mpv is initialized; a render thread redraws the layer whenever mpv reports a new frame. For the miniplayer the view is moved to the corner rectangle. |
| `MPV_LIBRARIES` | `libmpv-2.dll` | `libmpv.2.dylib` (in `Contents/Frameworks` with the libraries it links) |
| `hold_awake` | `SetThreadExecutionState` | an IOKit `PreventUserIdleDisplaySleep` assertion |
| Window buttons | drawn by the page (`WindowControls`) | the native traffic lights (`titleBarStyle: Overlay`, placed on the top bar's centre line); `set_window_buttons` hides them with the player's controls |
| `device_name` | `COMPUTERNAME` | the computer name from Sharing settings |
macOS and Linux currently provide stubs for `VideoSurface` (browsing, downloads,
settings and updates work; playback reports that it is unavailable). To add playback
there, render through mpv's render API into a layer beneath the web view and implement
the same methods (`set_rect` places the video in part of the window for the miniplayer). Per-OS bundling (libmpv, targets, dependencies) lives in
`tauri.macos.conf.json` and `tauri.linux.conf.json`. Credentials use the platform's
keychain through the `keyring` crate with per-OS features in `Cargo.toml`.
Linux provides stubs for `VideoSurface` (browsing, downloads, settings and updates
work; playback reports that it is unavailable); the macOS approach (render API beneath
the web view) applies there with an OpenGL surface under WebKitGTK. Per-OS bundling
(libmpv, targets, window style) lives in `tauri.<os>.conf.json`. Credentials use the
platform's keychain through the `keyring` crate with per-OS features in `Cargo.toml`;
macOS debug builds keep them in a private file instead, because each unsigned rebuild
would make the Keychain ask again.
On Windows the main window is created transparent and the page background turns
transparent only while video is visible (`html.video-active`), so browsing is opaque.
The page background turns transparent only while video is visible
(`html.video-active`), so browsing is opaque. The page knows its OS synchronously
(`hostOS` in `platform/native.ts`, from the web view's user agent) and tags the root
element (`html.os-macos`) for the few styles that differ, such as room for the traffic
lights.
HDR passthrough (`target-colorspace-hint`) works differently on each OS. On Windows mpv
switches its swapchain's colour space itself. On macOS the surface watches
`video-params/gamma`: for PQ or HLG video it has mpv output PQ in BT.2020
(`target-trc`, `target-prim`) into the 16-bit float framebuffer and turns on the layer's
extended dynamic range with the BT.2100 PQ colour space, so macOS maps the picture
into the display's HDR headroom; SDR video returns both to their defaults.
## Interface
@ -85,4 +98,5 @@ transparent only while video is visible (`html.video-active`), so browsing is op
cached in the app cache folder (`gpu-shader-cache-dir`), so a slow first Direct3D
compile happens once per shader set, mpv version and GPU driver.
- **Updates**: `app/updater.ts` checks the signed feed on start; installs need the
user's confirmation and then relaunch.
user's confirmation and then relaunch. One release carries every platform's build and
the feed lists each of them (`windows-x86_64`, `darwin-aarch64`).

View file

@ -11,6 +11,22 @@
debug builds and the Vite dev server. Never commit or print it.
5. `npm run tauri dev`
## Setup (macOS)
1. Node 22+, Rust stable (`brew install rustup && rustup default stable`), the Xcode
command line tools and Homebrew.
2. `npm ci`
3. `sh scripts/fetch-libmpv.sh` installs Homebrew's `mpv` and copies libmpv with every
library it links into `vendor/mpv/macos`, rewritten to find each other there
(`@loader_path`) and signed, so the bundle doesn't depend on Homebrew. Homebrew
builds for the macOS it runs on, so the app's minimum macOS is that of the build
machine (`scripts/build.sh` sets it from the libraries).
4. `.env` as on Windows, then `npm run tauri dev`.
Debug builds on macOS keep the Plex token in `dev-secrets.json` in the app data folder
rather than the Keychain: every rebuild is a new unsigned binary, which the Keychain
would ask about again. Release builds always use the Keychain.
The interface alone runs in a browser with `npm run dev` (port 1420), which is handy for
layout work; playback, downloads and native dialogs need the desktop app. In development
builds the stores are available as `window.__kaleido` for debugging.
@ -39,43 +55,67 @@ and copy back only the files already in `src-tauri/icons` (the Android and iOS s
## Releases
Releases are built and published from this Windows machine. CI only validates; it never
builds installers on push (there are no Windows/macOS runners). Versions follow SemVer;
betas use a prerelease suffix (`0.1.0-beta.1`) and are published as pre-releases.
Releases are built and published locally: Windows on the Windows machine, macOS on the
Mac. CI only validates; it never builds installers on push (there are no Windows/macOS
runners). Versions follow SemVer; betas use a prerelease suffix (`0.1.0-beta.1`) and are
published as pre-releases. **Each release carries both platforms**, and the update feed
is written only once both are uploaded.
Checklist for version `X.Y.Z` (run from the repository root):
1. **Version**: set `X.Y.Z` in `package.json`, `src-tauri/Cargo.toml` and
`src-tauri/tauri.conf.json`, then `npm install --package-lock-only` to update
1. **Version** (either machine): set `X.Y.Z` in `package.json`, `src-tauri/Cargo.toml`
and `src-tauri/tauri.conf.json`, then `npm install --package-lock-only` to update
`package-lock.json`.
2. **Changelog**: add a `## X.Y.Z` section at the top of `CHANGELOG.md`. It becomes the
release notes and the in-app update notes.
3. **Check**: `npm run typecheck`, `npm test`, `cargo check --manifest-path src-tauri/Cargo.toml`.
4. **Build**: `.\scripts\build.ps1` → `src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe`
and its `.sig`. The updater key is read from `.tools/updater.key` (ignored; keep it
safe — replacing it breaks in-app updates for existing installs) or from
`TAURI_SIGNING_PRIVATE_KEY`.
5. **Commit and tag**: commit as `Release Kaleido Desktop X.Y.Z`, then
4. **Commit and tag**: commit as `Release Kaleido Desktop X.Y.Z`, then
`git tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z"` and `git push origin main vX.Y.Z`
(SSH remote `origin`, already configured).
6. **Publish**: `node scripts/publish-release.mjs X.Y.Z` (add `--prerelease` for betas)
creates the Forgejo release with the notes from `CHANGELOG.md` and uploads the
installer and `.sig`. It reads `FORGEJO_TOKEN` (repository read/write) from the
environment or the ignored `.env`, and never prints it. Re-running it replaces the
assets.
7. **Update feed**: `node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z`
rewrites `updates/latest.json`; commit it (`Publish the X.Y.Z update feed`) and push.
Installed copies offer the update on their next start. Publish the feed only after
the release assets exist, or clients would be sent to a missing file.
8. **Verify**: download the installer from the release URL and compare its SHA-256 with
the local file; `https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json`
should show the new version; CI on Actions should finish green.
(SSH remote `origin`, already configured). Pull it on the other machine.
5. **Build and publish on Windows**: `.\scripts\build.ps1` →
`src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe` and its `.sig`;
then `node scripts/publish-release.mjs X.Y.Z` (add `--prerelease` for betas) creates
the Forgejo release with the notes from `CHANGELOG.md` and uploads them.
6. **Build and publish on macOS**: `sh scripts/build.sh` → `bundle/dmg/Kaleido_X.Y.Z_aarch64.dmg`
(first installs) and `bundle/macos/Kaleido_X.Y.Z_aarch64.app.tar.gz` with its `.sig`
(updates); then `node scripts/publish-release.mjs X.Y.Z [--prerelease]` adds them to
the same release. The order of 5 and 6 doesn't matter.
7. **Update feed** (either machine): `node scripts/update-manifest.mjs X.Y.Z` reads the
release's assets (downloading each `.sig`) and rewrites `updates/latest.json`; commit
it (`Publish the X.Y.Z update feed`) and push. Installed copies offer the update on
their next start. The script refuses while a platform's build is missing from the
release, so neither OS is ever pointed at an older build; `--allow-missing` publishes
the feed without it (that OS then sees no update until the feed is regenerated).
8. **Verify**: download each artifact from the release and compare its SHA-256 with the
local file; `https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json`
should list both platforms at the new version; CI on Actions should finish green.
The installer is per user (`%LOCALAPPDATA%\Kaleido`, no admin) and is not code-signed,
so SmartScreen warns on first run. In-app updates run it in passive mode and relaunch.
Both publishing scripts read `FORGEJO_TOKEN` (repository read/write) from the
environment or the ignored `.env`, and never print it. Re-running `publish-release.mjs`
replaces that machine's assets.
For macOS and Linux, build on those systems (`scripts/fetch-libmpv.sh`, then
`npx tauri build`) and merge their bundles into the same feed with `KALEIDO_BUNDLES`.
`.forgejo/workflows/release.yml` validates every push and tag;
**Update signing**: both build scripts sign update artifacts with the updater key from
`.tools/updater.key` (ignored; keep it safe — replacing it breaks in-app updates for
existing installs) or `TAURI_SIGNING_PRIVATE_KEY`. Both build machines need the same
key in `.tools/`; without it a build has no update archive.
**Windows** installs per user (`%LOCALAPPDATA%\Kaleido`, no admin) and is not
code-signed, so SmartScreen warns on first run. In-app updates run the installer in
passive mode and relaunch.
**macOS** builds are signed with a self-signed certificate, "Kaleido Self-Signed", in
the build Mac's login keychain (backed up, with its password, as
`.tools/macos-signing.p12` and `.tools/macos-signing.password`). A lasting signature
keeps the app's identity across updates, so the Keychain keeps trusting it with the
Plex token; ad hoc signatures change with every build and would make macOS ask again
after each update. To build on another Mac, import the backup:
`security import .tools/macos-signing.p12 -k ~/Library/Keychains/login.keychain-db -P "$(cat .tools/macos-signing.password)" -T /usr/bin/codesign`.
The app isn't notarized, so the first launch of a downloaded `.dmg` needs
System Settings → Privacy & Security → Open Anyway (or right-click → Open); in-app
updates aren't quarantined and install without that. Building runs Finder through
AppleScript to lay out the disk image window; set `CI=true` to skip that step.
Linux can be built with `sh scripts/fetch-libmpv.sh` and `npx tauri build` but isn't
published. `.forgejo/workflows/release.yml` validates every push and tag;
`.forgejo/workflows/build-installers.yml` can build installers in CI once runners exist
for each platform, and only runs when started by hand.