voculinux/packaging/flatpak/README.md

Vocalinux Flatpak Packaging

Manifest and AppStream metadata for building Vocalinux as a Flatpak.

Current Scope

The manifest ships the default whisper_cpp engine only. VOSK is omitted because the PyPI package is wheel-only (no sdist), so a Flathub-ready VOSK build would need to compile VOSK and its native deps from source.

Global keyboard shortcuts use evdev (/dev/input). Text injection uses wl-copy + ydotool Ctrl+V (instant paste into native Wayland apps). Character-by-character ydotool type is only a fallback. xdotool remains for pure X11/XWayland clients.

Permissions: --socket=wayland (clipboard), --socket=x11 (xdotool fallback), --device=all (evdev hotkeys + uinput; Flatpak has no narrower uinput flag).

Local Build

# one-time runtime/SDK
flatpak install flathub org.gnome.Platform//50 org.gnome.Sdk//50

# from repo root — add flags as needed:
#   --user --install     install for the current user
#   --repo=repo          export a local repo (then bundle or lint)
#   --compose-url-policy=full --mirror-screenshots-url=https://dl.flathub.org/media
flatpak-builder --force-clean build-dir packaging/flatpak/com.vocalinux.Vocalinux.yml

flatpak run com.vocalinux.Vocalinux --debug

# single-file bundle (after a --repo=repo build)
flatpak build-bundle repo vocalinux.flatpak com.vocalinux.Vocalinux
# elsewhere: flatpak install --user vocalinux.flatpak

Lint (needs org.flatpak.Builder):

flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest packaging/flatpak/com.vocalinux.Vocalinux.yml
flatpak run --command=flatpak-builder-lint org.flatpak.Builder builddir build-dir
flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo   # if you used --repo=repo

Prefer flatpak run after --install for GUI testing. On GNOME runtimes with glycin loaders, flatpak-builder --run can fail to load themed SVG icons for an uninstalled stable app ID; it is still fine for non-GUI smokes:

flatpak-builder --run build-dir packaging/flatpak/com.vocalinux.Vocalinux.yml \
  python3 -c 'from pywhispercpp.model import Model; print("pywhispercpp ok")'

Python Dependencies

python3-dependencies.yaml is generated with flatpak-pip-generator (offline builds). Regenerate when pyproject.toml deps change:

pipx run flatpak-pip-generator \
  --runtime org.gnome.Sdk//50 \
  --yaml \
  --ignore-pkg 'vosk>=0.3.45' "PyGObject; sys_platform == 'linux'" \
  --output packaging/flatpak/python3-dependencies \
  pywhispercpp pydub pynput evdev requests tqdm numpy pyaudio python-xlib psutil lxml \
  meson-python pyproject-metadata

python3-build-dependencies.yaml is a small hand-maintained helper so --no-build-isolation builds can import mesonpy before NumPy is built.

Flathub Submission Notes

1. Change the vocalinux module source from type: dir to a tagged release:

   sources:
     - type: git
       url: https://github.com/jatinkrmalik/vocalinux.git
       tag: v0.15.0
       commit: <release-commit-sha>
   

2. Keep build-time network access disabled; only declared sources.

3. Re-run AppStream validation and flatpak-builder locally.

4. Be ready to justify sandbox permissions (IBus and StatusNotifier D-Bus talk names).

Manifest Details

• Runtime / SDK: org.gnome.Platform//50, org.gnome.Sdk//50
• Mic: --socket=pulseaudio · GPU: --device=dri · models: --share=network
• Input: --device=all (evdev hotkeys + ydotool/uinput)
• Injection: packaged wl-copy, ydotool/ydotoold, plus xdotool/xsel fallback
• Display: --socket=wayland (clipboard) and --socket=x11 (xdotool fallback)
• IBus: --talk-name=org.freedesktop.IBus
• Tray: --talk-name=org.kde.StatusNotifierWatcher

Config and models use Flatpak XDG dirs under ~/.var/app/com.vocalinux.Vocalinux/.