SDK API Definition — Media Communications Mesh#
Header file to include: mesh_dp.h
mesh_create_client()#
int mesh_create_client(MeshClient **client,
const char *config_json)
Creates a new mesh client with the provided JSON configuration.
Parameters#
[OUT]
client
– Address of a pointer to a mesh client structure.[IN]
config_json
– Pointer to a mesh client configuration string in JSON format.
Client Configuration Example#
{
"apiVersion": "v1",
"apiConnectionString": "Server=127.0.0.1; Port=8002",
}
JSON structure fields#
"apiVersion"
– Default “v1”."apiConnectionString"
– IP address and the port number of Media Proxy SDK API in the form of a connection string as in the example: “Server=127.0.0.1; Port=8002”."apiDefaultTimeoutMicroseconds"
– Default timeout interval for SDK API calls, default 1000000."maxMediaConnections"
– Maximum number of media connections, default 32.
Environment variables#
MCM_MEDIA_PROXY_IP
– IP address of Media Proxy SDK API, default “127.0.0.1”.MCM_MEDIA_PROXY_PORT
– Port number of Media Proxy SDK API, default 8002.
Note on configuring the Media Proxy address#
There are two options to configure the IP address and the port number of Media Proxy SDK API, ordered by priority:
Specify
"apiConnectionString"
in the JSON configuration string.Set
MCM_MEDIA_PROXY_IP
andMCM_MEDIA_PROXY_PORT
.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_delete_client()#
int mesh_delete_client(MeshClient **client)
Deletes the mesh client and its resources.
Parameters#
[IN/OUT]
client
– Address of a pointer to a mesh client structure.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_create_tx_connection()#
int mesh_create_tx_connection(MeshClient *client,
MeshConnection **conn,
const char *config_json)
Creates a transmitter connection with the provided JSON configuration.
Parameters#
[IN]
client
– Pointer to a parent mesh client.[OUT]
conn
– Address of a pointer to the connection structure.[IN]
config_json
– Pointer to a connection configuration structure.
Transmitter/Receiver Connection Configuration Example#
{
"connection": {
"st2110": {
"transport": "st2110-20",
"ipAddr": "224.0.0.1",
"port": 9002,
"multicastSourceIpAddr": "192.168.95.10",
"pacing": "narrow",
"payloadType": 112,
"transportPixelFormat": "yuv422p10rfc4175"
},
},
"payload": {
"video": {
"width": 1920,
"height": 1080,
"fps": 60.0,
"pixelFormat": "yuv422p10rfc4175"
},
}
}
The following examples show optional parts of the JSON configuration that can be used
to setup various connection and payload options. The examples correspond to the main
(.
) level of the JSON document.
Configure connection – Multipoint Group#
"connection": {
"multipointGroup": {
"urn": "ipv4:224.0.0.1"
}
}
Configure connection – SMPTE ST 2110#
"connection": {
"st2110": {
"transport": "st2110-22",
"ipAddr": "224.0.0.1",
"multicastSourceIpAddr": "192.168.95.10",
"port": 9002,
"pacing": "narrow",
"payloadType": 112
}
}
Configure payload – Video#
"payload": {
"video": {
"width": 1920,
"height": 1080,
"fps": 60.0,
"pixelFormat": "yuv422p10le"
}
}
Configure payload – Audio#
"payload": {
"audio": {
"channels": 2,
"sampleRate": 48000,
"format": "pcm_s24be",
"packetTime": "1ms"
}
}
Configure payload – Blob Data#
"payload": {
"blob": {}
},
"maxPayloadSize": 2097152
The above maxPayloadSize
is set explicitly to define the buffer size for the Blob payload.
Configure optional parameters#
"bufferQueueCapacity": 16,
"maxMetadataSize": 8192,
"connCreationDelayMilliseconds": 100
JSON structure fields#
"bufferQueueCapacity"
– Dataplane buffer queue capacity between 2-128, default 16."maxPayloadSize"
– Payload maximum size. If set to 0, calculated automatically from the payload parameters at connection creation. Default 0."maxMetadataSize"
– User metadata maximum size, default 0."connCreationDelayMilliseconds"
– Delay between the connection creation and sending of the very first buffer, default 0."connection"
– Connection type, options 1-2 are the following:"st2110"
– SMPTE ST 2110 connection."transport"
– SMPTE ST 2110 connection type."st2110-20"
– Uncompressed video."st2110-22"
– Compressed video (JPEG XS)."st2110-30"
– Uncompressed audio (PCM).
"ipAddr"
– Tx connection: destination IP address. Rx connection: multicast IP address or unicast source IP address."port"
– Tx connection: destination port number. Rx connection: local port number."multicastSourceIpAddr"
– Rx connection only: optional multicast source filter IP address."pacing"
"narrow"
"payloadType"
– Default 112."transportPixelFormat"
– Required only for the"st2110-20"
transport type, default “yuv422p10rfc4175”.
"multipointGroup"
– Multipoint Group connection."urn"
– Uniform Resource Name (URN) of the multipoint group, e.g. “ipv4:224.0.0.1:9003”.
"payload"
– Payload type, options 1-3 are the following:"video"
– Video payload."width"
– Integer frame width, e.g. 1920."height"
– Integer frame height, e.g. 1080."fps"
– Float frame rate, e.g. 60.0."pixelFormat"
– Default “yuv422p10le”."yuv422p10le"
"v210"
"yuv422p10rfc4175"
"audio"
– Audio payload."channels"
– Default 2."sampleRate"
48000
96000
44100
"format"
– Default “pcm_s24be”."pcm_s24be"
"pcm_s16be"
"pcm_s8"
"packetTime"
– Default “1ms”."1ms"
– Sample rate 48000 or 96000."125us"
– Sample rate 48000 or 96000."250us"
– Sample rate 48000 or 96000."333us"
– Sample rate 48000 or 96000."4ms"
– Sample rate 48000 or 96000."80us"
– Sample rate 48000 or 96000."1.09ms"
– Sample rate 44100."0.14ms"
– Sample rate 44100."0.09ms"
– Sample rate 44100.
"blob"
– Blob payload.
Compatibility of connection types, transport types, and pixel formats#
Allowed use cases of "transportPixelFormat"
and "pixelFormat"
for "st2110-20"
“pixelFormat” |
“transportPixelFormat” |
Internal conversion |
FFmpeg support |
FFmpeg enum and string |
---|---|---|---|---|
“yuv422p10rfc4175” |
“yuv422p10rfc4175” |
No |
No |
N/A |
“yuv422p10le” |
“yuv422p10rfc4175” |
Yes |
Yes |
PIX_FMT_YUV422P10LE, “yuv422p10le” |
“v210” |
“yuv422p10rfc4175” |
Yes |
No |
N/A |
Allowed use cases of "pixelFormat"
for "st2110-22"
“pixelFormat” |
FFmpeg support |
FFmpeg enum and string |
---|---|---|
“yuv422p10le” |
Yes |
PIX_FMT_YUV422P10LE, “yuv422p10le” |
Allowed use cases of "pixelFormat"
for "multipointGroup"
“pixelFormat” |
FFmpeg support |
FFmpeg enum and string |
---|---|---|
“yuv422p10le” |
Yes |
PIX_FMT_YUV422P10LE, “yuv422p10le” |
“v210” |
No |
N/A |
Returns#
0 if successful. Otherwise, returns an Error code.
MeshConnection#
typedef struct MeshConnection {
MeshClient * const client;
const size_t payload_size;
const size_t metadata_size;
} MeshConnection;
Fields#
client
– Pointer to a parent mesh client.payload_size
– Maximum payload size, or frame size, configured for the connection.metadata_size
– Maximum metadata size, configured for the connection.
mesh_create_rx_connection()#
int mesh_create_rx_connection(MeshClient *client,
MeshConnection **conn,
const char *config_json)
Creates a receiver connection with the provided JSON configuration.
Parameters#
[IN]
client
– Pointer to a parent mesh client.[OUT]
conn
– Address of a pointer to the connection structure.[IN]
config_json
– Pointer to a connection configuration structure.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_delete_connection()#
int mesh_delete_connection(MeshConnection **conn)
Deletes the connection and its resources.
Parameters#
[IN/OUT]
conn
– Address of a pointer to the connection structure.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_get_buffer()#
int mesh_get_buffer(MeshConnection *conn,
MeshBuffer **buf)
Gets a buffer from the media connection.
The buffer must be returned back to the Mesh connection by calling mesh_put_buffer()
or mesh_put_buffer_timeout()
.
Parameters#
[IN]
conn
– Pointer to a connection structure.[OUT]
buf
– Address of a pointer to a mesh buffer structure.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_get_buffer_timeout()#
int mesh_get_buffer_timeout(MeshConnection *conn,
MeshBuffer **buf,
int timeout_us)
Gets a buffer from the media connection with a timeout.
The buffer must be returned back to the Mesh connection by calling mesh_put_buffer()
or mesh_put_buffer_timeout()
.
Parameters#
[IN]
conn
– Pointer to a connection structure.[OUT]
buf
– Address of a pointer to a mesh buffer structure.[IN]
timeout_us
– Timeout interval in microseconds.
Timeout definition constants#
MESH_TIMEOUT_DEFAULT
– Applies the default timeout interval defined for the Mesh client.MESH_TIMEOUT_INFINITE
– No timeout, blocks until success or an error.MESH_TIMEOUT_ZERO
– Polling mode, returns immediately.
Returns#
0 if successful. Otherwise, returns an Error code.
MeshBuffer#
typedef struct{
MeshConnection * const conn;
void * const payload_ptr;
const size_t payload_len;
void * const metadata_ptr;
const size_t metadata_len;
} MeshBuffer;
Fields#
conn
– Pointer to a parent connection structure.payload_ptr
– Pointer to shared memory area storing payload data.payload_len
– Actual length of payload data in the buffer.metadata_ptr
– Pointer to shared memory area storing metadata.metadata_len
– Actual length of metadata in the buffer.
mesh_put_buffer()#
int mesh_put_buffer(MeshBuffer **buf)
Puts the buffer to the media connection.
The buffer must be previously obtained from to the Mesh connection by calling
mesh_get_buffer()
or mesh_get_buffer_timeout()
.
In case of Tx connection, a call to this API function triggers transmittion of the buffer from SDK to Media Proxy and then to the receiver over the Mesh.
Parameters#
[IN/OUT]
buf
– Address of a pointer to a mesh buffer structure.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_put_buffer_timeout()#
int mesh_put_buffer_timeout(MeshBuffer **buf,
int timeout_us)
Puts the buffer to the media connection with a timeout.
The buffer must be previously obtained from to the Mesh connection by calling
mesh_get_buffer()
or mesh_get_buffer_timeout()
.
In case of Tx connection, a call to this API function triggers transmittion of the buffer from SDK to Media Proxy and then to the receiver over the Mesh.
Parameters#
[IN/OUT]
buf
– Address of a pointer to a mesh buffer structure.[IN]
timeout_us
– Timeout interval in microseconds.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_buffer_set_payload_len()#
int mesh_buffer_set_payload_len(MeshBuffer *buf,
size_t len)
Sets the payload length in the buffer provided by the media connection.
Parameters#
[IN]
buf
– Pointer to a mesh buffer structure.[IN]
len
– Payload length in bytes.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_buffer_set_metadata_len()#
int mesh_buffer_set_metadata_len(MeshBuffer *buf,
size_t len)
Sets the metadata length in the buffer provided by the media connection.
Parameters#
[IN]
buf
– Pointer to a mesh buffer structure.[IN]
len
– Metadata length in bytes.
Returns#
0 if successful. Otherwise, returns an Error code.
mesh_err2str()#
const char * mesh_err2str(int err)
Gets a text description of the error code.
Parameters#
[IN]
err
– Error code returned from any Mesh DP API call.
Returns#
NULL-terminated string describing the error code.
Return error codes#
API SDK functions may return the following error codes.
NOTE: The codes are negative integer values.
Error code macro name |
Description |
Meaning |
---|---|---|
|
Bad client pointer |
The client pointer is NULL. |
|
Bad connection pointer |
The connection pointer is NULL. |
|
Bad configuration pointer |
The configuration pointer is NULL. |
|
Bad buffer pointer |
The buffer pointer is NULL. |
|
Bad buffer length |
Rx connection: The buffer length is corrupted. |
|
Invalid client config |
JSON client configuration string is malformed. |
|
Reached max connections number |
An attempt to create a connection failed due to reaching the maximum number of connections defined in |
|
Found allocated resources |
When deleting a client, some connections were found not closed. Delete all connections explicitly before deleting the client. |
|
Connection creation failed |
An error occurred while creating a connection. |
|
Invalid connection config |
JSON connection configuration string is malformed or one of parameters has an incorrect value. |
|
Incompatible connection config |
Incompatible parameters found in the JSON connection configuration string. |
|
Connection is closed |
When getting a buffer, the connection appeared to become closed. |
|
Timeout occurred |
Timeout occurred when performing an operation. |