Files

T

Jatin K MalikandGitHub 9886e8cb9d feat(ui): add auto-start on boot support (#207 )

* feat(ui): add auto-start on boot support

- Add --start-minimized CLI flag for autostart entry
- Create autostart_manager.py to handle XDG autostart desktop entry
- Add autostart config option in config_manager.py
- Add Start on Login toggle in Settings dialog
- Add Start Minimized toggle in Settings dialog
- Add Start on Login checkbox in system tray menu
- Add first-run dialog to ask about autostart preference

Closes #184

* fix(test): add first_run: False to mock config settings

The tests were failing with StopIteration because main() now checks
for first_run and shows a dialog if True. By setting first_run: False
in the mock config, we skip the first-run dialog code path.

* fix(ui): harden autostart behavior across Linux sessions

Use XDG-compliant autostart paths and robust Exec command resolution, keep first-run prompt semantics correct, and fix GTK toggle handling so state changes are applied reliably.

* docs(autostart): document XDG startup model and limits

Clarify that Vocalinux uses desktop-session XDG autostart, not systemd services, and explain compatibility expectations for mainstream DEs versus minimal/custom WM sessions.

* feat(ui): add first-run quick-start guidance text

Expand the welcome dialog with concise first-time usage guidance and clear direction to the tray menu Settings entry while preserving the existing autostart decision flow.

* fix(uninstall): remove XDG autostart desktop entry

Ensure uninstall removes ~/.config autostart registration and reports leftover autostart entries during verification.

* fix(install): ignore defunct processes in running-check

Filter installer process detection to exclude defunct entries and installer/uninstaller shells so stale zombie rows do not block reinstall.

* fix(uninstall): ignore defunct processes in running-check

Use filtered process detection so zombie entries and installer shells do not trigger false running-process warnings during uninstall.

2026-02-21 15:06:20 -08:00

11 KiB

Raw Blame History

Linux Distribution Compatibility

Implementation Status

The cross-distribution compatibility improvements have been implemented in phases:

Phase	Status	Description
Phase 1	✅ Complete	Dynamic GI_TYPELIB_PATH detection using pkg-config, multi-arch support, ALSA library fallbacks
Phase 2	✅ Complete	Enhanced distro detection (Gentoo, Alpine, Void, Solus, Mageia)
Phase 3	✅ Complete	System dependency checker, improved error messages
Phase 4	✅ Complete	CI test matrix, pkg-config as core dependency
Phase 5	✅ Complete	Fixed remaining hardcoded GI_TYPELIB_PATH values in install.sh and CI workflow
Phase 6	✅ Complete	Added wrapper script verification tests, updated documentation
Phase 7	📋 Planned	Flatpak packaging for universal distribution support
Phase 8	📋 Planned	Snap packaging for Ubuntu Software Store

Technical Implementation

Dynamic GI_TYPELIB_PATH Detection

The installer now uses a robust multi-step approach to detect the correct GI_TYPELIB_PATH across different distributions:

Primary Method: Uses pkg-config --variable=typelibdir gobject-introspection-1.0 (most reliable)
Fallback Paths: Checks common distribution-specific paths in priority order:
- Ubuntu/Debian multi-arch: /usr/lib/x86_64-linux-gnu/girepository-1.0
- ARM64: /usr/lib/aarch64-linux-gnu/girepository-1.0
- Fedora/RHEL: /usr/lib64/girepository-1.0
- Arch/Generic: /usr/lib/girepository-1.0
- Local installs: /usr/local/lib/girepository-1.0
Architecture Support: Detected paths for x86_64, ARM64, ARMHF, RISC-V, POWER, and s390x

Wrapper Scripts

The installer creates wrapper scripts (~/.local/bin/vocalinux and ~/.local/bin/vocalinux-gui) that:

Set the correct GI_TYPELIB_PATH environment variable
Handle input group permissions for Wayland keyboard shortcuts
Provide seamless cross-distro compatibility

Desktop Entry

The .desktop entry is automatically configured with the detected GI_TYPELIB_PATH, ensuring the application launches correctly from the application menu regardless of distribution.

Officially Supported Distributions

These distributions are tested and known to work well with Vocalinux:

Distribution	Version	Status	Notes
Ubuntu	22.04+	✅ Full Support	Primary target, most thoroughly tested
Debian	11+, Testing	✅ Full Support	Well tested, use Ayatana AppIndicator on Debian 11+
Fedora	39+	✅ Good Support	Uses lib64 paths, fully supported
Arch Linux	Rolling	✅ Good Support	Community tested, rolling release compatible
openSUSE	Tumbleweed	✅ Good Support	Good support with zypper package manager

Experimental Support

These distributions may work but have known limitations or are less tested:

Distribution	Status	Known Issues
Gentoo	⚠️ Experimental	No package manager support, manual install required. Packages are compiled from source which takes longer.
Alpine Linux	⚠️ Experimental	Uses musl libc (not glibc). Some Python packages may not have pre-built wheels and may need to be compiled.
Void Linux	⚠️ Experimental	Untested, manual install required. Uses xbps package manager.
Solus	⚠️ Experimental	Untested, manual install required. Uses eopkg package manager.
Mageia	⚠️ Experimental	Untested, uses dnf/urpmi package managers.
Linux Mint	✅ Good Support	Based on Ubuntu, inherits Ubuntu compatibility
Pop!_OS	✅ Good Support	Based on Ubuntu, inherits Ubuntu compatibility
elementary OS	✅ Good Support	Based on Ubuntu, inherits Ubuntu compatibility
Zorin OS	✅ Good Support	Based on Ubuntu, inherits Ubuntu compatibility
Manjaro	✅ Good Support	Based on Arch, inherits Arch compatibility
EndeavourOS	✅ Good Support	Based on Arch, inherits Arch compatibility

Not Supported

These distributions are known to be incompatible:

Distribution	Status	Reason
NixOS	❌ Not Supported	Completely different filesystem layout (/nix/store), incompatible with standard installer

Requirements by Distribution

Ubuntu/Debian-based

sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 \
  portaudio19-dev python3-dev python3-venv pkg-config

Note for Debian 11+: Use gir1.2-ayatanaappindicator3-0.1 instead of gir1.2-appindicator3-0.1

Fedora/RHEL-based

sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

Arch Linux-based

sudo pacman -S --needed python-gobject gtk3 gobject-introspection \
  portaudio python pkg-config

openSUSE

sudo zypper install -y python3-gobject python3-gobject-cairo gtk3 \
  gobject-introspection-devel portaudio-devel python3-devel \
  python3-virtualenv pkg-config

Gentoo

sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 \
  media-libs/portaudio dev-lang/python:3.8

Note: Gentoo compiles packages from source, which will take longer.

Alpine Linux

sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev \
  py3-virtualenv pkgconf

Note: Alpine uses musl libc. Some Python packages may need to be compiled from source.

Void Linux

sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libappindicator \
  gobject-introspection portaudio-devel python3-devel pkg-config

Solus

sudo eopkg install python3-pip python3-gobject gtk3 libappindicator \
  gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config

Mageia

sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config
# or
sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config

Text Injection Tools

Vocalinux requires text injection tools to work with X11 or Wayland:

For X11

xdotool: Required for X11 sessions

For Wayland

wtype: Recommended for Wayland native sessions
ydotool: Universal alternative that works with both X11 and Wayland
xdotool: May work via XWayland fallback

Installation by Distribution

# Ubuntu/Debian/Fedora/Arch/openSUSE
sudo apt install xdotool wtype     # Ubuntu/Debian
sudo dnf install xdotool wtype     # Fedora
sudo pacman -S xdotool wtype       # Arch
sudo zypper install xdotool wtype  # openSUSE

Manual Installation

For unsupported or experimental distributions:

Run the dependency checker:
```
bash scripts/check-system-deps.sh
```
Install missing dependencies using your package manager based on the checker output
Run the installer with --skip-system-deps:
```
./install.sh --skip-system-deps
```

Or install from source in a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -e .[whisper]

Desktop Environment Compatibility

Desktop Environment	Status	Notes
GNOME	✅ Full Support	Primary target, uses AppIndicator
KDE Plasma	✅ Full Support	Works with AppIndicator
Xfce	✅ Full Support	Works with AppIndicator
Cinnamon	✅ Full Support	Works with AppIndicator
MATE	✅ Full Support	Works with AppIndicator
LXQt	✅ Full Support	Works with AppIndicator
sway	✅ Good Support	Wayland native, uses wtype
i3	✅ Good Support	X11, uses xdotool
Hyprland	⚠️ Experimental	Wayland, may need wtype configuration

Autostart Compatibility

Vocalinux uses XDG autostart desktop entries for "Start on Login".

Desktop-session autostart file location:
- $XDG_CONFIG_HOME/autostart/vocalinux.desktop, or
- ~/.config/autostart/vocalinux.desktop (fallback)
This launches Vocalinux as a user GUI app after login.
Vocalinux does not create a systemd service/unit for this feature.

Practical caveat:

Mainstream desktop environments generally honor XDG autostart.
Minimal/custom WM sessions may need an explicit autostart manager or WM startup hook.

Display Server

Display Server	Status	Notes
X11	✅ Full Support	Uses xdotool for text injection
Wayland	✅ Full Support	Uses wtype (native) or xdotool (XWayland)
XWayland	✅ Full Support	Automatically detected, falls back to xdotool if needed

Architecture Support

Architecture	Status	Notes
x86_64 (AMD64)	✅ Full Support	Primary target
arm64 (AArch64)	✅ Good Support	Tested on Raspberry Pi, ARM64 servers
armhf	⚠️ Experimental	Limited testing
riscv64	⚠️ Experimental	Limited testing, may need to compile dependencies

Reporting Issues

When reporting issues, please include:

Distribution information:
```
cat /etc/os-release
```

Desktop environment:

echo $XDG_CURRENT_DESKTOP
echo $SESSION_TYPE

Dependency checker output:
```
bash scripts/check-system-deps.sh
```
Python version:
```
python3 --version
```
Error messages or logs:
- Any error messages from the installer
- Output from running vocalinux-gui from terminal
- Relevant journal logs if applicable
Steps to reproduce:
- What you were trying to do
- What happened instead
- Expected behavior

Testing Checklist

Use this checklist when testing on a new distribution:

Pre-Install

Run dependency checker: bash scripts/check-system-deps.sh
Note missing packages
Check desktop environment
Check display server (X11/Wayland)

Installation

Run installer: ./install.sh
Check for errors during installation
Verify virtual environment was created
Check wrapper scripts exist

Post-Install

Launch from terminal: ~/.local/bin/vocalinux-gui
Launch from application menu
Verify tray icon appears
Test keyboard shortcuts (Ctrl+Alt+M by default)
Test audio recording
Test text injection in different applications
Test Settings dialog opens correctly
Test model download if using Whisper

Known Issues to Watch For

AppIndicator not showing in tray
Audio device not detected
Text injection not working
Model download failures
Permission errors with udev/input

Contributing Compatibility Fixes

If you successfully get Vocalinux working on an unsupported or experimental distribution:

Test thoroughly using the checklist above
Document any distribution-specific requirements
Submit a PR with:
- Distribution detection logic (if needed)
- Package installation commands
- Any patches or workarounds required
- Update to this compatibility document

11 KiB Raw Blame History