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 |
| `schedule.py` | planlagte sendinger, lagret i `data/scheduled.json` |
| `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` + `test_schedule.py` | `uv run pytest` – 80 tester |
| `Dockerfile` + `compose.yaml` | **drift** – appen kjøres i Docker |
| `.env.example` | bruker-ID, portbinding og hemmeligheter |
| `compose.test.yaml` | testoppsett med dummy-IdP, se under |
| `docker/dummy_idp.py` | falsk crew-panel, så OIDC kan prøves |

## Kjøring

**Announcer kjører i Docker, på en egen klient som er koblet til
høyttaleranlegget – aldri på kitsune.** Kitsune er utviklingsmaskin; der er
det bare koden som bor.

Ny klient (Debian/Ubuntu/Mint):

```bash
git clone https://git.1x1.no/kent/announcer.git
cd announcer && ./install.sh
```

`install.sh` installerer Docker om den mangler, lager `.env` med riktig
bruker-ID og portbinding, oppretter `data/`, bygger bildet, starter
containeren og setter ufw. Den rydder også bort en eventuell gammel nativ
`announcer.service`/`sg-announcer.service`. Kan kjøres på nytt; en `.env` som
finnes blir ikke overskrevet.

Drift:

```bash
docker compose logs -f             # følg loggen
docker compose restart             # etter endringer i data/config.toml
docker compose up -d --build       # etter endringer i koden
cat data/logs/announcements.jsonl  # hvem som sendte hva
```

Alt som skal overleve en ny container ligger i `data/` på verten
(bind-mount, ikke navngitt volum, så du kan lese loggen og slippe egne
jingler i `data/chimes/` uten å gå inn i containeren):

| | |
|---|---|
| `data/voices/` | Piper-modellene, ~670 MB, lastes ned ved første oppstart |
| `data/cache/` | ferdige WAV-er etter innholdshash. Trygt å slette |
| `data/chimes/` | egne jinglefiler |
| `data/logs/` | revisjonsloggen |
| `data/instance/` | sesjonsnøkkelen |
| `data/scheduled.json` | planlagte sendinger. Lesbar med `cat` |
| `data/config.toml` | valgfri. Uten den er sida åpen |

### Lyden ut av containeren

Det eneste virkelig uvanlige i oppsettet. Tre ting må stemme:

1. Hele vertens `XDG_RUNTIME_DIR` monteres inn på samme sti. Ikke bare
   `pipewire-0`: PulseAudio bruker `pulse/native` pluss en cookie i samme
   mappe, og ved å ta hele mappa virker begge lydservere uten at compose må
   vite hvilken maskina har. `player_cmd()` velger `pw-play` eller `paplay`.
2. `user: "${PUID}:${PGID}"` må være brukeren som **eier** socketen på
   verten. Stemmer ikke ID-en, kommer det ingen lyd. `install.sh` fyller inn
   `id -u`/`id -g`.
3. Maskina må være logget inn grafisk, ellers finnes socketen ikke.
   Containeren starter ved boot, altså før innlogging, og avspilling feiler
   til noen logger inn. Det retter seg selv: `player_cmd()` slås opp per
   melding, så første utrop etter innlogging virker uten omstart. Derfor
   anbefaler `install.sh` automatisk innlogging.

### Brannmur: BIND_IP, ikke ufw

**Dockers publiserte porter går forbi ufw.** De settes opp i nat-tabellen,
før ufws regler, så `ufw deny` på porten gjør ingenting. Tilgangen styres
derfor av `BIND_IP` i `.env`:

| | |
|---|---|
| `0.0.0.0` | alle nett maskina er på |
| `100.75.x.x` | bare NetBird. `install.sh` velger dette når `wt0` finnes |
| `127.0.0.1` | bare maskina selv |

ufw settes fortsatt for maskinens øvrige porter (ssh på `wt0`), men den er
ikke involvert i tilgangen til announcer. Dette er en endring fra den native
tida, da porten måtte åpnes eksplisitt i ufw.

## Testing i Docker

`docker compose -f compose.test.yaml 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 |

Egen fil, eget prosjektnavn og port 8091, så den ikke kan forveksles med
eller forstyrre den som kjører i drift. Begge porter er bundet til
`127.0.0.1`, så testriggen – som har PIN `1234` – aldri ligger åpen på
LAN-et.

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.

`compose.test.yaml` bind-monterer koden, så endringer slår inn med en
restart. Driftsbildet kopierer koden inn i stedet, så det som kjører er
uavhengig av hva som ligger i mappa. `UV_PROJECT_ENVIRONMENT=/opt/venv` er
derfor ikke pynt: med bind-mount ville containerens `uv sync` ellers
overskrevet `.venv` på verten.

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

## Utvikling på kitsune

`uv run announcer.py --port 8099` kjører appen direkte, uten Docker. Det er
veien for å prøve en endring kjapt; `uv run pytest` for testene. Men
**ingen tjeneste skal stå og kjøre på kitsune** – det var slik det var før, og
det er ryddet bort. Skal noe prøves med innlogging, bruk
`compose.test.yaml`.

## Planlagte sendinger

`schedule.py` er den første delen av appen som **må** ligge på disk. Kø og
historikk har alltid bare levd i minnet, og det går bra fordi en melding
spilles med en gang. En melding planlagt til 18:00 må overleve at containeren
startes om 17:45, så den lagres i `data/scheduled.json`, skrevet til side og
flyttet på plass så fila aldri er halvskrevet.

Ingen database, med vilje: dette er en håndfull meldinger på et arrangement,
og en fil man kan lese med `cat` er verdt mer her enn indekser.

Modulen vet ingenting om Flask eller avspilling. Den lagrer, og den svarer på
«hva skal sendes nå?». `_scheduler()` i `announcer.py` eier tråden som spør
hvert 20. sekund og legger forfalte meldinger i den vanlige køen – derfra
oppfører de seg nøyaktig som en melding sendt for hånd.

**Bare engangs**, ikke gjentakende. Derfor sender klienten et absolutt
tidspunkt (epoch), og hele tidssoneproblemet forsvinner: containeren kan stå
i UTC uten at det gjør noe. `TZ` settes likevel fra `.env`, ellers står
loggen i UTC mens du står i CEST. Skal gjentakelse inn senere, må «09:00»
tolkes i en tidssone, og da begynner `TZ` å bety noe.

**Gikk den glipp av, spilles den ikke.** `due()` skiller på `grace_seconds`
(standard 120): innenfor den sendes meldingen, utenfor markeres den `missed`.
Nådefristen er slingringsmonn for at tråden våkner med mellomrom og for en
kjapp omstart – ikke en policy om å ta igjen etterslep. «Turneringen starter
om ti minutter» skal ikke ut på anlegget en time etter at maskina kom
tilbake. `due()` endrer ingenting selv; `announcer.py` markerer først etter at
meldingen faktisk er lagt i kø, så ingenting kan stå som «sendt» uten å ha
blitt det.

Forhåndslytten gir en bonus: planlegging er låst til den samme nøkkelen som
«Send ut», så man planlegger bare det man har hørt – og siden forhåndslytt
varmer `cache/`, ligger WAV-en ferdig på disk. **En planlagt edge-tts-melding
spiller altså kl. 18:00 selv om nettet er nede da.**

Sine egne planlagte sendinger kan man alltid avbryte. Andres krever `clear` –
samme rett som å tømme køen, siden det er samme slags inngrep i noe andre har
satt i gang.

## 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 styrer ikke Docker-porter.** Se «Brannmur» over: tilgangen avgrenses
  med `BIND_IP` i `.env`. En `ufw deny` på porten gir falsk trygghet.
- **Ingen lyd?** Nesten alltid `PUID`/`PGID` i `.env` som ikke er brukeren
  som eier lydsocketen, eller at maskina ikke er logget inn grafisk. Sjekk
  hva containeren velger:
  `docker compose exec announcer python -c "import announcer,pathlib;print(announcer.player_cmd(pathlib.Path('/tmp/x.wav')))"`
- `pkill -f announcer.py` fra et skall som selv har `announcer.py` i
  kommandolinja dreper skallet. Gjelder utvikling med `uv run`; i drift er
  det `docker compose`.
- `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.
- **Oppgradering:** `schedule` er en ny handling. Har et oppsett et eksplisitt
  `[roles]` i `config.toml`, får `crew` den *ikke* automatisk – eksplisitt
  konfigurasjon overstyrer standardverdiene, og da blir svaret 403 «Rollen din
  har ikke lov til dette». Legg `"schedule"` inn selv. Dette traff
  `docker/config.test.toml` under testing.
- `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.