# More local transcription choices for Quill

> A pending proposal by lmn451 to the independently maintained Quill project. PR #76 is open, unmerged, and unreleased; this case study describes proposed behavior, not a shipped feature. Written by lmn451.

[Human-readable case study](https://subagentura.tech/contributions/quill/)

## Problem and proposal

[Quill](https://github.com/humanitas-labs/quill) is a local macOS meeting recorder and transcriber. The issue behind this proposal reports that Quill used Parakeet regardless of the configured transcription engine, so users could not select a model already downloaded by Handy or connect another local CLI without changing Quill itself. See [upstream issue #75](https://github.com/humanitas-labs/quill/issues/75).

In [open pull request #76, “feat(macos): add Handy and custom command transcription adapters”](https://github.com/humanitas-labs/quill/pull/76), lmn451 proposes selectable transcription providers:

- `parakeet` remains the default built-in engine.
- `handy` invokes Handy's headless CLI and passes a configured model ID, allowing Quill to reuse a model already downloaded by Handy.
- `command` invokes a configured local executable or wrapper that implements Quill's JSON output contract.

This is configuration-based model and provider selection, not a favorites or shortcuts UI. The proposal does not make Handy download a model automatically.

## Handy configuration

The proposed settings live in `~/.config/quill/config.json` under `transcription`. This example uses the model ID documented at the pinned PR revision; `handy_model` may be omitted to use that default. `handy_executable` is optional and can override executable discovery with an absolute path or a `~/...` path.

```json
{
  "transcription": {
    "engine": "handy",
    "handy_model": "handy-computer/parakeet-unified-en-0.6b-gguf/parakeet-unified-en-0.6b-Q8_0.gguf",
    "handy_executable": "/Applications/Handy.app/Contents/MacOS/handy"
  }
}
```

Users first download the selected model in Handy and obtain its ID with `handy --list-models --json`. Quill passes the configured ID explicitly, independently of Handy's current UI selection. The proposed `quill doctor` checks for the required Handy CLI capabilities (`--transcribe-file`, `--list-models`, and `--json`) and verifies that the selected model is downloaded. Older Handy builds without those headless commands are not supported.

Handy's documented file-transcription output is text-only. The adapter therefore proposes one coarse transcript segment per nonempty audio chunk, rather than word-level timestamps.

## Local command configuration

The `command` provider is for a local engine or wrapper that performs local inference and returns Quill's JSON contract. The upstream README documents this configuration shape:

```json
{
  "transcription": {
    "engine": "command",
    "command": {
      "name": "my-local-engine",
      "executable": "~/.local/bin/my-transcription-adapter",
      "arguments": ["--audio", "{audio}", "--model", "{model}"],
      "model": "/absolute/path/to/local/model",
      "chunk_seconds": 300,
      "timeout_seconds": 600
    }
  }
}
```

The executable, arguments, and model are required. Quill passes arguments directly without shell expansion; `{audio}` is the temporary WAV path and `{model}` is the configured model value. The wrapper must use local inference to preserve Quill's local-only behavior. It writes a JSON object to stdout, with timed segments relative to the input chunk when precise timings are available, or text for a coarse whole-chunk result. Quill adds the chunk and recording offsets itself.

## Proposed processing and limits

The shared command path converts audio to 16 kHz mono, 16-bit PCM WAV chunks of up to five minutes, validates returned JSON, offsets transcript segments onto the recording timeline, and records engine/model provenance. Handy's text-only response yields one coarse segment per nonempty chunk, with no word-level timestamps. Handy is launched for each chunk and reloads its model each time; speech context can be lost across chunk boundaries.

Handy use requires a downloaded model and a build with the documented CLI capabilities. For a generic command provider, `quill doctor` checks that the executable is present but does not verify model or output compatibility; the upstream documentation calls for a short test recording to check a custom provider. These are implementation limits described by the proposal, not benchmark results or independent production validation.

## Current upstream status

As of this case study, [PR #76](https://github.com/humanitas-labs/quill/pull/76) remains open and unmerged, and [issue #75](https://github.com/humanitas-labs/quill/issues/75) remains open. The PR's [proposed changelog entry](https://github.com/humanitas-labs/quill/blob/52c1f5c775bb6e0baaee7a7a20c14afba54683cb/CHANGELOG.md) is under “Unreleased.” This contribution has not been accepted or released upstream. Quill remains maintained by [humanitas-labs](https://github.com/humanitas-labs/quill); [Handy](https://github.com/cjpais/Handy) remains maintained by cjpais.

## Sources

- [Quill upstream repository](https://github.com/humanitas-labs/quill)
- [Quill issue #75](https://github.com/humanitas-labs/quill/issues/75)
- [Quill PR #76 by lmn451](https://github.com/humanitas-labs/quill/pull/76)
- [Quill macOS README at PR head `52c1f5c`](https://github.com/humanitas-labs/quill/blob/52c1f5c775bb6e0baaee7a7a20c14afba54683cb/macos/README.md)
- [Handy upstream repository](https://github.com/cjpais/Handy)