Release: Flatpak x86_64/aarch64, AppImage zsync updates, README Downloads (#13)

- AppImages embed gh-releases-zsync update information and ship a .zsync beside them.
- New flatpak job repackages the Linux tarball into soundcraft-<v>-linux-<arch>.flatpak
  (bundle manifest + flatpak-bundle.sh). Sandbox: pulseaudio socket (PipeWire's pulse server),
  ~/.vst3 and ~/.clap read-only, the LinuxAudio.Plugins extension point via VST3_PATH/CLAP_PATH;
  no raw ALSA devices, no JACK. The from-source Flathub manifest gets the same finish-args.
- Only signing jobs (macOS, Windows) and the draft job keep `environment: release`, so a branch
  dispatch dry-runs Linux, Flatpak, FreeBSD and web; the draft job still needs the signed jobs.
- README: Downloads section; docs/releasing.md updated.

Co-authored-by: Brandon Thomas <shared2@storyteller.ai>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.github/workflows/packaging-lint.yml

@@ -54,4 +54,14 @@ jobs:
           desktop-file-validate packaging/linux/ai.storyteller.soundcraft.desktop
           sed -e 's/@VERSION@/0.0.0/' -e 's/@DATE@/2026-01-01/' packaging/linux/ai.storyteller.soundcraft.metainfo.xml.in >"$RUNNER_TEMP/ai.storyteller.soundcraft.metainfo.xml"
           appstreamcli validate --no-net --explain "$RUNNER_TEMP/ai.storyteller.soundcraft.metainfo.xml"
-          python3 -c "import yaml; m = yaml.safe_load(open('packaging/linux/flatpak/ai.storyteller.soundcraft.yml')); assert m['id'] == 'ai.storyteller.soundcraft' and m['command'] == 'soundcraft'"
+          python3 - <<'EOF'
+          import yaml
+          src = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.soundcraft.yml"))
+          bundle = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.soundcraft.bundle.yml"))
+          for m in (src, bundle):
+              assert m["id"] == "ai.storyteller.soundcraft" and m["command"] == "soundcraft", m["id"]
+              assert "--socket=pulseaudio" in m["finish-args"], "audio needs --socket=pulseaudio"
+          for key in ("runtime", "runtime-version", "sdk", "finish-args", "add-extensions"):
+              assert src[key] == bundle[key], f"Flatpak manifests disagree on {key}: {src[key]} vs {bundle[key]}"
+          print("Flatpak manifests ok")
+          EOF

.github/workflows/release.yml

@@ -1,9 +1,11 @@
 # Release pipeline: every push to `release` builds signed installers for every platform and
 # creates or updates the draft GitHub Release "SoundCraft v<version>". See docs/releasing.md.
 #
-# All jobs run in the `release` environment (restricted to the `release` branch), which holds
-# the signing secrets. Every secret is optional: missing ones produce unsigned artifacts and a
-# warning, never a failed build.
+# The jobs that sign (macOS, Windows) and the one that drafts the release run in the `release`
+# environment (restricted to the `release` branch), which holds the signing secrets. Every secret
+# is optional: missing ones produce unsigned artifacts and a warning, never a failed build. The
+# other jobs sign nothing and get no secrets, so a dispatch on any branch builds and checks them
+# (a dry run); the signed jobs are refused there, and so the draft release is skipped.
 name: Release
 
 on:
@@ -35,7 +37,7 @@ jobs:
   version:
     name: version
     runs-on: ubuntu-latest
-    environment: release
+    # No `environment: release`: this job reads no secrets (and gates every other job).
     outputs:
       version: ${{ steps.v.outputs.version }}
       date: ${{ steps.v.outputs.date }}
@@ -157,7 +159,7 @@ jobs:
     # The oldest GitHub-hosted image, so the binaries only need glibc >= 2.35 (Ubuntu 22.04+,
     # Debian 12+, Fedora 36+, RHEL 10). See docs/releasing.md.
     runs-on: ${{ matrix.runner }}
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
     strategy:
       fail-fast: false
       matrix:
@@ -176,7 +178,7 @@ jobs:
           sudo apt-get install -y --no-install-recommends \
             libxkbcommon-dev libwayland-dev libx11-dev libxrandr-dev libxi-dev libgl1-mesa-dev \
             libasound2-dev pkg-config \
-            desktop-file-utils appstream python3-yaml
+            desktop-file-utils appstream python3-yaml zsync
           curl -fsSL -o "$RUNNER_TEMP/nfpm.deb" \
             "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_${{ matrix.deb }}.deb"
           sudo dpkg -i "$RUNNER_TEMP/nfpm.deb"
@@ -200,6 +202,9 @@ jobs:
           for appimage in dist/release/*.AppImage; do
             chmod +x "$appimage"
             APPIMAGE_EXTRACT_AND_RUN=1 "$appimage" --version
+            # Update information is embedded, and the .zsync for delta updates sits beside it.
+            "$appimage" --appimage-updateinformation | grep -F 'gh-releases-zsync|storytold|soundcraft|latest|soundcraft-*-linux-${{ matrix.arch }}.AppImage.zsync'
+            test -s "$appimage.zsync"
           done
       - uses: actions/upload-artifact@v4
         with:
@@ -207,13 +212,51 @@ jobs:
           path: dist/release/*
           if-no-files-found: error
 
+  flatpak:
+    name: Flatpak ${{ matrix.arch }}
+    needs: [version, linux]
+    # Repackages the Linux job's tarball (the same binaries as the AppImage/deb/rpm); no Rust
+    # build here. 24.04 for a newer flatpak-builder (1.4) than 22.04 ships.
+    runs-on: ${{ matrix.runner }}
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { arch: x86_64, runner: ubuntu-24.04 }
+          - { arch: aarch64, runner: ubuntu-24.04-arm }
+    env:
+      SOUNDCRAFT_VERSION: ${{ needs.version.outputs.version }}
+      SOUNDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-linux-${{ matrix.arch }}
+          path: dist/linux
+      - name: Install flatpak-builder
+        run: |
+          sudo apt-get update
+          # librsvg2-common: the SVG pixbuf loader. flatpak-builder runs the host's
+          # `appstreamcli compose`, which renders the scalable icon and fails without it.
+          sudo apt-get install -y --no-install-recommends flatpak flatpak-builder librsvg2-common
+          # Ubuntu 24.04's AppArmor blocks the unprivileged user namespaces bubblewrap needs.
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      - name: Build the Flatpak bundle
+        run: packaging/linux/flatpak-bundle.sh "dist/linux/soundcraft-$SOUNDCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-flatpak-${{ matrix.arch }}
+          path: dist/release/*.flatpak
+          if-no-files-found: error
+
   freebsd:
     name: FreeBSD x86_64
     needs: version
     # GitHub has no FreeBSD runners: build in a FreeBSD 14.3 VM (same image as freebsd.yml).
     runs-on: ubuntu-latest
     timeout-minutes: 150
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
     env:
       SOUNDCRAFT_VERSION: ${{ needs.version.outputs.version }}
       SOUNDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
@@ -253,7 +296,7 @@ jobs:
     name: Web (wasm)
     needs: version
     runs-on: ubuntu-latest
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
     env:
       SOUNDCRAFT_VERSION: ${{ needs.version.outputs.version }}
       SOUNDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
@@ -284,7 +327,8 @@ jobs:
 
   release:
     name: Draft GitHub Release
-    needs: [version, macos, windows, linux, freebsd, web]
+    # Needs the signed jobs, which only run on the `release` branch: a branch dispatch never drafts.
+    needs: [version, macos, windows, linux, flatpak, freebsd, web]
     runs-on: ubuntu-latest
     environment: release
     permissions:

README.md

@@ -54,6 +54,7 @@
   <a href="#for-agents-and-scripts">Agents &amp; scripts</a> ·
   <a href="#how-its-built">How it's built</a> ·
   <a href="#status-and-roadmap">Status</a> ·
+  <a href="#downloads">Downloads</a> ·
   <a href="#the-crafting-apps">The Crafting Apps</a> ·
   <a href="#license-and-credits">License</a>
 </p>
@@ -213,6 +214,50 @@ honest status, what's next and our effort estimates are in [`ROADMAP.md`](ROADMA
 menu-by-menu comparison is in [`docs/parity.md`](docs/parity.md). Bug reports and wish lists are
 very welcome, in the issues or on Discord.
 
+## Downloads
+
+Every [release](https://github.com/storytold/soundcraft/releases/latest) ships these builds. `<ver>` is the
+version number; `SHA256SUMS.txt` lists a checksum for every file.
+
+### macOS
+
+| Build | File | Notes |
+|---|---|---|
+| App, universal (Apple silicon + Intel) | `soundcraft-<ver>-macos-universal.dmg` | Signed and notarized |
+| Command-line tool, universal | `soundcraft-cli-<ver>-macos-universal.zip` | Signed and notarized |
+
+### Windows
+
+| Build | Installer | Portable |
+|---|---|---|
+| x64 (64-bit Intel/AMD) | `soundcraft-<ver>-windows-x64.msi` | `soundcraft-<ver>-windows-x64-portable.zip` |
+| arm64 (Snapdragon and other ARM PCs) | `soundcraft-<ver>-windows-arm64.msi` | `soundcraft-<ver>-windows-arm64-portable.zip` |
+| x86 (32-bit) | `soundcraft-<ver>-windows-x86.msi` | `soundcraft-<ver>-windows-x86-portable.zip` |
+
+Installers and executables are code-signed.
+
+### Linux
+
+| Format | x86_64 | aarch64 (ARM64) | Notes |
+|---|---|---|---|
+| AppImage | `soundcraft-<ver>-linux-x86_64.AppImage` | `soundcraft-<ver>-linux-aarch64.AppImage` | Runs anywhere; updates itself with [AppImageUpdate](https://github.com/AppImageCommunity/AppImageUpdate) (`.zsync` files) |
+| Flatpak | `soundcraft-<ver>-linux-x86_64.flatpak` | `soundcraft-<ver>-linux-aarch64.flatpak` | Sandboxed; `flatpak install --user <file>` |
+| Debian/Ubuntu | `soundcraft-<ver>-linux-x86_64.deb` | `soundcraft-<ver>-linux-aarch64.deb` | |
+| Fedora/RHEL/openSUSE | `soundcraft-<ver>-linux-x86_64.rpm` | `soundcraft-<ver>-linux-aarch64.rpm` | |
+| Tarball | `soundcraft-<ver>-linux-x86_64.tar.gz` | `soundcraft-<ver>-linux-aarch64.tar.gz` | Unpack anywhere |
+
+### FreeBSD
+
+| Build | File |
+|---|---|
+| x86_64 | `soundcraft-<ver>-freebsd-x86_64.tar.gz` |
+
+### Web (WebAssembly)
+
+| Build | File | Notes |
+|---|---|---|
+| Static site | `soundcraft-web-<ver>.zip` | Runs in a modern browser; host it on any static server |
+
 ## The Crafting Apps
 
 SoundCraft is one of the **Crafting Apps**: free, open-source creative tools from the

docs/releasing.md

@@ -35,9 +35,10 @@ After the draft is published, the workflow refuses to touch that version again,
 
 **Test runs:** *Actions → Release → Run workflow* runs the whole pipeline by hand. The optional
 `version` input (such as `0.2.0-rc.1`) overrides `Cargo.toml` for that run only. The jobs apply it
-with `cargo xtask version set` before building, so the binaries report it too. The run still needs
-the `release` environment, which only the `release` branch can use, so pick that branch in the
-dialog.
+with `cargo xtask version set` before building, so the binaries report it too. Only the signing
+jobs (macOS, Windows) and the draft-release job use the `release` environment, which only the
+`release` branch can use. On any other branch the run is a dry run: Linux, Flatpak, FreeBSD and
+web build and are checked, the signing jobs are refused, and no release is drafted.
 
 ## What gets built
 
@@ -49,11 +50,14 @@ dialog.
 | Windows 11 ARM64 | `soundcraft-<v>-windows-arm64.msi`, `soundcraft-<v>-windows-arm64-portable.zip` | `windows-latest` (cross-compiled; `windows-arm64.yml` installs and runs it on ARM64) |
 | Linux x86_64 | `soundcraft-<v>-linux-x86_64.{AppImage,deb,rpm,tar.gz}` | `ubuntu-22.04` |
 | Linux aarch64 | `soundcraft-<v>-linux-aarch64.{AppImage,deb,rpm,tar.gz}` | `ubuntu-22.04-arm` |
+| AppImage updates | `soundcraft-<v>-linux-{x86_64,aarch64}.AppImage.zsync` | with the AppImage |
+| Flatpak x86_64, aarch64 | `soundcraft-<v>-linux-{x86_64,aarch64}.flatpak` | `ubuntu-24.04`, `ubuntu-24.04-arm` (repackages the Linux tarball) |
 | FreeBSD 14 x86_64 | `soundcraft-<v>-freebsd-x86_64.tar.gz` (a `/usr/local` tree) | FreeBSD 14.3 VM on `ubuntu-latest` |
 | Web | `soundcraft-web-<v>.zip` (static site; see [`packaging/web/README.md`](../packaging/web/README.md)) | `ubuntu-latest` |
 
-The Flatpak manifest (`packaging/linux/flatpak/ai.storyteller.soundcraft.yml`) is kept ready for a
-Flathub submission and validated in CI, but not built there (see Linux below).
+The from-source Flatpak manifest (`packaging/linux/flatpak/ai.storyteller.soundcraft.yml`) is
+kept ready for a Flathub submission; the release's `.flatpak` bundles come from
+`ai.storyteller.soundcraft.bundle.yml` (see Linux below).
 
 ### Audio libraries
 
@@ -68,7 +72,8 @@ plugins), and WebAudio in the browser.
   routes ALSA to the OSS `sound(4)` devices. Without a device the player falls back to its
   silent clock, so the transport still runs.
 - **Flatpak**: alsa-lib and its PulseAudio plugin come with the freedesktop runtime; the
-  manifest grants `--socket=pulseaudio`.
+  manifests grant `--socket=pulseaudio` (PipeWire's pulse server answers on it). No raw ALSA
+  devices and no JACK: SoundCraft doesn't use either.
 - **Web**: browsers start audio only after a user gesture, so the first click in the page may be
   needed before sound plays. The web build has no recording.
 
@@ -131,14 +136,24 @@ Locally on Windows: `dotnet tool install -g wix --version 5.0.2`, then
 MIDI), hicolor icons from 16 px to 512 px plus a scalable SVG, AppStream metainfo, and a
 shared-mime-info file declaring `application/x-soundcraft-session` (`*.scraft`).
 
-- **AppImage** (maintained `AppImage/appimagetool`, static runtime: no libfuse2 needed).
+- **AppImage** (maintained `AppImage/appimagetool`, static runtime: no libfuse2 needed). Each
+  embeds the update information
+  `gh-releases-zsync|storytold|soundcraft|latest|soundcraft-*-linux-<arch>.AppImage.zsync`, and
+  the `.zsync` next to it (written when `zsyncmake` from the `zsync` package is installed, as in
+  CI) lets AppImageUpdate fetch only the changed blocks of the newest non-pre-release.
 - **.deb** and **.rpm** by [nfpm](https://nfpm.goreleaser.com/) from one `nfpm.yaml`; the
   `postinst.sh` hook refreshes the desktop, MIME and icon caches.
 - **.tar.gz** for people who manage their own `/opt` or `~/.local`.
-- **Flatpak**: `packaging/linux/flatpak/ai.storyteller.soundcraft.yml` builds from source on the
-  freedesktop 25.08 runtime with Wayland/X11, `dri`, PulseAudio and `xdg-music`; other files go
-  through the portals. A real build needs vendored crates (`cargo-sources.json` from
-  `flatpak-cargo-generator.py`); the commands are in the manifest's header.
+- **Flatpak**: the `flatpak` job runs `packaging/linux/flatpak-bundle.sh` on the Linux job's
+  tarball (no Rust build) with `flatpak/ai.storyteller.soundcraft.bundle.yml`, then installs the
+  bundle and runs `soundcraft-cli --version` in the sandbox. Install with
+  `flatpak install --user soundcraft-<v>-linux-<arch>.flatpak`. Both manifests use the freedesktop
+  25.08 runtime with Wayland/X11, `dri`, PulseAudio and `xdg-music`; other files go through the
+  portals. For the VST3 and CLAP hosts they grant `~/.vst3` and `~/.clap` read-only and mount
+  Flathub's `org.freedesktop.LinuxAudio.Plugins` extensions (pointed to by `VST3_PATH` and
+  `CLAP_PATH`); system plugin folders aren't visible in the sandbox.
+  `ai.storyteller.soundcraft.yml` builds from source for Flathub and needs vendored crates
+  (`cargo-sources.json` from `flatpak-cargo-generator.py`); the commands are in its header.
 
 Binaries are built on Ubuntu 22.04 and need **glibc ≥ 2.35**. X11, Wayland, xkbcommon, Vulkan
 and EGL are loaded at runtime, so the packages declare them as dependencies or recommendations.
@@ -164,8 +179,8 @@ through WebAudio.
 ## Secrets
 
 All secrets live in the repository's **`release` environment** (*Settings → Environments →
-release*), restricted to the `release` branch. Every job in `release.yml` declares
-`environment: release`. Each secret is optional: if one is missing, that platform's artifacts
+release*), restricted to the `release` branch. Only the jobs that sign (macOS, Windows) and the
+draft-release job declare `environment: release`; the others get no secrets. Each secret is optional: if one is missing, that platform's artifacts
 are unsigned and the run shows a `::warning::`. Scripts never echo secret values; certificates
 are written with `umask 077` and deleted in `always()`/`finally` steps.
 
@@ -197,5 +212,5 @@ those tools. `apps/soundcraft/src/main.rs` sets the runtime window/Dock/taskbar
 
 `.github/workflows/packaging-lint.yml` runs in seconds on any change to `packaging/`, the
 workflows or the icons: actionlint, shellcheck, a PowerShell parse, xmllint (WiX, plists,
-AppStream, MIME), `desktop-file-validate`, `appstreamcli validate`, and a YAML check of the
-Flatpak manifest.
+AppStream, MIME), `desktop-file-validate`, `appstreamcli validate`, and a check that the two
+Flatpak manifests agree on runtime, finish-args and plugin extensions.

packaging/linux/flatpak-bundle.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Repackage a SoundCraft Linux tarball as a single-file Flatpak bundle:
+#
+#   $DIST/soundcraft-<version>-linux-<arch>.flatpak
+#
+# Usage: packaging/linux/flatpak-bundle.sh [--no-test] [TARBALL]
+#
+# TARBALL defaults to $DIST/soundcraft-<version>-linux-<arch>.tar.gz from package.sh. The bundle
+# is built for the host architecture (x86_64 or aarch64), which must match the tarball's.
+# Needs flatpak, flatpak-builder and the SVG pixbuf loader (librsvg2-common) for the host's
+# `appstreamcli compose`; the freedesktop runtime and SDK named in the manifest are
+# installed per-user from Flathub. Unless --no-test, the bundle is then installed per-user and
+# `soundcraft-cli --version` is run inside the sandbox as a smoke test.
+# Manifest: packaging/linux/flatpak/ai.storyteller.soundcraft.bundle.yml.
+set -euo pipefail
+# shellcheck source=../env.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
+HERE="$ROOT/packaging/linux"
+APP_ID=ai.storyteller.soundcraft
+FLATHUB=https://dl.flathub.org/repo/flathub.flatpakrepo
+
+TEST=1
+TARBALL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-test) TEST=0; shift ;;
+    -h | --help) sed -n '2,14p' "$0"; exit 0 ;;
+    -*) echo "unknown argument: $1" >&2; exit 2 ;;
+    *) TARBALL="$1"; shift ;;
+  esac
+done
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64) ;;
+  aarch64 | arm64) ARCH=aarch64 ;;
+  *) echo "unsupported architecture $ARCH" >&2; exit 2 ;;
+esac
+BASENAME="soundcraft-$VERSION-linux-$ARCH"
+TARBALL="${TARBALL:-$DIST/$BASENAME.tar.gz}"
+[ -f "$TARBALL" ] || { echo "error: $TARBALL not found (run packaging/linux/package.sh --formats tar first)" >&2; exit 1; }
+for tool in flatpak flatpak-builder; do
+  command -v "$tool" >/dev/null || { echo "error: $tool not found (apt install flatpak flatpak-builder librsvg2-common)" >&2; exit 1; }
+done
+
+echo "==> SoundCraft $VERSION Flatpak bundle for $ARCH from $(basename "$TARBALL")"
+
+WORK="$CARGO_TARGET_DIR/flatpak-bundle"
+rm -rf "$WORK"
+mkdir -p "$WORK/stage"
+tar -xzf "$TARBALL" -C "$WORK/stage" --strip-components=1
+[ -x "$WORK/stage/bin/soundcraft" ] || { echo "error: $TARBALL has no bin/soundcraft" >&2; exit 1; }
+cp "$HERE/flatpak/$APP_ID.bundle.yml" "$WORK/$APP_ID.yml"
+
+flatpak remote-add --user --if-not-exists flathub "$FLATHUB"
+# --disable-rofiles-fuse: no FUSE in containers and CI runners.
+flatpak-builder --user --install-deps-from=flathub --disable-rofiles-fuse --force-clean \
+  --default-branch=stable --repo="$WORK/repo" --state-dir="$WORK/state" "$WORK/build" "$WORK/$APP_ID.yml"
+
+OUT="$DIST/$BASENAME.flatpak"
+# --runtime-repo lets `flatpak install` fetch the freedesktop runtime from Flathub if missing.
+flatpak build-bundle --runtime-repo="$FLATHUB" "$WORK/repo" "$OUT" "$APP_ID" stable
+echo "wrote $OUT"
+
+if [ "$TEST" = 1 ]; then
+  flatpak install --user -y --noninteractive --reinstall "$OUT"
+  flatpak info --user "$APP_ID"
+  flatpak run --command=soundcraft-cli "$APP_ID" --version
+  flatpak run --command=sh "$APP_ID" -c 'ls /app/share/applications /app/share/metainfo /app/share/mime/packages /app/share/icons/hicolor/scalable/apps'
+fi
+echo "==> done"
+ls -lh "$OUT"

packaging/linux/flatpak/ai.storyteller.soundcraft.bundle.yml

@@ -0,0 +1,73 @@
+# Flatpak manifest for the single-file bundle attached to every GitHub release
+# (soundcraft-<version>-linux-<arch>.flatpak). Build it with packaging/linux/flatpak-bundle.sh.
+#
+# It repackages the release's own Linux tarball (soundcraft-<version>-linux-<arch>.tar.gz,
+# built on Ubuntu 22.04 by package.sh) instead of compiling Rust inside flatpak-builder: no
+# network and no vendored crate sources during the build, a few seconds instead of 20+ minutes,
+# and byte-for-byte the same binaries as the AppImage/deb/rpm. The script unpacks the tarball
+# into `stage/` next to a copy of this file. The binaries need glibc >= 2.35 and load X11,
+# Wayland, xkbcommon, Vulkan and libasound at runtime; the freedesktop runtime has all of them
+# (plus alsa-lib's PulseAudio plugin), and the GPU driver comes from its
+# org.freedesktop.Platform.GL extension.
+#
+# ai.storyteller.soundcraft.yml (same directory) is the from-source manifest for Flathub. Keep
+# runtime-version, finish-args and add-extensions identical in both (packaging-lint checks this).
+id: ai.storyteller.soundcraft
+runtime: org.freedesktop.Platform
+runtime-version: '25.08'
+sdk: org.freedesktop.Sdk
+command: soundcraft
+finish-args:
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
+  - --socket=wayland
+  - --socket=fallback-x11
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
+  - --share=ipc
+  # GPU access for the wgpu UI (Vulkan, or GL as a fallback).
+  - --device=dri
+  # Playback and recording. cpal talks to ALSA; the runtime's alsa-lib routes ALSA through its
+  # PulseAudio plugin to this socket, which PipeWire's pulse server provides on modern desktops
+  # (and PulseAudio itself on older ones). Deliberately not granted: --device=all (raw /dev/snd
+  # for direct ALSA hardware access, which would bypass the sound server) and JACK, which
+  # SoundCraft doesn't use (cpal's jack feature is off; there is no live MIDI I/O either).
+  - --socket=pulseaudio
+  # Open/Save dialogs use the file-chooser portal (rfd) and drag-and-drop the document portal,
+  # so broad filesystem access isn't needed. Music is granted for sessions and their
+  # "Audio Files" folders opened by path from the command line.
+  - --filesystem=xdg-music
+  # VST3 and CLAP plugin hosts. The per-user plugin folders the hosts scan, read-only.
+  # System folders (/usr/lib/vst3, /usr/lib/clap) aren't reachable from the sandbox, and plugins
+  # there are linked against the host's libraries rather than the runtime's; sandboxed plugins
+  # come from Flatpak extensions instead (add-extensions below), found through these paths.
+  - --filesystem=~/.vst3:ro
+  - --filesystem=~/.clap:ro
+  - --env=VST3_PATH=/app/extensions/Plugins/vst3
+  - --env=CLAP_PATH=/app/extensions/Plugins/clap
+# Flathub's shared audio-plugin extension point (org.freedesktop.LinuxAudio.Plugins.*, the one
+# Ardour, Bitwig and friends use). Optional: nothing is downloaded unless the user installs a
+# plugin extension; merge-dirs lets every installed one appear under .../Plugins/{vst3,clap}.
+add-extensions:
+  org.freedesktop.LinuxAudio.Plugins:
+    directory: extensions/Plugins
+    version: '25.08'
+    add-ld-path: lib
+    merge-dirs: vst3;clap
+    subdirectories: true
+    no-autodownload: true
+modules:
+  - name: soundcraft
+    buildsystem: simple
+    build-commands:
+      - install -Dm755 bin/soundcraft /app/bin/soundcraft
+      - install -Dm755 bin/soundcraft-cli /app/bin/soundcraft-cli
+      - install -Dm644 share/applications/ai.storyteller.soundcraft.desktop /app/share/applications/ai.storyteller.soundcraft.desktop
+      # Session files; the runtime's shared-mime-info already knows WAV, AIFF, FLAC, MP3 and MIDI.
+      - install -Dm644 share/mime/packages/ai.storyteller.soundcraft.xml /app/share/mime/packages/ai.storyteller.soundcraft.xml
+      # Already has the release's version and date substituted by package.sh.
+      - install -Dm644 share/metainfo/ai.storyteller.soundcraft.metainfo.xml /app/share/metainfo/ai.storyteller.soundcraft.metainfo.xml
+      - mkdir -p /app/share/icons /app/share/doc && cp -R share/icons/hicolor /app/share/icons/ && cp -R share/doc/soundcraft /app/share/doc/
+      # Mount point for the plugin extensions (add-extensions).
+      - install -d /app/extensions/Plugins
+    sources:
+      - type: dir
+        path: stage

packaging/linux/flatpak/ai.storyteller.soundcraft.yml

@@ -8,6 +8,9 @@
 #   flatpak run ai.storyteller.soundcraft
 #
 # For Flathub, replace the `dir` source with a `git` source pinned to a release tag and commit.
+# ai.storyteller.soundcraft.bundle.yml repackages the release tarball into the .flatpak attached
+# to each GitHub release; keep runtime-version, finish-args and add-extensions identical in both
+# (packaging-lint checks this).
 #
 # Audio: cpal talks to ALSA. alsa-lib (headers in the Sdk, the library in the Platform) and its
 # PulseAudio plugin ship with the freedesktop runtime, which routes ALSA through the PulseAudio
@@ -20,16 +23,42 @@ sdk-extensions:
   - org.freedesktop.Sdk.Extension.rust-stable
 command: soundcraft
 finish-args:
-  - --share=ipc
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
   - --socket=wayland
   - --socket=fallback-x11
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
+  - --share=ipc
+  # GPU access for the wgpu UI (Vulkan, or GL as a fallback).
   - --device=dri
-  # Playback and recording (ALSA through the PulseAudio/PipeWire socket).
+  # Playback and recording. cpal talks to ALSA; the runtime's alsa-lib routes ALSA through its
+  # PulseAudio plugin to this socket, which PipeWire's pulse server provides on modern desktops
+  # (and PulseAudio itself on older ones). Deliberately not granted: --device=all (raw /dev/snd
+  # for direct ALSA hardware access, which would bypass the sound server) and JACK, which
+  # SoundCraft doesn't use (cpal's jack feature is off; there is no live MIDI I/O either).
   - --socket=pulseaudio
-  # Open/Save dialogs use the file-chooser portal (rfd), and drag-and-drop uses the document
-  # portal, so broad filesystem access isn't needed. Music is granted for sessions and their
+  # Open/Save dialogs use the file-chooser portal (rfd) and drag-and-drop the document portal,
+  # so broad filesystem access isn't needed. Music is granted for sessions and their
   # "Audio Files" folders opened by path from the command line.
   - --filesystem=xdg-music
+  # VST3 and CLAP plugin hosts. The per-user plugin folders the hosts scan, read-only.
+  # System folders (/usr/lib/vst3, /usr/lib/clap) aren't reachable from the sandbox, and plugins
+  # there are linked against the host's libraries rather than the runtime's; sandboxed plugins
+  # come from Flatpak extensions instead (add-extensions below), found through these paths.
+  - --filesystem=~/.vst3:ro
+  - --filesystem=~/.clap:ro
+  - --env=VST3_PATH=/app/extensions/Plugins/vst3
+  - --env=CLAP_PATH=/app/extensions/Plugins/clap
+# Flathub's shared audio-plugin extension point (org.freedesktop.LinuxAudio.Plugins.*, the one
+# Ardour, Bitwig and friends use). Optional: nothing is downloaded unless the user installs a
+# plugin extension; merge-dirs lets every installed one appear under .../Plugins/{vst3,clap}.
+add-extensions:
+  org.freedesktop.LinuxAudio.Plugins:
+    directory: extensions/Plugins
+    version: '25.08'
+    add-ld-path: lib
+    merge-dirs: vst3;clap
+    subdirectories: true
+    no-autodownload: true
 build-options:
   append-path: /usr/lib/sdk/rust-stable/bin
 modules:
@@ -51,6 +80,8 @@ modules:
         install -d /app/share/metainfo;
         sed -e "s/@VERSION@/$version/" -e "s/@DATE@/$(date -u +%Y-%m-%d)/"
         packaging/linux/ai.storyteller.soundcraft.metainfo.xml.in > /app/share/metainfo/ai.storyteller.soundcraft.metainfo.xml
+      # Mount point for the plugin extensions (add-extensions).
+      - install -d /app/extensions/Plugins
     sources:
       - type: dir
         path: ../../..

packaging/linux/package.sh

@@ -2,6 +2,7 @@
 # Build and package SoundCraft for Linux (<arch> is x86_64 or aarch64):
 #
 #   $DIST/soundcraft-<version>-linux-<arch>.AppImage  any distro with glibc >= the build host's
+#   $DIST/soundcraft-<version>-linux-<arch>.AppImage.zsync  delta updates (needs zsyncmake)
 #   $DIST/soundcraft-<version>-linux-<arch>.deb       Debian, Ubuntu, Mint, Pop!_OS, ...
 #   $DIST/soundcraft-<version>-linux-<arch>.rpm       Fedora, openSUSE, RHEL, ...
 #   $DIST/soundcraft-<version>-linux-<arch>.tar.gz    plain FHS-style tree (bin/, share/)
@@ -10,7 +11,8 @@
 #
 # Needs: cargo; nfpm for deb/rpm (https://nfpm.goreleaser.com); appimagetool for the AppImage
 # (downloaded into $CARGO_TARGET_DIR if missing). Build on an old distro (CI: Ubuntu 22.04,
-# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli.
+# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli,
+# zsyncmake (the zsync package) for the AppImage's .zsync.
 set -euo pipefail
 # shellcheck source=../env.sh
 . "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
@@ -23,7 +25,7 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --skip-build) SKIP_BUILD=1; shift ;;
     --formats) FORMATS="$2"; shift 2 ;;
-    -h | --help) sed -n '2,15p' "$0"; exit 0 ;;
+    -h | --help) sed -n '2,17p' "$0"; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 2 ;;
   esac
 done
@@ -108,11 +110,29 @@ if has appimage; then
       chmod +x "$TOOL"
     fi
   fi
-  OUT="$DIST/$BASENAME.AppImage"
+  # Absolute, because appimagetool runs in $DIST below (CARGO_TARGET_DIR or APPIMAGETOOL may be
+  # relative).
+  OUT="$(cd "$DIST" && pwd)/$BASENAME.AppImage"
+  APPDIR="$(cd "$APPDIR" && pwd)"
+  TOOL="$(cd "$(dirname "$TOOL")" && pwd)/$(basename "$TOOL")"
+  # A .zsync left by an earlier run would hide a missing zsyncmake and describe another file.
+  rm -f "$OUT.zsync"
+  # Update information: AppImageUpdate, AppImageLauncher and the like read it from the file and
+  # fetch only the blocks that changed in a newer release, through the .zsync published next to
+  # each AppImage on GitHub Releases. `latest` is the newest published release that is not a
+  # pre-release. A fork's builds point at its own releases through GITHUB_REPOSITORY.
+  REPO="${GITHUB_REPOSITORY:-storytold/soundcraft}"
+  UPDATE_INFO="gh-releases-zsync|${REPO%%/*}|${REPO#*/}|latest|soundcraft-*-linux-$ARCH.AppImage.zsync"
   # Extract-and-run: works without FUSE (containers, CI). The output embeds the static runtime,
-  # so users don't need libfuse2 either.
-  ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream "$APPDIR" "$OUT"
+  # so users don't need libfuse2 either. With zsyncmake on the host (CI installs the zsync
+  # package) appimagetool also writes the .zsync, into its working directory, hence the cd.
+  (cd "$DIST" && ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream -u "$UPDATE_INFO" "$APPDIR" "$OUT")
   echo "wrote $OUT"
+  if [ -s "$OUT.zsync" ]; then
+    echo "wrote $OUT.zsync"
+  else
+    warn "zsyncmake not found, so $OUT.zsync was not written; AppImage delta updates need it"
+  fi
 fi
 
 "$STAGE/usr/bin/soundcraft-cli" --version