2. Home
  4. Docs
  6. HTTP API of NDI
  8. NDI Encoder status and settings

NDI Encoder status and settings

Module name: encoder/ndi

Basic URL: /api/v1/encoder/ndi/

Note: APIs of this module is only effective when the device works in Encoder mode.

Get NDI Encoding configuration

API URL

​ /api/v1/encoder/ndi/get_config

Request

​ Method: GET/POST

​ Parameters: NONE

Response

Example:

{
    "result": "ok",
    "data": {
        "device_group": "public",
        "device_name": "Spark IO",
        "channel_name": "1916001002",
        "ndi_connection": "multicast",
        "netprefix": "239.254.0.0",
        "netmask": "255.255.0.0"
    }
}

Data field descriptions:

Field Value Descriptions
device_group [STRING] NDI Group Name. If the value is "" (empty string)，it means enable NDI default group, that is public.
device_name [STRING] NDI device name, also represents the host name of NDI Device.
channel_name [STRING] NDI encoding channel name
ndi_connection [STRING] "tcp" or "multicast"
As NDI Sender, NDI Receiver suggested Connection mode. According to NDI, currently it allows tcp (by default) or UDP multicast mode. UDP unicast mode will be provided in the future.
netprefix [STRING] (Only meaningful when ndi_connection is "multicast") A multicast IP address (224.0.0.0 ~ 239.255.255.255)

netprefix and netmask work in pair. Their relation is similar with IP and netmask, namely, netmask decides Subnet of NDI multicast address. NDI SDK will arbitarily select Multicast address from the Subnet for NDI actual transmission.
netmask [STRING] (Only meaningful when ndi_connection is "multicast") The netmask for multicast IP address
quality [INT] Valid range of Value: 75 ~ 150
Due to historical reasons, we may select an unappropriate parameter name, the meaning it represents is refer to bitrate recommended by NDI standard, bitrate in percent that we can control is 75%~150%.

NOTE: The current version of HTTP API may include other not-listed fields when returns to the result. These fields exist for software compatibility, please ignore them. In the future software updating, the fields that not listed in the document may be changed or discarded.

Set NDI Encoding parameter

API URL

​ /api/v1/encoder/ndi/set_config

Request

​ Method: GET/POST

Parameter Value Descriptions
device_group [STRING], Optional When you specify any one or more parameters of device_group, device_name, channel_name, it will modify Group, Device name or Channel Name. If no parameter is specified, the previously set value will be retained.
device_name [STRING], Optional
channel_name [STRING], Optional
ndi_connection [STRING], Optional Valid value is "tcp" or"multicast"，specifying the connection mode recommended for NDI Receiver. When specify as "multicast"，you need to specify netprefix and netmask parameter at the same time.
netprefix [STRING], Optional netprefix and netmask work in pair. Their relation is similar with IP and netmask, namely, netmask decides Subnet of NDI multicast address. NDI SDK will arbitarily select Multicast adress from the Subnet for NDI actual transmission.
netmask [STRING], Optional If you set net_connection="multicast" , but not specify netprefix/netmask，the previously set value of netprefix/netmask will be used if they have been set before; otherwise, NDI Device will generate a Multicast address randomly and select 255.255.0.0 as netmask.
quality [INT], Optional Due to historical reasons, we may select an unappropriate parameter name, the meaning it represents is refer to bitrate recommended by NDI standard, bitrate in percent that we can control is 75% ~ 150%.

Response

Example:

{
    "result": "ok"
}

If set succeeded, you will get the message result = "ok"；or refer to error message descriptions in 1.3.

Note:

  • If NDI Encoding parameter values changed, all current NDI connections will be disconnected, reconfiguring NDI Sender, and it will restart. This process is very fast, normally most NDI Receivers can reconnect in an instant. But please pay attention that it will reconnect all NDI connections of current NDI Device.
  • All the parameters listed above are optional. If you don’t specify any parameter, it means it will do nothing.

Get NDI Encoding status and video/audio formats information

API URL

​ /api/v1/encoder/ndi/status

Request

​ Method: GET/POST

​ Parameters: NONE

Response

Example:

{
    "result": "ok",
    "data": {
        "video_signal": "hdmi",
        "resolution": "1920x1080p 59.94Hz",
        "xRes": 1920,
        "yRes": 1080,
        "frame_rate": 59.94,
        "interlaced": false,
        "bitrate": 125000, /*in Kbps*/
        "audio_format": "48000 Hz/Stereo",
        "audio_signal": "embedded",
        "audio_sampling": 48000,
        "audio_channels": 2
    }
}

Data fields descriptions:

Field Value Descriptions
video_signal [STRING] none: no signal input
hdmi: signal is HDMI, input format identified.
sdi: signal is SDI, input format identified.

video_signal used to show the input signal status of current NDI encoding. When video_signal is"none", it means there no video input from the video input interface (or video format is unidentified or supported) "hdmi" / "sdi" is subject to the device.
resolution [STRING] Video resolution name
Note: This is a user-friendly resolution name, it may not be suitable for your program. You can get program-friendly resolution information via field xRes/yRes/frame_rate/interlaced.
xRes [INT] xRes/yRes shows the width/height of the current video, in pixel. If xRes/yRes = 0，it means current resolution is invalid.
yRes [INT]
frame_rate [NUMBER] Frame rate in fps. If frame_rate = 0，it means the frame rate of the current video is invalid.
interlaced [BOOLEAN] If the current video format is interlaced，value will be true；otherwise be false.
bitrate [INT] The bitrate of the current NDI encoding (video), in Kbps
audio_format [STRING] Audio format Note: This is a user-friendly audio format name, it may not be suitable for your program. You can get program-friendly audio information via audio_sampling / audio_channels.
audio_signal [STRING] none: no audio input
embedded: it’s from HDMI/SDI-embedded digital audio
analog: It’s from analog audio input

Note: For different devices, the audio source that embedded represents may be different. For HDMI Encoder, it means audio comes from HDMI-embedded digital audio; for SDI Encoder, it means audio comes from SDI-embedded digital audio.

Similarly, analog has different meanings for different devices as well. The analog audio input of some devices is Line In; while some devices may be Microphone In, please distinguish.
audio_sampling [INT] Audio sampling of the current audio
audio_channels [INT] Audio channels of the current audio

Get audio source and volume

API URL

​ /api/v1/encoder/ndi/get_audio

Request

​ Method: GET/POST

​ Parameters: NONE

Response

Example:

{
    "result": "ok",
    "data": {
        "signal": "embedded",
        "volume": 100
    }
}

Data fields description:

Field Value Descriptions
signal [STRING] none: no audio input
embedded: It’s from HDMI/SDI- embedded digital audio
analog: It’s from analog audio input

Note: For different devices, the audio source that embedded represents may be different. For HDMI Encoder, it means audio comes from HDMI-embedded digital audio; for SDI Encoder, it means audio comes from SDI-embedded digital audio.

Similarly, analog has different meanings for different devices as well. The analog audio input of some devices is Line In; while some devices may be Microphone In, please distinguish.
volume [INT] The current audio volume, valid value range 0~200. 100 means the original audio gain；<100 means audio decreasing (percentage)；>100 audio increasing (percentage).

Set signal source and/or volume

API URL

​ /api/v1/encoder/ndi/set_audio

Request

​ Method: GET/POST

Parameter Value Descriptions
signal [STRING], Optional embedded: It’s from HDMI/SDI-embedded digital audio
analog: It’s from analog audio input

Select current audio input. Please refer to 4.4 for audio signal description.
If not specify, then not modify the current audio input.
volume [INT], Optional Adjust the volume of current audio input. Valid value range: 0 ~ 200.100 means the original audio gain；<100 means audio decreasing (percentage)；>100 audio increasing (percentage).
If not specify, then not modify the current audio input.

Response

Example:

{
    "result": "ok",
}

If set successfully, it will return the message of result = "ok", or please refer to 1.3 for error message descriptions.

How can we help?