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:
parent
a3c05e9062
commit
7d0803481b
39 changed files with 1191 additions and 230 deletions
|
|
@ -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`).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue