We introduce XmaxSDK, a native HarmonyOS SDK designed for real-time interactive video generation via Xmax models. XmaxSDK implements an end-to-end pipeline covering media acquisition, video streaming, frame-by-frame generation, and on-device rendering, enabling developers to seamlessly integrate low-latency, high-fidelity video transformations into creative applications at a much lower cost than alternative solutions.

What you can build with XmaxSDK

Realtime Use Case	Description	Demo
Character Swapping	Replace anyone in your live feed with a designated avatar in real-time.	▶ Play demo
	Prompt: 视频中角色替换成参考图中角色 Reference image: Select a clear image of the desired character with a clean background.
Virtual Try-On	Seamlessly change outfits, preserving exact body shape, natural motion, and an authentic fit.	▶ Play demo
	Prompt: 视频中人物衣服替换成参考图中衣服 Reference image: Select a clear image of the target outfit with a clean background.
Video Restyling	Reimagine your world in any style with an immersive visual experience.	▶ Play demo
	Prompt: 视频风格变为参考图指定的风格 Reference image: Select an image that captures the artistic style you want to apply.
AI Companions	Summon virtual characters into your live camera feed and interact with them through gestures.	▶ Play demo
	Prompt: 指定角色在场景中互动 Reference image: Select a clear image of the virtual character you want to summon with a clean background.
Live Photo	Animate and control characters in your images simply by drawing motion trajectories.	▶ Play demo
	Prompt: 让画面自然动起来 Reference image: Use the input image as the reference

Why XmaxSDK?

Low latency	Cost efficiency	High fidelity
End-to-end latency is measured in , ensuring that updates to generation conditions and interaction controls are reflected instantly.	Run on a , reducing inference costs by orders of magnitude versus datacenter GPUs like H100.	Our models support real-time generation at up to , delivering production-ready, high-quality video output.

Prerequisites

• HarmonyOS 5.1.0 (API 18) or later
• An Xmax API key from the Xmax Platform

Warning

Do not commit an Xmax API key to version control. Supply credentials securely at runtime, or use a temporary key issued by the Xmax API. See Authentication for details.

Installation

The current release is distributed as a Harmony Archive (HAR). XmaxSDK depends on the VolcEngine RTC SDK for HarmonyOS, which is not currently available through the official OHPM Registry; both archives must therefore be integrated manually.

Download the following files:

• xmaxsdk-1.0.12.har from the XmaxSDK GitHub Release
• The VolcEngine RTC HAR from the HarmonyOS integration guide

Add both files to the application module's libs directory:

entry/libs/xmaxsdk-1.0.12.har
entry/libs/VolcEngineRTCToB-Release.har

Declare XmaxSDK in the module-level oh-package.json5:

{
  "dependencies": {
    "@xmax/sdk": "file:./libs/xmaxsdk-1.0.12.har"
  }
}

Override the VolcEngine dependency in the project-level oh-package.json5:

{
  "modelVersion": "6.1.1",
  "dependencies": {},
  "devDependencies": {},
  "overrides": {
    "@bytertc/volcenginertc": "file:./entry/libs/VolcEngineRTCToB-Release.har"
  }
}

Install the dependencies:

ohpm install

See Configure permissions before creating a local media stream.

Quick Start

Configure permissions

For camera-based input, declare the following permissions in the application module's module.json5:

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      },
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:reason_camera",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

Replace EntryAbility with the UIAbility that uses XmaxSDK when the application uses a different ability name. Define the permission reason in resources/base/element/string.json:

{
  "string": [
    {
      "name": "reason_camera",
      "value": "Camera access is required for realtime video input."
    }
  ]
}

If camera microphone input is enabled (useMicrophone set to true) or an input source contains audio, also declare ohos.permission.MICROPHONE with an appropriate permission reason and usedScene configuration. XmaxSDK checks and requests the required runtime permissions when a local media stream is created. If permission is unavailable, the SDK reports an XmaxError.

Before deploying to a device, configure application signing in DevEco Studio under File > Project Structure > Signing Configs.

Generate and display video

The following ArkTS snippets create a camera stream, start real-time generation, and bind the output to an ArkUI video component.

Within an ArkUI component, obtain the UIAbilityContext required by the SDK and create a realtime manager:

import { common } from '@kit.AbilityKit';
import {
  RealtimeConfiguration,
  RealtimeModel,
  RealtimeModels,
  XmaxClient,
  XmaxConfiguration
} from '@xmax/sdk';

const context = this.getUIContext().getHostContext() as common.UIAbilityContext;

const client = new XmaxClient(
  new XmaxConfiguration('YOUR_API_KEY'),
  context
);

const realtime = client.createRealtimeManager(
  new RealtimeConfiguration(
    RealtimeModels.realtime(RealtimeModel.X2_0)
  )
);

Realtime operations return promises and should be invoked from a lifecycle-aware component owned by the host application.

Create the input stream and start generation from an async method in that component:

import { RealtimeContext } from '@xmax/sdk';

const localStream = await realtime.createLocalCameraStream();
this.localVideoTrack = localStream.videoTrack;

const remoteStream = await realtime.startGeneration(
  localStream,
  new RealtimeContext(
    '视频中角色替换成参考图中角色',
    'https://platform.xmaxai.com/images/source/charx/chatx_image1.jpg'
  )
);
this.remoteVideoTrack = remoteStream.videoTrack;

The camera uses the selected model's default format. Store the tracks in component state and add XmaxRealtimeVideoView to your view hierarchy:

import {
  RealtimeVideoTrack,
  VideoContentMode,
  XmaxRealtimeVideoView
} from '@xmax/sdk';

@State private localVideoTrack: RealtimeVideoTrack | undefined = undefined;
@State private remoteVideoTrack: RealtimeVideoTrack | undefined = undefined;

build() {
  XmaxRealtimeVideoView({
    localTrack: this.localVideoTrack,
    remoteTrack: this.remoteVideoTrack,
    contentMode: VideoContentMode.FILL
  })
    .width('100%')
    .height('100%')
}

The component displays a local camera preview until the generated video is ready to render, with touch interaction enabled by default.

For streams created by createLocalVideoStream, call pauseLocalVideoStream, resumeLocalVideoStream, or toggleLocalVideoStreamPlayback on the realtime manager from your own button or onClick handler. Observe the current playing, pause, or ended value with localVideoPlaybackState or setLocalVideoPlaybackStateListener. While paused, the SDK continues sending the last input frame and silent audio, and overlays a still image on the generated video; the generation task remains active. See the playback control example. Videos loop by default. Pass false as the third argument to createLocalVideoStream(videoPath, undefined, false) to play once and receive LocalVideoPlaybackState.ENDED through the same listener on natural completion. Local playback and audio/video frame submission then stop, while in-flight remote results continue to render. This does not stop the generation task or disconnect the session; an active task remains in GENERATING.

Listen for events

After creating realtime, register the listeners you need before creating the input stream or starting generation.

Listener	Purpose
setStateListener	Observe preparation, preview readiness, connection, generation and failure reasons.
setNetworkQualityListener	Monitor uplink and downlink network quality.
setPerformanceAlarmListener	Detect device performance limitations or recovery, with a suggested video format when available.

Camera preview enters READY after a valid frame and view binding. Disconnect returns to READY when local media remains available; closing returns to IDLE. Normal termination, orientation changes and failures are carried in state.reason.

For example, monitor state changes and errors:

realtime.setStateListener((state) => {
  console.info(`State: ${state.connectionState}`);
  const error = state.reason?.error;
  if (error !== undefined) {
    console.error(`Error: ${error.code} ${error.message}`);
  }
});

Resource Cleanup

• disconnect() — Stop Remote Generation

  Ends the remote session while keeping the local camera stream and preview active. Use this when ending the online session but staying on the current screen. You can start a new session later using the same local stream:

  await realtime.disconnect();
  this.remoteVideoTrack = undefined;

• close() — Full Teardown & Release

  Ends the remote session, stops local media capture, and releases all engine resources. Use this when leaving or dismissing the generation screen:

  await realtime.close();

Note: These methods are alternatives, not sequential steps. When exiting a screen, call close() directly—there is no need to call disconnect() first.

Tip

For complete usage examples, including image and video inputs, model capabilities, reference images, touch interaction, and logging, see the usage guide.

Example Project

A complete example application featuring an ArkUI implementation is available in examples/XLab. It demonstrates real-time generation using live camera feeds, static images, and local video files.

Dependencies

• VolcEngine RTC SDK enables low-latency, real-time audio and video communication.
• Tencent Cloud COS SDK handles media upload and download via object storage.

Contact us

For bug reports and feature requests, please open a GitHub Issue. For integration assistance and technical support, contact us at sdk@xmax.ai.

License

XmaxSDK is available under the terms of the MIT License.