TiRTC 开发文档

中文

English

中文

English

HarmonyOS API 参考 ​

本页描述 HarmonyOS 原生 SDK tirtc-av 当前公开的 ArkTS API，适用于用 OpenHarmony / HarmonyOS NEXT 原生应用接入 TiRTC 的开发者。

如果你还没有完成 SDK 接入或连接准备，先看集成到客户端。页面里提到的 AppId、remote_id、token、stream_id 等术语，以名词解释为准。

对象总览 ​

对象作用清理方式
TiRtcInitOptions组织 SDK 初始化参数无需显式清理
TiRtc初始化和关闭共享 runtime，格式化错误码TiRtc.shutdown()
TiRtcConn建连、断连、收发命令、收发流消息、订阅媒体、请求关键帧dispose()
TiRtcAudioOutput播放一条远端音频流，读取指标和排查快照dispose()
TiRtcVideoOutput播放一条远端视频流，并配合 TiRtcVideoOutputView 渲染dispose()
TiRtcAudioInput采集本地麦克风，并在对讲等场景发布到当前连接dispose()
TiRtcVideoInput采集本地相机、提供预览，并在上行场景发布到当前连接dispose()
TiRtcLogging写 SDK 日志、上传日志无

TiRtcInitOptions ​

TiRtc.initialize(...) 的参数对象。

字段说明
contextcommon.UIAbilityContext，SDK 初始化所需的 Ability 上下文。必填。
appId你的 AppId。必填。
endpoint自定义服务入口。留空时使用 runtime 默认入口。
consoleLogEnabled是否把 SDK 日志镜像到控制台。默认值为 false。

TiRtc ​

典型调用顺序是：initialize() -> 创建连接、输入、输出等 runtime 对象 -> 业务结束后释放这些对象 -> shutdown()。

API说明
initialize(options: TiRtcInitOptions): Promise<number>初始化共享 TiRTC runtime。成功返回 0。重复初始化是幂等的，已初始化时返回 0，不会替换当前配置。
shutdown(): number关闭共享 runtime。调用前应释放所有连接、输入和输出对象；已经关闭时再次调用也返回 0。
isInitialized(): boolean返回当前进程是否已经初始化共享 runtime。
errorToString(code: number): string把错误码转成稳定错误标识字符串。
formatError(code: number): string把错误码格式化成可展示或可写日志的字符串。

TiRtcConn ​

TiRtcConn 是到远端设备或客户端的下行连接。先完成 connect()，再收发命令、流消息、订阅媒体或绑定输出。

状态 ​

状态含义
TiRtcConnState.idle连接对象已存在，但还没有开始建连
TiRtcConnState.connecting建连请求已提交
TiRtcConnState.connected连接已经建立
TiRtcConnState.disconnected连接已经断开；对象仍需要 dispose()

属性和回调 ​

成员说明
state当前连接状态
onStateChanged连接状态变化回调，签名为 (state: TiRtcConnState, errorCode: number) => void
onCommand收到命令通道消息时回调，签名为 (command: number, payload: Uint8Array) => void
onStreamMessage收到流消息时回调，签名为 (streamId: number, timestampMs: number, payload: Uint8Array) => void

方法 ​

API说明
connect(options: TiRtcConnConnectOptions): number发起到目标 remote_id 的连接。options.remoteId 和 options.token 分别传目标和连接凭证。
disconnect(): number断开当前连接；已经断开时调用也返回 0。
dispose(): void永久释放连接对象和本地流占用记录。
sendCommand(options: TiRtcConnCommandOptions): number在命令通道发送业务自定义命令。HarmonyOS 参数名是 commandId。
sendStreamMessage(options: TiRtcConnStreamMessageOptions): number发送带 streamId 和 timestampMs 的流消息。
subscribeAudio(options: TiRtcStreamControlOptions): number订阅远端音频包，但不自动创建本地播放。
unsubscribeAudio(options: TiRtcStreamControlOptions): number取消音频订阅；已绑定音频输出时需要先 detach。
subscribeVideo(options: TiRtcStreamControlOptions): number订阅远端视频包，但不自动创建本地播放。
unsubscribeVideo(options: TiRtcStreamControlOptions): number取消视频订阅；已绑定视频输出时需要先 detach。
requestKeyFrame(options: TiRtcStreamControlOptions): number向指定远端视频流请求关键帧。
getMetricsSnapshot(): TiRtcConnMetricsResult获取尽力而为的连接指标快照。

远端音视频输出 ​

同一条连接里，一个 streamId 不能同时被音频输出、视频输出或手动订阅重复占用。

远端播放不需要相机或麦克风权限。

TiRtcAudioOutput ​

API说明
configure(options: TiRtcAudioOutputOptions): number配置音频播放参数。应在 attach() 前调用，已绑定时会被拒绝。
attach(options: TiRtcOutputAttachOptions): number绑定一条远端音频流。
detach(): number解除当前音频绑定；未绑定时调用也返回 0。
dispose(): void释放音频输出对象，并释放仍然占用的流绑定。
getMetricsSnapshot(): TiRtcAudioOutputMetricsResult获取音频输出指标快照。
getDebugSnapshot(): TiRtcAudioOutputDebugSnapshotResult获取音频编码、采样率、声道数等排查信息。

常用状态是 TiRtcAudioOutputState.idle、buffering、playing、failed。

TiRtcVideoOutput ​

API说明
setOptions(options: TiRtcVideoOutputOptions): number设置视频解码偏好和缓冲策略。应在 attach() 前调用。
attach(options: TiRtcOutputAttachOptions): number绑定一条远端视频流。
detach(): number解除当前视频绑定；未绑定时调用也返回 0。
dispose(): void释放视频输出对象、流绑定和渲染状态。
getMetricsSnapshot(): TiRtcVideoOutputMetricsResult获取视频输出指标快照。
getDebugSnapshot(): TiRtcVideoOutputDebugSnapshotResult获取视频编码、分辨率、解码器等排查信息。

常用状态是 TiRtcVideoOutputState.idle、buffering、rendering、failed。

视频渲染使用 SDK 提供的 ArkUI 组件：

ts
import { TiRtcVideoFit, TiRtcVideoOutput, TiRtcVideoOutputView } from 'tirtc-av/Index';

@Builder
function RemoteVideo(output: TiRtcVideoOutput) {
  TiRtcVideoOutputView({
    output,
    fit: TiRtcVideoFit.contain,
    width: '100%',
    height: '100%',
  });
}

本地音视频上行 ​

本地输入用于客户端把麦克风或相机采集发布到已建立的连接，常见于对讲、语音回复或需要客户端回传画面的场景。

TiRtcAudioInput ​

start() 会检查 ohos.permission.MICROPHONE。应用需要先完成系统权限申请；权限缺失时 SDK 返回平台权限错误，不会主动弹出权限申请框。

API说明
setOptions(options: TiRtcAudioInputOptions): Promise<number>设置本地音频输入参数。运行中或已绑定连接时会被拒绝。
start(): Promise<number>开始麦克风采集。
attach(options: TiRtcInputAttachOptions): Promise<number>把本地音频发布到指定连接和 streamId。
detach(options: TiRtcInputDetachOptions): Promise<number>移除某条连接上的发布绑定。
stop(): Promise<number>停止采集；已经停止时调用也返回 0。
dispose(): Promise<void>释放输入对象并清理连接绑定。

音频输入默认使用 g711a、16 kHz、单声道。立体声不能和 AEC、AGC、ANS 同时开启。

TiRtcVideoInput ​

start() 会检查 ohos.permission.CAMERA。应用需要先完成系统权限申请；权限缺失时 SDK 返回平台权限错误，不会主动弹出权限申请框。

API说明
setOptions(options: TiRtcVideoInputOptions): Promise<number>设置本地视频输入参数。运行中或已绑定连接时会被拒绝。
start(): Promise<number>开始相机采集。
attach(options: TiRtcInputAttachOptions): Promise<number>把本地视频发布到指定连接和 streamId。
detach(options: TiRtcInputDetachOptions): Promise<number>移除某条连接上的发布绑定。
stop(): Promise<number>停止采集；已经停止时调用也返回 0。
dispose(): Promise<void>释放输入对象、预览绑定和连接绑定。

本地预览使用 TiRtcVideoInputPreview：

ts
import { TiRtcVideoFit, TiRtcVideoInput, TiRtcVideoInputPreview } from 'tirtc-av/Index';

@Builder
function LocalPreview(input: TiRtcVideoInput) {
  TiRtcVideoInputPreview({
    input,
    fit: TiRtcVideoFit.cover,
    mirror: true,
    width: '100%',
    height: '100%',
  });
}

常用选项和枚举 ​

类型说明
TiRtcVideoDecoderPreferenceauto、software、hardware。用于远端视频输出解码偏好。
TiRtcVideoEncoderPreferenceauto、software、hardware。用于本地视频输入编码偏好。
TiRtcOutputBufferStrategyautomatic 或 noBuffer。用于远端音视频输出缓冲策略。
TiRtcVideoFitcontain 或 cover。用于 SDK 渲染组件缩放策略。
TiRtcAudioCodecg711a、aac。用于本地音频输入。
TiRtcVideoCodech264、h265、mjpeg。用于本地视频输入。
TiRtcCameraFacingfront、back。用于选择本地摄像头。

TiRtcLogging ​

API说明
d(tag: string, message: string): void写一条 debug 日志
i(tag: string, message: string): void写一条 info 日志
w(tag: string, message: string): void写一条 warning 日志
e(tag: string, message: string): void写一条 error 日志
upload(): Promise<TiRtcLoggingUploadResult>上传 SDK 日志。成功时返回 logId。

相关文档 ​

TiRTC 开发文档

Copyright © 2025