moonsway-tts (0.2.0)
Installation
pip install --index-url About this package
On-device Moonshine dictation for Sway, wtype, and xdotool
Moonsway TTS
Moonsway TTS is a small on-device push-to-toggle dictation CLI for Sway.
Moonshine Voice transcribes the
microphone locally, and each finalized transcript line is typed into the
keyboard-focused application with wtype or xdotool.
Partial hypotheses are deliberately not typed. They can change while you speak, so inserting them would require destructive Backspace-based rewrites.
Requirements
- Linux with Sway and
virtual-keyboard-unstable-v1support wtypexdotool- Python 3.12+
- A working PortAudio input device
On Arch Linux, install the external system dependencies with:
sudo pacman -S portaudio wtype xdotool
The selected Moonshine model is downloaded on the first daemon launch and reused from the local cache. No API key or hosted speech service is used.
Installation
Run without installing:
uvx moonsway-tts --help
Install as a tool with uv:
uv tool install moonsway-tts
Install with pip:
pip install moonsway-tts
Or use my Forgejo PyPI instance:
uvx --index https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ moonsway-tts --help
uv tool install --index https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ moonsway-tts
pip install --index-url https://forgejo.chrispaganon.com/api/packages/chris-paganon/pypi/simple/ moonsway-tts
Usage
Start the long-running daemon:
moonsway-tts daemon
The model loads immediately, but the microphone remains stopped until a control command is sent. Stopping dictation closes the microphone capture stream, so the idle daemon does not reserve the input device and other applications can continue using it. Starting dictation opens the stream again without reloading the model. From another terminal:
moonsway-tts status
moonsway-tts start
moonsway-tts toggle
moonsway-tts stop
Each completed Moonshine line is trimmed and followed by one space. Before
inserting it, Moonsway queries Sway for the focused surface and automatically
uses wtype for native Wayland applications or xdotool for XWayland
applications. Both backends read the text from standard input without a shell.
This avoids the temporary-keymap incompatibility that can turn wtype text
into numbers or control keys in XWayland applications, including some Electron
applications. It does not copy dictated text through the clipboard.
Use --separator to change the suffix and --wtype-delay to change the delay
between text-injection key events for both backends:
moonsway-tts daemon --separator $'\n' --wtype-delay 2
The default delay is 1 ms because wtype 0.4 rejects a zero delay. At startup,
the daemon checks that swaymsg, wtype, and xdotool are available. Inspect
all model, language, logging, and socket options with:
moonsway-tts --help
moonsway-tts daemon --help
moonsway-tts --version
Sway configuration
Install Moonsway TTS as a tool, then locate its executable:
uv tool install moonsway-tts
uv tool dir --bin
Add the executable path reported by uv tool dir --bin to the Sway
configuration. For the usual uv tool location:
set $moonsway_tts /home/you/.local/bin/moonsway-tts
exec $moonsway_tts daemon
bindsym --release --no-repeat F9 exec $moonsway_tts toggle
Replace /home/you and F9 as needed. An unmodified key released before the
command runs avoids physical Ctrl, Shift, Alt, or Super state interfering with
injected text.
Do not run another microphone dictation service on the same binding. If
replacing Handy, remove or comment out its autostart and binding. Reloading a
Sway configuration adds the binding, but Sway's ordinary exec is intended for
session startup; start the daemon in a terminal for the current session or
restart the Sway session.
Text goes to the keyboard-focused field, not necessarily the window under the mouse pointer. Avoid moving focus or the caret until the finalized line has been inserted.
Development
Clone the repository and install the locked environment:
git clone https://codeberg.org/chris-paganon/moonsway-tts.git
cd moonsway-tts
uv sync --locked
Run the quality checks:
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests
uv run pytest -q