TiRTC Nano SDK API Reference

TiRTC Nano SDK API Reference

Error Codes

Constant	Value	Meaning
`TIRTC_E_INVALID_HANDLE`	-40001	Invalid connection handle
`TIRTC_E_INVALID_PARAMETER`	-40002	Invalid parameter
`TIRTC_E_INVALID_LICENSE`	-40003	Invalid license format
`TIRTC_E_TIMEOUTED`	-40004	Operation timed out
`TIRTC_E_BUSY`	-40005	Send buffer is full and the video frame was dropped
`TIRTC_E_CONN_HAS_ERROR`	-40006	The connection is already in an error state and sending is rejected

Types

tirtc_conn_t

typedef struct _tirtc_conn *tirtc_conn_t;

Represents the opaque handle of a peer-to-peer connection. It is delivered through on_conn_accepted or the TIRTCCONNECTCALLBACK callback. Its lifetime ends after on_disconnected fires, at which point the SDK releases it automatically.

TIRTCOPTION

Configuration items set through TiRtcSetOpt().

Enum Value	`data` Type	Description
`TIRTC_OPT_SERVICE_ENTRY`	`const char *`	Service entry URL. If not set, the default TiRTC entry is used
`TIRTC_OPT_DEVICE_LICENSE`	—	Device license. Reserved for now
`TIRTC_OPT_MAX_CONNECTIONS`	`int *`	Maximum connection count, used for constrained device resource planning
`TIRTC_OPT_NETWORK_TYPE`	`const char *`	Network type: `"wifi"` or `"4g"`, default is `"wifi"`
`TIRTC_OPT_ICCID`	`const char *`	4G SIM ICCID, required when `network=4g`
`TIRTC_OPT_WAKEUP`	`int *`	Whether sleep wakeup is supported: 0 or 1, default 0
`TIRTC_OPT_RESTRICTED_NETWORK`	`int *`	Whether the network is restricted: 0 or 1, default 0
`TIRTC_OPT_MAX_SEND_BUFFER`	`uint32_t *`	Send buffer size in bytes. Must be set before `TiRtcInit()`. Default is 512 KB; 100 KB under `CONFIG_SMALL_MEMORY`

TIRTCMEDIA

Media type. Stored in TIRTCFRAMEINFO.media.

Enum Value	Value	Description
`TIRTC_MEDIA_MESSAGE`	0	Message frame inserted into the media stream
`TIRTC_AUDIO_PCM`	1	Raw PCM audio
`TIRTC_AUDIO_ALAW`	2	G.711 A-law
`TIRTC_AUDIO_AAC`	3	AAC compressed audio
`TIRTC_AUDIO_OPUS`	4	Opus compressed audio
`TIRTC_VIDEO_JPEG`	65	JPEG image frame
`TIRTC_VIDEO_H264`	66	H.264 video frame
`TIRTC_VIDEO_H265`	67	H.265 video frame

Helper macros:

TIRTC_IS_AUDIO(mt)   // media value is in audio range [1, 64]
TIRTC_IS_VIDEO(mt)   // media value is in video range [65, 127]

TIRTCAUDIOSAMPLE

Audio sample format. Stored in TIRTCFRAMEINFO.flags for audio frames.

Enum Value	Description
`TIRTC_AUDIOSAMPLE_8K16B1C`	8 kHz, 16 bit, mono
`TIRTC_AUDIOSAMPLE_16K16B1C`	16 kHz, 16 bit, mono
`TIRTC_AUDIOSAMPLE_8K16B2C`	8 kHz, 16 bit, stereo
`TIRTC_AUDIOSAMPLE_16K16B2C`	16 kHz, 16 bit, stereo

TIRTCFRAMEINFO

Media frame header. The payload data follows immediately after this header.

typedef struct TIRTCFRAMEINFO {
    uint8_t  stream_id;  // Stream ID, range 0~15, globally unique within the connection
                         // Audio and video cannot use the same stream_id
    uint8_t  media;      // Media type, see TIRTCMEDIA
    uint8_t  flags;      // Video: low bit is keyframe flag (TIRTC_FRAME_FLAG_KEY_FRAME)
                         // Audio: sample format from TIRTCAUDIOSAMPLE
    uint8_t  dummy;      // Reserved, fill with 0
    uint32_t ts;         // Host-side timestamp in milliseconds
    uint32_t length;     // Payload byte length, excluding the header itself
} TIRTCFRAMEINFO;

Video keyframe macros:

#define TIRTC_FRAME_FLAG_KEY_FRAME  0x01
#define TIRTC_IS_KEY_FRAME(flags)   ((flags) & TIRTC_FRAME_FLAG_KEY_FRAME)

Note: The first frame of each video stream must be a keyframe. Otherwise, frames are dropped until a keyframe arrives.

TIRTCSYSEVENT

Internal SDK events reported through TIRTCCALLBACKS.on_event.

Enum Value	Description
`TiEVENT_SYS_STARTED`	The SDK has started successfully
`TiEVENT_SYS_STOPPED`	The SDK has stopped
`TiEVENT_ACCESS_HIJACKING`	The HTTP request was redirected, which may indicate a man-in-the-middle attack

TIRTCCALLBACKS

The SDK callback set passed to TiRtcStart(). It must not point to a temporary variable.

typedef struct TIRTCCALLBACKS {
    void (*on_event)(int event, const void *data, int len);
    void (*on_conn_accepted)(tirtc_conn_t hconn);
    void (*on_conn_error)(tirtc_conn_t hconn, int error);
    void (*on_disconnected)(tirtc_conn_t hconn);
    void (*on_audio)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_video)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_message)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_data)(tirtc_conn_t hconn, uint32_t cmd, const void *data, uint32_t len);
    void (*on_request_iframe)(tirtc_conn_t hconn, uint8_t stream_id);
    int  (*on_request_video)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_release_video)(tirtc_conn_t hconn, uint8_t stream_id);
    int  (*on_request_audio)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_release_audio)(tirtc_conn_t hconn, uint8_t stream_id);
} TIRTCCALLBACKS;

Callback	Trigger	Description
`on_event`	System event	`event` values come from `TIRTCSYSEVENT`
`on_conn_accepted`	The device receives a new inbound connection	`hconn` is the new connection handle
`on_conn_error`	A connection hits an error	Later send operations on that connection return `TIRTC_E_CONN_HAS_ERROR`
`on_disconnected`	The connection is fully closed	`hconn` is invalid after this callback; the SDK releases it automatically. You may still call `TiRtcConnGetUserData` inside this callback
`on_audio`	A remote audio frame arrives
`on_video`	A remote video frame arrives
`on_message`	A remote in-stream message arrives (`media == 0`)
`on_data`	Data arrives on the remote command channel	The command word format of `cmd` is described in Command Channel
`on_request_iframe`	The remote side requests an immediate keyframe
`on_request_video`	The remote side requests video start	Return 0 to accept
`on_release_video`	The remote side requests video stop
`on_request_audio`	The remote side requests audio start	Return 0 to accept
`on_release_audio`	The remote side requests audio stop

TIRTCCONNECTCALLBACK

typedef void (*TIRTCCONNECTCALLBACK)(int error, tirtc_conn_t hconn, void *user_data);

Result callback of TiRtcConnect(). user_data is the context pointer passed at call time. When error is 0, hconn is valid.

TIRTCLOGCALLBACK

typedef void (*TIRTCLOGCALLBACK)(const char *log, uint32_t length);

Logging callback configured by TiRtcLogSetCallback(). After it is set, the SDK stops writing logs to stdout or files on its own.

Lifecycle

TiRtcGetVersion

const char *TiRtcGetVersion(void);

Returns the SDK version string.

TiRtcInit

int TiRtcInit(void);

Initializes the SDK runtime. It must be called before TiRtcStart(). TIRTC_OPT_MAX_SEND_BUFFER takes effect only if it is set before this function.

TiRtcUninit

void TiRtcUninit(void);

Releases SDK runtime resources.

TiRtcSetOpt

int TiRtcSetOpt(TIRTCOPTION opt, const void *data, uint32_t len);

Sets a global configuration item. The valid call timing depends on the specific option. See TIRTCOPTION.

Returns: 0 on success. TIRTC_E_INVALID_PARAMETER means opt or data is invalid.

TiRtcStart

int TiRtcStart(const char *license, const TIRTCCALLBACKS *cbs);

Starts the SDK.

license: device-side license in the format "<uuid>,<key>". Passing NULL starts client-only mode, equivalent to TiRtcStartClientOnly(cbs)
cbs: pointer to the callback struct. It must not point to a temporary variable

Returns: 0 only means the parameters passed the first-level check. The real startup result is reported through on_event(TiEVENT_SYS_STARTED, ...).

// Convenience macro for client-only usage
#define TiRtcStartClientOnly(cbs)  TiRtcStart(NULL, cbs)

TiRtcStop

int TiRtcStop(void);

Stops the SDK. Completion is reported through on_event(TiEVENT_SYS_STOPPED, ...).

Connection Management

TiRtcConnect

int TiRtcConnect(const char *peer_id,
                 const char *token,
                 TIRTCCONNECTCALLBACK cb,
                 void *user_data);

Starts a P2P connection.

peer_id: the public identifier of the target device
token: connection credential issued by your backend service. The SDK uses it transparently and does not parse the content
cb: connection result callback. It must not be NULL
user_data: user context passed through to the callback

Returns: 0 means the request was submitted successfully. The final result is reported by cb.

TiRtcDisconnect

int TiRtcDisconnect(tirtc_conn_t hconn);

Disconnects actively. After the disconnect completes, on_disconnected is fired. The SDK then releases hconn automatically, so the caller does not free it manually.

TiRtcConnSetUserData

int TiRtcConnSetUserData(tirtc_conn_t hconn, void *user_data);

Associates a user data pointer with the connection. Retrieve it later through TiRtcConnGetUserData().

Returns: 0 on success. TIRTC_E_INVALID_HANDLE means hconn is invalid.

TiRtcConnGetUserData

void *TiRtcConnGetUserData(tirtc_conn_t hconn);

Returns the user data pointer previously set through TiRtcConnSetUserData(). If hconn is invalid, it returns NULL.

TiRtcGetSendBufferUsed

size_t TiRtcGetSendBufferUsed(tirtc_conn_t hconn);

Returns the number of bytes currently used in the send buffer for the connection. Compare it with the limit configured through TIRTC_OPT_MAX_SEND_BUFFER to decide whether to drop frames or apply rate limiting. Returns 0 if hconn is invalid.

Media Sending

TiRtcSendMedia

int TiRtcSendMedia(tirtc_conn_t hconn,
                   const TIRTCFRAMEINFO *pFi,
                   const void *frame);

Sends a media frame. It is thread-safe and supports concurrent multi-threaded calls.

Transport strategy:

Video: The first frame of each video stream must be a keyframe (TIRTC_FRAME_FLAG_KEY_FRAME). When the buffer is full, the SDK enters frame-drop mode and drops later non-keyframes until the next keyframe arrives
Audio: Frames are queued directly and do not use the frame-drop strategy
The send path chooses the transport strategy only from pFi->media. It does not validate the payload content
stream_id must be globally unique within the same connection. Audio and video cannot use the same stream_id
You may send frames with media == TIRTC_MEDIA_MESSAGE on any stream. The remaining header fields are interpreted by the application itself

Returns:

Return Value	Meaning
0	Queued successfully
`TIRTC_E_INVALID_HANDLE`	`hconn` is invalid
`TIRTC_E_INVALID_PARAMETER`	`pFi` is `NULL` or the media type is invalid
`TIRTC_E_CONN_HAS_ERROR`	The connection has already entered an error state
`TIRTC_E_BUSY`	The send buffer is full and the video frame was dropped

TciRtcSendVideo

inline int TciRtcSendVideo(tirtc_conn_t hconn,
                            const TIRTCFRAMEINFO *pFi,
                            const void *frame);

Video-type validation wrapper around TiRtcSendMedia. If pFi->media is not a video type, it returns TIRTC_E_INVALID_PARAMETER directly.

TciRtcSendAudio

inline int TciRtcSendAudio(tirtc_conn_t hconn,
                            const TIRTCFRAMEINFO *pFi,
                            const void *frame);

Audio-type validation wrapper around TiRtcSendMedia. If pFi->media is not an audio type, it returns TIRTC_E_INVALID_PARAMETER directly.

Command Channel

The SDK provides bidirectional data transport over a dedicated P2P command channel. It supports asynchronous requests and out-of-order responses.

Command Word Format

bit[31:16]  Command sequence number (SN), used to match requests and responses
bit[15]     Request/response flag: 0 = request, 1 = response
bit[14:0]   Command ID (cmd_id). Values below 0x1000 are reserved for internal SDK use

TiRtcSendCommand

int TiRtcSendCommand(tirtc_conn_t hconn,
                     uint32_t cmd,
                     const void *data,
                     uint32_t length);

Sends data on the command channel. cmd_id (the lower 15 bits) must be at least 0x1000, otherwise the function returns TIRTC_E_INVALID_PARAMETER.

TiRtcSendReq / TiRtcSendResp

// Send request (clear bit15)
#define TiRtcSendReq(hconn, cmd, data, length) \
    TiRtcSendCommand(hconn, (cmd) & ~0x00008000, data, length)

// Send response (set bit15)
#define TiRtcSendResp(hconn, cmd, data, length) \
    TiRtcSendCommand(hconn, (cmd) | 0x00008000, data, length)

When the sender receives a response, the response command word uses the same sequence number and cmd_id as the request, with bit15 set to 1.

atomic_get_cmd_sn

uint32_t atomic_get_cmd_sn(void);

Atomically returns the next command sequence number and increments it. The value wraps in 16 bits. SDK internal commands and application commands share the same counter.

Correct send flow:

Call atomic_get_cmd_sn() to get the sequence number
Register the handler with that sequence number in the pending queue
Send the command

You must register the pending handler before sending. Otherwise, the response may arrive before the handler is installed.

TiRtcRequestIFrame

int TiRtcRequestIFrame(tirtc_conn_t hconn, uint8_t stream_id);

Requests the remote side to output an immediate keyframe on the specified stream. This triggers on_request_iframe() on the remote side.

TiRtcRequestVideo / TiRtcReleaseVideo

int TiRtcRequestVideo(tirtc_conn_t hconn, uint8_t stream_id);
int TiRtcReleaseVideo(tirtc_conn_t hconn, uint8_t stream_id);

Requests the remote side to start or stop sending the specified video stream. They trigger on_request_video() and on_release_video() on the remote side respectively.

TiRtcRequestAudio / TiRtcReleaseAudio

int TiRtcRequestAudio(tirtc_conn_t hconn, uint8_t stream_id);
int TiRtcReleaseAudio(tirtc_conn_t hconn, uint8_t stream_id);

Requests the remote side to start or stop sending the specified audio stream. They trigger on_request_audio() and on_release_audio() on the remote side respectively.

Logging

TiRtcLogConfig

void TiRtcLogConfig(int bOutputToConsole, const char *path, uint32_t size);

Configures the built-in SDK logging. Linux only.

bOutputToConsole: when non-zero, logs are also written to stdout
path: log file path. Putting it on tmpfs is recommended. Pass NULL to disable file output
size: maximum log file size in bytes. The file is rotated and overwritten after the limit is exceeded

TiRtcLogSetLevel

void TiRtcLogSetLevel(int level);

Sets the log verbosity. When level > 10, the underlying WebRTC library log level is also set to level - 10.

TiRtcLogSetCallback

void TiRtcLogSetCallback(TIRTCLOGCALLBACK cb);

Sets the log output callback. After it is set, the SDK sends all log content through the callback and stops writing logs on its own. Pass NULL to clear the callback. This is typically used in systems without a filesystem.

TiRTC Nano SDK API Reference ​

Contents ​

Error Codes ​

Types ​

tirtc_conn_t ​

TIRTCOPTION ​

TIRTCMEDIA ​

TIRTCAUDIOSAMPLE ​

TIRTCFRAMEINFO ​

TIRTCSYSEVENT ​

TIRTCCALLBACKS ​

TIRTCCONNECTCALLBACK ​

TIRTCLOGCALLBACK ​

Lifecycle ​

TiRtcGetVersion ​

TiRtcInit ​

TiRtcUninit ​

TiRtcSetOpt ​

TiRtcStart ​

TiRtcStop ​

Connection Management ​

TiRtcConnect ​

TiRtcDisconnect ​

TiRtcConnSetUserData ​

TiRtcConnGetUserData ​

TiRtcGetSendBufferUsed ​

Media Sending ​

TiRtcSendMedia ​

TciRtcSendVideo ​

TciRtcSendAudio ​

Command Channel ​

Command Word Format ​

TiRtcSendCommand ​

TiRtcSendReq / TiRtcSendResp ​

atomic_get_cmd_sn ​

TiRtcRequestIFrame ​

TiRtcRequestVideo / TiRtcReleaseVideo ​

TiRtcRequestAudio / TiRtcReleaseAudio ​

Logging ​

TiRtcLogConfig ​

TiRtcLogSetLevel ​

TiRtcLogSetCallback ​