1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
# Parley
Parley is a planned local GNOME/Wayland dictation tool built around the Parakeet transcription runtime. It will provide a per-user D-Bus daemon, global shortcut, GNOME top-bar extension, transcript history, and tiered text insertion through IBus, clipboard, or an opt-in portal paste backend.
See [SPEC.md](SPEC.md) for the architecture, delivery phases, insertion experiments, and acceptance criteria.
## Status
Phase 1's core and the useful portion of Phase 2 are implemented. The repository contains the standalone frontend, asynchronous per-user D-Bus daemon, `parleyctl`, clipboard copying, prototype notifications, service definitions, and a GNOME Shell 50 top-bar extension. The custom shortcut and insertion experiments are not implemented yet.
## Development environment
The initial target is Arch Linux with GNOME 50 on Wayland. Expected host dependencies include:
- Python 3 and PyGObject
- GNOME Shell and `gnome-extensions`
- IBus
- PipeWire/WirePlumber with PulseAudio compatibility
- FFmpeg
- systemd user services
- XDG Desktop Portal and GNOME's portal backend
- libei/EIS development bindings for the portal-paste experiment
The existing runtime assets are currently located at:
```text
../transcribe-parakeet/bin/transcribe-cli
../transcribe-parakeet/models/parakeet-unified-en-0.6b-Q8_0.gguf
```
That binary presently requires host CUDA 13 and Intel MKL libraries. Do not copy the large model into this Git repository; development configuration should reference its existing path.
## Current developer usage
Set up the development checkout with `uv` and Arch's current system Python (Python 3.14). PyGObject is supplied by Arch, so the uv environment must inherit system site packages:
```bash
cd ../parley
uv venv --python /usr/bin/python --system-site-packages
uv pip install -e .
```
Use `uv run` for local Python commands.
Run the standalone frontend (Enter stops and transcribes; Escape cancels):
```bash
uv run parley
```
By default it finds `transcribe-cli` on `PATH` and the model at `$XDG_DATA_HOME/parley/models/parakeet-unified-en-0.6b-Q8_0.gguf`. During development, each falls back to the corresponding asset in `../transcribe-parakeet`. Transcripts are saved under `$XDG_DATA_HOME/parley/transcripts` (normally `~/.local/share/parley/transcripts`). Paths can be overridden with:
- `PARLEY_FFMPEG`
- `PARLEY_TRANSCRIBE_CLI`
- `PARLEY_MODEL`
- `PARLEY_TRANSCRIPT_DIR`
- `PARLEY_DEVICE`
- `PARLEY_LANGUAGE`
- `PARLEY_AUTO_INSERT`
- `PARLEY_INSERTION_MODE` (`clipboard` or `ibus`)
Run tests without desktop, microphone, or model dependencies:
```bash
uv run python -m unittest discover -s tests
```
Run the daemon in a terminal for development:
```bash
uv run parleyd
```
In another terminal, control it over the session bus:
```bash
uv run parleyctl status
uv run parleyctl toggle # start recording
uv run parleyctl toggle # stop and transcribe
uv run parleyctl cancel
uv run parleyctl copy
```
For the normal development loop, install an editable local user service once:
```bash
./scripts/install-dev
```
This writes only to `~/.config/systemd/user` and `~/.local/share/dbus-1/services`; it does not install a system package. Python source changes are visible through the editable uv install. Restart the daemon after changes and follow its journal with:
```bash
systemctl --user restart parley.service
journalctl --user -u parley.service -f
```
Rerun `./scripts/install-dev` after changing entry points or service files.
Install the development GNOME Shell extension as a symlink into your user extension directory:
```bash
./scripts/install-extension
gnome-extensions info parley@org.parley
```
The top-bar microphone shows daemon state and its menu provides start/stop, cancel, copy-last, and open-folder actions. Source changes are visible through the symlink, but GNOME Shell must reload the extension; toggle it off and on with the Extensions app. A newly installed extension may require one logout/login on Wayland before Shell discovers it.
### IBus insertion experiment
The development installer also starts a minimal persistent passthrough IBus engine. Enable the experiment with:
```bash
./scripts/enable-ibus-test
```
This saves the current engine, selects Parley, and enables automatic IBus insertion in the daemon. Put the caret in a normal text field and use the recording shortcut twice. Successful transcripts are still saved and copied before insertion. Password and PIN purposes are refused where the application reports them.
This is a bake-off prototype: while it is enabled, explicitly test normal typing, modifiers, shortcuts, compose/dead keys, layout switching, terminals, browsers, and Electron applications. Restore the previous engine and clipboard-only mode with:
```bash
./scripts/disable-ibus-test
```
## Arch Linux package
The local PKGBUILD installs `parleyd` and the other executables under `/usr/bin`, the systemd **user** unit under `/usr/lib/systemd/user`, and the session D-Bus service under `/usr/share/dbus-1/services`. It builds from the latest committed state of this checkout:
```bash
git status # commit the source you want packaged
cd packaging/arch
makepkg -si
systemctl --user daemon-reload
systemctl --user enable --now parley.service
```
The package deliberately does not bundle the runtime or model. Put `transcribe-cli` on `PATH` (for example at `~/.local/bin/transcribe-cli`) and the model at `~/.local/share/parley/models/parakeet-unified-en-0.6b-Q8_0.gguf`, or set the documented environment overrides. User-manager environment overrides can be placed in `~/.config/environment.d/parley.conf`; log in again after changing them.
The prototype daemon uses `xclip` through GNOME's XWayland clipboard bridge and `notify-send` for notifications.
## Planned first milestone
1. Extract recording, transcription, and persistence from the TTY frontend.
2. Preserve a standalone CLI using the shared core.
3. Add automated tests that do not require GNOME, a microphone, or the model.
4. Implement the user daemon, D-Bus interface, and `parleyctl toggle` workflow.
## Design principles
- Local-only transcription
- Never lose a successful transcript because insertion failed
- Keep model/audio work outside GNOME Shell
- Respect Wayland's security model
- Use IBus only if the passthrough/activation feasibility tests prove reliable
- Keep clipboard-only operation as the safe fallback
- Make synthetic portal paste explicit and revocable
|
