2. 主页
  4. 文档
  6. NDI 设备 HTTP API(Version 1.0)
  8. 4. NDI Encoder状态和设置

4. NDI Encoder状态和设置

Module name: encoder/ndi

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

注意：本模块的APIs仅当设备工作于Encoder模式下才有效。

获取NDI Encoding配置

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 Value 说明
device_group [STRING] NDI Group Name。如果该值为 ""（空字符串），表示启用NDI默认的组，即public
device_name [STRING] NDI设备名称，它同时也代表着NDI Device的host name。
channel_name [STRING] NDI编码通道名称。
ndi_connection [STRING] "tcp" 或 "multicast"。
作为NDI Sender，建议NDI Receiver采用的Connection方式。按NDI的建议，目前允许tcp（默认）或 UDP multicast方式。UDP unicast方式将在未来提供支持。
netprefix [STRING] (仅当ndi_connection 为 "multicast"时有意义) A multicast IP address (224.0.0.0 ~ 239.255.255.255)

netprefix 和 netmask 是成对使用的关系。和我们通常的IP和netmask关系相似，由netmask决定NDI multicast地址的Subnet。NDI SDK将在这个Subnet中随机选择Multicast地址用于实际的NDI传输。
netmask [STRING] (仅当ndi_connection为"multicast"时有意义) The netmask for multicast IP address
quality [INT] 值有效范围：75 ~ 150
由于历史原因，也许我们选择了一个不太恰当的参数名称，它所代表的意义是参照NDI标准推荐的bitrate，我们可以控制的bitrate in percent，范围在 75% ~ 150%之间。

请注意：当前版本的HTTP API可能在返回结果中包含某些其它的未列在文档中的字段。这些字段的存在是因为出于软件兼容性的目的，请忽略它们。在后续的软件升级中，未列于文档中的字段很有可能会发生改变或丢弃。

设置NDI Encoding参数

API URL

**/api/v1/encoder/ndi/set_config**

Request

Method: **GET/POST**
Parameter Value 说明
device_group [STRING], Optional 当您指定了device_group, device_name, channel_name其中的任意一个或多个参数时，它将修改NDI的Group, Device name或Channel Name。没有指定的参数，将保留之前设定的值。
device_name [STRING], Optional
channel_name [STRING], Optional
ndi_connection [STRING], Optional 有效值为"tcp"或"multicast"，指定建议NDI Receiver采用的Connection方式。当指定为"multicast"时，您还应该同时指定 netprefix 和 netmask 参数。
netprefix [STRING], Optional netprefix 和 netmask 是成对使用的关系。和我们通常的IP和netmask关系相似，由netmask决定NDI multicast地址的Subnet。NDI SDK将在这个Subnet中随机选择Multicast地址用于实际的NDI传输。
netmask [STRING], Optional 如果您设置 net_connection="multicast" 但没有指定 netprefix/netmask，如果之前有设置netprefix/netmask的值，则将沿用之前设置的值 ；否则，NDI Device将随机生成一个Multicast地址，并选择 255.255.0.0 作为netmask。
quality [INT], Optional 由于历史原因，也许我们选择了一个不太恰当的参数名称，它所代表的意义是参照NDI标准推荐的bitrate，我们可以控制的bitrate in percent，范围在 75% ~ 150%之间。

Response

Example:

{
    "result": "ok"
}

如果设置成功，将返回 result = "ok" 的消息；否则请参见HTTP响应和错误处理的标准错误消息描述。

请注意：

  • 如果NDI Encoding参数的值发生了改变，NDI Device将断开当前的NDI Connections、重新配置NDI Sender并再次启动。这个过程通常很快，大多数NDI Receivers也能在瞬间获得重新连接。但您必须注意，它会重置连接到当前NDI Device的所有NDI Connections。
  • 上面列出的所有参数都是可选的。如果您没有指定任何参数，意味着它什么也不做。

获取NDI Encoding状态和视频/音频格式信息

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字段说明：

Field Value 说明
video_signal [STRING] none: 没有视频信号输入
hdmi: 视频信号来自于HDMI，已识别输入格式
sdi: 视频信号来自于SDI，已识别输入格式

video_signal用于指示当前NDI encoding视频输入的信号状态。当video_signal="none"时，表示目前没有从视频输入接口获得视频输入（或者视频格式不被识别/支持）。 "hdmi" / "sdi" 视不同的设备而定。
resolution [STRING] 视频分辨率名称。
请注意：这是一个用户友好的分辨率名称，也许它不适合你的程序获取视频的详细格式信息。您可以通过xRes / yRes / frame_rate / interlaced 字段来获得程序友好的分辨率信息。
xRes [INT] xRes/yRes 表示当前视频的宽/高，以像素为单位。如果 xRes/yRes = 0，则表示当前分辨率无效。
yRes [INT]
frame_rate [NUMBER] Frame rate，单位: fps。如果frame_rate = 0，则表示当前视频的刷新率无效。
interlaced [BOOLEAN] 如果当前视频是interlaced格式，则值为 true；否则为 false
bitrate [INT] 当前NDI编码（视频）的实时码率，Kbps
audio_format [STRING] 音频格式。请注意：这是一个用户友好的音频格式名称（字符串），也许它不适合你的程序获取音频的详细格式信息。您可以通过 audio_sampling / audio_channels 来获得程序友好的音频信息。
audio_signal [STRING] none: 无音频输入
embedded: 来自于HDMI/SDI的内嵌数字音频
analog: 来自于模拟音频输入

请注意：对于不同的设备，embedded所代表的音频来源是有差异的。对于HDMI Encoder，这表示音频来自于HDMI的内嵌数字音频；对于SDI Encoder，这表示来自于SDI内嵌数字音频。

同样，analog对于不同的设备也有不同的意义。有的设备模拟音频的输入为Line In；而有的设备可能是Microphone In，请注意区分。
audio_sampling [INT] 当前音频的输入采样率
audio_channels [INT] 当前音频的声道数

获取音频信号源和音量

API URL

**/api/v1/encoder/ndi/get_audio**

Request

Method: **GET/POST**

Parameters: NONE

Response

Example:

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

Data字段说明：

Field Value 说明
signal [STRING] none: 无音频输入
embedded: 来自于HDMI/SDI的内嵌数字音频
analog: 来自于模拟音频输入

请注意：对于不同的设备，embedded所代表的音频来源是有差异的。对于HDMI Encoder，这表示音频来自于HDMI的内嵌数字音频；对于SDI Encoder，这表示来自于SDI内嵌数字音频。

同样，analog对于不同的设备也有不同的意义。有的设备模拟音频的输入为Line In；而有的设备可能是Microphone In，请注意区分。
volume [INT] 当前的音频音量，有效值范围 0 ~ 200。100表示原始的音频增益；<100表示音量减小（百分比）；>100表示音量增大（百分比）。

设置信号源和/或音量

API URL

**/api/v1/encoder/ndi/set_audio**

Request

Method: **GET/POST**
Parameter Value 说明
signal [STRING], Optional embedded: 来自于HDMI/SDI的内嵌数字音频
analog: 来自于模拟音频输入

选择当前的音频输入。请参考获取音频信号源和音量关于音频signal的说明。
如果不指定，则不修改当前的音频输入。
volume [INT], Optional 调节音频输入的音量。有效值范围 0 ~ 200。100表示原始的音频增益；<100表示音量减小（百分比）；>100表示音量增大（百分比）。
如果不指定，则不修改当前的音频音量。

Response

Example:

{
    "result": "ok",
}

如果设置成功，将返回 result = "ok" 的消息；否则请参见HTTP响应和错误处理的标准错误消息描述。

我们要如何帮助您？