HarmonyOS（ArkTS）快速开始与功能指南

HarmonyOS（ArkTS）：前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障；接口名与签名在构建时取自公开 SDK 接口定义。

接口小节由公开 SDK 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

HarmonyOS 端是 ArkTS 的 RtcEngine 形状，与 Android 同构（joinChannel + IRtcEngineEventHandler 回调），但运行在 HarmonyOS NEXT 的 ArkTS 运行时上。

前置条件

DevEco Studio 5.0+、HarmonyOS SDK API 12+、ohpm 包管理器。
module.json5 里申请 ohos.permission.CAMERA、ohos.permission.MICROPHONE，用户首次使用时授权。
已拿到 appId 与 Token 服务（见控制台开通服务与获取凭证）。

安装

text

# ohpm 坐标以发布版本为准
ohpm install @nimeet/rtc-harmonyos

获取 Token

Token 由你的后端签发；ArkTS 客户端只持有 { appId, rtcToken, rtcUid }。不要把 appCertificate 或 customerSecret 打进 HAP 包（HAP 可被解包读取）。

加入频道

typescript

import { RtcEngine, RtcEngineConfig, ChannelProfileType, ClientRoleType } from '@nimeet/rtc-harmonyos';

const engine: RtcEngine = createRtcEngine();
engine.initialize(new RtcEngineConfig(appId));

engine.registerEventHandler({
  onJoinChannelSuccess: (connection, elapsed) => console.info('joined'),
  onUserJoined: (connection, uid, elapsed) => console.info('remote', uid),
  onUserOffline: (connection, uid, reason) => console.info('left', uid),
  onTokenPrivilegeWillExpire: (token) => refreshToken(),
  onError: (err, msg) => console.error(`rtc ${err}: ${msg}`),
});

engine.setChannelProfile(ChannelProfileType.ChannelProfileLiveBroadcasting);
engine.enableVideo();
engine.startPreview();
engine.joinChannelWithOptions(token, 'weekly-sync', 10001, {
  clientRoleType: ClientRoleType.ClientRoleBroadcaster,
  autoSubscribeAudio: true,
  autoSubscribeVideo: true,
});

发布与订阅

typescript

engine.muteLocalAudioStream(true);
engine.muteLocalVideoStream(true);
engine.enableLocalVideo(false);
engine.updateChannelMediaOptions(options);

屏幕共享：startScreenCapture(parameters) / stopScreenCapture() / updateScreenCaptureParameters(parameters)，需要申请屏幕录制权限（系统弹窗授权）。

事件

IRtcEngineEventHandler 的 on* 方法（51 个）：onJoinChannelSuccess、onUserJoined、onUserOffline、 onFirstRemoteVideoDecoded、onTokenPrivilegeWillExpire、onError、onConnectionStateChanged。

错误处理

同步方法返回数字错误码，0 成功，负值为声网错误号；
异步错误走 onError；
未实现能力返回 -4（ERR_NOT_SUPPORTED）。

排障

现象	原因	处理
编译期找不到模块	ohpm 未安装/未同步	DevEco 里 Sync 工程
采集无权限崩溃	未申请 CAMERA/MICROPHONE	补 `module.json5` 权限并处理用户拒绝
屏幕共享失败	系统未授权屏幕录制	引导用户到系统设置授权
回调不触发	handler 未注册或已被回收	在页面 `aboutToAppear` 注册、`aboutToDisappear` 反注册
后台被固定	应用生命周期限制	使用长时任务/前台服务能力

下一步

完整接口与重载：同端 API 参考
错误码与排障：错误码全表、FAQ
服务端签发 Token：Token 鉴权

平台信息

项	值
平台	HarmonyOS（ArkTS）
语言	ArkTS
SDK 包	`@nimeet/rtc-harmonyos`
接口版本	`4.6.3`
兼容参考	声网 harmonyos 端 API

本端公开接口与声网 harmonyos 端 API 对齐；安装与运行要求见上面前置条件。

可用性

该端 SDK：正式可用。本页代码片段使用公开 API；运行时的能力边界以实际发布的 SDK 包为准。

加入频道链路

下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载，这里展示最常用的那一个；完整重载见同端 API 参考页。

步骤	接口	方法	重载数
创建实例 / 初始化	`__unattributed__`	`create`	1
续期 Token	`IAgoraMusicContentCenter`	`renewToken`	1
开启视频与本地预览	`RtcEngine`	`enableVideo`	1
加入频道	`RtcEngine`	`joinChannel`	1
离开频道	`RtcEngine`	`leaveChannel`	1
订阅远端媒体	`RtcEngine`	`muteRemoteAudioStream`	1
频道场景	`RtcEngine`	`setChannelProfile`	1
切换角色	`RtcEngine`	`setClientRole`	1
绑定本地画面	`RtcEngine`	`setupLocalVideo`	1

typescript

create(config: RtcEngineConfig): RtcEngine
renewToken(token: string): number
enableVideo(): number
joinChannel(key: string, channel: string, optionalInfo: string, uid: number): number
leaveChannel(options?: LeaveChannelOptions): number
muteRemoteAudioStream(uid: number, muted: boolean): number
setChannelProfile(profile: number): number
setClientRole(role: number, options?: ClientRoleOptions): number
setupLocalVideo(canvas: VideoCanvas): number

事件与回调

回调注册在 IRtcEngineEventHandler 上；不同端的命名可能不同，完整清单见同端 API 参考页。

回调	签名	用途
`onConnectionStateChanged`	`onConnectionStateChanged(state: Constants.ConnectionState, reason: Constants.ConnectionChangedReason): void`	入会结果 / 连接状态变化：据此更新 UI 并决定是否重连。
`onUserJoined`	`onUserJoined(uid: number, elapse: number): void`	远端用户加入：分配画面容器。
`onRemoteVideoStateChanged`	`onRemoteVideoStateChanged(uid: number, state: Constants.RemoteVideoStreamState, reason: Constants.RemoteVideoStreamReason, elapsed: number): void`	远端视频状态：首帧解码后即可渲染。
`onUserOffline`	`onUserOffline(uid: number, reason: number): void`	远端用户离开：释放容器与订阅。
`onRequestToken`	`onRequestToken(): void`	Token 即将过期：调用服务端续期后 `renewToken`。
`onError`	`onError(err: Constants.ErrorCode, message: string): void`	运行时错误：`err` 为声网错误号，按错误码表分流。
`onNetworkQuality`	`onNetworkQuality(uid: number, txQuality: Constants.NetworkQuality, rxQuality: Constants.NetworkQuality): void`	网络质量：上报到水晶球或提示用户。

接口	事件名	监听器参数
`IMediaPlayerObserver`	`onPlayerCacheStats`	`onPlayerCacheStats?:(stats:CacheStatistics`

错误码

常量	值
`ERR_ABORTED`	`20`
`ERR_ADM_GENERAL_ERROR`	`1005`
`ERR_ADM_INIT_PLAYOUT`	`1008`
`ERR_ADM_INIT_RECORDING`	`1011`
`ERR_ADM_START_PLAYOUT`	`1009`
`ERR_ADM_START_RECORDING`	`1012`
`ERR_ADM_STOP_PLAYOUT`	`1010`
`ERR_ADM_STOP_RECORDING`	`1013`
`ERR_ALREADY_IN_USE`	`19`
`ERR_BITRATE_LIMIT`	`115`
`ERR_BUFFER_TOO_SMALL`	`6`
`ERR_CONNECTION_INTERRUPTED`	`111`
`ERR_CONNECTION_LOST`	`112`
`ERR_DATASTREAM_DECRYPTION_FAILED`	`122`
`ERR_DECRYPTION_FAILED`	`120`
`ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH`	`130`
`ERR_FAILED`	`1`
`ERR_INIT_NET_ENGINE`	`21`
`ERR_INVALID_APP_ID`	`101`
`ERR_INVALID_ARGUMENT`	`2`
`ERR_INVALID_CHANNEL_NAME`	`102`
`ERR_INVALID_TOKEN`	`110`
`ERR_INVALID_USER_ACCOUNT`	`134`
`ERR_JOIN_CHANNEL_REJECTED`	`17`
`ERR_LEAVE_CHANNEL_REJECTED`	`18`
`ERR_LOAD_MEDIA_ENGINE`	`1001`
`ERR_NOT_INITIALIZED`	`7`
`ERR_NOT_IN_CHANNEL`	`113`
`ERR_NOT_READY`	`3`
`ERR_NOT_SUPPORTED`	`4`
`ERR_NO_PERMISSION`	`9`
`ERR_OK`	`0`
`ERR_REFUSED`	`5`
`ERR_RESOURCE_LIMITED`	`22`
`ERR_SIZE_TOO_LARGE`	`114`
`ERR_TIMEDOUT`	`10`
`ERR_TOKEN_EXPIRED`	`109`
`ERR_TOO_MANY_DATA_STREAMS`	`116`
`ERR_VDM_CAMERA_NOT_AUTHORIZED`	`1501`
`RtcEngine`	`null`

平台 REST 层用 REST 错误码；SDK 层把连接/鉴权失败映射成声网错误号，映射表见各端 SDK 错误标识。

HarmonyOS（ArkTS） 快速开始与功能指南

前置条件#

安装#

获取 Token#

加入频道#

发布与订阅#

事件#

错误处理#

排障#

下一步#

平台信息

可用性

加入频道链路

事件与回调

错误码

HarmonyOS（ArkTS）快速开始与功能指南

前置条件

安装

获取 Token

加入频道

发布与订阅

事件

错误处理

排障

下一步