# CONTEXT

Glossary of terms used in this codebase. This file is a glossary only — it
holds no implementation decisions or specs (those live in `docs/adr/`).

## Voice

- **Voice activity** — per-user join / leave / AFK *timing metadata*, persisted
  in the `voice_activity` table and updated by `events::handle_voice_state_update`.
  Despite the name, it contains **no audio** — only timestamps and durations.
- **Recording** — capturing the *audio* of a voice channel into a rolling
  in-memory buffer while the bot is connected. Distinct from *voice activity*
  (metadata). Recording is opt-in via `RECORDING_ENABLED` (default false); when
  enabled a bot records continuously while in a VC and "flushes" on `/record`.
- **Window** — the retention horizon of the recording buffer: how many seconds
  of the recent past are kept. Older audio is discarded as new audio arrives.
  Configured via `RECORDING_WINDOW_SECONDS` (default 900 = 15 minutes).
- **Flush** — the `/record` action: snapshot the current recording buffer to an
  mp3 and upload it to Copyparty. Non-destructive — the buffer keeps recording
  after a flush, so successive calls may overlap.

## Stats & Leaderboard

- **User stats** — cumulative per-user counters (message count, total voice
  active time, total voice AFK time) stored in the `user_stats` table. Persists
  across restarts. Distinct from *voice activity* which is session-scoped.
- **Voice activity** (session) — per-session timing metadata (join time, current
  active/AFK durations, is_afk flag). Resets when user joins VC. Used for
  real-time status, not leaderboard rankings.
- **Leaderboard** — `/leaderboard` command group showing ranked user stats.
  Metrics: `messages`, `active` (voice), `afk` (voice), `total` (voice active +
  afk). Paged at 10 entries, descending by default.
- **Tracked guild** — the guild containing `status_channel_id`. Message counts
  are only tracked in this guild.

## TTS

- **Synthesize** — convert text to audio via local Piper TTS (ONNX model
  loaded in-process via `piper-rs`). No external fallback. Output is f32 PCM
  at the model's native sample rate (typically 22050 Hz mono), resampled to
  48 kHz stereo via inline linear interpolation before playback. Songbird does
  not resample — playing un-resampled audio results in wrong playback speed.
- **TtsState** — struct held in poise `Data`: `OnceLock<Arc<std::sync::Mutex<Piper>>>`
  for the model instance, `DashMap<String, (Vec<u8>, Instant)>` for the
  text→audio cache. Piper is loaded lazily on first TTS call, off the async
  runtime. Cache is keyed by the full phrase, bounded by entries/bytes, and
  evicted by TTL. No external TTS fallback.
- **Pre-generation** — on first voice event for a user, synthesize all 6 event
  phrases (join/leave/deafen/undeafen/mute/unmute) with their display name and
  cache them. ~120ms first time, instant after. Lazy — no startup cost.

## Music Playback

- **Queue** — per-guild, in-memory list of tracks waiting to play. Lost on
  restart. `/music queue` shows the current track first, then the pending
  items in play order.
- **Position** — where `/music grajcuj` inserts a track: `now` interrupts the
  current track, `next` inserts after it, `last` appends (default). When
  nothing is playing, every position starts playback immediately.
- **Skip** — stop the current track and play the next queued one. With an
  empty queue, playback stops but the bot stays in the voice channel.
- **Auto-advance** — when a track ends (or errors), the next queued track is
  started automatically and announced in the channel.
- **Compressed playback** — `/music grajcuj ... compressed`: downloads audio, runs
  through the /compress pipeline (Opus 500bps, 12 kHz, mono → OGG), then
  decodes the compressed file via symphonia for playback. Produces properly
  destroyed audio via Opus codec, not just raw low-sample-rate PCM.