# Mudmouth

```text
                     _                 _   _
 _ __ ___  _   _  __| |_ __ ___   ___ | | | |_ ____
| '_ ` _ \| | | |/ _` | '_ ` _ \ / _ \| |_| | '_  /
| | | | | | |_| | (_| | | | | | | (_) |  _  | | | |
|_| |_| |_|\__,_|\__,_|_| |_| |_|\___/|_| |_|_| |_|
```

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.

## 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`.
- 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 real voice from 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

- Rust stable (edition 2024)
- A terminal with ANSI support: Windows Terminal, iTerm2, Terminal.app, GNOME
  Terminal, and similar terminals work well.
- A reachable [Kokoro-FastAPI](docs/kokoro-fastapi.json) instance. The default
  is `http://127.0.0.1:8880`.
- An EverQuest log with `/log on`.

No `ffplay`, `mpv`, PipeWire command, or other external audio player is
required; Mudmouth plays returned WAV audio itself.

## Build and run

On NixOS, enter the included development shell. It provides the ALSA
development metadata required by the native Linux audio backend:

```bash
doas systemctl start podman-kokoro-fastapi.service
nix-shell --run 'cargo run --release -- --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Pleb_oggok.txt"'
```

On other platforms, or when Rust and the native audio development packages are
already installed:

```bash
cargo run --release -- --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Pleb_oggok.txt"
```

Or persist the paths through the app:

```bash
cargo run --release
```

Press `s`, select **EverQuest log**, and enter the file path. Change the
Kokoro endpoint from the same screen. Mudmouth validates the endpoint in the
background and the header reads `CONNECTED`, `CHECKING`, or `UNREACHABLE`.
Changing a log path starts watching the new file immediately. A command-line
endpoint override is also available:

```bash
cargo run --release -- --kokoro-url http://127.0.0.1:8880
```

## TUI controls

| Key | Action |
| --- | --- |
| `d` | Dashboard / live tavern scroll |
| `s` | Settings |
| `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 two 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

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
```

## Development

```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
```

The parser tests cover the observed log formats, including NPC dialogue,
channel-chat exclusion, zone events, normalization, persistent/random speaker
voice policies, and log truncation.