9ae455a99b
No textual conflicts. One rate-and-pitch persistence mechanism, not two:
main's profile sync (71a804f3, the access method, motor profile, vocabulary
level and voice, once the saved state is in) already saves the voice, so
this branch's own voice-only effect is dropped. The README's voice line now
describes the simpler rule (the best device voice speaks; robotic ones last).
Co-Authored-By: Claude Opus 5.5 <[email protected]>
80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# aac-rs — the AAC reference implementation
|
||
|
||
Rust reference for the [AAC open standard](../SPEC.md). Apache-2.0.
|
||
|
||
| Crate | What it is |
|
||
|---|---|
|
||
| `access-core` | The shared access kernel: access methods, switch scanning with its response calibration (SPEC §5.2), dwell with two-way proposals (§5.3), gaze estimation, voice. Four dependencies (serde, serde_json, thiserror, web-time). |
|
||
| `aac-core` | The engine: boards, symbols, vocabulary, motor planning, prediction, i18n with each language's core status (§4.1), the cascade, interchange. |
|
||
| `aac-web` | **Express**, the reference communication app (Leptos → WASM, offline-first PWA). Live at [aac.transaction.science](https://aac.transaction.science). |
|
||
| `aac-conformance` | The harness: C1–C7 against the published vectors in [`../conformance/v1/`](../conformance/v1/). |
|
||
|
||
## Test and conform
|
||
|
||
```bash
|
||
cargo test --workspace
|
||
cargo run -p aac-conformance --bin aac-conformance # C1–C7; any FAIL exits non-zero
|
||
cargo run -p aac-conformance --bin gen-vectors -- ../conformance/v1 # regenerate C5/C6 vectors
|
||
```
|
||
|
||
## Build the app as a static site
|
||
|
||
```bash
|
||
bash prerender-static.sh # → target/site/, ready to rsync; deploy with no_cache_bust
|
||
```
|
||
|
||
The script builds with the `wasm-bindgen` CLI version the crate pins (installing a
|
||
private copy if the machine's differs), prerenders the SSR shell, content-hashes
|
||
`pkg/`, and writes a service worker that precaches the shell and every file it
|
||
loads, so the installed app opens with no network.
|
||
|
||
Four optional downloads ship beside the app, each built outside git and checked
|
||
against a catalogue committed here. Each is offered to the person, never
|
||
fetched by itself, and runs on their device:
|
||
|
||
- **Natural voices** (`tools/voices/`): neural text-to-speech, offered first
|
||
for the person's language (in setup, and when the language changes). Of the
|
||
device's own voices the best speaks (premium, enhanced, then basic), the
|
||
one the person chose while the device has it, and robotic or novelty
|
||
voices only when nothing else speaks the language; online voices never
|
||
(access-core `voice.rs`, aac-web `voices.rs`; device-voice facts from
|
||
Readium Speech, `third_party/readium-speech/`).
|
||
- **The sentence helper** (`tools/ai/`): an on-device language model that
|
||
turns a few chosen words into whole sentences, and suggests replies. It runs
|
||
on the graphics chip only, and only in the languages it was tested in.
|
||
- **Hearing your partner** (`tools/asr/`): on-device speech recognition that
|
||
writes down what someone says to the person, for the sentence helper's
|
||
replies. It listens only when asked, keeps and sends nothing, runs on the
|
||
graphics chip only, and only in the languages with evidence it is accurate.
|
||
- **First letters** (`tools/ae/`): abbreviation expansion. The person types
|
||
only the first letter of each word (`iwtgh`), and a small on-device model
|
||
offers whole sentences (`I want to go home`), fitting what their partner
|
||
said. It runs on the listener's runtime, on the graphics chip only, never
|
||
speaks by itself, and is offered only where we measured it (English).
|
||
|
||
Set `AAC_VOICES=none`, `AAC_AI=none`, `AAC_ASR=none` or `AAC_AE=none` to build
|
||
without them.
|
||
|
||
## Host it under your own site
|
||
|
||
Express reads four build-time variables (set them for both the cargo-leptos build
|
||
and the prerender):
|
||
|
||
| Variable | Default | Use |
|
||
|---|---|---|
|
||
| `AAC_BASE_PATH` | `""` | Mount path, e.g. `/app`. Also set `LEPTOS_SITE_PKG_DIR=app/pkg` for the prerender. |
|
||
| `AAC_SW_URL` | `/sw.js` | The service worker to register (a host usually runs one for its whole site). |
|
||
| `AAC_APP_TITLE` | `AAC — aac.transaction.science` | The document title. |
|
||
| `AAC_HIDE_ENERGY` | unset | Set to hide the energy meter. |
|
||
|
||
aac.aurasense.ai builds it this way at `/app`
|
||
([build-app.sh](https://github.com/dcharlot65-personal/aac-aurasense-web/blob/main/scripts/build-app.sh)).
|
||
|
||
## Two rules the app keeps
|
||
|
||
- **The first frame is the same on the server and in the browser.** Saved state is
|
||
restored only after hydration, behind a brief starting screen. Reading it earlier made
|
||
a returning user's first frame differ from the prerendered page, and hydration aborted.
|
||
- **Timing belongs to the person** (SPEC §5.1). Settings → Timing sets scan speed and
|
||
dwell, shows proposals from the person's own responses to accept or decline, and
|
||
adjusts automatically only if they turn that on.
|