# MIDI Bridge

## Formål

TuxDMX kan modtage normaliserede MIDI-events fra en ekstern Windows- eller Linux-maskine via en separat Python-bro i `tools/tuxdmx-midi-bridge/`.

Bridgen læser kun MIDI og sender events videre til TuxDMX. Den genererer aldrig DMX direkte.

## Eksisterende arkitektur før ændringen

- Sceneaktivering fandtes allerede via `POST /api/v1/scenes/{scene_slug}/activate`
- Scenerelease fandtes allerede via `POST /api/v1/scenes/{scene_slug}/release`
- Blackout fandtes allerede via `POST /api/v1/dmx/blackout` og `POST /api/v1/dmx/release-blackout`
- Effektstart/-stop fandtes allerede via `POST /api/v1/effects/{effect_slug}/trigger` og `POST /api/v1/effects/{effect_slug}/stop`
- Live status blev sendt ud via WebSocket på `/ws/live`
- Session/CSRF og API-tokenmodeller fandtes i backend, men MIDI-broen havde ingen eksisterende transport eller mappingmodel

## Nye backend-endpoints

### Admin / WebUI

- `GET /api/v1/integrations/midi/bridges`
- `GET /api/v1/integrations/midi/mappings`
- `POST /api/v1/integrations/midi/mappings`
- `PUT /api/v1/integrations/midi/mappings/{mapping_id}`
- `DELETE /api/v1/integrations/midi/mappings/{mapping_id}`
- `POST /api/v1/integrations/midi/mappings/{mapping_id}/test`
- `GET /api/v1/integrations/midi/tokens`
- `POST /api/v1/integrations/midi/tokens`
- `DELETE /api/v1/integrations/midi/tokens/{token_id}`
- `GET /api/v1/integrations/midi/learn`
- `POST /api/v1/integrations/midi/learn/start`
- `POST /api/v1/integrations/midi/learn/cancel`

### Bridge transport

- `POST /api/v1/integrations/midi/bridge/heartbeat`
- `POST /api/v1/integrations/midi/bridge/events`

Bridge-endpoints kræver `Authorization: Bearer <token>`.

## Datamodel

### `midi_bridges`

- `bridge_id`
- `device_name`
- `ip_address`
- `protocol_version`
- `online`
- `last_heartbeat_at`
- `last_event_at`
- `last_error`
- `last_event`

### `midi_bridge_tokens`

- `label`
- `token_hash`
- `bridge_id` valgfri låsning til ét bridge-id
- `scopes`
- `last_used_at`
- `revoked_at`

### `midi_mappings`

- `name`
- `enabled`
- `bridge_id`
- `device_name`
- `message_type`
- `channel`
- `number`
- `action`
- `target_type`
- `target_id`
- `mode`
- `minimum_value`
- `maximum_value`

## Understøttede actions

- `activate_scene`
- `deactivate_scene`
- `toggle_scene`
- `flash_scene`
- `blackout_on`
- `blackout_off`
- `blackout_toggle`
- `set_master_dimmer`
- `set_scene_intensity`
- `start_effect`
- `stop_effect`

## Modes

- `trigger`
- `toggle`
- `hold`
- `flash`
- `continuous`

## Sikkerhed

- Tokens returneres kun i klartekst ved oprettelse
- Efter lagring vises kun `token_preview`
- Bridge-token logges ikke
- Protokolversion skal være `1`
- Bridge kan låses til specifikt `bridge_id`
- Ugyldige eller tilbagekaldte tokens afvises med `401`

## Bridge-installation

Se den fulde bridgepakke i:

- `tools/tuxdmx-midi-bridge/README.md`
- `tools/tuxdmx-midi-bridge/config.example.yaml`
- `tools/tuxdmx-midi-bridge/tuxdmx-midi-bridge.service.example`

## Kendte begrænsninger

- Fysisk MIDI-hardware er ikke testet i denne workspace-session
- Bridge bruger HTTP, ikke indgående WebSocket, selv om UI stadig bruger WebSocket til live status
- `set_effect_speed` er ikke implementeret, fordi effektmotoren endnu ikke har et stabilt genanvendeligt speed-interface