TuxDMX-WebUI/TuxDMX-Codex-Komplet-Specifikation.md

# TuxDMX – komplet projektbeskrivelse til Codex

## 1. Din rolle

Du er senior softwarearkitekt og full-stack-udvikler. Byg et komplet, driftssikkert og dokumenteret system med navnet **TuxDMX**.

TuxDMX skal være en headless, browserbaseret DMX-controller til Raspberry Pi. Systemet skal bruge **Open Lighting Architecture (OLA)** som hardware- og protokolbackend, sende DMX gennem et USB-DMX-interface direkte til Raspberry Pi’en og kunne styres fuldt ud gennem et mørkt Web UI.

Systemet skal integreres med **MixItUp**, så Twitch-events, chatkommandoer og Channel Point-redemptions kan starte scener og effekter gennem HTTP-kald.

Codex får ikke adgang til den fysiske Raspberry Pi, USB-DMX-interfacet eller lamperne. Derfor skal al hardwareafhængig kode isoleres bag interfaces, og projektet skal indeholde en komplet simulator, mock-backend, automatiske tests, installationsscripts og en manuel hardwarevalidering, som Thomas kan køre på Raspberry Pi’en.

Der må ikke stå, at fysisk hardware er testet, når det ikke er tilfældet.

---

# 2. Produktmål

TuxDMX skal give følgende samlede løsning:

```text
Browser / mobil / tablet
          │
          ▼
TuxDMX Web UI og REST API
          │
          ├── Fixture-, patch-, scene- og effektmotor
          ├── MixItUp/Twitch-triggerkø
          ├── BPM- og beatmotor
          ├── Telemetri og logning
          └── Simulator
          │
          ▼
OLA / olad
          │
          ▼
USB-DMX-interface
          │
          ▼
DMX-lamper
```

Systemet skal kunne køre uden skærm, tastatur og mus på Raspberry Pi’en.

---

# 3. Ikke-forhandlingsbare krav

1. **100 % browserbetjening**
   - Den normale bruger må ikke skulle redigere JSON, YAML, Python, JavaScript eller shellkode.
   - Alle funktioner skal kunne konfigureres gennem formularer, knapper, dropdowns, sliders, farvevælgere, XY-felter, drag-and-drop og guider.
   - Rå data må kun vises som read-only diagnostik under en avanceret sektion.

2. **Mørkt design**
   - Primær baggrund: `#080b12`
   - Primær accent: `#00e5ff`
   - Sekundær accent: `#ff3df2`
   - God kontrast, responsivt layout og tydelig statusfarvekodning.
   - Dansk som standardsprog.
   - Arkitekturen skal være klar til engelsk oversættelse.

3. **Headless Raspberry Pi**
   - Målplatform: Raspberry Pi OS Lite 64-bit på Raspberry Pi 4 eller 5.
   - Ingen desktop eller tilsluttet skærm må være nødvendig.
   - Autostart med systemd.
   - Automatisk genstart ved fejl.
   - Web UI skal være tilgængeligt efter reboot.

4. **USB-DMX direkte i Raspberry Pi**
   - OLA skal stå for USB-DMX-driver, patch og output.
   - TuxDMX må ikke være hårdt bundet til én bestemt adaptermodel.
   - Systemet skal opdage og vise kompatible OLA-enheder og porte.
   - Der skal være en guided opsætning af universe og outputport.

5. **Open Fixture Library**
   - Fixtures skal kunne findes gennem en søgning direkte i TuxDMX.
   - Brugeren vælger manufacturer, fixture og DMX-mode fra UI.
   - Fixturedata skal importeres, valideres, normaliseres og gemmes lokalt.
   - Importerede fixtures skal kunne bruges offline efter import.

6. **MixItUp**
   - MixItUp skal være en integreret del af systemet.
   - Brugeren skal kunne oprette Twitch-eventmapping uden at skrive kode.
   - TuxDMX skal generere endpoint, token, HTTP-metode, headers og request-body, så de kan kopieres til MixItUp.
   - TuxDMX skal svare hurtigt og lægge effekten i kø, så MixItUp ikke rammer timeout.

7. **BPM og beat**
   - Manuel BPM.
   - Tap tempo.
   - Automatisk BPM fra lydinput.
   - JACK skal understøttes, men systemet skal også have en enklere ALSA/PipeWire-kompatibel capturemulighed.
   - Audioanalyse skal kunne bruge aubio eller en tilsvarende letvægtsløsning.
   - Effekter skal kunne synkroniseres til beat, halvnote, kvartnote, ottendedel og sekstendedel.

8. **Telemetri**
   - Live status for OLA, USB-DMX, output, frame rate, fejl og seneste DMX-frame.
   - Live visning af alle 512 kanalers aktuelle og ønskede værdier.
   - Log over scener, effekter, Twitch-events, BPM og hardwarestatus.
   - Systemressourcer: CPU, RAM, temperatur, disk, uptime og processstatus.
   - Der skal skelnes tydeligt mellem:
     - “Frame afleveret til OLA/USB-backend”
     - “Fysisk signal verificeret”
   - TuxDMX må ikke hævde at have målt det elektriske DMX-signal uden understøttet RX, RDM, loopback eller ekstern sniffer.

9. **Driftssikkerhed**
   - Blackout/Panic skal altid have højeste prioritet.
   - Strobe skal have maksimal varighed og cooldown.
   - Ved stop eller fejl skal systemet kunne gå til en konfigurerbar sikker scene.
   - Ingen Twitch-bruger må kunne holde en farlig eller generende effekt kørende permanent.

10. **Ingen automatisk MIT-licens**
    - Tilføj ikke MIT-licens eller anden permissiv licens.
    - Projektet skal som udgangspunkt være privat/proprietært.
    - Brug en kort “All rights reserved – Thomas / TuxiNet” notice, medmindre Thomas senere vælger en anden licens.
    - Opret `THIRD_PARTY_NOTICES.md` med relevante tredjepartskomponenter og licenser.
    - Kopiér ikke kode fra andre projekter uden korrekt licensgrundlag.

---

# 4. Teknologistak

## Backend

Brug:

- Python 3.11 eller nyere
- FastAPI
- Pydantic
- SQLAlchemy 2
- Alembic
- SQLite som standard
- WebSocket til live opdateringer
- `httpx` til OFL-integration
- `psutil` til systemtelemetri
- Argon2 til password hashing
- Struktureret logging i JSON samt menneskelæsbar log
- AsyncIO hvor det giver mening

Backend skal være typeannoteret og bestå statisk typekontrol.

## Frontend

Brug:

- React
- TypeScript
- Vite
- Et let komponentlag; undgå et unødvendigt tungt enterprise-framework
- CSS-variabler eller Tailwind til dark theme
- WebSocket til live data
- Drag-and-drop til patch, grupper og chasertrin
- Responsivt design til desktop, tablet og mobil

Frontend bygges til statiske filer og serveres af backend eller en lille lokal webserver. Node.js skal ikke være nødvendig ved normal drift på Raspberry Pi’en efter build.

## DMX-backend

- OLA / `olad`
- TuxDMX skal have et adapterinterface:
  - `OlaDmxBackend`
  - `SimulatorDmxBackend`
  - mulighed for senere `ArtNetBackend` eller `SacnBackend`
- DMX-motoren skal være adskilt logisk fra HTTP-requesthåndtering.
- En dedikeret worker/proces eller workertråd skal eje frame-loopet, så langsomme webrequests ikke påvirker DMX-timing.

## Installation

Normal produktion skal installeres native på Raspberry Pi OS. Brug ikke Docker som primær runtime, fordi USB-, realtime-audio- og OLA-adgang ellers bliver mere kompliceret.

Der må gerne være en valgfri Docker/devcontainer til lokal udvikling og CI, men den må ikke være den eneste installationsmetode.

---

# 5. Arkitektur

Opdel systemet i tydelige moduler:

```text
tuxdmx/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── auth/
│   │   ├── bpm/
│   │   ├── core/
│   │   ├── dmx/
│   │   ├── effects/
│   │   ├── fixtures/
│   │   ├── mixitup/
│   │   ├── models/
│   │   ├── scenes/
│   │   ├── telemetry/
│   │   └── websocket/
│   ├── alembic/
│   └── tests/
├── frontend/
│   ├── src/
│   └── tests/
├── systemd/
├── scripts/
├── docs/
├── test-data/
├── pyproject.toml
├── README.md
├── INSTALL-PI.md
├── HARDWARE-VALIDATION.md
├── TROUBLESHOOTING.md
├── SECURITY.md
└── THIRD_PARTY_NOTICES.md
```

## Procesmodel

Anbefalet:

1. `olad`
   - OLA-daemon.
   - Ejer USB-DMX-enheden og outputporten.

2. `tuxdmx`
   - FastAPI, database, triggerkø, WebSocket og UI.

3. `tuxdmx-engine`
   - Dedikeret DMX-frame-, scene- og effektmotor.
   - Kommunikerer lokalt med backend gennem Unix socket eller en anden enkel lokal IPC-løsning.
   - Må ikke eksponeres direkte på LAN.

4. `tuxdmx-bpm`
   - Kan være integreret i engine-processen eller være en separat proces.
   - Skal kunne genstartes uden at stoppe DMX-output.

Hvis en separat procesmodel bliver unødvendigt kompleks, kan backend og engine køre i samme Python-pakke, men DMX-loopet skal stadig være isoleret fra webserverens event loop.

---

# 6. Førstegangsopsætning

Ved første besøg skal en guide åbne automatisk.

## Trin 1 – Administrator

- Opret lokal administrator.
- Brugernavn.
- Stærkt password.
- Vis ikke standardpassword.
- Opret sessionsbaseret login.

## Trin 2 – System

- Vis hostname, IP, platform, arkitektur og OS.
- Kontroller om OLA/`olad` kører.
- Kontroller om TuxDMX kan kommunikere med OLA.
- Vis fundne OLA-devices og porte.

## Trin 3 – DMX

- Vælg universe.
- Vælg OLA outputdevice og port.
- Testknap:
  - “Send kanal 1 til 20 %”
  - “Send kanal 1 til 100 %”
  - “Sluk kanal 1”
- Test skal have timer og automatisk nulstille kanalen.

## Trin 4 – Sikkerhed

- Maksimal strobevarighed.
- Global master-limit, eksempelvis 80 %.
- Safe scene ved stop.
- Blackout-adfærd.
- Twitch-trigger rate limit.

## Trin 5 – MixItUp

- Generér integrations-token.
- Vis TuxDMX base-URL.
- Opret en testtrigger.
- Vis en trin-for-trin MixItUp-guide.

## Trin 6 – Færdig

- Gem konfiguration.
- Gå til Dashboard.
- Guiden skal kunne åbnes igen senere.

---

# 7. Brugere og adgang

Roller:

- **Administrator**
  - Alt.
- **Operator**
  - Live Desk, scener, effekter, BPM og blackout.
  - Må ikke ændre system-, bruger- eller API-sikkerhedsindstillinger.
- **Read only**
  - Dashboard og telemetri.

Krav:

- Lokalt login.
- Argon2 password hash.
- Session-cookie.
- CSRF-beskyttelse.
- Rate limit på login.
- Auditlog for konfigurationsændringer.
- Mulighed for at deaktivere login på et fuldstændigt isoleret LAN, men kun efter tydelig advarsel.
- API-tokens skal kunne tilbagekaldes og roteres.
- Tokens vises kun fuldt ud ved oprettelse.

---

# 8. Open Fixture Library-integration

## Officielle endpoints

Brug som udgangspunkt:

```text
POST https://open-fixture-library.org/api/v1/get-search-results
```

Eksempel på request:

```json
{
  "searchQuery": "showtec phantom",
  "manufacturersQuery": [],
  "categoriesQuery": []
}
```

Resultatet er fixture keys som:

```json
[
  "showtec/phantom-3r-beam",
  "showtec/phantom-50-led-spot"
]
```

Hent OFL JSON-formatet gennem:

```text
https://open-fixture-library.org/{manufacturerKey}/{fixtureKey}.ofl
```

Brug eventuelt manufacturer-endpoints til metadata:

```text
GET https://open-fixture-library.org/api/v1/manufacturers
GET https://open-fixture-library.org/api/v1/manufacturers/{manufacturerKey}
```

## Vigtigt om OFL-formatet

OFL-formatet kan ændre sig mellem schema-versioner. Derfor må resten af TuxDMX ikke bruge OFL-JSON direkte som sit interne runtime-format.

Implementér:

```text
OFL JSON
   │
   ▼
OflImporter
   │ validering og versionskontrol
   ▼
TuxDMX Normalized Fixture Model
   │
   ▼
Database og runtime
```

Gem både:

- Den originale importerede OFL-fil.
- `$schema`.
- Manufacturer key.
- Fixture key.
- OFL URL.
- Importdato.
- Hash.
- Normaliseret intern fixtureversion.
- Eventuelle warnings og unsupported capabilities.

## Søge-UI

Fixture-siden skal have:

- Søgefelt.
- Manufacturer-filter.
- Kategori-filter.
- Resultatkort med:
  - Manufacturer.
  - Fixture-navn.
  - Kategorier.
  - Tilgængelige modes.
  - Sidst ændret, når data findes.
- “Vis detaljer”.
- “Importér”.
- “Importér og patch”.
- Lokal cacheindikator.
- Offline fallback.

## Importfunktioner

Understøt mindst:

- Manufacturer.
- Fixture name og short name.
- Categories.
- Physical data.
- DMX connector.
- Modes.
- Available channels.
- Default value.
- Highlight value.
- HTP/LTP precedence.
- Fine channels og 16-bit værdier.
- Capability-ranges.
- ColorIntensity.
- Intensity.
- Pan.
- Tilt.
- Shutter og strobe.
- Gobo- og color wheels.
- Prism.
- Focus.
- Zoom.
- Iris.
- Effect speed.
- Maintenance.
- NoFunction.
- Switching channels.
- Matrix/pixels, hvor det kan normaliseres sikkert.
- Ukendte capability-typer skal bevares som “Generic/Unsupported”, ikke kasseres lydløst.

## Validering

- Valider JSON.
- Kontroller mode channel count.
- Kontroller at patchen holder sig inden for kanal 1–512.
- Vis warnings før import.
- Blokér kun ved reelle invalide data.
- Tillad brugerdefineret fixture, hvis en lampe ikke findes i OFL.

## Opdateringer

- Vis når en importeret fixture har en nyere OFL-version.
- Overskriv aldrig lokal fixture eller patch automatisk.
- Vis diff og kræv brugerens godkendelse.
- Bevar eksisterende scenes referencer.
- Opret automatisk backup før migration.

---

# 9. Internt fixtureformat

Design et stabilt internt fixtureformat med versionsnummer.

Eksempel på hovedbegreber:

```text
FixtureDefinition
├── manufacturer
├── model
├── categories
├── modes[]
├── channels[]
├── wheels[]
├── matrix
├── physical
├── source
└── schema_version
```

Et mode skal indeholde en ordnet kanalmap.

En normaliseret channel skal blandt andet have:

- Key.
- Display name.
- Kanaltype.
- Default.
- Highlight.
- Resolution.
- Fine channelrelation.
- Precedence: HTP/LTP.
- Crossfade allowed.
- Capabilities med DMX range og semantik.
- Optional pixel key.
- Optional switching dependency.

Opret en capability-adapter, så UI kan vise relevante kontroller:

| Capability | UI-kontrol |
|---|---|
| Intensity | Slider |
| ColorIntensity RGB(W/A/UV) | Farvevælger + kanalsliders |
| Pan/Tilt | XY-pad + sliders |
| ShutterStrobe | Dropdown + strobe slider |
| WheelSlot | Dropdown med slotnavn/ikon |
| Focus/Zoom/Iris | Slider |
| EffectSpeed | Slider |
| Maintenance | Beskyttet dropdown med advarsel |
| Generic/Unsupported | Rå DMX-slider med tydelig mærkning |

Maintenance-kanaler må ikke vises på Live Desk som standard.

---

# 10. Patch og universer

## Grundkrav

- Universe 1 skal være fuldt understøttet.
- Datamodel og API skal være klar til flere universer senere.
- En fixtureinstans består af:
  - Brugerdefineret navn.
  - Fixturedefinition.
  - Mode.
  - Startadresse.
  - Antal kanaler.
  - Gruppe(r).
  - Position.
  - Tags.
  - Enabled/disabled.

## Patch UI

- Universe-visning fra kanal 1 til 512.
- Vis optagede og frie områder.
- Drag-and-drop.
- Automatisk “find næste ledige adresse”.
- Konfliktkontrol.
- Vis kanalinterval, eksempelvis `1–14`.
- Mulighed for flere identiske fixtures.
- Duplicate fixture.
- Batch patch.
- Readdress.
- Disable uden at slette.
- Gruppér fixtures:
  - Front.
  - Bag.
  - Venstre.
  - Højre.
  - Moving heads.
  - PAR.
  - Strobe.
  - Egne grupper.

## OLA-patch

TuxDMX skal kunne:

- Læse OLA-status og devices.
- Vælge outputport.
- Gemme den valgte port.
- Kontrollere ved start om porten stadig findes.
- Gå til tydelig degraded mode, hvis USB-enheden mangler.
- Automatisk genforbinde, når USB-DMX kommer tilbage.
- Ikke sende tilfældige kanalværdier ved reconnect.

---

# 11. Live Desk

Live Desk er den normale betjeningsside.

## Toplinje

- Master dimmer.
- Blackout.
- Freeze.
- Release all temporary effects.
- Aktuel scene.
- Aktuel BPM.
- Beatindikator.
- DMX/USB-status.
- Frame rate.
- Twitch-triggerkø.

## Fixturekort

Hvert kort skal vise kontroller, der passer til fixturetypen:

- Dimmer.
- Farvevælger.
- RGB/RGBW/RGBAWUV.
- Pan/tilt XY-pad.
- Pan og tilt numeric/sliders.
- Shutter.
- Strobe.
- Gobo.
- Prism.
- Focus.
- Zoom.
- Iris.
- Effect/macro.
- Reset og maintenance skal kræve ekstra bekræftelse.

## Gruppekontrol

- Vælg fixturegruppe.
- Justér alle fixtures samlet.
- Relative pan/tilt.
- Fan/spread.
- Mirror.
- Invert pan/tilt.
- Global farve.
- Global dimmer.

## Programmer/preview

- Live output.
- Blind/editor mode.
- Preview i simulator uden at sende til hardware.
- “Take live” med fade.

---

# 12. Scener

En scene er et statisk eller delvist statisk sæt kanal-/fixtureværdier.

Funktioner:

- Opret.
- Redigér.
- Duplikér.
- Slet.
- Aktivér.
- Deaktivér.
- Fade in.
- Fade out.
- Hold time.
- Prioritet.
- Tags.
- Farve/ikon.
- Valgfri BPM-quantize.
- Valgfri master-limit.
- Gem kun berørte parametre, så en scene kan lægges oven på en anden.
- Preview før aktivering.
- Scenegrupper/banks.

Eksempler:

- Normal.
- Stream.
- Pause.
- Pink.
- Blue.
- Warm white.
- DJ intro.
- Raid.
- Blackout.
- Safe shutdown.

Ved aktivering skal UI vise:

- Starttid.
- Fade status.
- Kilde: manuel, MixItUp, API, schedule eller system.
- Bruger/event.
- Prioritet.
- Hvor længe scenen har kørt.

---

# 13. Chasers og effektmotor

## Chasers

- En chaser består af steps.
- Hvert step kan være:
  - Scene.
  - Delvis fixture-state.
  - Effekt.
  - Pause.
- Step duration.
- Fade duration.
- Loop count.
- Ping-pong.
- Random order.
- BPM-sync.
- Start/stop/pause/resume.
- Restore previous state.

## Indbyggede effekter

Implementér mindst:

1. Dimmer pulse.
2. Strobe med sikkerhedsbegrænsning.
3. RGB/RGBW color chase.
4. Rainbow.
5. Random color.
6. Alternate group chase.
7. Fade mellem farver.
8. Beat flash.
9. Moving-head circle.
10. Moving-head figure-eight.
11. Pan sweep.
12. Tilt sweep.
13. Fan/spread.
14. Raid-sekvens.
15. Subscriber-sekvens.
16. Follow flash.
17. Channel Point-farvevalg.
18. Blackout.
19. Return-to-base-scene.
20. Audio-reactive intensity.

## Parametre

Alle effektparametre skal konfigureres via UI:

- Fixturegruppe.
- Farver.
- Intensitet.
- Varighed.
- Hastighed.
- BPM division.
- Fade.
- Strobe rate.
- Bevægelsesstørrelse.
- Center.
- Retning.
- Loop.
- Prioritet.
- Cooldown.
- Restore behavior.

## Tilstand og prioritering

Implementér en state/effect stack.

Eksempel:

```text
Base scene: Stream
        │
        ├── Sub-effect, prioritet 40, 8 sekunder
        │
        └── Raid-effect, prioritet 60, 15 sekunder
                         │
                         └── Blackout, prioritet 1000
```

Når en midlertidig effekt slutter, skal systemet vende tilbage til den korrekte underliggende state.

## Merge

- Intensity-kanaler bruger normalt HTP.
- Movement, color, wheels og andre positionskanaler bruger normalt LTP.
- Brug OFL precedence, når det findes.
- Brug en dokumenteret fallbackmapping, når precedence mangler.
- Blackout skal kunne overstyre alt.
- Freeze skal stoppe ændringer uden at nulstille output.

---

# 14. DMX-frame engine

## Grundprincip

- 512 kanaler pr. universe.
- Værdier 0–255.
- Konfigurerbar outputrate, eksempelvis 25, 30 eller 40 frames/s.
- Standard: 30 frames/s, medmindre hardwaretest viser andet.
- Engine beregner target frame, transitions, effects og merge.
- Den seneste komplette frame afleveres til OLA.

## Målinger

For hver periode skal engine registrere:

- Target frame rate.
- Faktisk frame rate.
- Jitter.
- Frame calculation time.
- OLA send duration.
- Success/failure.
- Dropped/skipped frames.
- Queue depth.
- Seneste succesfulde send.
- Seneste fejl.
- Reconnect count.

## Fejlhåndtering

- OLA utilgængelig:
  - Log fejl.
  - Gå i degraded mode.
  - Fortsæt state engine.
  - Forsøg reconnect med backoff.
- USB mangler:
  - Tydelig rød status.
  - Ingen falsk “DMX OK”.
  - Automatisk reconnect.
- Engine crash:
  - systemd restart.
  - Safe state ved ny opstart.
- Databasefejl:
  - DMX-engine skal så vidt muligt fortsætte med seneste in-memory state.
- UI disconnect:
  - Må ikke stoppe lyset.

---

# 15. BPM- og beatmotor

## Input modes

1. **Manual**
   - Brugeren indtaster BPM.

2. **Tap tempo**
   - Stor tap-knap.
   - Tastaturgenvej.
   - Beregn median/robust average af seneste taps.
   - Reset efter længere pause.

3. **Audio**
   - Vælg audio device/input.
   - Understøt mono/stereo.
   - Vælg kanal: left, right eller mix.
   - Signal meter.
   - Silence detection.
   - BPM confidence.

4. **External API**
   - Modtag BPM og beat-pulse gennem REST/WebSocket.
   - Gør det muligt senere at koble DJ-software, Companion eller andre systemer på.

5. **Fremtidig adapter**
   - Arkitekturen skal gøre MIDI Clock og OSC muligt senere, men det behøver ikke være fuldt implementeret i første release.

## Audio capture

Prioritér denne rækkefølge:

1. JACK, når JACK er aktiveret og tilgængelig.
2. PipeWire/JACK compatibility, når relevant.
3. ALSA direkte capture som fallback.

Brug aubio eller tilsvarende til:

- Tempo detection.
- Beat detection.
- Confidence.
- Onsets.

## Stabilisering

- Konfigurerbart BPM-range, standard 60–200.
- Half/double-time correction.
- Smoothing.
- Minimum confidence.
- Hold seneste stabile BPM ved korte udfald.
- Markér BPM som “usikker” ved lav confidence.
- Beat phase må ikke hoppe voldsomt ved hver ny analyse.
- Mulighed for manuel “×2”, “÷2” og nudge.

## Beat event bus

Udsend interne events:

```text
beat
bar
half
quarter
eighth
sixteenth
```

Effekter skal kunne quantizes til næste beat eller bar.

## UI

BPM-siden skal vise:

- Aktuel BPM.
- Kilde.
- Confidence.
- Signalstyrke.
- Seneste beat.
- Beat-animation.
- Tap-knap.
- Start/stop audioanalyse.
- Audio device.
- Input channel.
- Sensitivity.
- BPM-range.
- Half/double.
- Test click track i simulator.

## Testdata

Opret syntetiske click tracks i tests ved eksempelvis:

- 90 BPM.
- 120 BPM.
- 128 BPM.
- 140 BPM.
- 174 BPM.

Brug ikke ophavsretligt beskyttet musik i repository.

---

# 16. MixItUp og Twitch

## Integrationsprincip

MixItUp bruger Web Request Actions til at kalde TuxDMX.

TuxDMX skal returnere hurtigt:

- HTTP `202 Accepted` ved accepteret trigger.
- Triggeren lægges i intern kø.
- Svartid skal normalt være under 200 ms på LAN.
- Langvarige lyseffekter må aldrig holde HTTP-requesten åben.

## API-token

- Opret et separat token til MixItUp.
- Bearer token i header.
- Token kan roteres.
- Mulighed for IP allowlist.
- Rate limiting.
- Auditlog.
- Ingen API-token i URL querystring.

## Generisk triggerendpoint

```http
POST /api/v1/triggers/{slug}
Authorization: Bearer <token>
Content-Type: application/json
```

Eksempel:

```json
{
  "eventType": "raid",
  "username": "$username",
  "displayName": "$displayname",
  "amount": "$raidviewercount",
  "eventId": "$eventid",
  "platform": "twitch",
  "metadata": {}
}
```

TuxDMX må acceptere, at nogle MixItUp-identifiers mangler.

## Simpelt endpoint

Der skal også kunne genereres simple endpoints:

```text
POST /api/v1/scenes/{sceneSlug}/activate
POST /api/v1/effects/{effectSlug}/trigger
POST /api/v1/blackout
POST /api/v1/bpm/tap
```

## Mapping-UI

Siden “MixItUp” skal gøre det muligt at:

- Oprette integration.
- Navngive integration.
- Generere token.
- Vælge eventtype:
  - Follow.
  - Subscription.
  - Resub.
  - Gift sub.
  - Bits/Cheers.
  - Raid.
  - Channel Point Reward.
  - Chat command.
  - Moderator command.
  - Giveaway event.
  - Custom.
- Vælge scene eller effekt.
- Vælge varighed.
- Prioritet.
- Cooldown.
- Minimum amount/viewers/bits.
- Tilladte brugerroller.
- Restore behavior.
- Max samtidige triggers.
- Duplicate/idempotency window.
- Aktiv/inaktiv.
- Test-knap.

## MixItUp-guide i UI

For hver mapping skal UI generere:

- HTTP-metode.
- URL.
- Headernavn og token.
- JSON body.
- Hvilke MixItUp special identifiers der foreslås.
- Copy-knapper.
- Testresultat.
- Seneste kald.
- Seneste fejl.

Brugeren må ikke skulle skrive JavaScript.

## Eventkø

Køen skal understøtte:

- Prioritet.
- Max længde.
- Deduplication med eventId.
- Cooldown per mapping.
- Cooldown per bruger.
- Global cooldown.
- Drop/replace/queue policy.
- “Raid erstatter mindre follow-effekt”.
- “Blackout rydder køen”.
- Live visning af køen.

## Standardpresets

Opret standardpresets, der kan redigeres:

- Follow: kort hvid flash.
- Sub: pink/guld pulse.
- Resub: længere pulse.
- Gift sub: chase afhængigt af antal.
- Bits: intensitet afhængigt af amount.
- Raid: stor sekvens afhængigt af viewer count.
- Channel Points: valgt farve.
- `!party`: rainbow.
- Moderator blackout.
- Moderator normal scene.

---

# 17. REST API

API skal være versioneret under `/api/v1`.

Minimum:

## System

```text
GET  /api/v1/health
GET  /api/v1/system/status
GET  /api/v1/system/diagnostics
POST /api/v1/system/restart-service
```

## OLA/DMX

```text
GET  /api/v1/dmx/status
GET  /api/v1/dmx/devices
GET  /api/v1/dmx/universes
GET  /api/v1/dmx/frame
POST /api/v1/dmx/test-channel
POST /api/v1/dmx/blackout
POST /api/v1/dmx/release-blackout
```

## Fixtures

```text
GET    /api/v1/fixtures
POST   /api/v1/fixtures/search-ofl
POST   /api/v1/fixtures/import-ofl
POST   /api/v1/fixtures/import-file
POST   /api/v1/fixtures/custom
GET    /api/v1/fixtures/{id}
PUT    /api/v1/fixtures/{id}
DELETE /api/v1/fixtures/{id}
```

## Patch

```text
GET    /api/v1/patch
POST   /api/v1/patch
PUT    /api/v1/patch/{id}
DELETE /api/v1/patch/{id}
POST   /api/v1/patch/validate
```

## Scenes

```text
GET    /api/v1/scenes
POST   /api/v1/scenes
GET    /api/v1/scenes/{id}
PUT    /api/v1/scenes/{id}
DELETE /api/v1/scenes/{id}
POST   /api/v1/scenes/{slug}/activate
POST   /api/v1/scenes/{slug}/release
```

## Effects/chasers

```text
GET    /api/v1/effects
POST   /api/v1/effects
PUT    /api/v1/effects/{id}
DELETE /api/v1/effects/{id}
POST   /api/v1/effects/{slug}/trigger
POST   /api/v1/effects/{slug}/stop
```

## BPM

```text
GET  /api/v1/bpm/status
POST /api/v1/bpm/manual
POST /api/v1/bpm/tap
POST /api/v1/bpm/audio/start
POST /api/v1/bpm/audio/stop
POST /api/v1/bpm/external
GET  /api/v1/bpm/devices
```

## MixItUp

```text
GET    /api/v1/integrations/mixitup
POST   /api/v1/integrations/mixitup
PUT    /api/v1/integrations/mixitup/{id}
DELETE /api/v1/integrations/mixitup/{id}
POST   /api/v1/integrations/mixitup/{id}/test
POST   /api/v1/triggers/{slug}
```

## Telemetri

```text
GET /api/v1/telemetry/live
GET /api/v1/telemetry/history
GET /api/v1/events
GET /api/v1/logs
```

## Backup

```text
POST /api/v1/backups
GET  /api/v1/backups
POST /api/v1/backups/{id}/restore
DELETE /api/v1/backups/{id}
```

FastAPI OpenAPI-dokumentation må eksistere, men skal som standard kun være tilgængelig for administrator eller på localhost i production.

---

# 18. WebSocket

Brug WebSocket til:

- DMX frame/live channel values.
- Telemetri.
- BPM og beat.
- Scene transitions.
- Effektstatus.
- Triggerkø.
- Hardwarestatus.
- Logs.

Klienten skal reconnecte automatisk med backoff.

Undgå at sende alle 512 kanaler unødigt ved hver UI-frame. Brug:

- Deltas, når det er praktisk.
- Begrænset UI-opdateringsrate.
- Snapshot ved connect.
- Binary format er valgfrit; almindelig kompakt JSON er acceptabelt i første release.

---

# 19. Telemetri og diagnostik

## Dashboard

Vis:

- TuxDMX version.
- Uptime.
- OLA connected/disconnected.
- USB-DMX device.
- Universe/port.
- DMX output aktiv.
- Software output status.
- Aktuel scene.
- Aktive effekter.
- BPM.
- Triggerkø.
- CPU.
- RAM.
- CPU-temperatur.
- Disk.
- Netværk.
- Seneste fejl.

## DMX-monitor

Vis:

- 512-kanals grid/heatmap.
- Kanalnummer.
- Current value.
- Target value.
- Source.
- Fixture.
- Parameter.
- Priority.
- Fade status.
- Sidst ændret.
- Mini-graf for valgte kanaler.

Vis også decoded fixture view, eksempelvis:

```text
Fixture: Moving Head Left
Dimmer: 255
Color: Blue
Pan: 32768 / 50 %
Tilt: 22000 / 34 %
Gobo: Stars
Shutter: Open
```

## USB/OLA

Vis:

- USB vendor/product ID, når tilgængeligt.
- Device path.
- OLA plugin.
- OLA device ID.
- Port.
- RX/TX/RDM capabilities.
- Connected since.
- Reconnect count.
- Seneste OLA-fejl.
- Seneste succesfulde frame.

## Fysisk verifikation

UI skal have en forklaring:

> TuxDMX kan se den frame, som er beregnet og afleveret til OLA. Det beviser ikke alene, at det elektriske DMX-signal når lampen. Fysisk verifikation kræver understøttet DMX-input, RDM, loopback eller ekstern analyzer.

Hvis adapteren understøtter RX eller RDM, må der senere tilføjes:

- DMX input monitor.
- RDM discovery.
- Device responses.
- Loopback test.

## Logning

Kategorier:

- SYSTEM.
- AUTH.
- OLA.
- USB.
- DMX.
- FIXTURE.
- PATCH.
- SCENE.
- EFFECT.
- BPM.
- MIXITUP.
- API.
- BACKUP.

Niveauer:

- DEBUG.
- INFO.
- WARNING.
- ERROR.
- CRITICAL.

UI skal kunne:

- Filtrere.
- Søge.
- Downloade diagnostikbundle.
- Vise seneste 100/1000 linjer.
- Redigere retention.

Standard retention:

- Detaljeret telemetri: 7 dage.
- Aggregeret telemetri: 30 dage.
- Eventlog: 90 dage.
- Auditlog: 180 dage.

Gør værdierne konfigurerbare.

---

# 20. Database

Brug SQLite med WAL mode.

Tabeller bør mindst dække:

- users
- sessions
- api_tokens
- audit_log
- settings
- fixture_sources
- fixture_definitions
- fixture_modes
- fixture_channels
- fixture_capabilities
- fixture_instances
- fixture_groups
- fixture_group_members
- universes
- ola_bindings
- scenes
- scene_layers
- scene_values
- effects
- effect_parameters
- chasers
- chaser_steps
- trigger_mappings
- trigger_events
- trigger_queue
- bpm_settings
- telemetry_samples
- system_events
- backups
- schema_migrations

Gem ikke telemetri ukontrolleret i fuld opløsning for evigt. Implementér pruning og aggregering.

---

# 21. Backup og restore

Backup skal indeholde:

- Database.
- Konfiguration.
- Importerede OFL-filer.
- Custom fixtures.
- Scener.
- Effekter.
- MixItUp mappings.
- Brugere, men aldrig plaintext passwords.
- Version og manifest.
- Checksums.

Funktioner:

- Manuel backup.
- Automatisk daglig backup.
- Retention.
- Download gennem UI.
- Upload og restore.
- Pre-restore backup.
- Valider backup før restore.
- Vis hvilke versioner backupen kommer fra.
- Migration ved ældre schema.
- Restore må kræve administratorpassword.

---

# 22. Systemservice og autostart

Opret systemd units:

```text
olad.service
tuxdmx.service
tuxdmx-engine.service
tuxdmx-bpm.service
```

Brug kun de services, arkitekturen reelt kræver.

Krav:

- `After=network-online.target`
- OLA skal være startet før DMX-engine.
- `Restart=on-failure`
- Fornuftig restart delay.
- Dedicated Linux user: `tuxdmx`
- Mindst mulige rettigheder.
- Medlemskab af nødvendige grupper:
  - dialout
  - plugdev
  - audio
- Skrivbare data under `/var/lib/tuxdmx`
- Konfiguration under `/etc/tuxdmx`
- Logs gennem journald samt applikationslog.
- Applikation under `/opt/tuxdmx`
- Ingen drift som root, medmindre en helt konkret hardwarefunktion kræver det.

## Safe shutdown

Ved normal service-stop:

1. Stop nye triggers.
2. Stop midlertidige effekter.
3. Fade til safe scene eller blackout efter indstilling.
4. Send flere sikre frames.
5. Stop DMX-engine.
6. Stop applikation.

---

# 23. Installationsscript

Opret:

```text
scripts/install-pi.sh
scripts/update-pi.sh
scripts/uninstall-pi.sh
scripts/pi-smoke-test.sh
scripts/collect-diagnostics.sh
```

## `install-pi.sh`

Skal:

- Kontrollere OS og arkitektur.
- Kontrollere internet.
- Installere nødvendige apt-pakker.
- Installere eller kontrollere OLA.
- Oprette systembruger og mapper.
- Oprette Python virtualenv.
- Installere låste Python dependencies.
- Kopiere frontend build.
- Installere systemd units.
- Oprette config.
- Generere secret.
- Aktivere services.
- Vise IP og Web UI URL.
- Ikke overskrive eksisterende installation uden backup og bekræftelse.
- Have `--non-interactive` til automatiseret installation.
- Have tydelige fejlbeskeder.

## `update-pi.sh`

- Stop nye triggers.
- Backup.
- Download/kopiér ny version.
- Installer dependencies.
- Kør Alembic migration.
- Byg/installer.
- Start services.
- Kør health check.
- Rollback ved fejl.

## `pi-smoke-test.sh`

Skal kontrollere:

- OS/arkitektur.
- OLA package/version.
- `olad` status.
- TuxDMX services.
- API health.
- Database.
- WebSocket.
- OLA forbindelse.
- USB devices.
- OLA device/port.
- Permission groups.
- Audio devices.
- JACK/ALSA status.
- Temperatur/disk.
- Send testframe i simulator.
- Valgfri hardwarekanaltest med eksplicit brugerbekræftelse.
- Returnere non-zero exit code ved fejl.
- Skrive en klar rapport.

## `collect-diagnostics.sh`

Skal generere en ZIP/TAR med:

- Service status.
- Journaluddrag.
- TuxDMX logs.
- OLA status/config.
- `lsusb`.
- Relevant `dmesg`, filtreret.
- OS info.
- Python/package versions.
- Netværksstatus.
- Audio devices.
- Redigeret config uden secrets.
- Database integrity check.
- Ingen API tokens eller password hashes i rapporten.

---

# 24. Simulator og udvikling uden Raspberry Pi

Dette er obligatorisk, fordi Codex ikke kan teste den fysiske Pi.

## Simulator backend

`SimulatorDmxBackend` skal:

- Emulere universe med 512 kanaler.
- Acceptere frames på samme måde som OLA-backenden.
- Simulere frame latency.
- Simulere fejl:
  - USB disconnected.
  - OLA unavailable.
  - Send timeout.
  - Dropped frame.
  - Slow backend.
- Vise output i UI.
- Gemme framehistorik i memory.
- Understøtte automatiske assertions.

## Fixture simulator

Vis fixturekort visuelt:

- PAR: farve og lysstyrke.
- Moving head: pan/tilt position, beam color, dimmer, gobo text.
- Strobe: vis sikker animation, ikke aggressiv fuldskærmsblink.
- Matrix: pixelgrid.

Simulatoren behøver ikke være en fuld 3D-visualizer.

## Fake OLA

Implementér et mock interface, ikke en kopi af OLA.

Tests skal kunne verificere:

- Frames har korrekt længde.
- Værdier er 0–255.
- Correct universe.
- Reconnect.
- Error handling.
- Frame rate.
- Merge.
- Fade.

## Recorded OFL responses

Læg små, lovlige testfixtures i `test-data`:

- RGB 3 channel.
- RGBW med dimmer og strobe.
- Moving head med 16-bit pan/tilt.
- Fixture med gobo/color wheel.
- Fixture med switching channel.
- Matrix/pixel fixture.
- Invalid fixture.

Brug snapshots eller reducerede testdata, og dokumentér kilden/licensen.

---

# 25. Tests

## Backend unit tests

- OFL parsing og normalisering.
- Schema/version detection.
- 8-bit og 16-bit.
- Fine channels.
- Capability ranges.
- Switching channels.
- Patch conflict.
- Address boundary 512.
- HTP.
- LTP.
- Scene merge.
- Fade interpolation.
- Effect stack.
- Restore previous state.
- Blackout priority.
- Strobe limits.
- Trigger cooldown.
- Idempotency.
- Token auth.
- Telemetry aggregation.
- Backup/restore.
- Database migrations.
- BPM smoothing.
- Half/double BPM.
- Synthetic click tracks.

## Integration tests

- FastAPI + SQLite.
- WebSocket.
- Mock engine.
- Fake OLA backend.
- OFL HTTP mock.
- MixItUp trigger request.
- Queue processing.
- Service degraded mode.

## Frontend tests

- Login.
- First-run wizard.
- Fixture search.
- Import.
- Patch.
- Scene creation.
- Effect creation.
- MixItUp mapping.
- Blackout.
- Telemetry.
- Responsive layout.
- Accessibility basics.

Brug Playwright eller tilsvarende til centrale flows.

## CI

CI skal køre:

- Formatting.
- Lint.
- Type check.
- Unit tests.
- Integration tests.
- Frontend tests.
- Production build.
- Dependency audit.
- Arm64 build/check gennem QEMU eller cross-build, hvor det er praktisk.

CI må ikke markere fysisk DMX-hardware som testet.

---

# 26. Sikkerhedsregler for lys

## Strobe

Standard:

- Max varighed: 3 sekunder.
- Absolut max: 10 sekunder.
- Cooldown: 30 sekunder.
- Twitch må ikke ændre de globale maxgrænser.
- UI skal advare om fotosensitivitet.
- Administrator kan sænke grænserne.
- Strobe skal stoppe ved blackout, enginefejl eller trigger cancellation.

## Master limit

- Global intensitetsgrænse.
- Twitch-specifik intensitetsgrænse.
- Testmode-grænse.
- Per fixture/group limit.

## Blackout

- Fast knap i alle relevante UI-visninger.
- Tastaturgenvej.
- API endpoint.
- Højeste prioritet.
- Ryd eller pause triggerkø efter konfiguration.
- Kræv bekræftelse for release, hvis aktiveret som emergency blackout.

## Maintenance/reset

- Fixture reset, lamp on/off og maintenance-funktioner skal være beskyttet.
- Ikke tilgængelig for Twitch.
- Kræv administrator eller særskilt confirmation.

---

# 27. UI-sider

## 1. Login

- Mørkt.
- TuxDMX logo/tekst.
- Ingen standardcredentials.

## 2. Dashboard

- Systemstatus.
- DMX.
- Scene.
- BPM.
- Twitch.
- Telemetri.
- Quick actions.

## 3. Live Desk

- Master.
- Blackout.
- Fixture- og gruppekontrol.
- Scene/effect launchpad.

## 4. Fixtures

- Lokale fixtures.
- OFL-søgning.
- Import.
- Custom fixture editor.
- Update status.

## 5. Patch

- Universe 1–512.
- Fixture placement.
- Conflict detection.
- OLA output.

## 6. Groups

- Fixturegrupper.
- Drag-and-drop.
- Tags.

## 7. Scenes

- Liste.
- Editor.
- Preview.
- Launch.

## 8. Effects

- Presets.
- Effect builder.
- Chaser timeline.
- BPM sync.

## 9. BPM

- Manual.
- Tap.
- Audio.
- Confidence.
- Input devices.

## 10. MixItUp

- Tokens.
- Mappings.
- Generator.
- Test.
- Eventlog.
- Queue.

## 11. DMX Monitor

- 512 grid.
- Decoded fixtures.
- Sources og priorities.

## 12. Telemetry

- Historik.
- Grafer.
- OLA/USB.
- System.

## 13. Logs

- Filter.
- Search.
- Download diagnostics.

## 14. Backup

- Create.
- Download.
- Restore.
- Retention.

## 15. Settings

- System.
- DMX.
- Safety.
- BPM.
- Telemetry.
- Language.
- Users.
- API.
- Update.

---

# 28. Designkrav

- Dark-only i første release.
- Undgå hvid flash ved sideindlæsning.
- Store touchvenlige knapper.
- Blackout skal være tydelig, men ikke kunne aktiveres ved et let fejltap uden valgfri bekræftelse.
- Brug status:
  - Grøn: normal.
  - Gul: degraded/warning.
  - Rød: fejl/blackout.
  - Blå/cyan: aktiv/live.
  - Pink: Twitch/event.
- Ingen rå JSON-editor i normal UI.
- Tooltips med fixturecapability.
- Tastaturgenveje må kunne slås fra.
- Browser refresh må ikke ændre DMX-state.
- UI skal kunne miste forbindelsen uden at lyset stopper.

---

# 29. Performancekrav

Mål for Raspberry Pi 4/5:

- Web UI reagerer normalt under 250 ms på LAN.
- Triggerendpoint svarer normalt under 200 ms.
- DMX-engine holder den valgte frame rate med begrænset jitter.
- WebSocket telemetri må ikke blokere DMX output.
- Database pruning skal køre uden mærkbar påvirkning.
- Fixture søgning skal bruge cache og debounce.
- Ingen memory leak ved 24 timers drift.
- Systemet skal kunne køre mindst 72 timer i simulator soak test.

---

# 30. Fejltilstande, der skal håndteres

- Ingen internet ved boot.
- OFL utilgængelig.
- USB-DMX ikke tilsluttet.
- USB-DMX trækkes ud under drift.
- OLA stopper.
- OLA starter langsomt.
- Audio device mangler.
- Audio device ændrer navn.
- JACK utilgængelig.
- Dårligt eller stille audiosignal.
- Database locked.
- Disk næsten fuld.
- Pi overtemperatur.
- Netværk forsvinder.
- Browser disconnect.
- Dublet Twitch-event.
- Trigger spam.
- Ugyldig OFL fixture.
- Fixture update ændrer mode.
- Scene refererer til slettet fixture.
- Backup fra ældre schema.
- Strømafbrydelse under write.
- Service restart midt i en effekt.

Systemet skal vise forklarende fejl og foreslå næste skridt.

---

# 31. Dokumentation

## `README.md`

- Hvad TuxDMX er.
- Arkitektur.
- Screenshots eller mock screenshots.
- Hurtig simulatorstart.
- Links til øvrig dokumentation.
- Ingen påstand om hardwaretest.

## `INSTALL-PI.md`

- Hardwarekrav.
- Raspberry Pi OS Lite 64-bit.
- USB-DMX.
- USB audio input.
- Installation.
- OLA.
- Firewall.
- Første login.
- Autostart.
- Update.
- Uninstall.

## `HARDWARE-VALIDATION.md`

En præcis trin-for-trin plan:

1. Kør diagnostics.
2. Kontrollér OLA.
3. Tilslut USB-DMX.
4. Identificér device.
5. Patch port.
6. Tilslut én simpel lampe.
7. Sæt lampens DMX address.
8. Test dimmer.
9. Test RGB.
10. Test blackout.
11. Test reconnect.
12. Test scene.
13. Test MixItUp.
14. Test BPM.
15. Test reboot/autostart.
16. Kør 2 timers soak test.
17. Gem diagnostic bundle.

Hvert trin skal have forventet resultat og fejlsøgning.

## `TROUBLESHOOTING.md`

- OLA kan ikke se USB.
- Permission denied.
- `/dev/ttyUSB*`.
- FTDI/Open DMX vs Pro device.
- Forkert plugin.
- Ingen DMX.
- Flimren.
- Service restart.
- Web UI virker ikke.
- MixItUp timeout.
- BPM finder forkert tempo.
- Audio xruns.
- Høj CPU.
- Databasefejl.

## `MIXITUP.md`

- Opret Web Request Action.
- Method.
- URL.
- Headers.
- JSON.
- Test.
- Special identifiers.
- Fejlsøgning.
- Sikkerhed.

## `OFL.md`

- Search.
- Import.
- Cache.
- Schema.
- Unsupported capabilities.
- Updating fixtures.

## `SECURITY.md`

- LAN deployment.
- Tokens.
- Passwords.
- Reverse proxy.
- HTTPS.
- Secrets.
- Backup.
- Reporting.

---

# 32. Første releases omfang

## Release 1.0 skal indeholde

- Raspberry Pi headless installation.
- OLA backend.
- Simulator backend.
- Ét universe.
- USB-DMX output gennem OLA.
- OFL search/import.
- Custom fixture editor.
- Patch.
- Groups.
- Live Desk.
- Scenes.
- Chasers.
- De beskrevne grundeffekter.
- HTP/LTP merge.
- Blackout.
- Strobe safety.
- Manual BPM.
- Tap BPM.
- Audio BPM.
- MixItUp.
- REST API.
- WebSocket.
- Telemetry.
- Logs.
- Backup/restore.
- Users/roles.
- Autostart.
- Diagnostics.
- Tests.
- Dokumentation.

## Må gerne udsættes til senere

- Fuld 3D visualizer.
- Flere universer i UI.
- RDM configuration.
- DMX input.
- MIDI Clock.
- Ableton Link.
- Native Stream Deck plugin.
- Home Assistant integration.
- Companion module.
- Cloud access.
- Multi-node DMX.

Arkitekturen må gerne forberede disse uden at gøre 1.0 unødvendigt kompliceret.

---

# 33. Implementeringsrækkefølge

Arbejd i disse faser og lav logiske git commits.

## Fase 1 – Fundament

- Repository.
- Backend.
- Frontend.
- Database.
- Login.
- Simulator.
- Health.
- Dark UI.
- CI.

## Fase 2 – Fixture og patch

- OFL client.
- Normalisering.
- Local cache.
- Fixture UI.
- Custom fixture.
- Patch.
- Conflict validation.

## Fase 3 – DMX-engine

- Frame model.
- Merge.
- Fades.
- Scene stack.
- Simulator output.
- OLA adapter.
- Reconnect.
- Telemetry.

## Fase 4 – Scenes og effects

- Scene editor.
- Launchpad.
- Chasers.
- Built-in effects.
- Safety.
- Restore state.

## Fase 5 – BPM

- Manual.
- Tap.
- Audio devices.
- JACK/ALSA.
- aubio.
- Beat event bus.
- BPM-sync effects.

## Fase 6 – MixItUp

- Tokens.
- Mapping UI.
- Trigger endpoints.
- Queue.
- Cooldowns.
- Presets.
- Test guide.

## Fase 7 – Drift

- systemd.
- Installer.
- Update.
- Backup.
- Diagnostics.
- Pi smoke test.
- Documentation.

## Fase 8 – Hardening

- Tests.
- Soak.
- Security review.
- Performance.
- Error states.
- Release package.

---

# 34. Definition of Done

Projektet er først færdigt, når:

1. Det kan startes lokalt i simulator mode med én kommando.
2. Simulatoren viser alle 512 kanaler.
3. En fixture kan søges frem fra OFL og importeres.
4. En fixture kan patches uden adressekonflikt.
5. En scene kan oprettes gennem UI og aktiveres.
6. En chaser kan oprettes gennem UI.
7. En effekt kan afspilles og returnere til base-scenen.
8. Blackout overstyrer alt.
9. Strobe safety virker og er dækket af tests.
10. MixItUp-testendpoint returnerer hurtigt og trigger en effekt.
11. Manuel og tap BPM virker.
12. Audio BPM kan testes med syntetiske click tracks.
13. Telemetri viser current/target/source for DMX-kanaler.
14. OLA- og USB-fejl vises tydeligt.
15. Backup og restore virker i automatiske tests.
16. Autostart og systemd-filer er leveret.
17. `pi-smoke-test.sh` er leveret.
18. Hardwarevalideringsguiden er komplet.
19. Alle tests kører i CI.
20. Dokumentationen siger tydeligt, hvad der ikke er fysisk testet.
21. Ingen normal funktion kræver, at brugeren skriver kode i Web UI.
22. Der er ingen MIT-licens tilføjet automatisk.

---

# 35. Acceptance tests på den rigtige Raspberry Pi

Disse tests kan Codex ikke udføre. De skal leveres som en checkliste til Thomas.

## Test A – Boot

- Genstart Pi.
- OLA og TuxDMX starter automatisk.
- Web UI svarer.
- Safe scene er aktiv.

## Test B – USB

- Tilslut USB-DMX.
- Device vises i TuxDMX.
- Vælg port.
- Send testkanal.
- Lampen reagerer.

## Test C – Reconnect

- Træk USB-DMX ud.
- UI går til degraded/error.
- Tilslut igen.
- Systemet reconnecter.
- Ingen tilfældig flash.

## Test D – Fixture

- Importér den konkrete lampe fra OFL.
- Vælg korrekt mode.
- Patch korrekt adresse.
- Test alle relevante parametre.

## Test E – Scene/effect

- Opret base scene.
- Trigger sub-effect.
- Trigger raid oveni.
- Effektprioritet virker.
- Systemet vender tilbage til base scene.

## Test F – MixItUp

- Opret Web Request Action.
- Kald testtrigger.
- Se event i log.
- Se effekt.
- Bekræft hurtig HTTP response.
- Test cooldown og duplicate event.

## Test G – BPM

- Tilslut USB audio input.
- Vælg input.
- Afspil musik/click track.
- BPM og confidence vises.
- Beat-effekt følger rytmen.
- Test half/double.

## Test H – Stabilitet

- Kør minimum 2 timer med:
  - Web UI åbent.
  - BPM.
  - Scener.
  - Periodiske triggers.
- Kontrollér dropped frames, temperatur, RAM og logs.

---

# 36. Kodestandard

- Klar modulopdeling.
- Ingen gigantiske filer.
- Ingen skjulte globale states.
- Type annotations.
- Docstrings på public interfaces.
- Pydantic models ved API boundaries.
- Database migrations.
- Dependency lock.
- Central error handling.
- Structured logs.
- Unit-testbare services.
- Hardware interfaces skal kunne mockes.
- Secrets må ikke committes.
- `.env.example` uden hemmeligheder.
- Ingen default admin password.
- Ingen TODO-stubs i releasekritiske flows.
- Ingen fake success responses.
- Ingen swallow af exceptions uden logning.
- Ingen hårdkodet Raspberry Pi IP.
- Ingen hårdkodet USB device path.
- Ingen hårdkodede fixture channels.

---

# 37. Vigtige designbeslutninger

1. **OLA er hardwarebackend, ikke hele lyspulten.**
   TuxDMX ejer scener, effects, UI, fixturelogik og Twitch-integration.

2. **OFL normaliseres.**
   Runtime må ikke afhænge direkte af en bestemt OFL schema-version.

3. **Webrequests må ikke drive DMX synkront.**
   De skal enqueue commands og returnere straks.

4. **UI og DMX timing er adskilt.**
   En langsom browser eller API-request må ikke skabe DMX-flimren.

5. **Simulator er en førsteklasses backend.**
   Ikke en eftertanke.

6. **Telemetri er ærlig.**
   Vis hvad software og OLA gør, men påstå ikke fysisk signalverifikation uden måling.

7. **Safety har højere prioritet end Twitch.**
   Blackout, master limit og strobe-limit kan aldrig omgås gennem integrationer.

8. **Ingen kode kræves i UI.**
   Avanceret funktionalitet bygges med forms og editors, ikke scripts.

---

# 38. Første handling

Start med at:

1. Oprette repositorystrukturen.
2. Skrive `ARCHITECTURE.md` med konkrete valg.
3. Implementere simulatorbackend og DMX frame model.
4. Implementere minimal FastAPI health/status.
5. Implementere mørkt React-dashboard.
6. Oprette CI.
7. Oprette tests for 512-kanals frame, HTP/LTP og blackout.
8. Dokumentere hvordan simulatoren startes.

Fortsæt derefter gennem implementeringsfaserne, indtil hele Release 1.0 er leveret.

Når et valg er uklart, vælg den løsning der:

- er lettest at vedligeholde,
- kører stabilt på Raspberry Pi,
- kan testes uden hardware,
- ikke kræver kode i UI,
- og ikke låser systemet til én bestemt USB-DMX-adapter.