showstack / protocols / citp
CITP
Also called Controller Interface Transport Protocol, MSEX, Media Server Extensions.
An open protocol for the traffic between consoles, visualisers and media servers that is not the show itself: peer discovery, DMX, fixture data, and through MSEX, media libraries, thumbnails and live preview streams. It is what puts clip thumbnails on a lighting console's encoder wheel.
Stewarded by Lars Wernlund; distributed via Capture Visualisation AB.
Control
Small, urgent, must arrive
Small messages that either repeat constantly or fire once. Bandwidth is almost never the problem.
What kills it. Latency and loss on the messages that fire once. A repeating level survives a dropped packet; a GO does not.
Ports
udp/4809
PINF peer discovery and location messages (multicast)
Peers advertise their own TCP listening port inside the PLoc message, so there is no fixed TCP port to open.
Peers advertise their own TCP listening port inside the PLoc message, so there is no fixed TCP port to open.
Multicast
224.0.0.180- Peer location is multicast to 224.0.0.180 on UDP 4809. Everything heavier, including MSEX thumbnails and streaming frames, runs over the TCP connection a peer advertises in its PLoc message.
What goes wrong
The old citp-protocol.org domain now redirects somewhere unrelated. The specification lives in a public Bitbucket repository linked from Capture's developer page; bookmark that, not the historic domain.
Discovery multicasts to 224.0.0.180, which sits in the link-local 224.0.0.0/24 block that routers do not forward. Put the console and the media server on different subnets and they will never see each other.
MSEX versions are not interchangeable. MADRIX, for example, implements MSEX 1.0 and 1.1 only, so a console asking for later features gets nothing back and shows an empty library.
MSEX 1.0 and 1.1 cap you at 255 storages and 255 storage places. A media server with a bigger library simply presents a truncated view, and the missing clips look like a failed transfer.
Thumbnail and stream traffic is bulk TCP on the same network as your lighting data. Give it somewhere it cannot starve sACN, or switch streaming preview off before doors.
CITP is meant for pre-production and non-show-critical information. Do not build a cue path or a live effects trigger on top of it.
What speaks CITP (20)
20 products — 11 hardware, 9 softwareshow all
| Product | Direction | Notes |
|---|---|---|
| ArKaos MediaMaster ArKaos |
bidirectional | CITP/MSEX thumbnails to the console. |
| Avolites Titan Avolites |
bidirectional | Patch syncs both ways with stand-alone Capture (fixture, position, orientation, legend, user number) and fixture selection follows across. Levels still need Art-Net or sACN enabled on those universes. |
| Capture Capture Visualisation AB |
bidirectional | Adds DMX talkback, selection sync and patch exchange with consoles that implement MSEX. |
| ChamSys MagicQ ChamSys |
bidirectional | CITP with the Capture visualiser carries both lighting control and transfer of the show patch between MagicQ and Capture in either direction. |
| Hippotizer Green Hippo (an ACT Entertainment brand) |
out | CITP component pushes media thumbnails, media names and low-resolution streaming previews to lighting consoles and visualisers; requires the DMX component to be running. Documented as Hippotizer-to-console only. |
| LightConverse LightConverse |
bidirectional | CITP for media server and console integration. |
| ONYX Obsidian Control Systems |
in | Media server thumbnails are pushed across the network into ONYX's parameter belts, and patch can be imported from compatible visualisers. Servers on the network are auto-detected. |
| Realizzer 3D Realizzer |
bidirectional | CITP for media server integration. |
| WYSIWYG CAST Group Inc. |
in | Live media-server preview is a supported feature; CAST's own known-issues list references CITP video-display behaviour after a resolution change. |
| Avolites Ai Q3 Avolites |
bidirectional | Thumbnails. |
| Avolites Arena Avolites |
bidirectional | Media server thumbnails and control. |
| Avolites Diamond 9 Avolites |
bidirectional | CITP/MSEX for media server thumbnails in the pixel mapper. |
| Avolites Tiger Touch III Avolites |
bidirectional | CITP/MSEX thumbnails from media servers. |
| ChamSys MagicQ MQ500M Stadium ChamSys |
bidirectional | CITP/MSEX for media server thumbnails and visualiser feeds. |
| Christie Pandoras Box Christie |
bidirectional | CITP/MSEX thumbnails to consoles. |
| grandMA2 full-size MA Lighting |
bidirectional | CITP/MSEX for media server thumbnails. |
| Green Hippo Hippotizer Karst+ MK2 Green Hippo |
bidirectional | Thumbnails to consoles. |
| Hippotizer Boreal+ MK2 Green Hippo |
bidirectional | Thumbnail and media exchange with lighting consoles. |
| Obsidian Control Systems NX4 Obsidian Control Systems |
bidirectional | CITP/MSEX for media server integration. |
| AV Stumpfl PIXERA one AV Stumpfl |
bidirectional | CITP/MSEX thumbnails to lighting consoles. |
Open source implementations
- citp (Rust) — Rust
- citp-lib
Typical use
- Media server clip libraries and thumbnails appearing on a lighting console
- Live preview streams from a media server to a console or visualiser
- Console to visualiser DMX feed without needing Art-Net or sACN
- Fixture focus and position feedback from a visualiser back to the console
Sources
- Capture Developers — CITP is open and free, specification location, supported uses — Capture Visualisation AB primary
- CITPDefines.h — CITP_PINF_MULTICAST_IP 224.0.0.180, CITP_PINF_MULTICAST_PORT 4809, per-peer ListeningTCPPort — jwarwick / citp-lib
- MADRIX 5 CITP documentation (MSEX 1.0 and 1.1 only, 255 storage limit) — inoage / MADRIX
- citp — CITP implementation in Rust (protocol layers PINF, SDMX, FPTC, FSEL, FINF, MSEX, CAEX) — nannou
Understand the mechanism
Something wrong, or missing?
Known gaps on this entry: first_published. If you can source one of them, that is a ten minute pull request.
Edit this entry on GitHub — one file, editable in your browser, and your handle goes on it permanently.
Work at Lars Wernlund; distributed via Capture Visualisation AB? Confirm or correct this entry — it is free, it stays free, and nothing about it is for sale.