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/USER_GUIDE.md
+49 -49
View File
@@ -1,10 +1,10 @@
# User guide
How to use Vocalinux day to day. Install first: [INSTALL.md](INSTALL.md).
How to use Voculinux day to day. Install first: [INSTALL.md](INSTALL.md).
## Getting started
1. Launch Vocalinux (`vocalinux` or the application menu)
1. Launch Voculinux (`voculinux` or the application menu)
2. Find the microphone icon in the system tray
3. Start dictation with the tray menu or your keyboard shortcut
4. Speak into the focused application; text is injected when an utterance completes
@@ -12,7 +12,7 @@ How to use Vocalinux day to day. Install first: [INSTALL.md](INSTALL.md).
### Start on login
Enable **Start on Login** from the first-run dialog, tray menu, or Settings. Vocalinux writes an XDG autostart entry (`~/.config/autostart/vocalinux.desktop`) and starts as a normal user app (`--start-minimized`). It does not create a systemd service.
Enable **Start on Login** from the first-run dialog, tray menu, or Settings. Voculinux writes an XDG autostart entry (`~/.config/autostart/voculinux.desktop`) and starts as a normal user app (`--start-minimized`). It does not create a systemd service.
Works on common desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt). Minimal window-manager sessions may need their own autostart helper.
@@ -26,15 +26,15 @@ Works on common desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt). M
### Dictation formatting
Vocalinux capitalizes the start of dictation and letters after `.`, `!`, or `?`. Each completed utterance leaves a trailing space so the next session does not glue onto the previous sentence.
Voculinux capitalizes the start of dictation and letters after `.`, `!`, or `?`. Each completed utterance leaves a trailing space so the next session does not glue onto the previous sentence.
### Dictating into terminals
When Vocalinux injects through the clipboard (the usual Wayland / ydotool path), it sends **Ctrl+V** in ordinary text fields and **Ctrl+Shift+V** in terminal emulator windows. Auto-detect works on X11 and on Hyprland, Sway, and niri. On GNOME or KDE Wayland, set **Settings → Dictation → Clipboard Paste Shortcut** to **Ctrl+Shift+V**.
When Voculinux injects through the clipboard (the usual Wayland / ydotool path), it sends **Ctrl+V** in ordinary text fields and **Ctrl+Shift+V** in terminal emulator windows. Auto-detect works on X11 and on Hyprland, Sway, and niri. On GNOME or KDE Wayland, set **Settings → Dictation → Clipboard Paste Shortcut** to **Ctrl+Shift+V**.
On non-US layouts such as German Neo, that chord uses the key that types **v** on the active layout (not physical KEY_V). Nested terminal panels inside an IDE are often invisible to window-class detection. If paste lands as a literal `^V` or does nothing, open **Settings → Dictation → Clipboard Paste Shortcut** and choose **Ctrl+Shift+V**.
On X11, **Paste long dictations** opts in to clipboard-pasting dictations of 30 or more characters instead of typing them key by key. It is off by default. Vocalinux restores the previous clipboard contents after pasting unless **Copy to Clipboard** is enabled. If the clipboard contains an image or other non-text content, Vocalinux types the dictation and leaves that content alone.
On X11, **Paste long dictations** opts in to clipboard-pasting dictations of 30 or more characters instead of typing them key by key. It is off by default. Voculinux restores the previous clipboard contents after pasting unless **Copy to Clipboard** is enabled. If the clipboard contains an image or other non-text content, Voculinux types the dictation and leaves that content alone.
The clipboard copy behind these pastes is temporary: your previous clipboard comes back right after. When the copy goes through `wl-copy` 2.2 or newer, it is also marked sensitive (`wl-copy --sensitive`), and clipboard managers that honor that hint, such as Klipper or cliphist, keep it out of their history. Older `wl-copy` builds and X11 or XWayland pastes (`xclip`/`xsel`) have no such hint, so there the dictated text can still show up in history. With **Settings → Dictation → Copy to Clipboard** on, the dictated text is an ordinary copy and stays in history.
@@ -46,11 +46,11 @@ Open **Settings → Audio → Input Device** to select a specific microphone or
**System Default**. A valid explicit microphone selection uses that device and
bypasses the System Default preference below.
With **System Default**, Vocalinux leaves valid default or virtual inputs under
With **System Default**, Voculinux leaves valid default or virtual inputs under
the audio system's control rather than pinning a hardware device.
On ALSA only, if PortAudio substitutes arbitrary hardware for the default input,
Vocalinux prefers an input-capable `pulse` PCM on the same host API to follow the
Voculinux prefers an input-capable `pulse` PCM on the same host API to follow the
microphone selected in desktop sound settings. If no suitable `pulse` PCM exists,
it keeps PortAudio's fallback device and logs a warning.
@@ -112,7 +112,7 @@ Parakeet runs NVIDIA NeMo ASR models through sherpa-onnx. The default bundle is
Pick the language you dictate in from **Language**, or leave it on auto-detect.
If you work in more than one language and switch keyboard layouts to do it, turn
on **Follow keyboard layout** instead. Vocalinux then reads your active layout at
on **Follow keyboard layout** instead. Voculinux then reads your active layout at
the start of every dictation and uses the matching language, so switching layout
switches dictation language with it. The Language picker greys out while this is
on and shows what your current layout resolves to; turning it off pins that
@@ -127,31 +127,31 @@ the configured primary layout.
### Activation via a KDE Plasma global shortcut
Instead of the built-in hotkey listener, you can let your desktop's global
shortcut system trigger Vocalinux. On Wayland the built-in listener reads
shortcut system trigger Voculinux. On Wayland the built-in listener reads
`/dev/input` (requiring membership in the `input` group and effectively acting
as a system-wide key reader). Delegating activation to the compositor avoids
this entirely: no `/dev/input` access and no `input` group needed just to
start/stop dictation. Text injection is unaffected.
Enable it in Vocalinux:
Enable it in Voculinux:
1. Open **Settings → Shortcuts** (the Keyboard Shortcuts group on the Dictation page)
2. Turn on **External Activation (Desktop Shortcut)**
The change applies immediately; you do not need to restart. The built-in key
listener stops, and a running instance exposes a D-Bus service on the session
bus (`com.vocalinux.Vocalinux`). The CLI can forward commands to it:
bus (`com.voculinux.Voculinux`). The CLI can forward commands to it:
```bash
vocalinux --toggle # start if idle, stop if active
vocalinux --start # start voice typing
vocalinux --stop # stop voice typing
voculinux --toggle # start if idle, stop if active
voculinux --start # start voice typing
voculinux --stop # stop voice typing
```
Then bind a compositor shortcut to `vocalinux --toggle` on a native install.
Then bind a compositor shortcut to `voculinux --toggle` on a native install.
For Flatpak, bind the `gdbus` command in
[Running without device access](../packaging/flatpak/README.md#running-without-device-access)
instead, because `vocalinux --toggle` is not on the host PATH. A desktop
instead, because `voculinux --toggle` is not on the host PATH. A desktop
shortcut only sends the key press, so it can toggle dictation but cannot
support push-to-talk because it never sees the release. On KDE Plasma:
@@ -159,16 +159,16 @@ support push-to-talk because it never sees the release. On KDE Plasma:
(older Plasma: **System Settings -> Shortcuts -> Custom Shortcuts -> Edit ->
New -> Global Shortcut -> Command/URL**).
2. Bind a key combination of your choice to the command `vocalinux --toggle`
2. Bind a key combination of your choice to the command `voculinux --toggle`
for a native install. For Flatpak, use the D-Bus command linked above.
Now your chosen key combination toggles dictation, handled by the compositor
rather than by Vocalinux reading the keyboard directly. This works the same way
rather than by Voculinux reading the keyboard directly. This works the same way
on other compositors that support binding a key to a command (e.g. GNOME custom
shortcuts, Sway/Hyprland `bindsym`/`bind`).
As an advanced alternative, you can set the same option in
`~/.config/vocalinux/config.json` under `shortcuts`:
`~/.config/voculinux/config.json` under `shortcuts`:
```json
"shortcuts": {
@@ -176,8 +176,8 @@ As an advanced alternative, you can set the same option in
}
```
Quit Vocalinux before editing that file so the running app cannot overwrite
the edit from its cached config. Start Vocalinux again after saving.
Quit Voculinux before editing that file so the running app cannot overwrite
the edit from its cached config. Start Voculinux again after saving.
### Model size (whisper.cpp / Whisper)
@@ -193,13 +193,13 @@ For whisper.cpp, also pick a **Specialization**: standard multilingual, English-
### Removing unused models
If leftover files are on disk that are not the model currently selected, **Unused downloads** appears under the model info card. Expand it to delete leftovers one at a time. Confirming removes those files from `~/.local/share/vocalinux`. Packaged system-wide VOSK models are left alone.
If leftover files are on disk that are not the model currently selected, **Unused downloads** appears under the model info card. Expand it to delete leftovers one at a time. Confirming removes those files from `~/.local/share/voculinux`. Packaged system-wide VOSK models are left alone.
### GPU
whisper.cpp prefers Vulkan when the bundled pywhispercpp libraries include it, then CUDA, then CPU. Host tools such as `vulkaninfo` only describe the machine. The engine follows the libraries actually loaded. On multi-GPU machines a discrete Vulkan device is preferred; override under **Settings → Performance → Vulkan GPU**. Check logs with `vocalinux --debug`.
whisper.cpp prefers Vulkan when the bundled pywhispercpp libraries include it, then CUDA, then CPU. Host tools such as `vulkaninfo` only describe the machine. The engine follows the libraries actually loaded. On multi-GPU machines a discrete Vulkan device is preferred; override under **Settings → Performance → Vulkan GPU**. Check logs with `voculinux --debug`.
Pip wheels of pywhispercpp are often CUDA builds. In that case Vocalinux uses CUDA device 0. `install.sh` rebuilds pywhispercpp with Vulkan or CUDA when it can.
Pip wheels of pywhispercpp are often CUDA builds. In that case Voculinux uses CUDA device 0. `install.sh` rebuilds pywhispercpp with Vulkan or CUDA when it can.
### Auto-pause and keep-alive
@@ -226,16 +226,16 @@ recording. This option is off by default.
## CLI
```bash
vocalinux --help
vocalinux --version
vocalinux --debug
vocalinux --engine whisper_cpp
vocalinux --engine faster_whisper
vocalinux --engine parakeet
vocalinux --model medium.en-q5_0
vocalinux --wayland
vocalinux --start-minimized
vocalinux --transcribe-file meeting.wav # diarized transcript on stdout, then exits
voculinux --help
voculinux --version
voculinux --debug
voculinux --engine whisper_cpp
voculinux --engine faster_whisper
voculinux --engine parakeet
voculinux --model medium.en-q5_0
voculinux --wayland
voculinux --start-minimized
voculinux --transcribe-file meeting.wav # diarized transcript on stdout, then exits
```
## Custom Dictionary Support
@@ -243,15 +243,15 @@ vocalinux --transcribe-file meeting.wav # diarized transcript on stdout, then
Open **Settings → Custom Dictionary** to configure two separate capabilities:
- **Custom terms** bias recognition toward product names, people, and jargon.
They are read from `~/.config/vocalinux/dictionary.txt` by default, as UTF-8
They are read from `~/.config/voculinux/dictionary.txt` by default, as UTF-8
with one term per line. Blank lines and `#` comments are allowed, so the same
file remains friendly to an accessibility scanner. Use the add/remove editor
or choose a different readable terms file with the file picker.
- **Transcript corrections** replace a known misheard word or phrase after
transcription, for example `super base` with `Supabase`. Corrections are
stored separately in `~/.config/vocalinux/custom-dictionary-corrections.json`.
stored separately in `~/.config/voculinux/custom-dictionary-corrections.json`.
VocaLinux re-reads both files before each completed dictation segment, so an
Voculinux re-reads both files before each completed dictation segment, so an
external edit applies to the next segment without restarting the app. Vocabulary
bias works with Whisper, whisper.cpp, and Faster Whisper. Corrections work with
every engine, including VOSK, Parakeet, and the configured remote API.
@@ -261,10 +261,10 @@ command-like misrecognition from acting, but avoid replacements that create a
voice command unless that is intentional. Correction replacements are not
automatically added to recognition bias.
For a one-session terms override, start Vocalinux with:
For a one-session terms override, start Voculinux with:
```bash
vocalinux --dictionary-file /path/to/dictionary.txt
voculinux --dictionary-file /path/to/dictionary.txt
```
This temporarily enables terms from that file without changing saved settings;
@@ -275,7 +275,7 @@ transcript corrections.
### Post-Processing
Vocalinux can pipe each transcription result through a user-defined script before injecting it into your application. This lets you apply custom transformations — for example, grammar correction, abbreviation expansion, or domain-specific formatting.
Voculinux can pipe each transcription result through a user-defined script before injecting it into your application. This lets you apply custom transformations — for example, grammar correction, abbreviation expansion, or domain-specific formatting.
**To configure:**
1. Open Settings from the tray icon menu (right-click)
@@ -295,19 +295,19 @@ Vocalinux can pipe each transcription result through a user-defined script befor
#!/bin/bash
tr '[:lower:]' '[:upper:]'
```
Make the script executable (`chmod +x`) before setting the path in Vocalinux.
Make the script executable (`chmod +x`) before setting the path in Voculinux.
## Troubleshooting
```bash
vocalinux --debug
voculinux --debug
```
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for tray, audio, injection, and model issues. Distro notes: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md). Updates: [UPDATE.md](UPDATE.md). Help channels: [SUPPORT.md](../SUPPORT.md).
### Text injection backend
Vocalinux types your dictated text using one of several backends. It picks one
Voculinux types your dictated text using one of several backends. It picks one
automatically, and on most desktops the automatic choice is correct.
Autodetection can be wrong, though, and it fails in a way that is easy to
@@ -316,7 +316,7 @@ applications, IBus reports the text as delivered while nothing appears. If
dictation works in some windows (typically XWayland ones, like a browser) but
silently does nothing in others, that is the symptom.
Pin the backend explicitly in `~/.config/vocalinux/config.json`:
Pin the backend explicitly in `~/.config/voculinux/config.json`:
```json
{
@@ -350,19 +350,19 @@ particular application. Pinning `ibus` keeps the IBus path; pinning anything
else turns it off.
To try a backend for a single run without changing the saved setting, set
`VOCALINUX_FORCE_BACKEND`, which overrides the config value. Set it to `auto`
`VOCULINUX_FORCE_BACKEND`, which overrides the config value. Set it to `auto`
to ignore a saved pin for that run:
```bash
VOCALINUX_FORCE_BACKEND=wtype vocalinux --debug
VOCULINUX_FORCE_BACKEND=wtype voculinux --debug
```
The setting and environment override are read at startup, so restart Vocalinux
The setting and environment override are read at startup, so restart Voculinux
after editing `config.json`. The startup log first records a backend pin request;
it does not prove the backend was available or that text reached the focused
application. Later logs identify a fallback when a pin was not applied.
If a pinned tool is unavailable, Vocalinux warns and continues with its normal
If a pinned tool is unavailable, Voculinux warns and continues with its normal
fallback selection. `portal` needs a desktop implementing the
`org.freedesktop.portal.RemoteDesktop` interface (GNOME and KDE Plasma do;
most wlroots compositors do not). `ydotool` also needs a usable `/dev/uinput`