# American Explorer

A free audio guide to all fifty US states, the District of Columbia and the
five inhabited territories. Fifty six in all, with a quiz and a comparison
tool.

Keyboard only, and built to be used with the screen off.

**TG Studios** — Tony Gebhard, info@tonygebhard.me

## Speech

It works out which to use, and nobody is asked anything on first run.

| Mode | When it is used |
|---|---|
| Screen reader | Whenever one is running. NVDA, JAWS and anything else `accessible_output2` reaches, in the voice and at the rate you already use. |
| SAPI 5 | When no screen reader is running. Windows' built-in voices, with rate and pitch in Settings. |

F7 switches between them if both are available.

Detection happens on every launch rather than being read from the settings
file, because it genuinely changes: a saved preference for a screen reader is
worthless on a morning it is not running, and honouring it would open the app
silent. The preference is kept, not deleted, so it returns when the reader
does.

An earlier version had a third option, a recorded voice. It was withdrawn: it
held whole recordings for the lines it knew and stitched the rest together
from individual word clips, and anything assembled that way sounds assembled.
A settings file naming it is treated as undecided rather than reassigned.

## Keys

Every letter key belongs to the list filter, so no command is bound to one.

| Key | What it does |
|---|---|
| Up / Down | Move through the list |
| Enter | Choose |
| Escape | Clear what you typed; press again to go back |
| Left / Right | Change the setting you are on |
| Home / End | First and last item |
| any letter | Narrow the list to what matches |
| Backspace | Delete a typed letter, or go back |
| F1 | Help |
| F2 / F3 | Music volume |
| F4 / F5 | Sound volume |
| F6 | A random fact |
| F7 | Switch the voice |
| Ctrl+R | Say that again |

Typing `R` `H` `O` finds Rhode Island. Every list works this way — regions,
states, cities, facts, quiz answers, settings.

## What is in it

- **Browse by region** — five mainland regions plus the territories
- **All states and territories** — all 56, type to narrow
- **Quiz** — capital cities, state nicknames, or which region
- **Compare two states** — population, area, statehood, region
- **Random fact** — 224 of them
- Per state: overview, capital, population, major cities, industries,
  agriculture, history, what it is famous for, geography, and its facts

## Running from source

```bash
pip install -r requirements.txt
python main.py
```

```bash
python tests/test_explorer.py
```

The tests drive the app by keystroke with SDL on its dummy drivers and speech
captured rather than spoken, so they run silently and assert against what the
app *said*.

## Building

```bash
pyinstaller american_explorer.spec --noconfirm
```

A folder build, not one file: the voice library is thousands of small clips,
and unpacking them to `%TEMP%` on every launch would mean seconds of silence
at startup.

## Regenerating the audio

Both need an ElevenLabs key at `~/.eleven_tts/config.json`, and neither is
needed to run the app.

```bash
python tools/build_audio.py
```

The seven UI sounds and the background music. Each generated sound is trimmed
to its own onset, levelled to a fixed peak and fade-edged, because what a
sound-effects model returns is a performance rather than a UI asset. The music
is crossfaded into itself so it loops without a seam.

## Where things are kept

Settings and the crash log live in `%APPDATA%\AmericanExplorer\`, not beside
the program, so they survive an install into Program Files.

### Using your own sounds

Drop a file into `%APPDATA%\AmericanExplorer\sounds\` with the same name as
one of the bundled ones and it wins over it, file by file. So replacing just
the move click means putting one `menu_move.ogg` there and leaving the rest
alone.

| File | When it plays |
|---|---|
| `menu_move.ogg` | Moving between rows. The most-heard sound by far |
| `menu_select.ogg` | Enter |
| `menu_back.ogg` | Escape |
| `menu_open.ogg` | Opening a submenu |
| `edge.ogg` | The top or bottom of a list, or a key that does nothing here |
| `correct.ogg` / `wrong.ogg` | Quiz answers |
| `music_main_theme.ogg` | Background music |

Ogg Vorbis or WAV. An MP3 renamed to `.ogg` will not load — the app says so on
startup rather than silently going quiet.

## Data

The 56 entries carry name, capital, largest city, major cities, population,
area, statehood date and order, nickname, motto, region, industries,
agriculture, facts, what it is famous for, state song, bordering states and
time zone.

Two senses of "region" coexist on purpose. `State.region` is what a person
would say — Puerto Rico is Caribbean, Guam is Pacific. The browse menu needs
all 56 filed exactly once, so it buckets the territories together. The region
quiz only draws on the five mainland regions, because asking which region Guam
is in and offering Midwest, Southwest and West is not a question.

Corrections to info@tonygebhard.me.
