Initialize repository for MUDMOUTH

2026-07-14 13:44:32 -07:00
parent 13e12e7740
commit 54fa53222e
15 changed files with 5664 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 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.
+- 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
+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.
+
+## 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.