proposal for GPI Trigger support in NDI:NDI-GPI

This page contains a technical proposal which is not currently a published or formal standard. If you have comments or feedback on the content of this proposal PLEASE contact us with your contribution.


The NDI IP Video protocol SDK does not currently offer any guidance on provision for carrying generic GPI state messages.  However, NDI has multiple real time metadata mechanisms which could easily carry this sort of data. This document is an attempt to standardise support for GPIs in order to prevent different implementations by each vendor by way of a recommended practice technical note.


Basic Premise:

The focus is based on the need of an NDI Sender or NDI Receiver to send or receive GPI state information in a standardised protocol. This document simply standardises a mechanism for sending boolean state GPI information over an NDI Connection. Note that this mechanism could be used to deliver changed state messages, or it can be used in real time to constantly communicate GPI state.


The objectives are to allow the following scenarios:

- Support for generic, unambiguous and non-specific communication of GPI boolean state from NDI Sender to NDI Receiver, or from Receiver to Sender.


The GPI concept is straightforward and unambigious. A GPI which has an index, is either set or not (0 or 1). GPIs are widely used as an unambiguous and generic mechanism to communicate state or to issue triggers between broadcast equipment.  Typical examples would be tallies, which are set to 1 when a signal is considered 'tallied' and 0 when it is not.  Similarly a brief change from a 0 to a 1 state and back to 0 is generally used as a trigger, to start an event such as a play command to a media player, or an animate step instruction to a CG.


In this proposal, the GPI data is sent using dedicated metadata messages already defined in the NDI Protocol, the same type used for PTZ control of cameras, and NDI specific tally information.  It uses the real time (non frame based) NDI Metadata stream, with GPI information in either a discrete or global message.


Example 1 : This message allows a GPI device to communicate a complete map of its inputs.  Here a GPI device with 16 GPI inputs can communicate the state of all 16 inputs with a single message.  This takes the form of a binary bit field in big endian order (ie, highest order bit first / left and lowest order bit last / right. There is no limitation to the size of the GPI bitfield.


NDIlib_metadata_frame_t meta_data


meta_data.p_data =


This represents a bitmap from bit zero on the right up to bit 15 on the left.

An optional XML attribute can indicate a device ID where multiple GPI devices exist:

<GPI_GLOBAL_MAP deviceid="2">0000011110000111</GPI_GLOBAL_MAP>



Example 2 : This message allows a GPI device to communicate a single GPI state.  Here a GPI device with an arbitrary number of GPI inputs can communicate the state of a single pin.


meta_data.p_data =

<GPI_BIT bit="0">0</GPI_BIT>

This represents a value of zero for GPI bit 0.  GPI indexes should be zero indexed, so the lowest GPI index would be 0, not 1.  Note: This might be labelled as GPI1 on a device which indexes from 1.

An optional XML attribute can indicate a device ID where multiple GPI devices exist:

<GPI_BIT deviceid="2" bit="0">0</GPI_BIT>

An optional XML attribute can indicate a label for this bit:

<GPI_BIT deviceid="2" label="IFB-A" bit="0">0</GPI_BIT>


Example 3 : For convenience, this standard also supports the notion of a trigger, which is commonly implemented by a brief change from 0 to 1 and back to 0. However, triggers are notoriously unpredictable due to ambiguity about the direction of trigger, leading or trailing edge, trigger duration etc. To accomodate this, the NDI:GPI standard supports an unambigious trigger message which communicates the concept of a generic trigger.


meta_data.p_data =


This message communicates a generic trigger on GPI pin 16, indexed from zero.  It is a stateless message which is purely a temporal indication that a trigger has been actioned. it is suitable for triggering CG animates, transport actions etc.

An optional XML attribute can indicate a device ID where multiple GPI devices exist:

<GPI_TRIGGER deviceid="2" label="VTR1">16</GPI_TRIGGER>

An optional XML attribute can indicate a label for this trigger:



This protocol can be used for both sensing GPI state, and also for issuing GPI state changes. In other words an NDI Source SENDING a  <GPI_BIT bit="6">1</GPI_BIT> message can TELL an NDI Receiver to SET bit 6. Whether a sender or receiver is sending an instruction to SET a bit, or it is reporting the state of a bit is irrelevant, since in the concept of GPI its the same thing. What any given NDI device does in response to the message is defined by implementation.


An NDI Sending Device would send NDI-GPI messages (to connected clients) on an NDI 'send' it has created using the NDIlib_send_send_metadata() message, and could receive NDI-GPI messages back from connected clients using the NDIlib_send_capture() message


An NDI Receiving Device would receive NDI-GPI messages from the device it has connected to using the NDIlib_recv_capture_v2() message, and would send NDI-GPI messages back to the sender using the NDIlib_recv_send_metadata() message.


Sienna's Free NDI Signal Generator for macOS can generate a range of test messages  in the NDI:GPI protocol format.


If you have any questions, or you would like to engage Sienna for NDI Consultancy or Custom Development, please contact info @ sienna.tv