HarmonyOS API Reference

This page describes the public ArkTS API of the HarmonyOS native SDK tirtc-av for OpenHarmony / HarmonyOS NEXT apps.

If you have not added the SDK or prepared the connection flow, start with Client Integration. Terms such as AppId, remote_id, token, and stream_id follow the glossary.

Object Overview

Object	Purpose	Cleanup
TiRtcInitOptions	Holds SDK initialization options	No explicit cleanup
TiRtc	Initializes and shuts down the shared runtime; formats error codes	TiRtc.shutdown()
TiRtcConn	Connects, disconnects, sends commands and stream messages, subscribes to media, and requests key frames	dispose()
TiRtcAudioOutput	Plays one remote audio stream and reads metrics/debug snapshots	dispose()
TiRtcVideoOutput	Plays one remote video stream with TiRtcVideoOutputView rendering	dispose()
TiRtcAudioInput	Captures local microphone audio and publishes it to the current connection for uplink use cases such as intercom	dispose()
TiRtcVideoInput	Captures local camera video, provides preview, and publishes it to the current connection for uplink use cases	dispose()
TiRtcLogging	Writes and uploads SDK logs	None

TiRtcInitOptions

Options passed to TiRtc.initialize(...).

Field	Description
context	common.UIAbilityContext required by SDK initialization.
appId	Your TiRTC AppId.
endpoint	Custom service endpoint. Leave empty to use the runtime default.
consoleLogEnabled	Mirrors SDK logs to the console when enabled. Default is false.

TiRtc

Typical order: initialize() -> create connection, input, or output objects -> release those objects -> shutdown().

API	Description
initialize(options: TiRtcInitOptions): Promise<number>	Initializes the shared runtime. Returns 0 on success. Repeated initialization is idempotent and does not replace the active configuration.
shutdown(): number	Shuts down the shared runtime after every connection, input, and output object has been released. Calling it while already shut down also returns 0.
isInitialized(): boolean	Returns whether this process has initialized the runtime.
errorToString(code: number): string	Converts an error code to a stable error token.
formatError(code: number): string	Formats an error code for logs or UI.

TiRtcConn

TiRtcConn is a downlink connection to a remote device or client. Connect first, then send commands, send stream messages, subscribe to media, or attach outputs.

API	Description
connect(options: TiRtcConnConnectOptions): number	Starts connecting with remoteId and token. A 0 return means the request was accepted; use onStateChanged for lifecycle updates.
disconnect(): number	Disconnects the connection. Calling it while already disconnected is OK.
dispose(): void	Permanently releases the connection and local stream bookkeeping.
sendCommand(options: TiRtcConnCommandOptions): number	Sends an application command. HarmonyOS uses the public parameter name commandId.
sendStreamMessage(options: TiRtcConnStreamMessageOptions): number	Sends a timestamped stream message.
subscribeAudio(options: TiRtcStreamControlOptions): number	Subscribes to remote audio packets without creating local playback.
unsubscribeAudio(options: TiRtcStreamControlOptions): number	Cancels an audio subscription. Attached audio outputs must detach first.
subscribeVideo(options: TiRtcStreamControlOptions): number	Subscribes to remote video packets without creating local playback.
unsubscribeVideo(options: TiRtcStreamControlOptions): number	Cancels a video subscription. Attached video outputs must detach first.
requestKeyFrame(options: TiRtcStreamControlOptions): number	Requests a key frame for a remote video stream.
getMetricsSnapshot(): TiRtcConnMetricsResult	Returns best-effort connection metrics.

Callbacks:

Member	Description
onStateChanged	(state: TiRtcConnState, errorCode: number) => void
onCommand	(command: number, payload: Uint8Array) => void
onStreamMessage	(streamId: number, timestampMs: number, payload: Uint8Array) => void

Remote Outputs

Within one connection, a streamId cannot be claimed by audio output, video output, and manual subscription at the same time.

Remote playback does not require camera or microphone permission.

Object	Main APIs
TiRtcAudioOutput	configure(...), attach(...), detach(), dispose(), getMetricsSnapshot(), getDebugSnapshot()
TiRtcVideoOutput	setOptions(...), attach(...), detach(), dispose(), getMetricsSnapshot(), getDebugSnapshot()

Render remote video with the SDK ArkUI component:

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

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

Local Uplink Inputs

Local inputs publish microphone or camera capture to an established connection. Use them for client uplink scenarios such as intercom, voice reply, or sending local camera video.

Object	Main APIs
TiRtcAudioInput	setOptions(...), start(), attach(...), detach(...), stop(), dispose(). start() checks ohos.permission.MICROPHONE; request permission in the app before calling it.
TiRtcVideoInput	setOptions(...), start(), attach(...), detach(...), stop(), dispose(). start() checks ohos.permission.CAMERA; request permission in the app before calling it.

If the required permission is missing, the SDK returns a platform permission error. It does not show permission dialogs.

Render local camera preview with TiRtcVideoInputPreview:

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

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

Common Enums

Type	Values
TiRtcVideoDecoderPreference	auto, software, hardware
TiRtcVideoEncoderPreference	auto, software, hardware
TiRtcOutputBufferStrategy	automatic, noBuffer
TiRtcVideoFit	contain, cover
TiRtcAudioCodec	g711a, aac
TiRtcVideoCodec	h264, h265, mjpeg
TiRtcCameraFacing	front, back

TiRtcLogging

API	Description
d(tag: string, message: string): void	Writes a debug log entry.
i(tag: string, message: string): void	Writes an info log entry.
w(tag: string, message: string): void	Writes a warning log entry.
e(tag: string, message: string): void	Writes an error log entry.
upload(): Promise<TiRtcLoggingUploadResult>	Uploads collected SDK logs and returns logId when available.

Common Misuse

• Creating or using runtime-backed objects before await TiRtc.initialize(...).
• Treating connect(...) == 0 as already connected.
• Updating output options after attach().
• Reusing one streamId for audio and video in the same connection.
• Starting local input before requesting camera or microphone permission.
• Calling only disconnect() or detach() and forgetting to dispose() objects.
• Calling TiRtc.shutdown() while connection, input, or output objects still exist.

Related Docs

• Client Integration
• Connection
• Real-Time Audio and Video
• Command Messaging
• Stream Messaging
• Diagnostics and Logs
• HarmonyOS SDK Release Notes