# 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 is underway. The repository now contains a terminal-independent Python core for FFmpeg recording, JSONL transcription, and atomic transcript persistence, plus a standalone terminal frontend. The daemon, D-Bus API, clipboard integration, 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

Create an environment and install the development checkout:

```bash
cd ../parley
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
```

Run the standalone frontend (Enter stops and transcribes; Escape cancels):

```bash
parley
```

By default it uses the runtime and model in `../transcribe-parakeet` and saves under `$XDG_DATA_HOME/parley/transcripts` (normally `~/.local/share/parley/transcripts`). Development 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
python -m unittest discover -s tests
```

Commands such as `parleyctl` and daemon startup will be documented when Phase 2 lands.

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