peerspeak/docs/FEATURES.md

# PeerSpeak Feature Inventory

A capability list of what PeerSpeak **already does**, so we don't keep
re-deriving it. This is the user-facing companion to `ARCHITECTURE.md` (which
covers internals). When you ship a feature, add it here.

**Field-test status legend:**

- ✅ **Verified** — confirmed working on a real call (usually desktop ↔ dopedart).
- 🧪 **Tests-green** — unit-tested and/or smoke-tested locally, but **not** yet
  exercised on a real 2-machine call. Treat as unproven.
- ⚙️ **Plumbing** — wiring/persistence that has no separate field test of its own.

---

## Rooms & sessions

| Feature | Status | Notes |
|---|---|---|
| Create a room → shareable join ticket | ✅ | Ticket carries host addr + topic id. |
| Join a room via ticket | ✅ | Paste ticket on the launch screen. |
| Leave a room | ✅ | |
| Multi-peer rooms (mesh) | ✅ | Presence over the iroh gossip plane. |
| Copy ticket to clipboard | ✅ | Button on the room screen. |
| Remembered nickname | ✅ | `config.username` pre-fills the launch field, saved on join/create. |
| In-call duration timer | ✅ | `call_started` drives the header clock. |

## Audio I/O & codec

| Feature | Status | Notes |
|---|---|---|
| PipeWire capture + playback | ✅ | `src/audio/pipewire_impl.rs`. |
| Input device selection | ✅ | |
| Output device selection | ✅ | |
| App-internal input (mic) gain slider | ✅ | Unity default; applied pre-gate/encode. |
| App-internal output gain slider | ✅ | Unity default; applied on the mixed output. |
| Opus codec | ✅ | 48 kHz mono, `Application::Voip`, 20 ms / 960-sample frames. |
| Adaptive jitter buffer + Opus PLC | 🧪 | `src/core/jitter.rs`; reorders by seq, adaptive playout delay, conceals drops. Not field-tested. |

## Voice controls

| Feature | Status | Notes |
|---|---|---|
| Self mute | ✅ | |
| Deafen | ✅ | |
| Push-to-talk + rebindable hotkey | ✅ | `TogglePtt` / `StartSettingHotkey`; gate ahead of the encoder. |
| Noise gate (hysteresis + attack/release/hangover) | ✅ | `src/audio/gate.rs`. |
| Draggable gate threshold on the mic meter | ✅ | Discord/OBS-style `GateMeter` canvas widget. |
| Mic level meter — in-call | ✅ | |
| Mic level meter — off-call "Test mic" | ✅ | `SetMicMonitor` / standalone capture stream. |
| Mix-bus soft limiter | 🧪 | `src/audio/limiter.rs`; A/B never confirmed on a real call. |
| Echo cancellation (opt-in) | 🧪 | `src/audio/echo_cancel.rs`; PipeWire `module-echo-cancel` (WebRTC AEC+NS+AGC) via RAII pactl guard. **Needs a 2-machine call through speakers, not headphones.** |

## Per-peer controls

| Feature | Status | Notes |
|---|---|---|
| Per-peer volume | ✅ | `SetPeerVolume`. |
| Per-peer local mute | ✅ | Still decoded (levels show) but not mixed. |
| Per-peer speaking indicator | ✅ | `audio_levels` per `EndpointId`. |

## Text chat

| Feature | Status | Notes |
|---|---|---|
| In-room text chat | 🧪 | Over the gossip plane; full-width bottom-dock UI. 2-machine delivery not confirmed. |
| Outgoing + incoming sanitization | ✅ | `sanitize_chat`: strips control chars, collapses whitespace, caps 2000. |
| History cap | ⚙️ | `CHAT_HISTORY_MAX = 300`. |
| Local echo of own messages | ✅ | |

## Screen share (via pixelpass)

| Feature | Status | Notes |
|---|---|---|
| Share your screen | ✅ | Spawns `pixelpass --host --output json`, announces the ticket on presence. `src/screenshare/mod.rs`. Field-verified desktop↔dopedart 2026-06-06. Capture portal appears on the host when the first viewer connects. |
| Watch a peer's share | ✅ | 👁 Watch spawns a pixelpass viewer → opens the stream in mpv (vlc fallback). Field-verified: laptop watched the desktop's screen. |
| Live badge on sharing peers | ✅ | 🔴 Live on the peer card; 🔴 Sharing badge on the self card. |
| Multiple simultaneous sharers | 🧪 | Discord-style: each sharer is an independent pixelpass host; the room shows one offer per sharer. Single-sharer path verified; concurrent not yet. |
| Late-joiner sees in-progress share | 🧪 | Sharing rides presence, so the existing gossip re-announce delivers the offer to late joiners. Not yet explicitly tested. |
| Graceful "needs pixelpass" state | ✅ | Share button disabled + labelled when the binary isn't on `$PATH`. Config override: `pixelpass_path`. |
| Viewer limit | ⚙️ | Not overridden — pixelpass bandwidth-measures its own safe cap (protects the sharer's uplink); refusals surface as an error. |
| Audio of the share | ⚙️ | Video only on the room path (so it can't echo/double with the voice mix). |

## Recording

| Feature | Status | Notes |
|---|---|---|
| Local call recording (mic + incoming mix → WAV) | 🧪 | `src/audio/recorder.rs`; writes to `~/peerspeak-recordings/`. Solo + 2-machine recording not confirmed. Header REC timer present. |

## Notifications & sounds

| Feature | Status | Notes |
|---|---|---|
| Desktop notifications toggle | ✅ | `notifications_enabled`. |
| Event chimes | ✅ | 8 events: self-join, peer-join, peer-leave, reconnect-attempt, reconnected, self-leave, mic-toggle, reconnect-failed. |
| Per-event custom sound override | ✅ | `custom_sound_*` paths in config. |

## Networking & privacy

| Feature | Status | Notes |
|---|---|---|
| iroh QUIC transport | ✅ | |
| Network mode picker | ✅ | `RelayNoDiscovery` (default), `N0Full`, `DirectOnly`. Takes effect next join. |
| Retained-address reconnect | ✅ | Dials last-known full addr before falling back to bare id. |
| Per-peer connection badge (direct/relay + RTT, hover for addr/loss/bitrate) | ✅ | Peer-card badge fed by a 1 Hz poll of the live audio link's selected QUIC path (`connection_stats` → `core::connstats::derive`). Field-verified on a real 2-machine call 2026-07-08. |
| Reconnect + eviction model | ✅ | Incl. two-outage reconnect-eviction fix + regression test. |
| Self-hosted relay | ❌ | Decided against — rely on n0 relays, `RelayNoDiscovery` default. |

## UI & layout

| Feature | Status | Notes |
|---|---|---|
| Selectable room layouts | ✅ | 3-Column, Bottom Dock (default), Drawer. |
| Layout picker popup w/ canvas thumbnails | ✅ | `LayoutThumb`, no image dependency. |
| Draggable + persisted panel dividers | ✅ | Per-layout, clamped to window; saved on drag-release. |
| Chat drawer toggle (drawer layout) | 🧪 | Toggle + restart-persistence not explicitly confirmed. |
| Responsive full-window Settings screen | ✅ | |
| Canvas-drawn icon set | ✅ | 18 icons (`Icon`/`IconKind` in `src/app/mod.rs`), no image/font dep, theme-recolored. Replaces all emoji; SVG design source in `~/Documents/peerspeak-mockups/icons/`. |
| Selectable UI themes | ✅ | 10 palettes (`src/theme.rs`): Catppuccin Mocha (default)/Macchiato/Frappé/Latte, Dracula, Nord, Tokyo Night, Gruvbox Dark, Solarized Light, Gruvbox Light. Picked via canvas palette swatches in Settings (`ThemeSwatch`), applied live + persisted (`config.theme`). All palettes unit-tested for WCAG-AA text legibility. |

## Persistence

| Feature | Status | Notes |
|---|---|---|
| Config file | ✅ | `~/.config/peerspeak/config.json`. |
| Backward-compatible loading | ✅ | serde `default`s fill missing fields; unknown fields tolerated. |
| Window size restored | ✅ | `window_width`/`window_height`, saved on close. |
| Window position restored | ✅ | `window_x`/`window_y`, saved on close. **X11 only** — see Platform support. |

## Platform support (Linux desktop)

| Concern | Status | Notes |
|---|---|---|
| Wayland | ✅ | Default on this dev box; winit's Wayland backend. App/taskbar icon comes from the `.desktop` file matched by `application_id = "peerspeak"`. |
| X11 (incl. XWayland) | ✅ | winit's X11 backend (both backends compile in by default; winit auto-selects — Wayland if `WAYLAND_DISPLAY` is set, else X11 via `DISPLAY`). Launch verified rendering on X11. The embedded RGBA window icon (`from_rgba`) is honored on X11 even without the `.desktop` installed. |
| Window position restore | X11 only | Wayland's xdg-shell gives clients no way to place their own window, so we center there. On X11 the saved `window_x`/`window_y` is restored via `Position::Specific` (outer position; no drift across save/restore — iced's `Moved` and `Position::Specific` both use the outer position). Verified live on X11 (saved an off-center position; the window reopened there, not centered). Gated by `is_wayland()` (`src/app/mod.rs`); decision logic unit-tested (`initial_window_position`). |

---

## Known field-test debt (the 🧪 rows above, collected)

Re-run on a real desktop ↔ dopedart call before calling these done:

1. **Echo cancellation** — 2-machine call *through speakers* (the only path that
   actually exercises AEC).
2. **Mix-bus soft limiter** — A/B a hot signal.
3. **Local call recording** — solo + 2-machine, verify the WAV.
4. **In-room text chat** — 2-machine delivery.
5. **Adaptive jitter buffer** — behaviour under real packet loss/jitter.
6. **Chat drawer** — toggle + persistence across restart.
7. **Screen share** — single-sharer 2-machine path VERIFIED 2026-06-06
   (desktop hosted, laptop watched via mpv). Remaining: multiple concurrent
   sharers, late-joiner sees an in-progress share, and Stop clears the peer's
   badge. Requires `pixelpass` + `mpv` on both ends.

## Not built (candidate features)

Things that came up but **do not** exist yet:

- Soundboard (play short clips into the call mix).
- Invite links beyond the raw ticket / room persistence.