announcer/AGENTS.md

# announcer – utrop på høyttaleranlegget

Liten Flask-app: tekst inn i nettleseren → forhåndslytt → «Send ut på anlegget»
spiller lyden lokalt på **denne** maskinen med `pw-play`. TTS er edge-tts
(nevrale stemmer, krever nett) med Piper som lokal reserve.

Appen er generisk: tittel, undertittel, aksentfarge og hurtigfraser kommer fra
`config.toml`, ikke fra HTML-en. Den het `sg-announcer` og var skrevet for Sauda
Gathering fram til oktober 2026.

Dokumentasjon for Kent: Athena-notatet `30 Ressurser/Teknologi/Announcer.md`.
Oppdater det, ikke denne fila, når noe som er verdt å huske endres.

Filer:

| Fil | Hva |
|---|---|
| `announcer.py` | server, kø, TTS, jingler, ruter |
| `auth.py` | `Principal`, leverandørene, OIDC-rutene |
| `config.py` | `config.toml` + miljøvariabler, standardverdier |
| `index.html` | hele sida, inline CSS/JS, ingen byggesteg |
| `config.example.toml` | kommentert mal; kopier til `config.toml` |
| `docs/crew-integration.md` | kontrakten mot crew-panelet |
| `tests/test_auth.py` | `uv run pytest` |
| `compose.yaml` + `Dockerfile` | testoppsett, se under. Ikke produksjon |
| `docker/dummy_idp.py` | falsk crew-panel, så OIDC kan prøves |

## Kjøring

Tjenesten er en systemd-brukerenhet: `~/.config/systemd/user/announcer.service`
(enabled, port 8090). `systemctl --user restart announcer` etter endringer i
koden. Manuelt: `uv run announcer.py --port 8090`.

Ny maskin (Debian/Ubuntu/Mint): `git clone https://git.1x1.no/kent/announcer.git`
og `./install.sh` gjør alt (apt, uv, Python 3.13, stemmer, enhet, ufw). Finnes
NetBird (`wt0`) skrur det på ufw med deny incoming og åpner 22, 22022 og porten
kun på `wt0`. Kan kjøres på nytt, og rydder da bort en gammel
`sg-announcer.service` hvis den ligger der. Avspilling bruker `pw-play` når
PipeWire kjører, ellers `paplay` (`player_cmd()`), så Mint 21 med PulseAudio
virker også.

### Omdøpingen: ett punkt gjenstår

Mappa er flyttet til `~/Work/announcer`, enheten heter `announcer.service`, og
remote peker på `https://git.1x1.no/kent/announcer.git`. **Men repoet i Forgejo
heter `annuoncer`** – en skrivefeil. Rett navnet i Forgejo, så virker remote;
Forgejo legger selv inn en omdirigering fra det gamle navnet.

Flytter du mappa igjen: `.venv` har absolutte stier i `pyvenv.cfg` og i
shebangen til hvert konsollskript, så `uv sync` alene er ikke nok. Da må
`rm -rf .venv && uv sync` til, og tjenesten startes om.


## Testing i Docker

`docker compose up --build` gir to containere:

| | |
|---|---|
| `http://localhost:8091` | announcer med PIN, JWT **og** OIDC slått på (`docker/config.test.toml`) |
| `http://localhost:9000` | `docker/dummy_idp.py`, som later som den er crew-panelet |

Port 8091 med vilje, så den ikke kolliderer med tjenesten på 8090.

Dummy-IdP-en finnes fordi crew-panelet ikke har OIDC ennå: uten den kan
OIDC-veien ikke prøves i det hele tatt. Den kjører en ekte
autorisasjonskode-runde med PKCE (og avviser feil `code_verifier`), signerer
`id_token` med klienthemmeligheten, og lar deg velge hvem du logger inn som –
Kari (`crew`), Kent (`admin`) eller Ola (ingen roller, skal gi 403, ikke 401).
`http://localhost:9000/token?who=kari&go=1` logger deg rett inn via
token-lenka, slik panelet skal gjøre.

Merk i `docker/config.test.toml`: `authorization_endpoint` peker på
`localhost:9000` fordi nettleseren skal dit, mens `token_endpoint` peker på
`idp:9000` fordi announcer selv snakker med den inne i compose-nettet. Delt
horisont, og samtidig en test av at manuelle endepunkter virker når et panel
mangler discovery.

Lyd: `/run/user/1000` er montert inn, så `pw-play` i containeren spiller på
vertens anlegg. Kommenter ut den linja i `compose.yaml` hvis du bare skal
teste innlogging.

`UV_PROJECT_ENVIRONMENT=/opt/venv` i bildet er ikke pynt: `/app` er et
bind-mount av repoet, og uten det ville containerens `uv sync` overskrevet
`.venv` som den kjørende tjenesten bruker.

## Konfigurasjon

Tre lag, siste vinner: `DEFAULTS` i `config.py` → `config.toml` →
`ANNOUNCER_*`-miljøvariabler. **Uten `config.toml` virker alt**, med de gamle
standardverdiene og uten innlogging; det er med vilje, og
`test_uten_konfig_er_alt_apent` passer på det.

`config.toml` er gitignorert. `config.example.toml` er malen, og den er
kommentert – les den framfor å gjette.

Hemmeligheter settes som miljøvariabler i enheten, ikke i `config.toml`:
`ANNOUNCER_PIN`, `ANNOUNCER_JWT_SECRET`, `ANNOUNCER_OIDC_CLIENT_SECRET`,
`ANNOUNCER_SECRET_KEY`. Hele tabellen over variabler står i `ENV` i `config.py`;
den er eneste sted en ny variabel legges til.

## Autentisering

Modellen er én datatype og én funksjon: `Principal` (hvem + roller +
rettigheter) og `require(action)` som enten gir deg den eller stopper
forespørselen. Handlingene er `view`, `preview`, `announce`, `stop`, `clear`.

Tre leverandører, prøvd i rekkefølge, alle valgfrie:

- **pin** – `X-Pin`-header, som før. `hmac.compare_digest`, ikke `==`.
  Får rollen `admin` som standard, så gammelt oppsett oppfører seg som før.
  Virker uten nett, derfor beholdt.
- **jwt** – `Authorization: Bearer <jwt>` fra crew-panelet. HS256 med delt
  hemmelighet, eller RS256/ES256 mot panelets JWKS (PyJWT cacher nøklene).
  Krever `exp`; roller leses av et konfigurerbart claim.
- **oidc** – autorisasjonskode med PKCE. `/auth/login` → panelet →
  `/auth/callback`. Discovery hentes først ved første innlogging, så tjenesten
  starter selv om panelet er nede.

**En leverandør er aktiv når den står i `auth.providers` *eller* når den er
ferdig konfigurert.** Derfor slår `ANNOUNCER_PIN=1234` alene fortsatt på PIN.
Er ingen aktiv, er alt åpent.

`/auth/token?t=<jwt>` er broa mens panelet mangler OIDC: panelet lenker hit med
et kortlevd token, announcer setter sesjonscookie. Se
`docs/crew-integration.md` – det er kontrakten panelet skal oppfylle.

Roller → handlinger står i `[roles]` i `config.toml`. `"*"` betyr alt.
Rettighetene slås opp på nytt per forespørsel, så en endring der slår inn uten
at noen må logge inn igjen; nye `[auth.*]`-verdier krever omstart.

401 betyr «vi vet ikke hvem du er, logg inn», 403 betyr «vi vet hvem du er, men
rollen din får ikke dette». Et gyldig token uten roller gir 403, ikke 401 – å
logge inn på nytt ville ikke hjulpet.

Sesjonsnøkkelen genereres én gang og lagres i `instance/secret_key` (0600).
Uten den logges alle ut ved hver `systemctl restart`. `SESSION_COOKIE_SECURE`
settes bare når `server.behind_tls` er sann – appen kjører på rå HTTP over LAN
og NetBird, og med Secure på ville cookien aldri blitt sendt.

## Hvordan det henger sammen

- `/api/config` er alt sida trenger for å tegne seg selv: branding, stemmer,
  jingler og en `auth`-blokk med hvem du er og hva du får gjøre. Svarer alltid
  200, også med feil PIN – klienten spør «hvem er jeg?», og «ikke innlogget» er
  et svar, ikke en feil. Route-funksjonen heter `client_config()`; navnet
  `config` er tatt av modulen.
- `/api/preview` syntetiserer og returnerer WAV til nettleseren. Ingen lyd på PC-en.
- `/api/announce` legger meldingen i én FIFO-kø; en bakgrunnstråd spiller én om
  gangen med `pw-play`. `/api/stop` dreper gjeldende avspilling, `/api/clear`
  tømmer køen.
- `/api/status` krever `view`. Den var åpen før, og lekket både meldingstekster
  og IP-ene til dem som hadde sendt noe. IP vises nå bare for den som har
  `clear`; alle andre ser navnet.
- `/` er åpen uansett, ellers kunne ingen komme til innloggingsknappen.
- Knappen «Send ut» er låst til nøyaktig den teksten/stemmen/hastigheten som
  sist ble forhåndslyttet. Det er med vilje: ingen skal sende noe de ikke har hørt.
- Ferdige WAV-er bufres i `cache/` etter innholdshash. Trygt å slette.
- `audit()` skriver én JSON-linje per hendelse til `logs/announcements.jsonl`
  (`announce`, `played`, `stop`, `clear`) med navn, subject, metode og IP.
  Rullerer til `.jsonl.1` ved 5 MB. Den feiler aldri forespørselen – en logg
  som ikke lar seg skrive skal ikke hindre et utrop.
- Jingler: de innebygde (`BUILTIN_CHIMES`) genereres i Python med `_tone`/
  `_mix`/`_overlay`, ingen lydfiler. Egne filer i `chimes/` (wav/mp3/ogg/flac)
  dukker opp i menyen som `file:<stem>`; ffmpeg kutter til 6 s, normaliserer
  til -18 LUFS og fader ut. Mappa leses ved hver forespørsel, så nye filer
  vises uten restart. Toppnivå på de innebygde ligger mellom -4 og -10 dBFS,
  talen går til 0 dBFS, så jinglen skal aldri være høyere enn stemmen.

## Stemmer og motorer

`VOICES_LIST` i `announcer.py` er eneste sted en stemme legges til. To motorer:

- **edge** (`_edge`): Microsofts nevrale stemmer via `edge-tts`-pakken. Gratis,
  ingen nøkkel, men krever internett og er en uoffisiell bruk av Edge sin
  «les høyt»-tjeneste – kan slutte å virke uten varsel. Norsk: bare
  `nb-NO-FinnNeural` og `nb-NO-PernilleNeural`. `*MultilingualNeural`-stemmene
  kan lese norsk med engelsk aksent. Liste: `uv run edge-tts --list-voices`.
  Leverer MP3 24 kHz; dekodes med ffmpeg til PCM i `edge_pcm()`.
- **piper** (`_piper`): lokalt, robotaktig, reserve når nettet er nede.
  Modellen lastes ned ved oppstart til `voices/` (gitignored). Norsk finnes
  bare som `talesyntese-medium` og `nvcc-medium` (ti talere, `speaker`-indeks).
  Full liste: `https://huggingface.co/rhasspy/piper-voices/resolve/main/voices.json`.

Vil Kent ha enda bedre lyd: ElevenLabs (nøkkel, best norsk) eller OpenAI
`gpt-4o-mini-tts` er neste trinn; legg til som ny motor i `synthesize()`.

## Feller

- **ufw**: appen kjører nativt, så Docker-smutthullet gjelder ikke. Porten må
  åpnes eksplisitt for LAN-et (`sudo ufw allow from 10.20.70.0/23 to any port 8090 proto tcp`).
- `pkill -f announcer.py` fra et skall som selv har `announcer.py` i
  kommandolinja dreper skallet. Bruk `systemctl --user`.
- `player = Player()` står på modulnivå, så avspillingstråden starter ved
  `import announcer` – også i `install.sh`, som importerer modulen for å laste
  ned stemmer. Harmløst, men greit å vite.
- `tests/conftest.py` nuller ut alle `ANNOUNCER_*`-variabler før hver test.
  Uten den arver testene maskinens miljø – systemd-enheten setter
  `ANNOUNCER_PORT`, og compose setter JWT- og OIDC-hemmeligheter, noe som
  gjorde 28 tester røde i containeren med feilmeldinger som ikke pekte på noe
  galt.
- `pyproject.toml` har `[tool.uv] package = false`. Appen er løse `.py`-filer
  som kjøres på plass, ikke en pakke; uten den vil `uv sync` bygge et wheel og
  klage på at `announcer/__init__.py` mangler.
- Piper 1.8 bruker `SynthesisConfig(length_scale=…)`; lavere = raskere.
- Forhåndslytt svarer 502 med feilmelding hvis edge-tts feiler (ingen nett).
  Køen markerer meldingen som `failed`. Bytt til en lokal reserve-stemme.