Files
otunes/apps/desktop
T
joshuafhigginsandClaude Opus 5.5 Verified 2a77c92332 feat(desktop): ship stock Electron for Windows and Linux
Drop the custom EAC-3 Chromium build and macOS packaging. Windows NSIS
installers and Flatpaks for x64 and ARM64 now build in one Linux
container image.

Packaged installers previously lost the bundled Next.js dependencies:
electron-builder drops the pnpm store and NSIS cannot carry symlinks.
The bundle now replaces pnpm links with nested real copies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2a77c92332 · 2026-11-20 00:14:47 -05:00
History
..

oTunes desktop

The Windows and Linux desktop app. It runs stock Electron, bundles the web UI and runs its standalone Next.js server on loopback using Electron's Node utility process. It never loads the UI hosted on your music server. On first launch, enter the oTunes server domain, then sign in. The address is saved in the app's user data directory, not compiled into the package.

For music.example.com, Convex connects to https://convex.music.example.com. Local hosts follow the mobile convention and use port 3210. The selected oTunes server provides streaming audio, cover art and avatars through the desktop's local gateway. Authentication routes stay local and connect to the selected Convex backend. The desktop app does not bundle Convex, FFmpeg or a music library.

The server-entry view uses the web app's controls, colors and logos, with the system theme by default. Use Server > Change server to select another server. Switching servers clears the local login session and cached data.

Stock Chromium cannot decode EAC-3, so the player's codec check reports no Dolby Atmos support and the server streams the regular track instead.

Run and package

pnpm install
pnpm dev:desktop
# Or create installers for this OS, x64 and ARM64:
pnpm build:desktop
# Or a specific target from a Linux host:
pnpm --filter @otunes/desktop build:windows
pnpm --filter @otunes/desktop build:linux

All of these first build and bundle the local web UI. pnpm --filter @otunes/desktop build:web builds that bundle alone. Desktop builds use apps/web/.next-desktop and copy the standalone output, static assets and public assets into apps/desktop/web. Installers cannot carry symlinks, so pnpm's links are replaced with real copies, with each package's dependencies nested under it. The web app's normal .next output is separate. On Windows, enable Developer Mode or symlink permissions before building. The build rejects absolute junctions or links outside the standalone directory because they cannot be relocated into an installer.

Desktop images bypass Next's optimizer, so the bundle drops Sharp's native libraries. Any other native library fails the build, because it would match the build host rather than the target.

The desktop gateway binds only to 127.0.0.1:47836. A single instance owns that port. The bundled Next.js process uses a separate OS-assigned loopback port and restarts when the server selection changes. No external Node.js installation is required by the installed app.

Packaging writes to apps/desktop/dist: an NSIS installer per architecture for Windows, a Flatpak per architecture for Linux. To pick one architecture, pass it after the target: node scripts/package.mjs linux x64. Building Windows installers on Linux needs Wine. Flatpaks need flatpak-builder with Flathub added, and ARM64 Flatpaks on an x64 host need qemu-user-static registered with binfmt. Installers are unsigned unless you configure electron-builder's signing environment.

Flatpaks pin org.freedesktop.Platform, its SDK and org.electronjs.Electron2.BaseApp to 25.08. Network, audio, graphics and display access are enabled. Home-directory access is not needed.

Gitea builds

.gitea/workflows/desktop-build.yml runs manually and on v* tags, matching the Docker workflow. Both jobs run on the ubuntu-latest Docker runner and upload installers with actions/upload-artifact@v3. Tags set the installer version, so use semantic version tags such as v1.2.3. Manual runs use the desktop package version. Nothing is published.

Both jobs use the electronuserland/builder:wine container: windows builds x64 and ARM64 NSIS installers, and linux installs flatpak-builder from apt and builds x64 and ARM64 Flatpaks.

The Linux job needs two things from the runner host:

  • Privileged job containers, since flatpak-builder sandboxes its build. Set container.privileged: true in the runner's config.
  • An ARM64 binfmt handler. Register it once with apt install qemu-user-static on Debian/Ubuntu, which persists across reboots.