TuxDMX-WebUI/docs/MIDI_BRIDGE.md

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