# Mudmouth

<p align="center">
  <img src="docs/mudmouth-logo.svg" alt="Mudmouth — The log awakens; the dungeon speaks" width="660">
</p>

Mudmouth is a cross-platform, classic-MUD-inspired TUI for EverQuest Legends.
It follows an EverQuest log, gives NPC dialogue a Kokoro-FastAPI voice, and
remembers the chosen voice for each NPC. It is entirely local: your log,
speaker mappings, generated audio, and TTS endpoint stay on your computer.

<video controls preload="metadata" width="960" src="docs/mudmouth-demo-01.mp4">
  Your browser does not support HTML5 video.
</video>

## What it does

- Watches an EverQuest log without replaying historical lines on startup.
- Speaks `Name says, '…'` NPC dialogue by default.
- Calls `GET /health`, shows live Kokoro connectivity in the status bar, and
  refreshes its selectable voice catalog from `GET /v1/audio/voices`. NPC
  selection is limited to Mudmouth's curated 27-voice English pool.
- Sends non-streaming WAV requests to `POST /v1/audio/speech` and plays clips
  sequentially with native audio support.
- Repeats an NPC's identical line at 1.5x speed, then 2x speed when each repeat
  arrives within 15 seconds; a later line returns to normal speed.
- Picks a curated voice available on your Kokoro server for a newly seen NPC
  and saves it.
- Lets you pin an NPC to a particular voice, reroll a persistent random voice,
  or set the NPC to get a new random voice for every line.
- Can optionally narrate zone entries (`You have entered Lake Rathetear.`).
  This is disabled by default, as are future optional message categories.

## Requirements

- A reachable [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI) instance. Install and
  run it using the upstream instructions; Mudmouth uses `http://127.0.0.1:8880` by default.
- An EverQuest log with `/log on`.

## Build and run

See [development and build notes](docs/development.md) for local setup,
running Mudmouth, validation, and multi-platform release packaging.

## TUI controls

| Key | Action |
| --- | --- |
| `d` | Dashboard / live tavern scroll |
| `s` | Settings |
| `p` | Choose EverQuest game folder during first-time setup |
| `r` | Rescan for character logs during first-time setup |
| `v` | NPC voice manager |
| `?` | Help |
| `q` | Quit |
| `↑` / `↓`, `j` / `k` | Move selection |
| `Enter`, `Space` | Edit or toggle a setting |
| `←` / `→`, `h` / `l` | Choose a voice |
| `p` | Pin selected NPC to selected voice |
| `r` | Random voice every NPC line |
| `x` | Choose a fresh persistent random voice |
| `Esc` | Close a menu or edit box |

## Data and privacy

Mudmouth writes only three human-readable files in the operating system's
standard application-data directory:

- `config.toml` — endpoint, log path, event toggles, and playback settings
- `speakers.json` — NPC names, voice modes, and last-seen context
- `filters.toml` — dialogue prefixes to ignore; created with the default
  ambient-NPC and combat-chatter filters

On Linux this is normally `~/.local/share/mudmouth`; the equivalent platform
directory is used on macOS and Windows.

The repeat behavior can be adjusted in `config.toml`:

```toml
repeat_window_seconds = 15
repeat_second_speed = 1.5
repeat_third_plus_speed = 2.0
```

To ignore additional repetitive dialogue, edit `filters.toml` and add literal
prefixes. For example:

```toml
speaker_prefixes = ["A ", "An "]
text_prefixes = ["Time to die, ", "Guards! "]
```