HarmonyOS SDK Guide

HarmonyOS Next SDK install, join and capability boundaries.

Interface sections generated from the public SDK definitions

Version v1.1.0 · Updated 2026-10-26 · revision 1

The HarmonyOS SDK has the ArkTS RtcEngine shape; it is isomorphic to Android (joinChannel + IRtcEngineEventHandler callbacks) but runs on the ArkTS runtime of HarmonyOS NEXT.

Prerequisites#

• DevEco Studio 5.0+, HarmonyOS SDK API 12+, the ohpm package manager.
• Declare ohos.permission.CAMERA and ohos.permission.MICROPHONE in module.json5; the user grants them on first use.
• An appId and a token service (see Enable Services and Get Credentials).

Installation#

# planned ohpm coordinates (not published yet)
ohpm install @nimeet/rtc-harmonyos

Get a token#

Your backend issues the token; the ArkTS client only holds { appId, rtcToken, rtcUid }. Never package appCertificate or customerSecret into the HAP (a HAP can be unpacked and read).

Join a channel#

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

Publishing and subscribing#

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

Screen sharing: startScreenCapture(parameters) / stopScreenCapture() / updateScreenCaptureParameters(parameters); it needs the screen-recording permission (granted through a system dialog).

Events#

IRtcEngineEventHandler exposes 51 on* methods: onJoinChannelSuccess, onUserJoined, onUserOffline, onFirstRemoteVideoDecoded, onTokenPrivilegeWillExpire, onError, onConnectionStateChanged.

Error handling#

• Synchronous methods return a numeric error code; 0 means success and a negative value is an Agora error number;
• Asynchronous errors arrive through onError;
• Unimplemented capabilities return -4 (ERR_NOT_SUPPORTED).

Troubleshooting#

Next steps#

• Full interfaces and overloads: API reference for this platform
• Error codes and troubleshooting: Error code table, FAQ
• Issue tokens on your server: Token authentication

Platform information

The public interfaces are aligned with the Agora harmonyos API; installation and runtime requirements are listed under Prerequisites above.

Availability

This platform's SDK: Generally available. The examples use the public API; runtime capability follows the published SDK package.

join-channel flow

The method names, parameter types and return values match the API reference for the same platform. Where a method has several overloads, the most common one is shown here; see the API reference for all overloads.

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

Events and callbacks

Callbacks are registered on IRtcEngineEventHandler; naming differs by platform, and the full list is in the API reference for the same platform.

Error codes

the platform REST layer uses REST error codes；the SDK layer maps connection/authentication failures to Agora error numbers, for the mapping table see SDK error identifiers per platform。