Skip to content

README.md

Latest commit

 

History

History
106 lines (80 loc) · 4.16 KB

README.md

File metadata and controls

106 lines (80 loc) · 4.16 KB
Raw

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

Read this first: the submission, flathub/flathub#9368, was closed on 2026-07-23 on policy grounds — the generative-AI policy, plus a "tray-only application" reading. Nothing below was the reason it failed, and re-submitting without addressing that is a repeat. See #167 for the channel decision.

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

    sources:
  - type: git
    url: https://github.com/VocaHQ/vocalinux.git
    tag: v0.16.2
    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/.