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>
6.7 KiB
Development
Setup (Windows)
- Node 22+, Rust stable (MSVC), Visual Studio C++ build tools, 7-Zip.
npm ci.\scripts\fetch-libmpv.ps1downloads the shinchirompv-dev-x86_64build (the Windows libmpv builds linked from mpv.io) intovendor/mpv/windows.- Put a
.envin the repository root for the development sign-in:PLEX_SERVER_URL=...andPLEX_TOKEN=.... It is ignored by git and only read by debug builds and the Vite dev server. Never commit or print it. npm run tauri dev
Setup (macOS)
- Node 22+, Rust stable (
brew install rustup && rustup default stable), the Xcode command line tools and Homebrew. npm cish scripts/fetch-libmpv.shinstalls Homebrew'smpvand copies libmpv with every library it links intovendor/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.shsets it from the libraries)..envas on Windows, thennpm 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.
To drive the desktop app from scripts, start it with
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333 and attach over the
Chrome DevTools Protocol.
Checks
npm run typecheck
npm test
cargo check --manifest-path src-tauri/Cargo.toml
Playback tests change real Plex progress; resume an in-progress title near its saved position, or restore it afterwards. Selecting audio or subtitle tracks is saved to Plex for that file.
App icon
src-tauri/icons/app-icon.svg is the source. Render it to a 1024×1024 app-icon.png
with a transparent background, run npx tauri icon src-tauri/icons/app-icon.png -o <temp dir>,
and copy back only the files already in src-tauri/icons (the Android and iOS sets aren't used).
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):
- Version (either machine): set
X.Y.Zinpackage.json,src-tauri/Cargo.tomlandsrc-tauri/tauri.conf.json, thennpm install --package-lock-onlyto updatepackage-lock.json. - Changelog: add a
## X.Y.Zsection at the top ofCHANGELOG.md. It becomes the release notes and the in-app update notes. - Check:
npm run typecheck,npm test,cargo check --manifest-path src-tauri/Cargo.toml. - Commit and tag: commit as
Release Kaleido Desktop X.Y.Z, thengit tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z"andgit push origin main vX.Y.Z(SSH remoteorigin, already configured). Pull it on the other machine. - Build and publish on Windows:
.\scripts\build.ps1→src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exeand its.sig; thennode scripts/publish-release.mjs X.Y.Z(add--prereleasefor betas) creates the Forgejo release with the notes fromCHANGELOG.mdand uploads them. - Build and publish on macOS:
sh scripts/build.sh→bundle/dmg/Kaleido_X.Y.Z_aarch64.dmg(first installs) andbundle/macos/Kaleido_X.Y.Z_aarch64.app.tar.gzwith its.sig(updates); thennode scripts/publish-release.mjs X.Y.Z [--prerelease]adds them to the same release. The order of 5 and 6 doesn't matter. - Update feed (either machine):
node scripts/update-manifest.mjs X.Y.Zreads the release's assets (downloading each.sig) and rewritesupdates/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-missingpublishes the feed without it (that OS then sees no update until the feed is regenerated). - 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.jsonshould list both platforms at the new version; CI on Actions should finish green.
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.
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.