# 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 is implemented and Phase 2 is underway. The repository contains the standalone frontend, an asynchronous per-user D-Bus daemon, `parleyctl`, GDK clipboard copying, prototype notifications, and service definitions. The custom shortcut installer, insertion experiments, and GNOME extension 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`

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
```

## 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 daemon uses GDK 4 for clipboard ownership and `notify-send` for prototype 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