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.