One Playback State, Two Visual Languages

Translate once, give each consumer what it needs

A playback update should mean the same thing to every consumer, even when source fields differ. The coordinator resolves those differences into one normalized state: revision, track identity, playback state, cue, timestamps, and available musical metadata. Downstream mappers work from that state instead of interpreting raw JSON independently.

Normalize the changes that matter

Normalization also creates a meaningful boundary for change detection. The coordinator fingerprints the state it actually understands, so irrelevant differences in an upstream response do not trigger another round of visual updates. Repeated states are suppressed, but the most recent state is periodically replayed after a configurable freshness interval so downstream systems do not become stale simply because the music remained unchanged.

Suppress noise, preserve freshness

A meaningful change triggers delivery; an unchanged state can still be replayed when its freshness interval is due.

flowchart TD
    Input[Playback update] --> Normalize[Normalize understood fields]
    Normalize --> Changed{Meaningful change?}
    Changed -->|Yes| Deliver[Map and deliver]
    Changed -->|No| Due{Refresh due?}
    Due -->|Yes| Deliver
    Due -->|No| Wait[Keep current state]

Purpose-built contracts for each consumer

The two consumers speak related but distinct languages. Visualizer Stream receives a track-oriented representation plus recommendation and diagnostics context. DungeonOPC receives a stricter now-playing contract centered on revision, time, track, playback state, tempo, palette, and visual guidance. This mapping strategy lets either downstream evolve without forcing the source service to adopt its presentation model.

Observability follows the same separation. Liveness answers whether the coordinator process is running. Dependency health records whether MixMan and each configured downstream are reachable. Delivery state tracks attempts, successes, failures, recovery, last status, and the most recent payload fingerprint. Keeping those signals distinct turns “the visuals stopped changing” from a vague complaint into a traceable question about polling, normalization, deduplication, or delivery.