Horus 客户端侧 SDK 开发者文档

1. 交付内容

• talite_xrstream.h：Context、连接、回调、H.265 裸流、音频、遥测、业务控制与链路统计接口（当前版本 1.0.0 build 5，见 TALITE_VERSION_* 宏）。
• libtalite_xrstream.so（仅 arm64-v8a）：SDK 主体，随 xrstreamerlib.aar 交付。
• libvr_quic.so（仅 arm64-v8a，预编译）：QUIC 传输层。libtalite_xrstream.so 对它有动态链接依赖并在连接时按名加载，必须与其放在同一目录（AAR 已一并打包）。
• PKI 证书（s100_ca.pem / vr_cert.pem / vr_key.pem）：位于 AAR 的 assets/pki/。App 启动时经 PkiInstaller.extractPki(context) 释放到沙箱，再通过 talite_set_pki_dir 注入 SDK（见 3.1）。

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);

talite_create_context 创建 Context 并初始化 SDK 日志；talite_destroy_context 会先停止该 Context 上的连接再释放资源。talite_stop 见 3.3。

// 统一设置 SDK 日志与视频 trace 的输出目录（绝对路径）。
TALITE_API talite_result DC_CALL talite_set_log_dir(
    TALITE_CONTEXT context,
    const char* log_dir
);

// 设置 PKI 证书沙箱目录（绝对路径，目录下应含 s100_ca.pem 等）。
TALITE_API talite_result DC_CALL talite_set_pki_dir(
    TALITE_CONTEXT context,
    const char* pki_dir
);

talite_set_log_dir：log_dir 为 App 可写的绝对目录（Android 建议 getExternalFilesDir(null)），SDK 在其中自行命名三类文件：通用日志 talite_xrstreamer.log（200KB 轮转，含每 5s 一组的 [QUIC][METRICS] 链路 / 音视频统计）、视频帧 trace vr_video_quic_<timestamp>_<seq>.csv（64MB 轮转）以及 libvr_quic.so 内部日志 s100_log-vr_quic_<pid>-<timestamp>.log（10MB 轮转，目录上限 100MB）。必须在 talite_create_context 之后、本进程首次 talite_connect 之前调用：libvr_quic 的日志系统只在首次建链时装配一次，之后再设目录对它不生效。

talite_set_pki_dir：pki_dir 为 App 私有沙箱内的绝对路径（形如 /data/data/<pkg>/files/pki），SDK 据此拼出证书绝对路径写入 QUIC 配置，必须在 talite_connect 之前调用。Android 侧可直接使用 AAR 内的 PkiInstaller.extractPki(context)：它把 assets/pki/ 释放到 filesDir/pki/ 并返回该目录。文件名必须逐字对齐下表，名字不符视同缺失并静默降级。

3.2 设备发现

TALITE_API talite_result DC_CALL talite_discover_devices(void);

// 【Android 专有】设置设备发现使用的 Android Network 句柄，
// net_handle 为 Java 层 android.net.Network#getNetworkHandle() 的返回值；
// 传 0 清除绑定。非 Android 平台为 no-op 并返回 talite_result_success。
TALITE_API talite_result DC_CALL talite_set_discovery_network(uint64_t net_handle);

talite_discover_devices：发起一轮 mDNS 查询（服务类型 _s100-kiosk._tcp.local）。发现是进程级能力，不依赖某个 Context；每次调用先清空上一轮结果，随后每发现一台设备就通过设备列表回调增量上报当前完整列表。外部应用应先完成设备发现，再从列表中选择设备并建立连接。

talite_set_discovery_network（Android 专有）：把后续 talite_discover_devices 打开的每个 mDNS socket 绑定到指定 Android Network（等价于 Network.bindSocket），使多播查询能从 USB 有线直连等非默认路由网络发出，而不是走内核默认路由（通常是 WiFi）。应在 talite_discover_devices 之前调用；接收多播响应所需的 MulticastLock 仍需由 App 层持有。

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_connect 以 QUIC 直连设备：streamer_ip 取设备列表回调中的 device_ip，必须是不带端口和协议前缀的 IPv4 字面量（端口由 SDK 固定为 4433），否则返回 talite_result_invalid_param。调用前须已完成 talite_set_log_dir / talite_set_pki_dir。连接为异步过程，本函数返回 talite_result_success 仅表示拨号已发出：链路建立后遥测状态回调收到 connected，握手完成后开始收到 H.265 裸流；加载 libvr_quic.so 失败或拨号失败会同步返回错误码并触发错误回调。同一进程内只允许一个活跃连接，在另一个 Context 上再次 talite_connect 会先停止之前的连接。

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

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

// 上行控制数据通道：设备姿态、控制指令等二进制消息（QUIC 数据通道，有序可靠）。
TALITE_API talite_result DC_CALL talite_send_control_data(
    TALITE_CONTEXT context,
    const uint8_t* data,
    size_t size
);

向当前已连接设备发送原始字节数组（原 talite_send_data，已改名）。data 指向待发送数据，size 为字节数，SDK 经 QUIC 遥操通道有序可靠地原样透传，不解析内容。data 为空或 size 为 0 返回 talite_result_invalid_param；链路尚未建立时返回 talite_result_transport_not_supported，调用方应在连接成功后再调用。

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 被销毁前有效。

QUIC 链路相关错误的对应关系：libvr_quic.so 加载失败或拨号失败报 talite_result_transport_not_supported；链路断开（空闲超时、服务端关闭、TLS 校验失败等）同样报 talite_result_transport_not_supported，message 为对端 CONNECTION_CLOSE 携带的原因短语（可能为空，此时为 "quic disconnected"）；QUIC 内部故障报 talite_result_internal_error。断线后 SDK 不会自动重连，需由应用层再次调用 talite_connect。

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。

下发时机：QUIC 链路建立时 SDK 会先回调一份内置的默认相机标定，保证上层在设备数据到达前即可完成初始化；之后设备侧若通过会话通道下发 data_json 标定数据，会再次触发回调，应以后到的设备值为准。

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

3.9 音频控制

SDK 提供经 QUIC 承载的双向 Opus 音频通道。下行播放支持暂停 / 恢复与音量控制；上行采集在会话握手完成后由 SDK 自动启动并持续发送，不再提供单独的暂停 / 恢复接口（原 talite_pause_audio_capture / talite_resume_audio_capture 已移除）。如需让机器人侧停止下发音频以节省带宽，请使用 3.12 的 talite_set_expected_audio_mute。

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_get_audio_status：获取音频通道运行状态统计。out 由调用方分配，SDK 填充；返回 talite_result_success 表示成功。
• talite_pause_audio_playback / talite_resume_audio_playback：暂停 / 恢复音频播放（下行）。暂停期间 SDK 仍在接收音频包但不送入扬声器；resume 会预先创建播放设备，避免丢掉恢复后的首帧。
• talite_set_audio_playback_volume：设置播放音量，volume 取值范围 [0.0, 1.0]。

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 遥测相关

遥测不再是独立连接，而是复用主 QUIC 会话通道：设备侧经会话通道下发、且 SDK 内部不消费的 JSON 文本帧（如 heartbeat 回包、operation_info、signal_quality 等）会原样上抛给遥测帧回调，SDK 只搬运字节，消息语义由应用层定义。VR 侧向设备表达录制 / 静音 / 关机等意图改由 3.12 的心跳业务字段接口完成，原 talite_send_telemetry 已移除。

// 连接状态（跟随主 QUIC 会话）
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 仅在回调期间有效；文本帧 payload 不带结尾 NUL。
typedef void (*talite_on_telemetry)(
    talite_telemetry_frame_type frame_type,
    const uint8_t* data,
    size_t size
);

// 连接状态变化回调。url 为 QUIC 对端地址，格式 <ip>:<port>。
typedef void (*talite_on_telemetry_state)(
    talite_telemetry_state state,
    const char* url
);

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

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

方法说明

• talite_set_telemetry_callback：注册入站帧回调。设备侧每下发一条 SDK 内部不消费的 JSON 文本帧就触发一次（当前实现均为 talite_telemetry_frame_text，payload 为 UTF-8 JSON 且不带结尾 NUL，需按 size 截取）。建议在 talite_create_context 之后、talite_connect 之前注册。传 NULL 清除回调。
• talite_set_telemetry_state_callback：注册连接状态变化回调。QUIC 链路建立时收到 connected，断开或主动停止时收到 disconnected；url 为当前 QUIC 对端地址（<ip>:<port>）。connecting 为保留值，当前实现不会触发。

3.12 心跳业务字段控制（录制 / 静音 / 关机）

会话握手完成后，SDK 每 1 秒向设备发送一条心跳 JSON，并在其中携带 VR 侧的期望状态 expected_state（录制、静音）以及一次性的关机请求。下面三个接口只修改 SDK 内部保存的业务字段，不直接发包：字段变更后 SDK 会在 100ms 内插队补发一拍心跳，之后每拍持续携带，直到再次修改。连接建立前即可调用，字段会随握手完成后的第一拍心跳带出。

// 设置期望录制状态。recording=true 时 operator_name / project_name 必须同时非空
//（取自设备经遥测通道推送的 operation_info 列表），缺一返回 talite_result_invalid_param；
// recording=false 时二者可为 NULL。不影响其他业务字段。
TALITE_API talite_result DC_CALL talite_set_expected_recording(
    TALITE_CONTEXT context,
    bool recording,
    const char* operator_name,
    const char* project_name
);

// 设置期望静音状态：通知设备停止 / 恢复下发音频（节省带宽）。
// 与 talite_set_audio_playback_volume(0) 的本地静音不同，后者设备仍在持续发送。
TALITE_API talite_result DC_CALL talite_set_expected_audio_mute(
    TALITE_CONTEXT context,
    bool mute
);

// 请求设备安全关机。随下一拍心跳发送一次后自动清除；不可逆，调用前应由用户确认。
TALITE_API talite_result DC_CALL talite_request_robot_shutdown(
    TALITE_CONTEXT context
);

方法说明

• talite_set_expected_recording：设置期望录制状态。开始录制时必须同时给出操作员与项目名（设备侧缺一则拒绝作业信息并告警），二者随心跳的 expected_state.operator / expected_state.project 字段上报；停止录制时 SDK 会清空已保存的作业信息，避免下次开录误带旧值。
• talite_set_expected_audio_mute：设置期望静音状态，设备据此停止或恢复音频下发。只影响下行音频，不改变本地播放音量与上行采集。
• talite_request_robot_shutdown：置位一次性关机请求，随下一拍心跳以 robot_shutdown: true 发出后自动清除。该操作不可逆，SDK 不做二次确认。

3.13 链路统计查询（视频丢包率 / RTT）

SDK 提供两项链路质量查询：视频下行丢包率与 QUIC 往返时延（RTT），可周期性调用用于评估链路质量、驱动码率调整（见 3.10）或界面提示。原 talite_video_fec_stats / talite_get_video_fec_stats 已分别改名为 talite_video_stats / talite_get_video_stats，字段不变。

// 视频下行丢包率快照（从 context 创建起累计，disconnect / 重连不重置）。
// 丢包由视频帧头部 sequence 的缺口推算，按帧计而非网络包：
//   丢包率 % = missing / (rx_frames + missing) × 100
typedef struct talite_video_stats_ {
    float loss_rate_percent;    // 丢包率（百分比，0~100）
} talite_video_stats;

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

// 查询当前 QUIC 连接的往返时延（微秒）。
TALITE_API talite_result DC_CALL talite_get_rtt_us(
    TALITE_CONTEXT context,
    uint32_t* out_rtt_us
);

方法说明

• talite_get_video_stats：查询视频下行累计丢包率。统计从 Context 创建起累计，talite_disconnect 与重连均不重置；尚未收到任何视频帧时返回 talite_result_transport_not_supported。
• talite_get_rtt_us：查询当前 QUIC 连接由传输层测得的往返时延，单位微秒，写入 out_rtt_us。未连接或传输层尚无有效样本（返回值为 0）时返回 talite_result_transport_not_supported。

4. 调用顺序

1. 调用 talite_create_context 创建 Context。
2. 调用 talite_set_log_dir 设置日志目录，调用 talite_set_pki_dir 注入证书目录（Android 先用 PkiInstaller.extractPki(context) 把证书释放到沙箱并取得该目录）。二者都必须在首次 talite_connect 之前完成。
3. 调用 talite_set_h265_stream_callback 注册 H.265 裸流回调。
4. 调用 talite_set_error_callback 注册错误回调。
5. 调用 talite_set_device_list_callback 注册设备列表回调。
6. 调用 talite_set_data_callback 注册统一数据回调，以接收相机内外参等结构化设备数据。
7. 按需调用 talite_set_telemetry_callback / talite_set_telemetry_state_callback 注册遥测回调，用于接收设备推送的状态 JSON 和感知链路连接 / 断开。
8. 调用 talite_discover_devices 开始发现设备，并等待设备列表回调（Android 上若需经 USB 有线直连等非默认网络发现，先调用 talite_set_discovery_network 绑定该网络）。
9. 从设备列表中选择目标设备，以其 device_ip 调用 talite_connect 建立 QUIC 连接。链路建立后遥测状态回调收到 connected，握手完成后开始收到 H.265 裸流回调。
10. 连接成功后，可调用 talite_send_control_data 发送原始字节数据；如需音频，调用 talite_resume_audio_playback 启用播放（上行采集自动启动），并通过 talite_set_audio_playback_volume / talite_get_audio_status 调节音量与查询状态；如需监控链路质量，可周期性调用 talite_get_video_stats / talite_get_rtt_us；如需调整视频编码码率，可调用 talite_set_video_bitrate_kbps；录制、静音、关机等意图分别通过 talite_set_expected_recording、talite_set_expected_audio_mute、talite_request_robot_shutdown 随心跳下发。
11. 结束连接时调用 talite_disconnect；不再使用 Context 时再调用 talite_destroy_context。