1. 交付内容

• talite_xrstream.h：Context、连接、回调、H.265 裸流和数据通信接口。
• talite_xrstream.so（目前仅支持arm-v8）

2. 公共类型

typedef void* TALITE_CONTEXT;

typedef enum talite_result_ {
    talite_result_success                 = 0,
    talite_result_invalid_param           = 1,
    talite_result_not_initialized         = 2,
    talite_result_not_connected           = 3,
    talite_result_transport_not_supported = 4,
    talite_result_already_active          = 5,
    talite_result_out_of_memory           = 6,
    talite_result_internal_error          = 7
} talite_result;

typedef struct talite_h265_stream_params_ {
    const uint8_t* data;
    size_t size;
    uint64_t timestamp_us;
    bool key_frame;
} talite_h265_stream_params;

typedef void (*talite_on_h265_stream)(
    const talite_h265_stream_params* params
);

回调参数中的 H.265 Annex-B 裸流数据仅在本次回调期间有效。如需异步处理，应由调用方复制参数结构体及其数据内容。

3. 对外方法

3.1 初始化与生命周期

TALITE_API TALITE_CONTEXT DC_CALL talite_create_context(void);
TALITE_API talite_result DC_CALL talite_stop(TALITE_CONTEXT context);
TALITE_API talite_result DC_CALL talite_destroy_context(TALITE_CONTEXT context);

3.2 设备发现

TALITE_API talite_result DC_CALL talite_discover_devices(void);

调用该方法开始发现设备。发现结果通过设备列表回调返回；外部应用应先完成设备发现，再从列表中选择设备并建立连接。

3.3 连接控制

TALITE_API talite_result DC_CALL talite_connect(
    TALITE_CONTEXT context,
    const char* streamer_ip
);

TALITE_API talite_result DC_CALL talite_disconnect(
    TALITE_CONTEXT context
);

talite_disconnect 主动断开当前设备连接并释放信令、音视频以及数据通道资源，但保留 Context 和已注册回调；断开后可再次调用 talite_connect 连接设备。talite_stop 继续保留为兼容接口，行为等同于 talite_disconnect。

3.4 数据发送（开发者自定义的控制面数据，全程透传）

TALITE_API talite_result DC_CALL talite_send_data(
    TALITE_CONTEXT context,
    const uint8_t* data,
    size_t size
);

向当前已连接设备发送原始字节数组。data 指向待发送数据，size 为字节数；调用方应在设备连接成功后调用该方法。

3.5 H.265 裸流回调

TALITE_API talite_result DC_CALL talite_set_h265_stream_callback(
    TALITE_CONTEXT context,
    talite_on_h265_stream callback
);

SDK 收到视频数据后，通过该回调向上层交付 H.265 Annex-B 裸流。SDK 不负责外部应用的解码与渲染。

3.6 错误回调

typedef void (*talite_on_error)(
    TALITE_CONTEXT context,
    talite_result result,
    const char* message
);

TALITE_API talite_result DC_CALL talite_set_error_callback(
    TALITE_CONTEXT context,
    talite_on_error callback
);

TALITE_API const char* DC_CALL talite_get_last_error_string(TALITE_CONTEXT context);

参数说明
• context：发生错误的上下文句柄，与 talite_create_context 返回值一致。
• result：错误码，取值见「2. 公共类型」。
• message：可读的错误描述；若无可读信息则为空字符串。

talite_get_last_error_string 用于获取当前 context 最近一次错误的描述字符串；在错误回调外部也可调用。返回的指针在 context 被销毁前有效。

3.7 设备列表回调

typedef struct talite_device_info_ {
    const char* device_id;
    const char* device_name;
    const char* device_ip;
} talite_device_info;

typedef struct talite_device_list_ {
    const talite_device_info* devices;
    size_t device_count;
} talite_device_list;

typedef void (*talite_on_device_list)(
    const talite_device_list* device_list
);

TALITE_API talite_result DC_CALL talite_set_device_list_callback(
    TALITE_CONTEXT context,
    talite_on_device_list callback
);

3.8 数据回调（相机内外参）

typedef enum talite_data_type_ {
    talite_data_type_camera_calibration = 1
} talite_data_type;

typedef struct talite_float_array_ {
    const float* data;
    size_t size;
} talite_float_array;

typedef struct talite_int32_array_ {
    const int32_t* data;
    size_t size;
} talite_int32_array;

typedef struct talite_camera_calibration_ {
    talite_float_array r_raw_l_row;
    talite_float_array r_raw_r_row;
    talite_float_array k_l;
    talite_float_array k_r;
    talite_float_array d_l;
    talite_float_array d_r;
    talite_int32_array image_size;
    talite_float_array yaw_deg;
    talite_float_array pitch_deg;
} talite_camera_calibration;

typedef union talite_data_value_ {
    talite_camera_calibration camera_calibration;
} talite_data_value;

typedef struct talite_data_ {
    talite_data_type type;
    talite_data_value value;
} talite_data;

typedef void (*talite_on_data)(const talite_data* data);

TALITE_API talite_result DC_CALL talite_set_data_callback(
    TALITE_CONTEXT context,
    talite_on_data on_data
);

void on_data(const talite_data* data)
{
    if (data == NULL) {
        return;
    }

    switch (data->type) {
    case talite_data_type_camera_calibration: {
        const talite_camera_calibration* calibration =
            &data->value.camera_calibration;
        break;
    }
    default:
        break;
    }
}

生命周期说明：回调参数 talite_data 及其中的相机参数数组指针仅在本次回调期间有效。回调返回后 SDK 会释放临时解析结果；如需异步使用，调用方必须复制结构体及数组内容。调用方根据 data->type 读取 data->value 中对应的联合体成员；当前仅支持 camera_calibration。

设备列表及其中的字符串指针仅在本次回调期间有效。如需异步处理，应由调用方复制。

3.9 音频控制

SDK 提供双向 Opus 音频通道，支持音频播放（下行）与采集（上行）的独立控制，以及运行状态查询

typedef struct talite_audio_status_ {
    int transport_supported;
    int channel_supported;
    int receiving_audio;
    int pushing_audio;
    int playback_created;
    int playback_paused;
    int capture_created;
    int capture_paused;
    int capture_start_allowed;
    uint64_t rx_pkts;
    uint64_t rx_bytes;
    uint64_t tx_pkts;
    uint64_t tx_bytes;
    uint64_t last_rx_timestamp_ms;
    uint64_t last_tx_timestamp_ms;
    uint64_t rx_age_ms;
    uint64_t tx_age_ms;
    uint64_t capture_callback_calls;
    uint64_t capture_callback_frames;
    uint64_t capture_callback_samples;
    uint64_t capture_callback_bytes;
    uint64_t capture_callback_nonzero_samples;
    uint64_t capture_encode_skipped_callbacks;
    uint64_t capture_encoded_pkts;
    uint64_t capture_encoded_bytes;
    uint64_t capture_send_skipped;
    uint64_t capture_last_callback_timestamp_ms;
    uint64_t capture_last_nonzero_timestamp_ms;
    uint64_t capture_last_encoded_timestamp_ms;
    uint64_t capture_last_send_skipped_timestamp_ms;
    uint64_t capture_callback_age_ms;
    uint64_t capture_nonzero_age_ms;
    uint64_t capture_encoded_age_ms;
    float playback_volume;
    int playback_muted_by_volume;
} talite_audio_status;

TALITE_API talite_result DC_CALL talite_get_audio_status(
    TALITE_CONTEXT context,
    talite_audio_status* out
);

TALITE_API void DC_CALL talite_pause_audio_playback(TALITE_CONTEXT context);
TALITE_API void DC_CALL talite_resume_audio_playback(TALITE_CONTEXT context);
TALITE_API talite_result DC_CALL talite_set_audio_playback_volume(
    TALITE_CONTEXT context,
    float volume
);
TALITE_API void DC_CALL talite_pause_audio_capture(TALITE_CONTEXT context);
TALITE_API void DC_CALL talite_resume_audio_capture(TALITE_CONTEXT context);

方法说明

• talite_get_audio_status：获取音频通道运行状态统计。out 由调用方分配，SDK 填充；返回 talite_result_success 表示成功。
• talite_pause_audio_playback / talite_resume_audio_playback：暂停 / 恢复音频播放（下行）。resume 时会按需建立音频传输。
• talite_set_audio_playback_volume：设置播放音量，volume 取值范围 [0.0, 1.0]。
• talite_pause_audio_capture / talite_resume_audio_capture：暂停 / 恢复音频采集（上行）。resume 时会按需建立音频传输并启动采集。

3.10 视频编码码率控制

SDK 提供视频编码码率动态调整能力。连接前调用时，码率随握手 viewconfig 生效；连接中调用时，会立即重发 viewconfig 通知服务端编码器改码率。

// 视频编码码率钳制范围（单位 kbps）。0 表示恢复 SDK 默认码率。
#define TALITE_VIDEO_BITRATE_DEFAULT_KBPS   8000
#define TALITE_VIDEO_BITRATE_MIN_KBPS       2000
#define TALITE_VIDEO_BITRATE_MAX_KBPS       200000

// 设置视频编码码率（单位 kbps，超出范围时自动钳制，传 0 恢复默认值）。
// 返回值为实际生效的码率（写入 out_applied_kbps，可为 NULL）。
TALITE_API talite_result DC_CALL talite_set_video_bitrate_kbps(
    TALITE_CONTEXT context,
    uint32_t bitrate_kbps,
    uint32_t* out_applied_kbps
);

方法说明

• talite_set_video_bitrate_kbps：设置视频编码码率。码率超出 [2000, 200000] 范围时自动钳制；传 0 恢复 SDK 默认码率 8000 kbps。连接前调用时码率随握手生效；连接中调用时立即通知服务端编码器改码率。out_applied_kbps 可为 NULL，成功时返回 talite_result_success。

3.11 遥测相关

SDK 提供一条独立于主流媒体通道的遥测数据通道，用于应用自定义的双向数据收发。SDK 只负责搬运原始字节，消息语义（JSON、二进制协议等）由应用层定义。

// 连接状态
typedef enum talite_telemetry_state_ {
    talite_telemetry_state_disconnected = 0,
    talite_telemetry_state_connecting   = 1,
    talite_telemetry_state_connected    = 2
} talite_telemetry_state;

// 帧类型（区分文本帧 / 二进制帧）
typedef enum talite_telemetry_frame_type_ {
    talite_telemetry_frame_binary = 0,
    talite_telemetry_frame_text   = 1
} talite_telemetry_frame_type;

// 入站帧回调。data 在回调期间有效，回调返回后可能被释放。
typedef void (*talite_on_telemetry)(
    talite_telemetry_frame_type frame_type,
    const uint8_t* data,
    size_t size
);

// 连接状态变化回调。
typedef void (*talite_on_telemetry_state)(
    talite_telemetry_state state,
    const char* url
);

// 注册入站帧回调。传 nullptr 清除。
TALITE_API talite_result DC_CALL talite_set_telemetry_callback(
    TALITE_CONTEXT context,
    talite_on_telemetry callback
);

// 注册连接状态回调。传 nullptr 清除。
TALITE_API talite_result DC_CALL talite_set_telemetry_state_callback(
    TALITE_CONTEXT context,
    talite_on_telemetry_state callback
);

// 发送原始字节。未连接时返回 talite_result_not_connected。
TALITE_API talite_result DC_CALL talite_send_telemetry(
    TALITE_CONTEXT context,
    talite_telemetry_frame_type frame_type,
    const uint8_t* data,
    size_t size
);

方法说明

• talite_set_telemetry_callback：注册入站帧回调。每收到一帧（文本或二进制）都会触发一次回调。建议在 talite_create_context 之后、talite_connect 之前注册。传 nullptr 清除回调。
• talite_set_telemetry_state_callback：注册连接状态变化回调。状态切换（disconnected → connecting → connected，或反向）时触发，url 为当前连接的通道地址。
• talite_send_telemetry：通过遥测通道发送原始字节。frame_type 指示数据为文本或二进制；data 会被拷贝，调用返回后可立即释放。未连接时返回 talite_result_not_connected。

3.12 FEC 统计查询

视频下行启用 Talite RS-FEC 后，SDK 提供丢包率查询接口，返回自本次 stream 启动以来的累计丢包率，用于评估下行链路质量与 FEC 生效情况。

// 视频下行 FEC 统计快照（自本次 stream 启动累计）。
typedef struct talite_video_fec_stats_ {
    float loss_rate_percent;    // 丢包率（百分比，0~100）
} talite_video_fec_stats;

// 查询当前视频下行 FEC 丢包率。
TALITE_API talite_result DC_CALL talite_get_video_fec_stats(
    TALITE_CONTEXT context,
    talite_video_fec_stats* out
);

方法说明

• talite_get_video_fec_stats：查询视频下行自本次 stream 启动以来的累计丢包率

4. 调用顺序

1. 调用 talite_create_context 创建 Context。
2. 调用 talite_set_h265_stream_callback 注册 H.265 裸流回调。
3. 调用 talite_set_error_callback 注册错误回调。
4. 调用 talite_set_device_list_callback 注册设备列表回调。
5. 调用 talite_set_data_callback 注册统一数据回调，以接收相机内外参等结构化设备数据。
6. 调用 talite_discover_devices 开始发现设备，并等待设备列表回调。
7. 从设备列表中选择目标设备，调用 talite_connect 建立连接。
8. 连接成功后，可调用 talite_send_data 发送原始字节数据；如需音频，调用 talite_resume_audio_playback / talite_resume_audio_capture 启用音频通道，并通过 talite_get_audio_status 查询运行状态；如需监控下行链路质量，可周期性调用 talite_get_video_fec_stats 查询视频 FEC 丢包率；如需调整视频编码码率，可调用 talite_set_video_bitrate_kbps 设置目标码率。
9. 结束连接时调用 talite_disconnect；不再使用 Context 时再调用 talite_destroy_context。