136 lines
3.5 KiB
Markdown
136 lines
3.5 KiB
Markdown
# AWARE — Aviation Weighted Active Recall Engine
|
|
|
|
A cross-platform CLI study tool built for aviation knowledge retention.
|
|
Named after the AWARE briefing — the same commitment to situational
|
|
awareness in the cockpit, applied to systems knowledge on the ground.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd aware
|
|
python3 aware.py
|
|
```
|
|
|
|
## Text-to-Speech
|
|
|
|
Voice is auto-detected by platform — no configuration needed:
|
|
|
|
| Platform | Engine | Install |
|
|
|----------|--------|---------|
|
|
| Linux | espeak-ng | `sudo apt install espeak-ng` |
|
|
| macOS | say | Built-in, nothing to install |
|
|
| Windows | SAPI (PowerShell) | Built-in, nothing to install |
|
|
|
|
Toggle voice on/off with `v` from any menu or during a quiz.
|
|
|
|
### Pronunciation Glossary
|
|
|
|
The file `tts_glossary.json` (next to `aware.py`) controls how abbreviations are spoken.
|
|
Edit it to add, remove, or change pronunciations:
|
|
|
|
```json
|
|
{
|
|
"abbreviations": {
|
|
"APU": "A-P-U",
|
|
"DU": "display unit",
|
|
"FADEC": "FADEC"
|
|
},
|
|
"symbols": {
|
|
">=": "greater than or equal to",
|
|
"\u00b0": " degrees "
|
|
}
|
|
}
|
|
```
|
|
|
|
Abbreviations are matched as **whole words only** — "DU" won't corrupt "DURING" or "PROCEDURE."
|
|
Longer abbreviations match first, so "KCAS" is caught before "CAS" can interfere.
|
|
|
|
### Custom TTS Override
|
|
|
|
To use a different engine (e.g. `piper` for better voice quality),
|
|
create `~/.aware/config.json`:
|
|
|
|
```json
|
|
{
|
|
"tts_command": "piper",
|
|
"tts_args": ["--model", "en_US-lessac-medium", "--output-raw", "{text}"]
|
|
}
|
|
```
|
|
|
|
Use `{text}` as the placeholder — it gets replaced with the spoken text.
|
|
|
|
## Adding New Decks
|
|
|
|
Drop any `.json` file into the `decks/` folder. Two formats supported:
|
|
|
|
### Minimal (flat)
|
|
```json
|
|
{
|
|
"title": "My Study Deck",
|
|
"questions": [
|
|
{"question": "What is X?", "answer": "X is Y."}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Full (with categories and references)
|
|
```json
|
|
{
|
|
"title": "My Study Deck",
|
|
"categories": [
|
|
{
|
|
"name": "Topic A",
|
|
"questions": [
|
|
{"id": 1, "question": "...", "answer": "...", "ref": "Chapter 3"}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
- `id` is auto-assigned if omitted
|
|
- `ref` is optional (displays after the answer)
|
|
- `category` enables the "By Category" filter in the menu
|
|
- `cas` is optional (string or array — displays CAS messages above the question)
|
|
- `detail` is optional (extended explanation displayed after the answer)
|
|
|
|
## Controls
|
|
|
|
After revealing an answer, grade yourself:
|
|
|
|
- **n** — Didn't get the answer at all → Bucket 1
|
|
- **1** — Got some of the answer → Bucket 2
|
|
- **2** — Got about half right → Bucket 3
|
|
- **3** — Got most of the answer → Bucket 4
|
|
- **y** — Nailed it → promotes by one (max Bucket 5)
|
|
|
|
Numpad aliases: **-** = n, **+** = y. Bare **Enter** defaults to missed.
|
|
|
|
Other keys:
|
|
- **v** — Toggle text-to-speech on/off
|
|
- **q** — Quit current session (progress is saved)
|
|
- **d** — Switch to a different deck
|
|
|
|
## Weighted Repetition
|
|
|
|
Questions live in 5 buckets:
|
|
- **Bucket 1** (No Clue) — 8x selection weight
|
|
- **Bucket 2** (Some) — 5x weight
|
|
- **Bucket 3** (Half) — 3x weight
|
|
- **Bucket 4** (Most) — 2x weight
|
|
- **Bucket 5** (Nailed It) — 1x weight
|
|
|
|
Grades `n` through `3` set the bucket directly based on self-assessment.
|
|
Grade `y` promotes by one — meaning you have to nail it from Bucket 4 to reach
|
|
Bucket 5, which matches the physical flashcard pattern of "getting it right regularly."
|
|
|
|
## Progress
|
|
|
|
Per-deck progress saved to `~/.aware/progress/`.
|
|
Reset per-deck via menu option 7, or delete the file to reset:
|
|
|
|
```bash
|
|
rm ~/.aware/progress/deckname_*.json # single deck
|
|
rm -rf ~/.aware/progress/ # all decks
|
|
```
|