Thales Maciel
dd2813340b
Stop implying that one Ubuntu 3.11 unit lane validates the full Linux support surface Aman documents.\n\nSplit CI into an Ubuntu CPython 3.10/3.11/3.12 unit-package matrix, a portable install plus doctor smoke lane, and a packaging lane gated on both. Add a reproducible ci_portable_smoke.sh helper with fake systemctl coverage, and force the installer onto /usr/bin/python3 so the smoke path uses the distro-provided GI and X11 Python packages it is meant to validate.\n\nUpdate the README, release/distribution docs, and Debian metadata to distinguish the automated Ubuntu CI floor from broader manual GA signoff families, and add the missing AppIndicator introspection package to the Ubuntu/Debian dependency lists.\n\nValidate with python3 -m unittest discover -s tests -p 'test_*.py', python3 -m py_compile src/*.py tests/*.py, and bash -n scripts/ci_portable_smoke.sh. The full xvfb-backed smoke could not be run locally in this sandbox because xvfb-run is unavailable.
180 lines
6.5 KiB
Markdown
180 lines
6.5 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.
|
|
|
|
Published bundles, checksums, and release notes live on the
|
|
[`git.thaloco.com` releases page](https://git.thaloco.com/thaloco/aman/releases).
|
|
Support requests and bug reports go to
|
|
[`SUPPORT.md`](SUPPORT.md) or `thales@thalesmaciel.com`.
|
|
|
|
## 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` |
|
|
| Automated CI floor | Ubuntu CI: CPython `3.10`, `3.11`, `3.12` for unit/package coverage, plus portable install and `aman doctor` smoke with Ubuntu system `python3` |
|
|
| Manual GA signoff 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).
|
|
|
|
The wider distro-family list is a manual validation target for release signoff.
|
|
It is not the current automated CI surface yet.
|
|
|
|
## 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 gir1.2-ayatanaappindicator3-0.1 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. Download, verify, and extract the portable bundle from the releases page.
|
|
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. Leave the default hotkey `Cmd+m` unless it conflicts. On Linux, `Cmd` and
|
|
`Super` are equivalent in Aman, so this is the same modifier many users call
|
|
`Super+m`.
|
|
5. Click `Apply`.
|
|
6. Put your cursor in any text field.
|
|
7. 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.
|
|
- Release-specific notes for `1.0.0` live in
|
|
[`docs/releases/1.0.0.md`](docs/releases/1.0.0.md).
|
|
|
|
## 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)
|
|
- Release notes: [docs/releases/1.0.0.md](docs/releases/1.0.0.md)
|
|
- Support and issue reporting: [SUPPORT.md](SUPPORT.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)
|