Introduce and maintain a Flatpak release for Psysonic

[Psychotoxical]

Summary

Psysonic currently ships Linux builds as .deb, .rpm, and .AppImage (plus the AUR recipe for Arch users). What's still missing is a Flatpak / Flathub presence — the single biggest discoverability channel on the Linux desktop, and the only sane install path on immutable distros.

This issue tracks introducing a Flatpak release, publishing it to Flathub, and wiring the maintenance into our existing release flow.

Motivation

• Flathub is the de facto cross-distro app store for Linux desktops. .deb / .rpm / AUR / AppImage cover the "I know what I want" crowd; Flathub is where users discover apps.
• Sandboxing is a real user-facing benefit for a network-facing desktop app (Subsonic credentials, arbitrary server URLs, LRCLIB / Last.fm / Discord / Bandsintown integrations).
• Immutable distros (Fedora Silverblue, Bazzite, Aurora, Bluefin, SteamOS / Steam Deck Desktop Mode, Endless OS) cannot install .deb / .rpm / AUR packages cleanly, and .AppImage works but is second-class there — Flatpak is the native option.
• Auto-updates via Flathub come for free for end users; we do not need to ship our own updater logic inside the Flatpak (and in fact must not — see below).

Scope

1. Manifest + build

• Add a packages/flatpak/ directory alongside packages/aur/ containing:
  • app.psysonic.Psysonic.yaml (or .json) — Flatpak manifest
  • app.psysonic.Psysonic.desktop — desktop entry (reuse existing)
  • app.psysonic.Psysonic.metainfo.xml — AppStream metadata (required by Flathub, includes screenshots, release notes, content rating)
  • Icon set (reuse the existing Tauri icons, at least 128×128 and 256×256 PNG)
• Decide on runtime: org.freedesktop.Platform 23.08 or 24.08 with the rust-stable SDK extension and the node SDK extension (we need both to build the Tauri bundle inside the Flatpak sandbox).
• Handle the cmake build-time dep (symphonia-adapter-libopus bundles libopus) — the Freedesktop SDK already ships cmake, so this should be a no-op, but verify.
• Handle WebKitGTK: the Flatpak runtime ships it, so we do not bundle it ourselves. Nicer than the .deb / .rpm story on newer distros.
• Network + filesystem permissions in the manifest:
  • --share=network (Subsonic / Last.fm / Discord RPC / LRCLIB / Bandsintown)
  • --socket=pulseaudio + --device=all (audio engine, output device selection, USB DACs like UMC202HD)
  • --socket=wayland + --socket=fallback-x11
  • --socket=session-bus + --talk-name=org.mpris.MediaPlayer2.* (MPRIS)
  • --talk-name=com.discordapp.* + --filesystem=xdg-run/discord-ipc-*:ro (Discord RPC via unix socket in $XDG_RUNTIME_DIR)
  • --filesystem=xdg-music:ro (optional, for local-file playback if/when we add it)
• Single-instance: tauri-plugin-single-instance uses a lockfile under $XDG_RUNTIME_DIR — should Just Work inside Flatpak, verify.
• Tray icon: verify the TrayIconBuilder flow works under Flatpak — StatusNotifierItem needs --talk-name=org.kde.StatusNotifierWatcher and the host must run a tray (GNOME needs the AppIndicator extension).

2. Auto-updater interaction

• Disable the in-app Tauri updater in Flatpak builds. Flathub owns updates for its packages; shipping a second updater is explicitly disallowed and confuses users. Gate AppUpdater.tsx behind an env var (e.g. PSYSONIC_FLATPAK=1 set in the manifest) or a Cargo feature.
• Make sure the "Check for updates" UI is hidden in Flatpak builds too.

3. CI / release pipeline

• New job in .github/workflows/release.yml that builds the Flatpak on v* tag push, using flatpak-builder inside a container. Sits alongside the existing deb/rpm/AppImage job.
• Produce a single-file .flatpak bundle as a GitHub release asset (convenient for sideload testing before Flathub approval, and useful long-term for users who want to install without adding the Flathub remote).
• Once on Flathub: the canonical manifest lives in flathub/app.psysonic.Psysonic (separate repo under the Flathub org). Our in-repo packages/flatpak/ manifest stays as the source of truth and gets mirrored on release — same pattern as AUR.
• Document the bump flow in CLAUDE.md's "Release-Prozess" alongside the existing AUR steps.

4. Flathub submission

• Open PR to flathub/flathub with the manifest.
• Provide required AppStream data: summary, description, screenshots (at least 3, 16:10 or 16:9, no window decorations / full-screen mocks), license, content rating (OARS — likely none on everything), supported form factors (desktop).
• Verified-app process via flathub.json once merged (optional but nice — gives the green checkmark).
• Subscribe @Psychotoxical and @cucadmuh to the Flathub repo for review notifications.

5. Post-release maintenance

• Each Psysonic release bumps: version string, tag reference, and the cargo-sources.json + npm-sources.json lock files generated by flatpak-builder-tools (flatpak-cargo-generator, flatpak-node-generator).
• Automate the lock regeneration in CI so we don't have to remember.
• Monitor Flathub PR queue for runtime bumps (23.08 → 24.08 etc.) — they announce deprecations ~6 months ahead.

Open questions

• Do we want an org.freedesktop.Sdk.Extension.rust-stable pinned version, or latest? Pinning gives reproducibility; latest tracks upstream. Flathub reviewers generally prefer pinned.
• Beta channel: Flathub supports stable + beta branches. Worth it, or is the GitHub Releases page (where .AppImage already lives) enough for beta testers?
• i18n: AppStream <description> can be localized per-locale. We already have 8 locales — worth translating the store listing, or ship English-only at first?

Non-goals

• Snap package — separate can of worms (snapd-confinement, Canonical-hosted store). Out of scope here.
• AppImage changes — already shipping from release.yml, no work needed here.

References

• Flathub submission guide: https://docs.flathub.org/docs/for-app-authors/submission
• Tauri v2 Flatpak distribution docs: https://v2.tauri.app/distribute/flatpak/
• flatpak-builder-tools (cargo + node generators): https://github.com/flatpak/flatpak-builder-tools
• AppStream metainfo spec: https://www.freedesktop.org/software/appstream/docs/

[kilyabin]

Tauri v2 Flatpak distribution docs: https://v2.tauri.app/distribute/flatpak/

goes to 404

[kilyabin]

I'm taking on the case with @cucadmuh

[kilyabin]

checking

[cucadmuh]

At the moment, @kilyabin is working on the task independently. I’d like to express my personal thanks to him for that.

[kilyabin]

Development is ongoing in this branch

[kilyabin]

it's good but im currently stucked on this little problem

[kilyabin]

https://github.com/kilyabin/psysonic/actions/runs/24803679994/
i think it's be correct but nix and other builds may stop because last.fm api keys is null

[kilyabin]

Hi! I'm back and applied the fixes you suggested in #271. I'll check the build and test the package on my PC now.

Branch that provide fixes: https://github.com/kilyabin/psysonic/tree/flatpak-release

[kilyabin]

I encountered a lot of problems due to the new version of the application, I can’t continue working tonight, I’ll come back to this later.