thomas
1f110866f5
CI / backend (pull_request) Canceled after 0s
CI / shell (pull_request) Canceled after 0s
CI / frontend (pull_request) Canceled after 0s
CI / arm64-smoke (pull_request) Canceled after 0s
CI / backend (push) Canceled after 0s
CI / shell (push) Canceled after 0s
CI / frontend (push) Canceled after 0s
CI / arm64-smoke (push) Canceled after 0s
125 lines
3.2 KiB
Markdown
125 lines
3.2 KiB
Markdown
# 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
|