1.

CITP protocol suite specification
1.1 History
2007-09-16 2007-09-28 2008-01-25 2008-05-28 2008-08-21 2008-10-11 2008-11-08 2009-02-14 2009-02-18 2009-05-17 2009-06-23 Revised documentation into a single document. Added first comments for MSEX revision, highlighted in red. Cleaned up MSEX 1.1 changes for element libraries. Minor corrections and clarifications in MSEX. Completed MSEX element types 4 - 8, accompanied by the Generic Element Information packet. Added BSR E1.31 to the DMX connection strings table. Added first OMEX packet suggestions. OMEX packet suggestion update and general revision of the introduction section. Removed deprecation note of PINF/PNam as it does have its use (with clarifying comments). Added note regarding problems with MSEX/GLEI message. Clarified the note regarding contiguous element identifiers.

1.2 Introduction
The CITP (Controller Interface Transport Protocol) is a dual layer protocol suite that has been designed for communication between lighting consoles, media servers and visualizers. This document describes how it is used on top of an IP stack, but the packets could easily be used over other media as well, such as USB links. The top layer, CITP, consists of a single message header with content information and support for fragmentation and stream synchronization. This message header is used in the beginning of all CITP protocol suite packets. The second layer of CITP consists of the PINF, SDMX, FPTC, FSEL, FINF, MSEX and OMEX protocols. Each of these have been designed for a specific purpose, but some of them are closely related (such as FPTC, FSEL and FINF that all operate on a given set of lighting fixtures). Any manufacturer can extend the CITP protocol at the second layer level using a non-reserved layer identifier.

Lighting Console / Media Server / Visualizer PINF SDMX FPTC FSEL CITP TCP UDP IP The layers of CITP and surrounding layers (IPX) (RS232) (MIDI) (USB) ... FINF OMEX MSEX

1.3 Lighting console behaviour
Datagram (UDP) socket, port 4809, joined to multicast address 224.0.0.180: - Regularly send a CITP/PINF/PLoc message with no listening port. - Receive CITP/PINF/PLoc messages to be aware of available visualizers and media servers. - Connect either automatically or on user demand to an available visualizer and/or media server. - Receive CITP/MSEX/StFr Stream Frame video content from media server video subscriptions. For all TCP connections to a media server: - Receive CITP/MSEX/SInf Server information and CITP/MSEX/LSta layer status messages. - Send CITP/MSEX/GELI Get Element Library Information message(s) and initiate element library update.

Request all libraries of relevant type to the media server in question (as identified by the CITP/PINF/PLoc Name field). - Send CITP/MSEX/GVsr Get Video Sources message to retrieve information about available video feeds. For all TCP connections to a visualizer: - Send a CITP/SDMX/UNam Universe Name for each DMX universe controlled to provide display names. - Either Send CITP/SDMX/ChBk Channel Block messages with DMX data, - or Send a CITP/SDMX/SXSr Set External Source message to specify an alternative DMX transfer method. - Receive CITP/SDMX/ChBk messages for "autofocus" purposes. - Send and receive CITP/FPTC, CITP/FSEL and CITP/FINF messages when fit.

1.4 Media server behaviour
TCP listening socket on any (known) port: - Accept incoming connections from any lighting console or visualizer. Datagram (UDP) socket, port 4809, joined to multicast address 224.0.0.180: - Regularly send a CITP/PINF/PLoc message containing the port on which the listening socket is listening. For all accepted incoming TCP connections from a lighting console or visualizer: - Send a CITP/MSEX/SInf Server Information message. - Regularly send a CITP/MSEX/LSta Layer Status message. - Receive and respond to CITP/MSEX element library browsing messages. - Send CITP/MSEX element library information messages on library changes. - Receive and respond to CITP/MSEX video stream browsing and subscription messages.

1.5 Visualizer behaviour
TCP listening socket on any (known) port: - Accept incoming connections from any lighting console. Datagram (UDP) socket, port 4809, joined to multicast address 224.0.0.180: - Regularly send a CITP/PINF/PLoc message containing the port on which listening socket is listening. - Receive CITP/PINF/PLoc message to be aware of available media servers. - Connect either automatically or on user demand to an available media server. - Receive CITP/MSEX/StFr Stream Frame video content from media server video subscriptions. For all accepted incoming TCP connections from a lighting console: - Receive CITP/SDMX/UNam Universe Name messages. - Receive CITP/SDMX/ChBk messages with DMX data. - Optionally support CITP/SDMX/SXSr messages and receive DMX data over other protocols. - Send CITP/SDMX/ChBk messages for "autofocus" purposes. - Send and receive CITP/FPTC, CITP/FSEL and CITP/FINF messages when fit. For all TCP connections to a media server: - Receive CITP/MSEX/SInf Server Information and CITP/MSEX/LSta layer status messages. - Send CITP/MSEX/GVSr Get Video Sources message to retrieve information about available video feeds.

1.6 Device status / Operations management servers
Work in progress.

1.7 General IP notes and hints
PC based applications must choose listening ports and set socket address reusability flags as necessary to avoid blocking eachother when run on the same network interface. Achieve this by calling listen() for port 0 and retrieving the port chosen by the operating system with getsockname(), and by setting the SO_REUSEADDR (and possibly also SO_REUSEPORT) option on the multicast socket before joining the multicast address. To join a multicast address, use setsockopt() with IPPROTO_IP and IP_ADD_MEMBERSHIP.

for instance “CITP” for the CITP header Cookie field. uint64 ucs1. int16. uint32.31/0/1" . a connection string approach is used instead.) // 64-bit IEEE floating point (11-bit exp. 16-bit. The following table illustrates well-defined DMX connection strings in CITP: Protocol ArtNet Avab IPX Format "ArtNet/<net>/<universe> /<channel>" "AvabIPX/<net>/<universe> /<channel>" Examples "ArtNet/0/0/1" . although mostly on a pseduo-code level.The first channel of the first universe on the first network. int32. uint16.2 DMX Connection Strings Instead of defining constants and fixed field for various DMX source protocols.31/<universe>/<channel>" ETC Net2 "ETCNet2/<channel>" . "PC standard") and 1-byte packing of C-structures. "AvabIPX/0/0/1" .The first channel of the first universe. The constant values of these fields are documented using string notation.31 "BSRE1.Data types All structures and variables of CITP use little endian byte order (least significant byte first. ucs2 float32 float64 // 8-bit.The first channel of the first universe on the first network. "ETCNet2/1" .2. 2.. 32-bit and 64-bit unsigned integers // 8-bit and 16-bit unicode characters (character types correspond to uint8 and uint16) // 32-bit IEEE floating point (8-bit exp.) Open arrays of ucs1 or ucs2 are null terminated strings. 2. 32-bit and 64-bit signed integers // 8-bit. 52-bit mant. "BSRE1.1 Cookies The Cookie (and ContentType) fields can be found in CITP headers in both layers. BSR E1.. 16-bit. int64 uint8. 23-bit mant. int8.‘P’ over the network. Definitions These specifications target lighting software developers.The first ETCNet2 channel. It contains C style types and annotation.‘I’. This should be interpreted as sending ‘C’.‘T’.

uint8 VersionMajor. // Cookie identifying the type of contents (the name of the second layer). header used at the start of all CITP packets: struct CITP_Header { uint32 Cookie. // Index of this message fragment (0-based). // // // // // . uint8 VersionMinor. MessagePartCount. uint8 Reserved[2]. 4-byte alignment The size of the entire message. it merely adds a header that encapsulate all messages. single. including this header. CITP. Set to "CITP". // Number of message fragments.1 Header definitions 3.3. Set to 0.1 The CITP header The CITP layer provides a standard. base layer The base layer as such does not define any packages.1. Set to 1. 3. MessagePart. uint32 MessageSize. uint16 uint16 uint32 }. ContentType.

The PNam message is still useful though. Peer Information layer The Peer Information layer is used to exchange peer information. PINF ContentType is "PNam". Correspons to the PINF/PNam/Name field.2. both when connected and when locating peers on the network.1. or a combination. ucs1 ucs1 ucs1 Type[]. The Type field instructs the receiver what kind of peer it is and the Name and State fields provide display name and information. CITP/PINF. "Running" etc.now the PLoc message is multicasted instead. uint32 ContentType. In early implementations of CITP. as a message transferred from a peer connected to a listening peer. CITP ContentType is "PINF".1 PINF / PNam . }.2 Message definitions 4. // The display state of the peer.Peer Name message The PeerName message provides the receiver with a display name of the peer.4. If the ListeningTCPPort field is non-null. // The CITP PINF header. uint16 ListeningTCPPort. 4. it is possible to connect to the peer on that port using TCP.1 Header definitions 4. the PNam message was broadcasted as a means of locating peers . Instead. The PINF/PNam message was previousley broadcasted on UDP port 4810 but has now been deprecated.2 PINF / PLoc .180. PINF ContentType is "PLoc". port 4809. 4. State[]. // The display name of the peer. Name[].1 The PINF header The PINF layer provides a standard. // The CITP PINF header. header used at the start of all PINF packets: struct CITP_PINF_Header { CITP_Header CITPHeader. 4. This can be any descriptive string presentable to the user such as "Idle". 0 if not listening. }.0. // A cookie defining which PINF message it is. "Visualizer" or "OperationHub". the PINF/PLoc message is multicasted on address 224. }. struct CITP_PINF_PNam { CITP_PINF_Header CITPPINFHeader.Peer Location message The PeerLocation message provides the receiver with connectivity information. ucs1 Name[]. // The display name of the peer (null terminated). // The CITP header. "MediaServer". .0. // Can be "LightingConsole". // The port on which the peer is listening for incoming TCP connections. single. This could be anything from a // user defined alias for the peer of the name of the product. struct CITP_PINF_PLoc { CITP_PINF_Header CITPPINFHeader.2.

Set External Source message The Set External Source message can be sent as an alternative to the ChBk message above. 5. Number of channels.3 SDMX / ChBk . // Cookie defining which SDMX message it is. 5.1 Header definitions 5. ChannelCount.2.5.1 The SDMX header The SDMX layer provides a standard. 5. SDMX ContentType is "UNam". uint8 UniverseIndex.3. }. It also supports designating an alternative DMX source such as ArtNet or ETCNet2 (see "connection strings" in the Definitions section). // Encryption scheme identifier. ucs1 Identifier[]. Raw channel levels. ucs1 UniverseName[]. UniverseIndex. uint32 ContentType. the external source specified should be treated as the base universe of a consecutive series. 5.1 SDMX / SXSr . but the recommended procedure for a visualizer is to switch over to blind DMX whenever such is present and to revert back after some short timeout when it is no longer transmitted. How to handle Blind DMX levels is up to the recipient. . Blind. struct CITP_SDMX_ChBk { CITP_SDMX_Header uint8 uint8 uint16 uint16 uint8 }. when DMX should be tapped from another protocol on the other end. The usage of this message depends completely on the peers communicating it. ChannelLevels[]. }. SDMX ContentType is "EnId". In the event of handling multiple universes. 0-based index of first channel in the universe. the contents and results of this message is not part of the CITP specification . 0 otherwise.it must be agreed upon a priori.2.1. Send DMX layer The SDMX layer is used to transmit DMX information.2 SDMX / UNam . CITP/SDMX. single. Set to 1 for blind preview dmx.3 Message definitions: Alternate DMX source management 5. // CITP header. // // // // // // CITP SDMX header. // 0-based index of the universe. }. FirstChannel. struct CITP_SDMX_UNam { CITP_SDMX_Header CITPSDMXHeader.Universe Name message The Universe Name message can be sent by a DMX transmitting peer in order to provide the other end with a displayable name of a universe.wide . // Name of the universe.1 SDMX / EnId . CITPSDMXHeader. // CITP SDMX header.2.Channel Block message The Channel Block message transmits raw DMX levels to the recipient. 0-based index of the universe. 5. SDMX ContentType is "ChBk". struct CITP_SDMX_EnId { CITP_SDMX_Header CITPSDMXHeader. CITP ContentType is "SDMX".2 Message definitions: Transfer of DMX channel levels 5.universe of DMX channels with at most 65536 channels. // CITP SDMX header.Encryption Identifier message The EncryptionIdentifier message is used to agree on encryption schemes when transferring DMX channels. header used at the start of all SDMX packets: struct CITP_SDMX_Header { CITP_Header CITPHeader. CITP supports transmitting a single .

// CITP SDMX header. }. See DMX Connection Strings in Definitions. // DMX-source connection string.struct CITP_SDMX_SXSr { CITP_SDMX_Header CITPSDMXHeader. SDMX ContentType is "SXSr". ucs1 ConnectionString[]. .

A fixture can change its patch and mode.2. If the new mode consumes a different amount of channels. header used at the start of all FPTC packets: struct CITP_FPTC_Header { CITP_Header CITPHeader. Fixture patch layer The Fixture Patch layer is used to communicate fixture existence and patch information. single. uint16 uint8 uint8 uint16 uint16 ucs1 ucs1 }. Reserved[1]. // Patch channel (0-based).Patch message Patch messages are sent when fixtures are introduced or repatched. without association to a universe.1 FPTC / Ptch . there is no way of telling. "Unit" or "Device". // Patch channel count (1-512). Universe. however sometimes a different mode only changes the interpretation of one or more control channels. 6. // Fixture identifier. This must be handled by the user by opening and closing matching projects simultaneously. 6. ChannelCount. CITP/FPTC. Different modes for one fixture usually use different amounts of channels. uint32 ContentHint. it is reintroduced through the Patch message.2 FPTC / UPtc . }.1 Header definitions 6. it may possible to change the mode of a fixture. the sender fixture (library) type make and name of the fixture added and the patching information. Whenever the fixture is associated with a universe again. When the visualizer or console takes automatic actions as a result of incoming patch messages. fixtures are not unpatched.2 Message definitions 6. but never its make or name. FixtureIdentifier. Fixtures are identified by 16-bit unsigned integeres with a range of valid values between 1 and 65535. The patch message contains the identifier of the fixture added. The visualizer attempts to map the fixture make and name against its library. A cookie defining which FSEL message it is. 0x00000002 Message part of and ends a sequence of messages. When a project is closed on either side.Unpatch message . // // // // // The CITP header. // Fixture make (only null if omitted). Content hint flags. When a fixture is repatched (ie moved to another channel or universe) it does not pass through an unpatched state. // Fixture name (never omitted). // 4-byte alignment.1 The FPTC header The FPTC layer provides a standard. CITP ContentType is "FPTC". // Patch universe (0-based). the fixture identifiers must still be the same. it must not result in an echo. this can be told by the ChannelCount field of the patch message. FPTC ContentType is "Ptch". When a mode is changed in the visualizer.. No synchronisation mechanism exists in CITP. However. only a new patch message. which communicates project closing/opening information. an unpatch message is not sent. 0x00000001 Message part of a sequence of messages. When a fixture is unpatched using the UnPatch message. FixtureMake[]. the fixture may continue to live in the visualizer or the console. Channel. The same applies to when a universe in the visualizer is deleted or unassociated with a console. FixtureName[]. it is deleted and seizes to exist. In most consoles this value maps directly to a "Channel". struct CITP_FPTC_Ptch { CITP_FPTC_Header CITPFPTCHeader. Fixture identifiers must be persistent. uint32 ContentType. When both the visualizer and the console have reloaded a pair of matching projects. 6. The FPTC layer is built on the following design decisions: Unpatched fixtures do not exist from the FPTC layers’s point of view. In the visualizer.1.2. // The CITP FPTC header. If it does not.6.

FPTC ContentType is "SPtc".SendPatch message The SendPatch message instructs the receiver to send Patch messages in response.2. FixtureIdentifiers[]. FixtureIdentifiers[].3 FPTC / SPtc . FixtureCount. struct CITP_FPTC_UPtc { CITP_FPTC_Header CITPFPTCHeader. // Fixture count (0 to request all). the entire Patch should be transferred in response. // The CITP FPTC header.. This procedure can be used for testing the existence of fixtures on the remote side or to synchronize the entire patch information. one for each fixture specified in the FixtureIdentifiers array. // The CITP FPTC header. // Fixture count (0 to unpatch all). .Unpatch messages are sent when fixtures are deleted or unpatched. uint16 uint16 }. The unpatch message only contains the identifiers of the fixtures removed. uint16 uint16 }. FixtureCount. If no fixture identifiers are specified. An empty fixture identifier array indicates complete unpatching. // Fixture identifiers 6.. struct CITP_FPTC_SPtc { CITP_FPTC_Header CITPFPTCHeader. FPTC ContentType is "UPtc". // Fixture identifiers.

Complete.2. Fixture identification is discussed in the CITP/FPTC section. If the Complete field is non-zero.1 FSEL / Sele . // The CITP FSEL header. CITP/FSEL. a Deselect message deselects the fixture specified. // The CITP header. FSEL ContentType is "DeSe". thus achieving a full synchronization. CITP ContentType is "FSEL". only the fixtures identified in the message should be selected and all others should be deselected. 7. uint32 ContentType.2 Message definitions 7. // Set to non-zero for complete selection // 4-byte alignment // Greater than 0 // Fixture identifiers 7. However. FixtureCount.2 FSEL / DeSe .1.1 The FSEL header The FSEL layer provides a standard. Reserved[1]. struct CITP_FSEL_Sele { CITP_FSEL_Header CITPFSELHeader. // A cookie defining which FSEL message it is. single.1 Header definitions 7.2. FSEL ContentType is "Sele". Fixture Selection layer The Fixture Selection layer is used to carry fixture selection information. // 0 for complete deselection // Fixture identifiers .7. uint8 uint8 uint16 uint16 }. // The CITP FSEL header. FixtureIdentifiers[]. FixtureCount. 7. uint16 uint16 }.Select message The Select message instructs the receive to select a number of fixtures. rather than selectin them. struct CITP_FSEL_DeSe { CITP_FSEL_Header CITPFSELHeader. FixtureIdentifiers[].Deselect message The Deselect message acts similarly to the Select message. A Deselect with no fixture specified should deselect all fixtures. }. header used at the start of all FSEL packets: struct CITP_FSEL_Header { CITP_Header CITPHeader.

FINF ContentType is "LSta".8. 8.1 The FINF header The FINF layer provides a standard. // List of (first) filters and (last) gobos. 8. 8. struct CITP_FINF_LSta { CITP_FINF_Header CITPFINFHeader. FixtureIdentifier. FixtureCount. FINF ContentType is "Fram". // Flag mask.1. Fixture identification is discussed in the CITP/FPTC. Flags[FlagSize]. The flag mask and flag fields size is dynamic in order to allow future expansion without redifinition. struct CITP_FINF_Fram { CITP_FINF_Header CITPFINFHeader.2. // Number of gobos in the FrameNames field. // 0x01 TBD . }. // The CITP header. single. 8. CITP ContentType is "FINF". Contains at least the null. // Fixture identifiers. FlagSize. uint16 uint16 }. }.2. // Fixture count (0 to request all). struct CITP_FINF_SFra { CITP_FINF_Header CITPFINFHeader. LiveStatusCount. // A cookie defining which FINF message it is. newline separated (\n) & null terminated. // Flags. FlagMask[FlagSize]. uint16 uint8 uint8 ucs1 FixtureIdentifier. // Fixture identifier. CITP/FINF.Live status message PRELIMINARY This message can be sent in any direction on a regular basis.2 FINF / Fram . uint16 uint8 struct LiveStatus { uint16 uint8 uint8 }[]. // The CITP FINF header. // Fixture identifier.1 Header definitions 8. // Number of bytes in the flag field.Send Frames message This messages informs the receiver to send frame messages for the specified fixtures. }. FrameGoboCount. uint32 ContentType. FrameFilterCount.1 FINF / SFra .3 FINF / LSta . header used at the start of all FINF packets: struct CITP_FINF_Header { CITP_Header CITPHeader.2 Message definitions 8. // The CITP FINF header.2. FrameNames[]. FixtureIdentifiers[]. FINF ContentType is "SFra". Fixture Information layer The Fixture Information layer is used to carry additional fixture information. // Fixture identifier. // Number of filters in the FrameNames field.Frames message This messages informs the receiver about the filters & gobos of a fixture. // The CITP FINF header.

Category[].Clear DMX Device Status Sent to clear a specific status from a set of devices. OMEX ContentType is "CDDS". 100 = Warning. // CITP OMEX header.Signal DMX Device Status Sent to signal a status for one or more devices. 9. StatusIdentifier[]. CITP ContentType is "OMEX". }. uint32 ContentType. struct CITP_OMEX_SDDS { CITP_OMEX_Header ucs2 uint8 ucs2 ucs2 ucs2 uint16 CITPOMEXHeader. Set to 0. . }. struct DeviceInformation { ucs1 DMXConnectionString.. // The number of following device information blocks.2 OMEX / CDDS . such as "Offline". Cookie defining which OMEX message it is. Set to 1. 9. uint8 VersionMinor. Operations Management layer PRELIMINARY The Operations Management EXtensions layer is used for metadata communication. struct DeviceInformation { ucs1 DMXConnectionString.1 Header definitions The OMEX layer provides a standard. StatusIdentifier[].1 OMEX / SDDS . single. OMEX ContentType is "SDDS". // A DMX connection string. It is not necessary that the status is cleared from all deviced that have it set. 9.. // Displayable status tag.2. uint8 VersionMajor. }. Severity.. // Long descriptive text. // Displayable status tag. struct CITP_OMEX_CDDS { CITP_OMEX_Header ucs2 uint16 CITPOMEXHeader. 150 = Error // Category identifier. header used at the start of all OMEX packets: struct CITP_OMEX_Header { CITP_Header CITPHeader. // // // // CITP header. }. It is typically a short string. DeviceCount. A status is identified by a short string which is used again when clearing or updating the status (by sending a new SDDS message). ShortText[]. // Short descriptive text. LongText[]. If a status clear is requested for a device that is not known to have status. }. the request is silently ignored.2 Message definitions: DMX device status signalling Status signalling of DMX devices is . CITP/OMEX. // The number of following device information blocks for which to set this status.2.9. // CITP OMEX header. // 50 = Info. // A DMX connection string. "On fire" or "Lamp fail". but it is possible. DeviceCount. 9.

MediaNumber. // CITP MSEX header. // Current media number.1. // // // // CITP header. Issue . The version field of the MSEX header should be set to the highest supported version of MSEX messages.Server Information message The ServerInformation provides the receiver with product and layer information.Layer Status message The LayerStatus message is sent at a regular interval (suggestion: 4 times / second) to provide the receiver with live status information. // Current media resolution in frames per second. 0-based. MediaPosition.10. struct CITP_MSEX_SInf { CITP_MSEX_Header CITPMSEXHeader. // Current media position (in frames). MediaLength. // Current physical video output index. uint8 uint8 uint8 ucs2 uint32 uint32 uint8 PhysicalOutput. Typically all packets are sent over a peer-to-peer TCP socket connection. // DMX-source connection string.2. struct LayerStatus { uint8 LayerNumber.1. For information about how peers find eachother and connect. // Display name of the product. See DMX Connection Strings in Definitions. struct LayerInformation { ucs1 DMXSource[]. single. uint8 VersionMinor. header used at the start of all MSEX packets: struct CITP_MSEX_Header { CITP_Header CITPHeader. // Major version number of the product. During a session messages of varying MSEX versions may be sent and received. Currently acknowledged versions of MSEX are 1. MediaLibraryNumber. except for the MSEX/StFr message which is sent over the multicast address for all to process. // Minor version number of the product.0 and 1. .1 Header definitions 10.no Layer Status message has been defined for MSEX 1. // Current media name. // CITP MSEX header.2. uint8 VersionMajor. }. MSEX ContentType is "LSta" and version is 1. }. CITP ContentType is "MSEX". 10. // 0-based layer number.2 Message definitions: General media server information 10. Media Server Extensions layer The Media Server EXtensions layer is used for communication with Media Servers. MediaName[]. // Current media library number. MSEX ContentType is "SInf". // Number of following layer information blocks. ucs2 ProductName[]. See below. struct CITP_MSEX_1. Cookie defining which MSEX message it is.0. uint8 ProductVersionMajor. uint32 ContentType. 10. See below.1. See the MSEX / SInf message also regarding supported version signalling. CITP/MSEX.1 MSEX / SInf . // Number of following layer information blocks. MediaFPS.1 The MSEX header The MSEX layer provides a standard. uint8 LayerCount. corresponding to the layers reported in the SInf message. }. // Current media length (in frames). See above on version.0_LSta { CITP_MSEX_Header CITPMSEXHeader. see the Connectivity section.2 MSEX / LSta . 10. uint8 ProductVersionMinor. uint8 LayerCount.

0. It is highly recommended that new implementations of media servers use contiguous element identifiers as the specification is likely to be changed to allow only this.0.0.0. when Depth == 3.mpg ID{2. Effect or Generic) are returned: 1.0} /One. MSEX ContentType is "GELI" and version is 1.Get Element Library Information message The GetElementLibraryInfo message is sent to a media server in order to request information about an element library. the parent of all first level libraries. This is designed to match the common media server layout of 2 dmx channels identifying the library and item respectively.0.4.0} /Two. it is specifying the builtin root level. struct CITP_MSEX_1. there is a finite set of at most 256 libraries.0} /Empty folder ID{1.0} /Secundo.0. // CITP MSEX header.gif ID{2.0} /Three.0. there is a finite set of at most 3 library levels with at most 256 elements each.0} There are currently eight recognized elements types (a library can only contain elements of one type) and when information about elements is requested.0} /Primo. each containing a finite set of at most 256 elements. Level2. 2. When it's Level byte is set to 0.1. }.the original intention of the protocol specification is that element and library numbers should be arranged contiguousley.avi ID{2. An attempt to visualize by example the most traditional structure. // // // // 0 .0} /More Movies ID{1. Issue . when Depth >= 1. LayerStatusFlags. Sublevel 2 specifier. as the specification has been unclear. set to 0 when requesting all available.1.0. 4.uint32 }[].2. 8. two levels: /Root Folder (abstract) ID{0. Level3.0} /Movies ID{1. some implementatioins do not honor this pattern and allow for non-continuous library and element identifiers. LibraryCount.0. 5.1 MSEX / GELI . Media (images & video) Effects Cues Crossfades Masks Blend presets Effect presets Image presets 10.0} /Images ID{1. different kinds of Element Information messages (Media. a 4-byte integer divided into four 1-byte fields. none if LibraryCount is 0. // Content type requested.0. a media server can only report a library to contain a maximum of 255 libraries or elements. when Depth >= 2. struct MSEXLibraryId { uint8 uint8 uint8 uint8 }.1. Level.gif ID{2. // Requested library numbers.0} /Empty folder ID{1.0. LibraryType.3 Message definitions: Element libraries and element information In MSEX 1. 6.1. Level1.0} /Test. LibraryNumbers[].4.avi ID{2.gif ID{2.1.mpg ID{2. In MSEX 1. uint8 uint8 uint8 }.1.0.0} /Tertio.0.0_GELI { CITP_MSEX_Header CITPMSEXHeader.mpg ID{2.0} /Test2.3. Libraries are identified using a library identifier.1. Issue .2. Sublevel 3 specifier. .1 however.4. or all available element libraries.0. // Current layer status flags // 0x0001 MediaPlaying 10. However.2.3 Sublevel 1 specifier. // Number of libraries requested.0.due to limitations imposed by the somewhat unwise choise of using an uint8 as data type for the number of elements in a library.3. 3. 7.0.

LibraryCount. 0.1. MSEX ContentType is "ELUp" and version is 1. uint8 }[].0. struct ElementLibraryInformation { uint8 Number. but up to 255 sub libraries). // Parent library id. LibraryNumber. LibraryType. // Content type requested.0_ELIn { CITP_MSEX_Header CITPMSEXHeader.1_ELIn { CITP_MSEX_Header CITPMSEXHeader. For each N of these (up to 255) libraries. uint8 uint8 }[]. N. uint8 uint8 LibraryType. ElementCount. ucs2 Name[]. LibraryNumbers[]. uint8 DMXRangeMin. }. Library name. struct ElementLibraryInformation { MSEXLibraryId Id. // Number of elements in the library. uint8 MSEXLibraryId uint8 uint8 }. Library name. DMX range end value.0. 0. // Number of following element library information blocks. uint8 DMXRangeMax. }. // CITP MSEX header. First the procedure in Example 1 is executed to collect all Level 1 libraries (none of these will contain any elements. 0.1_GELI { CITP_MSEX_Header CITPMSEXHeader. 10.1. Example 2: three DMX channel media selection media server.3 MSEX / ELUp . // CITP MSEX header. UpdateFlags.0_ELUp { CITP_MSEX_Header CITPMSEXHeader.Element Library Updated message The ElementLibraryUpdated message is sent by a media server to notify a console or visualizer about updated media library contents. ElementCount. none if LibraryCount is 0. N. DMX range end value. 0}. A GELI message with LibraryParentId set to {0. MSEX ContentType is "GELI" and version is 1. This generates a response with an ELIn message with at most 255 items with LibraryId values of {1.struct CITP_MSEX_1. uint8 uint8 LibraryType. 0. 10. // CITP MSEX header. // Number of following element library information blocks. uint8 DMXRangeMax. DMX range start value. DMX range start value. // // // // 0-based library number.Element Library Information message The ElementLibraryInfo message is sent in response to the GetElementLibraryInfo message. // Number of libraries requested. LibraryCount. It should contain individual element library information for the entire contents of the requested element library. This will trigger a response with an ELin message with at mosts 255 items with LibraryId values of {2. // Library that has been updated. 0}. 0}. 0-255. struct CITP_MSEX_1. ucs2 Name[]. MSEX ContentType is "ELIn" and version is 1. uint8 uint8 uint8 LibraryType. // Content type of updated library. // Requested library numbers. LibraryCount. // Content type requested. // Number of sub libraries // Number of elements in the library. uint8 DMXRangeMin. MSEX ContentType is "ELIn" and version is 1. // 0x01 Existing elements have been updated // 0x02 Elements have been added or . 0-255.3. // Content type requested. LibraryParentId. an additional GELI message is sent with the LibraryParentId set to {1.2 MSEX / ELIn . Example 1: two DMX channel media selection media server. set to 0 when requesting all available. struct CITP_MSEX_1. in the library. struct CITP_MSEX_1. // // // // Library id. // Additional information flags.3. LibraryCount. // CITP MSEX header. 0} is sent to retrieve all libraries on the folder selection channel.

// Library containing the media elements. ElementNumbers[]. // CITP MSEX header. uint8 DMXRangeMax. Media version in seconds since 1st January 1970. MSEX ContentType is "MEIn" and version is 1. Media width.1_MEIn { CITP_MSEX_Header CITPMSEXHeader. // CITP MSEX header. // Content type requested. set to 0 when requesting all available. DMX range start value. Media length (in frames). ElementCount. struct CITP_MSEX_1. uint8 }. MediaLength. uint64 MediaVersionTimestamp. uint8 MSEXLibraryId uint8 LibraryType. Media name.5 MSEX / MEIn . MSEX ContentType is "GEIn" and version is 1. struct CITP_MSEX_1. // CITP MSEX header. Media height. UpdateFlags. DMX range end value.3. uint8 uint8 uint8 LibraryType.1. It should contain individual media element information for all elements requested. MediaHeight. // Number of elements for which information is requested. // Content type requested.1_GEIn { CITP_MSEX_Header CITPMSEXHeader. // Additional information flags.0. ucs2 MediaName[]. set to 0 when requesting all available. struct CITP_MSEX_1.0_MEIn { CITP_MSEX_Header CITPMSEXHeader. MSEX ContentType is "GEIn" and version is 1. MediaWidth. ElementCount.4 MSEX / GEIn . // 0x01 Existing elements have been updated // 0x02 Elements have been added or removed // 0x04 Sub libraries have been updated // 0x08 Sub libraries have been added or removed }. MSEX ContentType . // CITP MSEX header. uint8 MSEXLibraryId uint8 LibraryType. MSEX ContentType is "ELUp" and version is 1. // Library that has been updated. 10. ElementNumbers[]. ElementCount. // Numbers of the elements for which information is requested. uint8 DMXRangeMin. LibraryId. struct MediaInformation { uint8 Number.1. // Library for which to retrieve elements // Number of elements for which information is requested. MediaFPS.1_ELUp { CITP_MSEX_Header CITPMSEXHeader. struct CITP_MSEX_1. uint16 uint16 uint32 uint8 }[]. // Content type of updated library.removed // 0x04 Sub libraries have been updated // 0x08 Sub libraries have been added or removed }. }. uint8 uint8 LibraryNumber. // Numbers of the elements for which information is requested. uint8 }. LibraryId. // // // // // // // // // 0-based number of the media. // Number of following (media) information blocks. Media resolution (in frames per second). // Library for which to retrieve element info. struct CITP_MSEX_1.0_GEIn { CITP_MSEX_Header CITPMSEXHeader.0.3. 10. LibraryNumber.Get Element Information message The GetElementInformation message is sent by a console or visualizer to a media server in order to request information about individual elements.Media Element Information message The MediaElementInformation message is sent in response to the GetElementInformation message for element type 1. // CITP MSEX header.

// Number of following information blocks.1_EEIn { CITP_MSEX_Header CITPMSEXHeader. struct CITP_MSEX_1. struct CITP_MSEX_1. uint64 MediaVersionTimestamp. DMX range end value. Media name. DMX range start value. MediaWidth.6 MSEX / EEIn . // Library containing the media elements.MSEXLibraryId uint8 LibraryId. MSEX ContentType is "EEIn" and version is 1.1. Media width. is "MEIn" and version is 1.Effect Element Information message The EffectElementInformation message is sent in response to the GetElementInformation message for element type 2. It contains individual effect element information for all elements requested. ucs2 EffectName[]. uint8 DMXRangeMin. // Library containing the elements. ElementCount. // List of effect parameter names. // Number of following (effect) information blocks. Number of following effect parameter names.1. Issue . // Library containing the effect elements. Effect name. uint8 uint8 LibraryNumber. // Number of following (media) information blocks. // List of effect parameter names. ucs2 EffectName[].3. }. }. DMX range end value. }. uint8 DMXRangeMin. // Number of following (effect) information blocks. ucs2 }[]. ucs2 }[]. uint16 uint16 uint32 uint8 }[]. It contains individual element information for all elements requested.1.Generic Element Information message The GenericElementInformation message is sent in response to the GetElementInformation message for element types 3 through 8.7 MSEX / GLEI . Media height. DMX range start value. // // // // // 10. uint8 DMXRangeMin. MSEX ContentType is "GLEI" and version is 1.this message lacks a field indicating which library type the contained information belongs to (which is not necessary with the MEIn and EEIn messages since each is for a particular library type). struct EffectInformation { uint8 ElementNumber. EffectParameterNames[][]. 0-based number of the effect. Effect name. // // // // // // // // // 0-based number of the media. uint8 DMXRangeMax. struct MediaInformation { uint8 Number. ElementCount. struct GenericInformation . 10. struct EffectInformation { uint8 ElementNumber. Media length (in frames). uint8 DMXRangeMax. MediaLength. Media version in seconds since 1st January 1970. 0-based number of the effect. The only feasible workaround is for the requesting peer to attempt to match GLEI replies with information requests in such a way that library types are not mixed. struct CITP_MSEX_1.0. MSEXLibraryId uint8 LibraryId. ElementCount. uint8 DMXRangeMax. // CITP MSEX header. DMX range start value. // Library containing the effect elements. ElementCount. EffectParameterNames[][]. MSEX ContentType is "EEIn" and version is 1. MediaHeight. uint8 EffectParameterCount. Media resolution (in frames per second). ucs2 MediaName[]. Number of following effect parameter names. MSEXLibraryId uint8 LibraryId.3. // CITP MSEX header. DMX range end value. uint8 EffectParameterCount.1_GLEI { CITP_MSEX_Header CITPMSEXHeader. MediaFPS. // // // // // // CITP MSEX header.0_EEIn { CITP_MSEX_Header CITPMSEXHeader.

10. // CITP MSEX header. uint8 uint8 uint32 uint16 uint16 uint16 uint8 }. LibraryIds[]. LibraryCount. struct CITP_MSEX_1. MSEX ContentType is "GELT" and version is 1. // Id of the library that the thumbnail belongs to.1_ELTh { CITP_MSEX_Header CITPMSEXHeader. MSEX ContentType is "ELTh" and version is 1. not present if LibraryCount is 0. LibraryType. Can be "RGB8" or "JPEG". ThumbnailHeight. // VersionTimestamp. Can be "RGB8" or "JPEG". LibraryCount. uint8 MSEXLibraryId LibraryType. // seconds since 1st January 0-based number of the element. // 0x01 Preserve aspect ratio of image (use width and height as maximum) LibraryType.0_GELT { CITP_MSEX_Header CITPMSEXHeader. // Additional information flags. LibraryNumbers[]. LibraryNumber. LibraryId. 10. // Format of the thumbnail.1_GELT { CITP_MSEX_Header CITPMSEXHeader. set to 0 when requesting all available. // DMXRangeMax.Get Element Library Thumbnail message The GetElementLibraryThumbnail message is sent to a media server in order to retrieve a thumbnail of an element library. // Number of libraries requested. MSEX ContentType is "GELT" and version is 1. ThumbnailHeight. 2 for Effects. // Number of libraries requested.0. ThumbnailFormat.1 MSEX / GELT . // CITP MSEX header. or of all available element libraries.0_ELTh { CITP_MSEX_Header CITPMSEXHeader. the thumbnail belongs to. // Number of the library that // Format of the thumbnail. }. Element version in 1970. // CITP MSEX header.0.{ uint8 uint8 uint8 ucs2 uint64 }[]. // Size of the thumbnail buffer.4 Message definitions: Thumbnail information 10. // Thumbnail height. // DMXRangeMin. struct CITP_MSEX_1. // 0x01 Preserve aspect ratio of image (use width and height as maximum) // 1 for Media.2 MSEX / ELTh . // Format of the thumbnail. 2 for Effects. . // Thumbnail width. // Preferred thumbnail image width. ThumbnailWidth. ElementNumber.Element Library Thumbnail message The ElementLibraryThumbnail message is sent in response to the GetElementLibraryThumbnail message. // Numbers of the libraries requested. DMX range end value. uint32 uint16 uint16 uint8 uint8 uint8 uint8 }. not present if LibraryCount is 0. // 1 for Media. ThumbnailWidth. ThumbnailBuffer. // Name[]. // Preferred thumbnail image height. MSEX ContentType is "ELTh" and version is 1. ThumbnailHeight. ThumbnailWidth. set to 0 when requesting all available.1.4.1. 2 for Effects. // CITP MSEX header. // Ids of the libraries requested. uint32 uint16 uint16 uint8 ThumbnailFormat. // 1 for Media. Can be "RGB8" or "JPEG". // Thumbnail image buffer. 2 for Effects. // Preferred thumbnail image height. struct CITP_MSEX_1. ThumbnailFormat. ThumbnailBufferSize. Element name. // 1 for Media. struct CITP_MSEX_1.4. ThumbnailFlags // Additional information flags. LibraryType. ThumbnailFlags uint8 uint8 MSEXLibraryId }. // Preferred thumbnail image width. DMX range start value.

uint8 }. Can be "RGB8" or "JPEG".0_GETh { CITP_MSEX_Header CITPMSEXHeader. ElementNumber. // Preferred thumbnail image width.uint32 uint16 uint16 uint16 uint8 }. 10. ThumbnailFormat. ThumbnailBuffer. 10. ThumbnailHeight. // Preferred thumbnail image width. MSEX ContentType is "EThn" and version is 1. LibraryId. // 1 for Media. ThumbnailWidth. MSEX ContentType is "GETh" and version is 1. // CITP MSEX header. // Format of the thumbnail.0_EThn { CITP_MSEX_Header CITPMSEXHeader. LibraryId. // 0x01 Preserve aspect ratio of image (use width and height as maximum) // 1 for Media. Not present if ElementCount = 0. // CITP MSEX header.0. struct CITP_MSEX_1. 2 for Effects. set to 0 when requesting all available. // Preferred thumbnail image height. // Number of the element. Can be "RGB8" or "JPEG". // CITP MSEX header. ThumbnailFlags uint8 MSEXLibraryId uint8 LibraryType. ThumbnailHeight. // Format of the thumbnail. // The numbers of the requested elements. ElementNumbers[]. // Format of the thumbnail. // Thumbnail height. ThumbnailWidth. ThumbnailWidth. // Preferred thumbnail image height. ThumbnailBufferSize. ThumbnailHeight. struct CITP_MSEX_1.0. ThumbnailWidth. Can be "RGB8" or "JPEG". // Size of the thumbnail buffer. // Thumbnail width. struct CITP_MSEX_1.4. // Size of the thumbnail buffer. 2 for Effects.Element Thumbnail message The ElementLibraryThumbnail message is sent in response to the GetElementLibraryThumbnail message. 2 for Effects. uint32 uint16 uint16 uint8 ThumbnailFormat. // Thumbnail width. ElementCount. // Number of medias for which information is requested. ThumbnailBuffer. // Thumbnail image buffer. ThumbnailHeight. // Format of the thumbnail. // 0x01 Preserve aspect ratio of image (use width and height as maximum) // 1 for Media. // CITP MSEX header. MSEX ContentType is "EThn" and version is 1. // Id of the media's library. // Number of the media's library. // Id of the element's library. Not present if ElementCount is 0.1_EThn { CITP_MSEX_Header CITPMSEXHeader.4 MSEX / EThn .1_GETh { CITP_MSEX_Header CITPMSEXHeader. // Number of the element.4. 2 for Effects. ThumbnailFlags uint8 uint8 uint8 LibraryType. LibraryNumber. ElementNumbers[].. LibraryNumber. ElementCount. uint8 MSEXLibraryId uint8 uint32 LibraryType. // The numbers of the requested elements. uint32 uint16 uint16 uint8 ThumbnailFormat. struct CITP_MSEX_1. . uint8 uint8 uint8 uint32 uint16 uint16 uint16 uint8 }. // Additional information flags. // Number of medias for which information is requested. Can be "RGB8" or "JPEG". ThumbnailBufferSize. ThumbnailFormat. MSEX ContentType is "GETh" and version is 1. // 1 for Media. set to 0 when requesting all available. LibraryType. // Additional information flags. // Format of the thumbnail. // Number of the element's library. // Thumbnail height. ElementNumber. // Thumbnail image buffer.1.3 MSEX / GETh . uint8 }. ThumbnailFormat.Get Element Thumbnail message The GetElementThumbnail message is sent to a media server in order to retrieve a thumbnail of one or many library elements. Can be "RGB8" or "JPEG".1.

uint16 uint16 uint16 }.4 MSEX / StFr . 0 to ask for only one frame). Otherwise 0xFF. MSEX ContentType is "GVSr". FrameFormat. CITPMSEXHeader.5. // CITP MSEX header. 0-based index designating the physical video output index. SourceIdentifier. ThumbnailBuffer.3 MSEX / RqSt . // If applicable. // Display name of the source (ie "Output 1".GetVideoSources The GetVideoSources message is sent to a media server in order to receive all available video source feeds. MSEX ContentType is "RqSt". struct SourceInformation { uint16 SourceIdentifier. struct CITP_MSEX_RqSt { CITP_MSEX_Header uint16 uint32 uint16 uint16 uint8 uint8 }. // Requested frame format. Width. 10. struct CITP_MSEX_GVSr { CITP_MSEX_Header }. struct CITP_MSEX_VSrc { CITP_MSEX_Header uint16 CITPMSEXHeader.Video Sources The VideoSources message is sent in response to a GetVideoSources message. Height. ucs2 SourceName[]. based on its timeout parameter. FPS.5. // CITP MSEX header. formats and FPS are determine by the current set of subscribing peers. corresponding to the layers reported in the SInf message. The PhysicalOutput and LayerNumber fields can be used for automatic connection to outputs and individual layers (for instance the video of output 1 would have PhysicalOutput = 0 and LayerNumber = 0xFF). // Timeout in seconds (for instance 5 seconds. 10. The resolutions. // Source identifier. CITPMSEXHeader. FrameWidth. Thumbnail height. . // Preferred minimum frame width.2 MSEX / VSrc . if it wishes receive a continuous feed.Request Stream message The RequestStream message is sent by a console or visualizer to a media server in order to create a time limited subscription of a video source. The media server will not provide multiple resolutions and frame rates of a single source. Flags. MSEX ContentType is "VSrc". // Full height.5. // Preferred minimum frame height. Can be "RGB8" or "JPEG". FrameHeight. "Layer 2". Size of the thumbnail buffer.5. ThumbnailWidth. 10. // 0x0001 Without effects // Full width. 10. ThumbnailBufferSize. Otherwise 0xFF. "Camera 1" etc). // Preferred minimum frames per second. Thumbnail image buffer. 0-based layer number.uint16 uint16 uint16 uint8 }. but it may provide a feed for each requested format. // Information flags.1 MSEX / GVSr . // // // // Thumbnail width. // Number of following source information blocks. uint8 PhysicalOutput. High values of the timeout field is of course discouraged. uint8 LayerNumber. ThumbnailHeight. }. Timeout.5 Message definitions: Streams 10. It is up to the peer to regularly request a stream. SourceCount. // CITP MSEX header. // If applicable. // Identifier of the source requested.Stream Frame message The StreamFrame message is multicasted regularly from a media server.

FrameBufferSize. // Frame image buffer. // Preferred minimum frame width. FrameFormat. .1.struct CITP_MSEX_StFr { CITP_MSEX_Header uint16 uint32 uint16 uint16 uint16 uint8 }. Can be "RGB8" or "JPEG". // Size of the frame image buffer. // Requested frame format. RGB8 data was transmitted as BGR rather then RGB. SourceIdentifier. FrameBuffer[]. // Identifier of the frame's source. As of version 1. stream frames are to be transmitted over the multicast channel only (sames as used by PINF) and never over a TCP connection. // Preferred minimum frame height.1 of MSEX. FrameHeight. CITPMSEXHeader. Prior to version 1. MSEX ContentType is "StFr". FrameWidth. // The CITP MSEX header.