Thales Maciel
359b5fbaf4
Make the X11 user path visible on first contact instead of burying it under config and maintainer detail. Rewrite the README around the supported quickstart, expected tray and dictation result, install validation, troubleshooting, and linked follow-on docs. Split deep config and developer material into separate docs, add checked-in screenshots plus a short WebM walkthrough, and add a generator so the media assets stay reproducible. Also fix the CLI discovery gap by letting `aman --help` show the top-level command surface while keeping implicit foreground `run` behavior, and align the settings, help, and about copy with the supported service-plus-diagnostics model. Validation: `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui`; `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`; `python3 -m py_compile src/*.py tests/*.py scripts/generate_docs_media.py`; `PYTHONPATH=src python3 -m aman --help`. Milestone 4 stays open in the roadmap because `docs/x11-ga/first-run-review-notes.md` still needs a real non-implementer walkthrough.
164 lines
5.6 KiB
Markdown
164 lines
5.6 KiB
Markdown
# aman
|
|
> Local amanuensis for X11 desktop dictation
|
|
|
|
Aman is a local X11 dictation daemon for Linux desktops. The supported path is:
|
|
install the portable bundle, save the first-run settings window once, then use
|
|
a hotkey to dictate into the focused app.
|
|
|
|
## Supported Path
|
|
|
|
| Surface | Contract |
|
|
| --- | --- |
|
|
| Desktop session | X11 only |
|
|
| Runtime dependencies | Installed from the distro package manager |
|
|
| Supported daily-use mode | `systemd --user` service |
|
|
| Manual foreground mode | `aman run` for setup, support, and debugging |
|
|
| Canonical recovery sequence | `aman doctor` -> `aman self-check` -> `journalctl --user -u aman` -> `aman run --verbose` |
|
|
| Representative GA validation families | Debian/Ubuntu, Arch, Fedora, openSUSE |
|
|
| Portable installer prerequisite | System CPython `3.10`, `3.11`, or `3.12` |
|
|
|
|
Distribution policy and user persona details live in
|
|
[`docs/persona-and-distribution.md`](docs/persona-and-distribution.md).
|
|
|
|
## 60-Second Quickstart
|
|
|
|
First, install the runtime dependencies for your distro:
|
|
|
|
<details>
|
|
<summary>Ubuntu/Debian</summary>
|
|
|
|
```bash
|
|
sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 libayatana-appindicator3-1
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Arch Linux</summary>
|
|
|
|
```bash
|
|
sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Fedora</summary>
|
|
|
|
```bash
|
|
sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>openSUSE</summary>
|
|
|
|
```bash
|
|
sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject python3-python-xlib
|
|
```
|
|
|
|
</details>
|
|
|
|
Then install Aman and run the first dictation:
|
|
|
|
1. Verify and extract the portable bundle.
|
|
2. Run `./install.sh`.
|
|
3. When `Aman Settings (Required)` opens, choose your microphone and keep
|
|
`Clipboard paste (recommended)` unless you have a reason to change it.
|
|
4. Click `Apply`.
|
|
5. Put your cursor in any text field.
|
|
6. Press the hotkey once, say `hello from Aman`, then press the hotkey again.
|
|
|
|
```bash
|
|
sha256sum -c aman-x11-linux-<version>.tar.gz.sha256
|
|
tar -xzf aman-x11-linux-<version>.tar.gz
|
|
cd aman-x11-linux-<version>
|
|
./install.sh
|
|
```
|
|
|
|
## What Success Looks Like
|
|
|
|
- On first launch, Aman opens the `Aman Settings (Required)` window.
|
|
- After you save settings, the tray returns to `Idle`.
|
|
- During dictation, the tray cycles `Idle -> Recording -> STT -> AI Processing -> Idle`.
|
|
- The focused text field receives text similar to `Hello from Aman.`
|
|
|
|
## Visual Proof
|
|
|
|
|
|
|
|
|
|
|
|
[Watch the first-run walkthrough (WebM)](docs/media/first-run-demo.webm)
|
|
|
|
## Validate Your Install
|
|
|
|
Run the supported checks in this order:
|
|
|
|
```bash
|
|
aman doctor --config ~/.config/aman/config.json
|
|
aman self-check --config ~/.config/aman/config.json
|
|
```
|
|
|
|
- `aman doctor` is the fast, read-only preflight for config, X11 session,
|
|
audio runtime, input resolution, hotkey availability, injection backend
|
|
selection, and service prerequisites.
|
|
- `aman self-check` is the deeper, still read-only installed-system readiness
|
|
check. It includes every `doctor` check plus managed model cache, cache
|
|
writability, service unit/state, and startup readiness.
|
|
- Exit code `0` means every check finished as `ok` or `warn`. Exit code `2`
|
|
means at least one check finished as `fail`.
|
|
|
|
## Troubleshooting
|
|
|
|
- Settings window did not appear:
|
|
run `aman run --config ~/.config/aman/config.json` once in the foreground.
|
|
- No tray icon after saving settings:
|
|
run `aman self-check --config ~/.config/aman/config.json`.
|
|
- Hotkey does not start recording:
|
|
run `aman doctor --config ~/.config/aman/config.json` and pick a different
|
|
hotkey in Settings if needed.
|
|
- Microphone test fails or no audio is captured:
|
|
re-open Settings, choose another input device, then rerun `aman doctor`.
|
|
- Text was recorded but not injected:
|
|
run `aman doctor`, then `aman run --config ~/.config/aman/config.json --verbose`.
|
|
|
|
Use [`docs/runtime-recovery.md`](docs/runtime-recovery.md) for the full failure
|
|
map and escalation flow.
|
|
|
|
## Install, Upgrade, and Uninstall
|
|
|
|
The canonical end-user guide lives in
|
|
[`docs/portable-install.md`](docs/portable-install.md).
|
|
|
|
- Fresh install, upgrade, uninstall, and purge behavior are documented there.
|
|
- The same guide covers distro-package conflicts and portable-installer
|
|
recovery steps.
|
|
|
|
## Daily Use and Support
|
|
|
|
- Supported daily-use path: let the `systemd --user` service keep Aman running.
|
|
- Supported manual path: use `aman run` in the foreground for setup, support,
|
|
or debugging.
|
|
- Tray menu actions are: `Settings...`, `Help`, `About`, `Pause Aman` /
|
|
`Resume Aman`, `Reload Config`, `Run Diagnostics`, `Open Config Path`, and
|
|
`Quit`.
|
|
- If required settings are not saved, Aman enters a `Settings Required` tray
|
|
state and does not capture audio.
|
|
|
|
## Secondary Channels
|
|
|
|
- Portable X11 bundle: current canonical end-user channel.
|
|
- Debian/Ubuntu `.deb`: secondary packaged channel.
|
|
- Arch `PKGBUILD` plus source tarball: secondary maintainer and power-user
|
|
channel.
|
|
- Python wheel and sdist: developer and integrator channel.
|
|
|
|
## More Docs
|
|
|
|
- Install, upgrade, uninstall: [docs/portable-install.md](docs/portable-install.md)
|
|
- Runtime recovery and diagnostics: [docs/runtime-recovery.md](docs/runtime-recovery.md)
|
|
- Config reference and advanced behavior: [docs/config-reference.md](docs/config-reference.md)
|
|
- Developer, packaging, and benchmark workflows: [docs/developer-workflows.md](docs/developer-workflows.md)
|
|
- Persona and distribution policy: [docs/persona-and-distribution.md](docs/persona-and-distribution.md)
|