HarmonyOS API 说明

HarmonyOS 原生 SDK tirtc 提供客户端 ArkTS API，适用于用 OpenHarmony / HarmonyOS NEXT 原生应用接入 TiRTC。

如果你还没有完成 SDK 接入、工程配置或连接流程准备，先看 HarmonyOS SDK 接入。

生命周期与调用顺序

典型客户端流程是：连接一个设备端，播放设备端音视频，并按需收发命令或发起语音对讲。主干从 TiRtc.initialize(...) 开始，以 disconnect() 和 dispose() 收尾。

初始化：传入 AppId，启动 SDK 运行时。
ts
```
await TiRtc.initialize({ context, appId });
```

创建连接：创建 TiRtcConn，并在连接前设置状态、命令和流消息回调。

const conn = new TiRtcConn();
conn.onStateChanged = handleConnStateChanged;
conn.onCommand = handleCommand;
conn.onStreamMessage = handleStreamMessage;

准备播放：在发起连接前创建音频输出和视频输出，并指定要播放的 streamId。

const audioOutput = new TiRtcAudioOutput();
audioOutput.attach({ connection: conn, streamId: audioStreamId });

const videoOutput = new TiRtcVideoOutput();
videoOutput.attach({ connection: conn, streamId: videoStreamId });

渲染视频：在 ArkUI 中挂载 TiRtcVideoOutputView，让视频输出有对应的显示位置。

@Builder
function RemoteVideoView() {
  TiRtcVideoOutputView({
    output: videoOutput,
    width: '100%',
    height: '100%',
  });
}

发起连接：传入目标设备的 device_id 和业务服务端签发的 token。
ts
```
conn.connect({ remoteId, token });
```

请求媒体：连接进入 connected 后，按需请求设备端发送音频流和视频流。

conn.subscribeAudio({ streamId: audioStreamId }); // 连接成功后订阅音频
conn.subscribeVideo({ streamId: videoStreamId }); // 连接成功后订阅视频

命令交互：连接进入 connected 后，按需通过命令通道和设备端交换业务数据。

conn.sendCommand({ commandId, data }); // 需要命令交互时调用
// 收到设备端命令时，在 handleCommand(commandId, payload) 中处理。

语音对讲（按需）：应用获得 ohos.permission.MICROPHONE 权限后，创建音频输入，绑定到同一条连接，并启动采集发送。

const talkbackInput = new TiRtcAudioInput();
await talkbackInput.setOptions(talkbackOptions);
await talkbackInput.attach({ connection: conn, streamId: talkbackStreamId });
await talkbackInput.start();

收尾释放：业务结束时先释放按需创建的输入对象，再按订阅、输出、连接的顺序收尾。

await talkbackInput.stop(); // 创建了 talkbackInput 时调用
await talkbackInput.detach({ connection: conn });
await talkbackInput.dispose();

conn.unsubscribeAudio({ streamId: audioStreamId }); // 停止播放时取消音频订阅
conn.unsubscribeVideo({ streamId: videoStreamId }); // 停止播放时取消视频订阅

audioOutput.detach();
videoOutput.detach();
audioOutput.dispose();
videoOutput.dispose();

conn.disconnect();
conn.dispose();

`TiRtcInitOptions`

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

初始化时必须传 appId，取值为你的 AppId。

interface TiRtcInitOptions {
  context: common.UIAbilityContext; // 必填：Ability 上下文
  appId: string; // 必填：你的 AppId
  endpoint?: string; // 切换自部署云端实例或测试、联调环境时传，例如 "https://ep-tirtc.my-domain.com"；其他情况不传
  consoleLogEnabled?: boolean; // true 时同时把 SDK 日志打印到控制台
}

`TiRtc`

TiRtc 提供初始化、初始化状态查询和错误码名称转换入口。

// 初始化 SDK。返回 0 表示成功，非 0 为错误码。
// 重复调用成功时返回 0，不会替换已生效的配置。
static initialize(options: TiRtcInitOptions): Promise<number>

// 返回当前进程是否已经完成 SDK 初始化。
static isInitialized(): boolean

// 把错误码转成错误名称。
static errorToString(code: number): string

示例：

const code = await TiRtc.initialize({
  context,
  appId: 'your-app-id',
});
if (code !== 0) {
  console.error(`initialize failed: ${TiRtc.errorToString(code)} (${code})`);
}

`TiRtcConn`

TiRtcConn 表示客户端到远端设备的一条连接。创建对象不会立即发起连接；通常先设置回调，再调用 connect(...)。连接建立后，可以通过它发送命令、发送流消息、发起媒体订阅和请求视频关键帧。

音频播放和视频显示由 TiRtcAudioOutput / TiRtcVideoOutput 负责，TiRtcConn 本身不播放也不显示媒体。

状态

TiRtcConnState.idle：连接对象已创建，但还没有开始连接。
TiRtcConnState.connecting：连接请求已提交，正在等待结果。
TiRtcConnState.connected：连接已经建立，可收发命令、流消息，发起媒体订阅和关键帧请求。
TiRtcConnState.disconnected：连接失败、对端断开或调用 disconnect() 后进入该状态。

属性和回调

// 当前连接状态。
state: TiRtcConnState

// 连接状态变化时触发。errorCode 为 0 表示本次状态变化没有错误；非 0 为错误码。
onStateChanged?: (state: TiRtcConnState, errorCode: number) => void

// 收到设备端命令时触发。
onCommand?: (commandId: number, payload: Uint8Array) => void

// 收到设备端的流消息时触发。
onStreamMessage?: (streamId: number, timestampMs: number, payload: Uint8Array) => void

方法

// 创建连接对象；构造函数本身不会发起连接。通常先设置回调，再调用 connect。
new TiRtcConn()

// 发起连接；初始化完成并拿到连接凭证后调用。
// remoteId 是连接目标；连接设备端时传目标设备的 device_id，例如 "PRODFENGXXXX"。
// token 是业务服务端为本次连接签发的 token，二者不能为空。
// 返回 0 只表示请求已提交，最终连接结果看 onStateChanged；非 0 为错误码。
connect(options: TiRtcConnConnectOptions): number

// 断开当前连接；业务结束、切换设备或重新连接前调用。对象仍可重新 connect。
disconnect(): number

// 释放连接对象；确认不再使用这条连接后调用。调用后不要再使用这个实例。
dispose(): void

// 在命令通道上发送自定义命令；连接进入 connected 后调用。
sendCommand(options: TiRtcConnCommandOptions): number

// 发送流消息；连接进入 connected 后调用。
// streamId 按 stream_id 约定使用 0..15，两端需要提前约定消息语义。
sendStreamMessage(options: TiRtcConnStreamMessageOptions): number

// 请求远端开始发送指定 streamId 的音频流；连接进入 connected 后调用。
// streamId 按 stream_id 约定使用 0..15。
// 这个方法只请求远端发送音频，不会自动播放。
// 播放远端音频前，先调用 TiRtcAudioOutput.attach(...) 指定要播放的 connection 和 streamId；然后调用 connect(...) 建立连接。
// 连接成功后，再调用 subscribeAudio(...) 请求远端发送这路音频。
subscribeAudio(options: TiRtcStreamControlOptions): number

// 请求远端停止发送指定 streamId 的音频流；streamId 按 stream_id 约定使用 0..15。
// 不会停止已经创建的 TiRtcAudioOutput。停止播放时再调用 TiRtcAudioOutput.detach()。
unsubscribeAudio(options: TiRtcStreamControlOptions): number

// 请求远端开始发送指定 streamId 的视频流；连接进入 connected 后调用。
// streamId 按 stream_id 约定使用 0..15。
// 这个方法只请求远端发送视频，不会自动显示。
// 显示远端视频前，先调用 TiRtcVideoOutput.attach(...) 指定要显示的 connection 和 streamId；然后调用 connect(...) 建立连接。
// 连接成功后，再调用 subscribeVideo(...) 请求远端发送这路视频。
subscribeVideo(options: TiRtcStreamControlOptions): number

// 请求远端停止发送指定 streamId 的视频流；streamId 按 stream_id 约定使用 0..15。
// 不会停止已经创建的 TiRtcVideoOutput。停止显示时再调用 TiRtcVideoOutput.detach()。
unsubscribeVideo(options: TiRtcStreamControlOptions): number

// 向远端请求指定视频流的关键帧；连接已建立且远端正在发送该视频流时调用。
// streamId 按 stream_id 约定使用 0..15。
requestKeyFrame(options: TiRtcStreamControlOptions): number

相关类型：

interface TiRtcConnConnectOptions {
  remoteId: string; // 目标 remote_id
  token: string; // 连接凭证
}

interface TiRtcConnCommandOptions {
  commandId: number; // 业务命令 ID
  data: Uint8Array; // 命令 payload
}

interface TiRtcConnStreamMessageOptions {
  streamId: number; // 消息所属流
  timestampMs: number; // 业务时间戳
  data: Uint8Array; // 消息 payload
}

interface TiRtcStreamControlOptions {
  streamId: number; // 远端音视频流编号
}

示例：

const conn = new TiRtcConn();
conn.onStateChanged = (state: TiRtcConnState, errorCode: number): void => {
  if (errorCode === 0) {
    console.info(`conn state=${state}`);
    return;
  }
  console.warn(`conn state=${state} error=${TiRtc.errorToString(errorCode)} (${errorCode})`);
};
conn.onCommand = (commandId: number, payload: Uint8Array): void => {
  console.info(`command=${commandId} bytes=${payload.length}`);
};

const code = conn.connect({ remoteId, token });
if (code !== 0) {
  console.error(`connect failed: ${TiRtc.errorToString(code)} (${code})`);
}

// 结束时：
conn.disconnect();
conn.dispose();

`TiRtcAudioOutputOptions`

TiRtcAudioOutputOptions 配置 TiRtcAudioOutput 的音频输出参数。只需要填写要覆盖默认值的字段。

interface TiRtcAudioOutputOptions {
  agcLevel?: TiRtcAudioAgcLevel; // 自动增益等级
  ansLevel?: TiRtcAudioAnsLevel; // 自动噪声抑制等级
  bufferStrategy?: TiRtcOutputBufferStrategy; // 输出缓冲策略
  // 最大输出缓冲水位，单位为毫秒；仅 automatic 有效。
  // 不传表示由 SDK 自动决定。
  maxBufferWatermarkMs?: number;
}

相关枚举：

// 自动增益控制等级。
enum TiRtcAudioAgcLevel {
  disabled = 0, // 关闭
  low = 1, // 低
  medium = 2, // 中
  high = 3, // 高
}

// 自动噪声抑制等级。
enum TiRtcAudioAnsLevel {
  disabled = 0, // 关闭
  low = 1, // 低
  medium = 2, // 中
  high = 3, // 高
}

// 输出缓冲策略。
enum TiRtcOutputBufferStrategy {
  automatic = 0, // SDK 根据当前平台和链路状态决定缓冲策略
  noBuffer = 1, // 不使用输出缓冲；不要同时设置 maxBufferWatermarkMs
}

`TiRtcAudioOutput`

TiRtcAudioOutput 用来播放某条远端音频流。播放远端音频前，先创建 TiRtcAudioOutput，调用 attach(...) 指定要播放的 connection 和 streamId，再调用 connect(...) 建立连接；连接成功后，调用 TiRtcConn.subscribeAudio(...) 请求远端发送这路音频。 attach(...) 成功只表示播放对象已经知道要播放哪路音频。如果远端还没有发送这路音频，用户仍然听不到声音。 attach(...) 只选择这路音频由哪个 TiRtcAudioOutput 播放；subscribeAudio(...) 才会请求远端发送。

状态

TiRtcAudioOutputState.idle：还没有选择要播放的远端音频流，或已经 detach()。
TiRtcAudioOutputState.buffering：已经选择要播放的远端音频流，正在等待可播放数据。
TiRtcAudioOutputState.playing：正在播放远端音频。
TiRtcAudioOutputState.failed：播放路径发生错误。

属性和回调

// 当前音频播放状态。
state: TiRtcAudioOutputState

// 播放状态变化时触发。
onStateChanged?: (state: TiRtcAudioOutputState) => void

// 音频输出对象发生错误时触发。
onError?: (code: number) => void

方法

// 创建音频输出对象。
new TiRtcAudioOutput()

// 配置音频输出参数；创建对象后、attach 前调用。
// 返回 0 表示成功，非 0 为错误码；已绑定后调用会返回错误码。
configure(options: TiRtcAudioOutputOptions): number

// 指定这个输出对象要播放的远端音频流。通常在 connect 前调用；如果输出对象晚创建，也可以在连接建立后调用。
// 远端发送这路音频后，用户才会听到声音。
attach(options: TiRtcOutputAttachOptions): number

// 停止使用这个输出对象播放当前音频流；切换流或释放对象前调用。成功后状态回到 idle。
detach(): number

// 释放音频输出对象；通常在 detach 后调用。调用后不要再使用这个实例。
dispose(): void

相关类型：

interface TiRtcOutputAttachOptions {
  connection: TiRtcConn; // 要播放或显示远端媒体的连接对象
  streamId: number; // 远端音视频流编号
}

示例：

const audioOutput = new TiRtcAudioOutput();
audioOutput.onError = (code: number): void => {
  console.error(`audio output error: ${TiRtc.errorToString(code)} (${code})`);
};

const code = audioOutput.attach({ connection: conn, streamId: 10 });
if (code !== 0) {
  console.error(`audio attach failed: ${TiRtc.errorToString(code)} (${code})`);
}

// 结束时：
audioOutput.detach();
audioOutput.dispose();

`TiRtcVideoOutputOptions`

TiRtcVideoOutputOptions 配置 TiRtcVideoOutput 的解码和缓冲参数。只需要填写要覆盖默认值的字段。

interface TiRtcVideoOutputOptions {
  // 解码偏好；这只是请求偏好，实际选择取决于设备、系统和视频编码格式。
  decoderPreference?: TiRtcVideoDecoderPreference;
  bufferStrategy?: TiRtcOutputBufferStrategy; // 输出缓冲策略
  // 最大输出缓冲水位，单位为毫秒；仅 automatic 有效。
  // 不传表示由 SDK 自动决定。
  maxBufferWatermarkMs?: number;
}

相关枚举：

// 视频解码偏好。
enum TiRtcVideoDecoderPreference {
  auto = 0, // SDK 自动选择
  software = 1, // 请求软件解码
  hardware = 2, // 请求硬件解码
}

// 输出缓冲策略。
enum TiRtcOutputBufferStrategy {
  automatic = 0, // SDK 根据当前平台和链路状态决定缓冲策略
  noBuffer = 1, // 不使用输出缓冲；不要同时设置 maxBufferWatermarkMs
}

`TiRtcVideoOutput`

TiRtcVideoOutput 用来显示某条远端视频流。显示远端视频前，先创建 TiRtcVideoOutput，调用 attach(...) 指定要显示的 connection 和 streamId，并在页面中使用 TiRtcVideoOutputView(...) 选择画面显示位置，再调用 connect(...) 建立连接；连接成功后，调用 TiRtcConn.subscribeVideo(...) 请求远端发送这路视频。 attach(...) 成功只表示输出对象已经知道要显示哪路视频。如果远端还没有发送这路视频，页面不会出画面。 attach(...) 只选择这路视频由哪个 TiRtcVideoOutput 显示；subscribeVideo(...) 才会请求远端发送。

状态

TiRtcVideoOutputState.idle：还没有选择要显示的远端视频流，或已经 detach()。
TiRtcVideoOutputState.buffering：已经选择要显示的远端视频流，正在等待可渲染数据或渲染视图准备。
TiRtcVideoOutputState.rendering：正在渲染远端视频。
TiRtcVideoOutputState.failed：视频输出路径发生错误。

属性和回调

// 当前视频播放状态。
state: TiRtcVideoOutputState

// 最近一次远端画面渲染尺寸。还没有画面或已经 detach 时可能为 undefined。
renderSize?: TiRtcSize

// 播放状态变化时触发。
onStateChanged?: (state: TiRtcVideoOutputState) => void

// 远端画面尺寸变化时触发。
onRenderSizeChanged?: (size: TiRtcSize) => void

// 视频输出对象发生错误时触发。
onError?: (code: number) => void

相关类型：

interface TiRtcSize {
  width: number;
  height: number;
}

方法

// 创建视频输出对象。
new TiRtcVideoOutput()

// 设置视频输出参数；创建对象后、attach 前调用。
// 返回 0 表示成功，非 0 为错误码；需要修改参数时先 detach，再重新 setOptions 和 attach。
setOptions(options: TiRtcVideoOutputOptions): number

// 指定这个输出对象要显示的远端视频流。通常在 connect 前调用；如果输出对象晚创建，也可以在连接建立后调用。
// 远端发送这路视频后，页面才会出画面。
attach(options: TiRtcOutputAttachOptions): number

// 停止使用这个输出对象显示当前视频流；切换流或释放对象前调用。成功后状态回到 idle，并清空 renderSize。
detach(): number

// 释放视频输出对象和相关系统资源；通常在 detach 后调用。调用后不要再使用这个实例。
dispose(): void

视图组件

interface TiRtcVideoOutputViewOptions {
  output: TiRtcVideoOutput; // 要显示的远端视频输出对象
  fit?: TiRtcVideoFit; // 画面适配方式
  backgroundColor?: ResourceColor;
  width?: Length;
  height?: Length;
}

// 在 ArkUI 中挂载远端视频画面。
function TiRtcVideoOutputView(options: TiRtcVideoOutputViewOptions): void

相关枚举：

// 视频画面适配方式。
enum TiRtcVideoFit {
  contain = 0, // 完整显示，可能留边
  cover = 1, // 填满容器，可能裁剪
}

示例：

const videoOutput = new TiRtcVideoOutput();
videoOutput.onRenderSizeChanged = (size: TiRtcSize): void => {
  console.info(`remote video size=${size.width}x${size.height}`);
};

const code = videoOutput.attach({ connection: conn, streamId: 11 });
if (code !== 0) {
  console.error(`video attach failed: ${TiRtc.errorToString(code)} (${code})`);
}

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

`TiRtcAudioInputOptions`

TiRtcAudioInputOptions 配置 TiRtcAudioInput 的麦克风采集和本地音频发送参数。配置会在下一次采集启动时生效；运行中调用 setOptions(...) 会返回错误码。

interface TiRtcAudioInputOptions {
  codec?: TiRtcAudioCodec; // 本地音频传输编码
  sampleRate?: TiRtcAudioSampleRate; // 麦克风采样率
  channels?: TiRtcAudioChannelCount; // 声道数；公开能力只支持单声道
  aecMode?: TiRtcAudioAecMode; // 回声消除模式
  agcLevel?: TiRtcAudioAgcLevel; // 自动增益等级
  ansLevel?: TiRtcAudioAnsLevel; // 自动噪声抑制等级
}

相关枚举：

// 本地音频传输编码。
enum TiRtcAudioCodec {
  g711a = 1,
  aac = 2,
  pcm = 3,
}

// 麦克风采样率。
enum TiRtcAudioSampleRate {
  rate8k = 8000,
  rate16k = 16000,
}

// 声道数。公开能力只支持单声道。
enum TiRtcAudioChannelCount {
  mono = 1,
}

// 回声消除模式。
enum TiRtcAudioAecMode {
  disabled = 0, // 关闭
  enabled = 1, // 开启
}

// 自动增益控制等级。
enum TiRtcAudioAgcLevel {
  disabled = 0, // 关闭
  low = 1, // 低
  medium = 2, // 中
  high = 3, // 高
}

// 自动噪声抑制等级。
enum TiRtcAudioAnsLevel {
  disabled = 0, // 关闭
  low = 1, // 低
  medium = 2, // 中
  high = 3, // 高
}

`TiRtcAudioInput`

TiRtcAudioInput 采集本地麦克风声音，并通过已建立的连接发送给远端设备。常见用途是语音对讲或语音回复。

应用需要自己申请 ohos.permission.MICROPHONE 权限；SDK 不会替应用弹出系统权限申请框。

状态

TiRtcInputState.idle：输入对象已创建，但还没有开始采集。
TiRtcInputState.running：正在采集并传输本地音频。
TiRtcInputState.stopped：已停止采集；当前绑定仍可保留给后续 start() 复用。
TiRtcInputState.failed：采集或传输路径发生错误。

属性和回调

// 当前本地音频输入状态。
state: TiRtcInputState

// 输入状态变化时触发。
onStateChanged?: (state: TiRtcInputState) => void

// 本地音频输入发生错误时触发。message 可能为空。
onError?: (code: number, message?: string) => void

方法

// 创建本地音频输入对象。
new TiRtcAudioInput()

// 设置下次采集使用的参数；创建对象后、start 前调用。
// 返回 0 表示成功，非 0 为错误码；正在采集或已绑定连接时调用会返回错误码。
setOptions(options: TiRtcAudioInputOptions): Promise<number>

// 把本地麦克风音频通过指定连接和 streamId 发送给远端设备。
// 连接必须已进入 connected；在 start 前调用，streamId 使用 0..15。
attach(options: TiRtcInputAttachOptions): Promise<number>

// 开始麦克风采集和传输；返回 0 表示成功，非 0 为错误码。
// 调用 start 前，应用必须确保已经获得系统麦克风权限；SDK 不负责申请该权限。
// 还没有 attach 时会返回错误码。
start(): Promise<number>

// 停止采集和传输，但保留当前绑定；已经停止时调用也返回 0。
stop(): Promise<number>

// 移除当前连接上的本地音频绑定；停止发送、切换连接或切换 streamId 前调用。
// 运行中先 stop 再 detach。
detach(options: TiRtcInputDetachOptions): Promise<number>

// 释放本地音频输入对象并清理绑定；通常在 stop 和 detach 后调用。调用后不要再使用这个实例。
dispose(): Promise<void>

相关类型：

interface TiRtcInputAttachOptions {
  connection: TiRtcConn; // 已建立的连接
  streamId: number; // 本地音频流编号
}

interface TiRtcInputDetachOptions {
  connection: TiRtcConn; // 要移除绑定的连接
}

示例：

const input = new TiRtcAudioInput();
input.onError = (code: number, message?: string): void => {
  console.error(`audio input error: ${TiRtc.errorToString(code)} (${code}) ${message ?? ''}`);
};

const attachCode = await input.attach({ connection: conn, streamId: 14 });
if (attachCode === 0) {
  await input.start();
}

// 结束时：
await input.stop();
await input.detach({ connection: conn });
await input.dispose();

`TiRtcLogging`

TiRtcLogging 用于上传当前 SDK 日志。排查问题时，把上传成功返回的 logId 提供给支持人员。

// 上传当前 SDK 日志；code == 0 且 logId 有值表示上传成功。
static upload(): Promise<TiRtcLoggingUploadResult>

相关类型：

interface TiRtcLoggingUploadResult {
  code: number;
  logId?: string;
}

示例：

const result = await TiRtcLogging.upload();
if (result.code === 0 && result.logId !== undefined && result.logId.length > 0) {
  console.info(`TiRTC logId=${result.logId}`);
}

HarmonyOS API 说明 ​

生命周期与调用顺序 ​

TiRtcInitOptions ​

TiRtc ​

TiRtcConn ​

状态 ​

属性和回调 ​

方法 ​

TiRtcAudioOutputOptions ​

TiRtcAudioOutput ​

状态 ​

属性和回调 ​

方法 ​

TiRtcVideoOutputOptions ​

TiRtcVideoOutput ​

状态 ​

属性和回调 ​

方法 ​

视图组件 ​

TiRtcAudioInputOptions ​

TiRtcAudioInput ​

状态 ​

属性和回调 ​

方法 ​

TiRtcLogging ​

HarmonyOS API 说明

生命周期与调用顺序

`TiRtcInitOptions`

`TiRtc`

`TiRtcConn`

状态

属性和回调

方法

`TiRtcAudioOutputOptions`

`TiRtcAudioOutput`

状态

属性和回调

方法

`TiRtcVideoOutputOptions`

`TiRtcVideoOutput`

状态

属性和回调

方法

视图组件

`TiRtcAudioInputOptions`

`TiRtcAudioInput`

状态

属性和回调

方法

`TiRtcLogging`