# 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.

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

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

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

## Build and run

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

### NixOS

Install the packaged application from this repository:

```bash
nix profile install github:pleb/mudmouth
mudmouth --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Character_server.txt"
```

Or run it without installing:

```bash
nix run github:pleb/mudmouth -- --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Character_server.txt"
```

The flake includes the ALSA runtime dependency. Start Kokoro-FastAPI separately;
Mudmouth connects to `http://127.0.0.1:8880` by default.

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