9 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.
Up Next opens at the first Plex credits marker for an episode, including after a seek; without markers it opens at EOF. Movie-credit skipping is independent. There is one autoplay timer, measured by elapsed time without requiring webview keyboard focus. Mouse movement, clicks, keypresses (including Tab), and scrolling cancel it. Esc or clicking the video returns to playback; F/F11 toggles full screen. Video hover/focus shows only a white outline. The play button's fill is the visible countdown. The video rectangle must follow window resizes and DPI changes and return to the full window on dismissal, episode changes, errors, and closing. Verify those native video transitions on a GPU-equipped machine; browser layout checks cannot prove rendering.
Diagnostics
src-tauri/src/diagnostics.rs writes to the app's log folder
(%LOCALAPPDATA%\tv.kaleido.desktop\logs on Windows); nothing is uploaded.
- Hangs: a watchdog asks the UI thread to answer every second. After 5 seconds of
silence it writes
kaleido-hang-<time>-v<version>.dmpwith every thread's stack (once per stall) and notes the stall and the recovery indiagnostics.log. - Crashes (Windows): an unhandled exception writes
kaleido-crash-…dmpand logs the exception and faulting module, e.g.access violation at libmpv-2.dll+0x1234. - Panics are logged with a backtrace.
The newest five dumps of each kind are kept. To read one, open it in WinDbg with the
symbols of the exact build that wrote it: scripts/build.ps1 keeps each release's
kaleido.exe and kaleido.pdb in .tools/symbols/<version>/ (release builds keep
function names and line tables in the .pdb; the installer doesn't change). In WinDbg:
.sympath+ <that folder>, .reload, then ~*k for every thread's stack.
Development builds have two test commands: debug_freeze_ui ({ seconds }, holds the
UI thread) and debug_crash (an access violation); both refuse to run in release builds.
Threading rule learned the hard way: Tauri's window getters (hwnd(), sizes…) called
off the UI thread wait for it to answer, so never call one while holding a lock the UI
thread might wait on, and keep window-event handlers from waiting on the player's locks
(they run on the UI thread; lib.rs hands resize handling to a background thread).
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.