xavierk/voculinux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(identity): rename user-visible identity to voculinux with one-time legacy import

Browse Source 
The fork takes its own name everywhere a user can see it: binaries
(voculinux, voculinux-gui), desktop entry, autostart, tray, D-Bus
namespace (com.voculinux.Voculinux, no alias for the old name),
config/data/cache dirs, single-instance lock, IBus engine identity,
tray icons, resource prefixes, VOCULINUX_* environment names, and the
update-checker user agent. The internal Python module stays vocalinux
and the distribution metadata keeps the upstream URLs as provenance.

On first run a previous Vocalinux install's config.json, custom
dictionary, and portal restore token are copied once into the new
locations (new config always wins, no merge, no write-back); models
re-resolve through the pinned-checksum download path. An offline
naming-sweep test proves no old-name strings remain on user-visible
surfaces outside the allowlist.

Refs #18
This commit is contained in:
soubarnak
2026-11-06 01:29:39 +05:30
parent c565e6d946
commit ea7be5f111
251 changed files with 2449 additions and 1991 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DISTRO_COMPATIBILITY.md
+42 -42
View File
@@ -1,8 +1,8 @@
# Linux distribution compatibility
How Vocalinux behaves across distributions, what is tested, and what to install manually when needed.
How Voculinux behaves across distributions, what is tested, and what to install manually when needed.
For install steps, prefer [INSTALL.md](INSTALL.md). Flatpak packaging (useful on immutable or non-standard layouts): [packaging/flatpak/README.md](../packaging/flatpak/README.md). Snap Store listing: [snapcraft.io/vocalinux](https://snapcraft.io/vocalinux) (`--edge`; pack/upload steps in [INSTALL.md](INSTALL.md)). Flatpak is not on Flathub: submission [flathub#9368](https://github.com/flathub/flathub/pull/9368) closed 2026-07-23 on policy grounds; channel tracked in [#167](https://github.com/VocaHQ/vocalinux/issues/167).
For install steps, prefer [INSTALL.md](INSTALL.md). Flatpak packaging (useful on immutable or non-standard layouts): [packaging/flatpak/README.md](../packaging/flatpak/README.md). Snap Store listing: [snapcraft.io/voculinux](https://snapcraft.io/voculinux) (`--edge`; pack/upload steps in [INSTALL.md](INSTALL.md)). Flatpak is not on Flathub: submission [flathub#9368](https://github.com/flathub/flathub/pull/9368) closed 2026-07-23 on policy grounds; channel tracked in [#167](https://github.com/VocaHQ/vocalinux/issues/167).
## Cross-distro behavior
@@ -24,7 +24,7 @@ The installer uses a multi-step approach to detect the correct GI_TYPELIB_PATH:
### Wrapper Scripts
The installer creates wrapper scripts (`~/.local/bin/vocalinux` and `~/.local/bin/vocalinux-gui`) that:
The installer creates wrapper scripts (`~/.local/bin/voculinux` and `~/.local/bin/voculinux-gui`) that:
- Set the correct `GI_TYPELIB_PATH` environment variable
- Handle input group permissions for Wayland keyboard shortcuts
- Provide seamless cross-distro compatibility
@@ -35,7 +35,7 @@ The `.desktop` entry is automatically configured with the detected `GI_TYPELIB_P
## Officially Supported Distributions
These distributions are tested and known to work well with Vocalinux. A
These distributions are tested and known to work well with Voculinux. A
derivative is judged by the Python and package repositories it ships rather
than by its own version number, which rarely tracks the base release. In
particular, `install.sh` does not interpret a Debian-based derivative's product
@@ -94,7 +94,7 @@ sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-ibus-1.0 gir1.2-gdkpixbuf-2
### Debian-specific notes
Debian's standard repositories differ from Ubuntu in a few ways that matter for Vocalinux:
Debian's standard repositories differ from Ubuntu in a few ways that matter for Voculinux:
**pywhispercpp build prerequisites.** On a clean Debian install the following packages are not
pulled in transitively (unlike Ubuntu) but are required when `pywhispercpp` must be compiled
@@ -125,16 +125,16 @@ package-scoped flag to avoid compiling unrelated deps like NumPy from source (wh
long time and can fail):
```bash
source ~/.local/share/vocalinux/venv/bin/activate
source ~/.local/share/voculinux/venv/bin/activate
PYWHISPERCPP_CLEAN=1 pip install --force-reinstall --no-binary=pywhispercpp pywhispercpp
deactivate
```
**Verifying libwhisper.so resolution.** If Vocalinux starts with
**Verifying libwhisper.so resolution.** If Voculinux starts with
`libwhisper.so.1: cannot open shared object file`, check for unresolved symbols:
```bash
ldd $(find ~/.local/share/vocalinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'
ldd $(find ~/.local/share/voculinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'
```
If any libraries are listed, re-run the installer with `--rebuild-whispercpp` or switch to
@@ -215,11 +215,11 @@ sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \
## PyPI, pip, and pipx Installation
The PyPI package is useful when you want a standard Python package install, or
when you want to manage Vocalinux with `pipx`. However, **Vocalinux requires
when you want to manage Voculinux with `pipx`. However, **Voculinux requires
system desktop packages** that cannot be installed by pip or pipx.
Use the official installer when possible. It installs the required system
packages, creates the virtual environment, installs Vocalinux, sets up desktop
packages, creates the virtual environment, installs Voculinux, sets up desktop
integration, and downloads the default speech model:
```bash
@@ -229,8 +229,8 @@ bash /tmp/vl.sh
### Important: Install System Packages First
Before running `pip install vocalinux`, `pip install "vocalinux[vosk]"`, or
`pipx install vocalinux`, you **must** install the required system packages:
Before running `pip install voculinux`, `pip install "voculinux[vosk]"`, or
`pipx install voculinux`, you **must** install the required system packages:
#### Ubuntu/Debian
```bash
@@ -272,8 +272,8 @@ sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 ibus typeli
2. **Create a virtual environment with system site-packages enabled**:
```bash
python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
python3 -m venv ~/.local/share/voculinux-pypi/venv --system-site-packages
source ~/.local/share/voculinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
```
@@ -281,15 +281,15 @@ sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 ibus typeli
as `python3-gi`, which are often more reliable than building PyGObject from
source in a venv.
3. **Install Vocalinux from PyPI**:
3. **Install Voculinux from PyPI**:
```bash
pip install vocalinux
# vosk engine: pip install "vocalinux[vosk]"
pip install voculinux
# vosk engine: pip install "voculinux[vosk]"
```
4. **Run Vocalinux**:
4. **Run Voculinux**:
```bash
vocalinux
voculinux
```
### pipx Installation Steps
@@ -311,20 +311,20 @@ sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 ibus typeli
pipx ensurepath
```
3. **Install Vocalinux**:
3. **Install Voculinux**:
```bash
pipx install vocalinux
# vosk engine: pipx install "vocalinux[vosk]"
pipx install voculinux
# vosk engine: pipx install "voculinux[vosk]"
```
4. **Run Vocalinux**:
4. **Run Voculinux**:
```bash
vocalinux
voculinux
```
### Why System Packages Are Required
Vocalinux uses GTK3 for its GUI, AppIndicator/Ayatana for the system tray icon,
Voculinux uses GTK3 for its GUI, AppIndicator/Ayatana for the system tray icon,
PortAudio for microphone capture, and tools such as `xdotool`, `wtype`, and clipboard utilities (`wl-clipboard`, `xclip`, `xsel`) for
text injection and layout-independent Wayland paste fallback. These are system libraries and desktop tools that must be
installed with your distribution's package manager. Python packages from PyPI
@@ -333,20 +333,20 @@ typelibs, tray support, audio development libraries, or text injection binaries.
### Troubleshooting pip/pipx Installation
If `vocalinux` fails to start:
If `voculinux` fails to start:
1. **Check for missing system packages** - The error message will indicate which packages are missing
2. **Verify GI_TYPELIB_PATH** - In rare cases, you may need to set this environment variable:
```bash
export GI_TYPELIB_PATH=/usr/lib/x86_64-linux-gnu/girepository-1.0
vocalinux
voculinux
```
3. **Check package metadata** - Run `pip show vocalinux` or
`pipx runpip vocalinux show vocalinux` to confirm which version was installed.
3. **Check package metadata** - Run `pip show voculinux` or
`pipx runpip voculinux show voculinux` to confirm which version was installed.
4. **Check Python dependencies** - Run `pip check` inside the venv, or
`pipx runpip vocalinux check` for pipx.
`pipx runpip voculinux check` for pipx.
If Vocalinux reports that a speech recognition model is missing, open Settings
If Voculinux reports that a speech recognition model is missing, open Settings
and download a model, or use the official installer to download the default model
during setup.
@@ -362,7 +362,7 @@ This installer automatically detects your distribution and installs all required
## Text Injection Tools
Vocalinux requires text injection tools to work with X11 or Wayland:
Voculinux requires text injection tools to work with X11 or Wayland:
### For X11
- **xdotool**: Required for X11 sessions
@@ -370,7 +370,7 @@ Vocalinux requires text injection tools to work with X11 or Wayland:
### For Wayland
- **IBus**: Recommended for KDE Plasma Wayland and generally the most reliable direct text input path
- **wtype**: Recommended for wlroots-style Wayland compositors such as sway
- **ydotool**: Universal alternative that works with both X11 and Wayland. Current distro packages use the per-user `ydotool.service`; source builds can install the system-level `ydotoold.service`. Vocalinux uses clipboard paste with `wl-clipboard`, `xclip`, or `xsel` to avoid non-US layout scrambling.
- **ydotool**: Universal alternative that works with both X11 and Wayland. Current distro packages use the per-user `ydotool.service`; source builds can install the system-level `ydotoold.service`. Voculinux uses clipboard paste with `wl-clipboard`, `xclip`, or `xsel` to avoid non-US layout scrambling.
- **xdotool**: May work via XWayland fallback
### Installation by Distribution
@@ -383,7 +383,7 @@ sudo zypper install xdotool wtype wl-clipboard xclip xsel # openSUSE
```
Ubuntu releases which package `ydotool` install a **user** unit named
`ydotool.service`. Enable it only for the account running Vocalinux:
`ydotool.service`. Enable it only for the account running Voculinux:
```bash
sudo apt install ydotool
@@ -443,13 +443,13 @@ For unsupported or experimental distributions:
### Autostart Compatibility
Vocalinux uses **XDG autostart desktop entries** for "Start on Login".
Voculinux 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.
- `$XDG_CONFIG_HOME/autostart/voculinux.desktop`, or
- `~/.config/autostart/voculinux.desktop` (fallback)
- This launches Voculinux as a user GUI app after login.
- Voculinux does **not** create a `systemd` service/unit for this feature.
Practical caveat:
@@ -500,7 +500,7 @@ When reporting issues, please include:
5. **Error messages or logs:**
- Any error messages from the installer
- Output from running `vocalinux-gui` from terminal
- Output from running `voculinux-gui` from terminal
- Relevant journal logs if applicable
6. **Steps to reproduce:**
@@ -525,7 +525,7 @@ Use this checklist when testing on a new distribution:
- [ ] Check wrapper scripts exist
### Post-Install
- [ ] Launch from terminal: `~/.local/bin/vocalinux-gui`
- [ ] Launch from terminal: `~/.local/bin/voculinux-gui`
- [ ] Launch from application menu
- [ ] Verify tray icon appears
- [ ] Test keyboard shortcuts (Hold Right Alt by default)
@@ -543,7 +543,7 @@ Use this checklist when testing on a new distribution:
## Contributing Compatibility Fixes
If you successfully get Vocalinux working on an unsupported or experimental distribution:
If you successfully get Voculinux working on an unsupported or experimental distribution:
1. Test thoroughly using the checklist above
2. Document any distribution-specific requirements