We introduce XmaxSDK, a native iOS 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

• iOS 15.0 or later
• Swift 6
• An Xmax API key

Warning

Never commit your Xmax API key to version control. Pass it securely at runtime or use short-lived temporary keys issued by the Xmax API. For step-by-step instructions, see Authentication.

Installation

Because certain underlying dependencies lack Swift Package Manager support, XmaxSDK currently supports CocoaPods and manual integration only.

CocoaPods

Add the following to your application's Podfile:

source 'https://github.com/volcengine/volcengine-specs.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '15.0'

use_frameworks! :linkage => :static

target 'YourApp' do
  pod 'XmaxSDK',
      :git => 'https://github.com/XingMai/XmaxSDK-iOS.git',
      :tag => '1.0.7'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |configuration|
      configuration.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
    end
  end
end

Install the dependencies:

pod install --repo-update

Manual

Download XmaxSDK-1.0.7.xcframework.zip, then follow the manual integration guide to add the required dependencies and configure your Xcode target.

Quick Start

Configure permissions

Add a camera usage description to your application's Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time video input.</string>

Customize this message to match your application's user experience. XmaxSDK automatically prompts for camera access when creating the video stream and throws an XmaxError if permission is denied or unavailable.

Generate and display video

The following UIKit snippet creates a camera stream, starts real-time generation, and binds the output to a video view. Run this within a @MainActor async context.

import UIKit
import XmaxSDK

let client = XmaxClient(
    configuration: XmaxConfiguration(apiKey: "YOUR_XMAX_API_KEY")
)

let realtime = client.createRealtimeManager(
    options: RealtimeConfiguration(model: .x2_0)
)

let localStream = try await realtime.createLocalCameraStream(
    videoFormat: RealtimeVideoFormat(width: 704, height: 1280, fps: 24),
    position: .front
)

let videoView = XmaxRealtimeVideoView(
    localTrack: localStream.videoTrack,
    videoContentMode: .fill
)

let remoteStream = try await realtime.startGeneration(
    localStream: localStream,
    context: RealtimeContext(
        prompt: "视频中角色替换成参考图中角色",
        referencePath: "https://platform.xmaxai.com/images/source/charx/chatx_image1.jpg"
    )
)

videoView.remoteTrack = remoteStream.videoTrack

Add the video view to your view hierarchy. The view displays a local camera preview until the first generated frame arrives, with touch interaction enabled by default.

Using SwiftUI

Use XmaxRealtimeVideo as your primary SwiftUI view. Store the local and remote tracks in observable state, updating them dynamically as streams become available:

XmaxRealtimeVideo(
    localTrack: localTrack,
    remoteTrack: remoteTrack,
    videoContentMode: .fill
)

See the SwiftUI guide for state binding and the example project for a complete implementation.

Listen for events

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

Listener	Purpose
setStateListener	Observe pipeline states and termination reasons during real-time generation.
setRemoteVideoFrameListener	Receive generated frames for recording or custom processing.
setNetworkQualityListener	Monitor uplink and downlink network quality.
setPerformanceAlarmListener	Detect device performance limitations or recovery, with a suggested video format when available.

For example, monitor state changes and errors:

await realtime.setStateListener { state in
    print("State: \(state.connectionState.rawValue)")
    if case .failure(let error) = state.reason {
        print("Error: \(error.code.rawValue) \(error.message)")
    }
}

Handle errors thrown by async calls with do/catch. Failures that end the realtime workflow are also available through state.reason after cleanup completes.

For camera input, bind the returned video track to a preview view. The SDK enters ready after it has received a valid frame and the preview view is bound; observe this through setStateListener.

Resource Cleanup

• disconnect() — Stop Remote Generation

  Stops remote generation and cancels billing 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()

• 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, reference images, and touch interaction, see the usage guide.

Example Project

A complete example application featuring both UIKit and SwiftUI implementations is available in Examples/XLab. It demonstrates real-time generation using live camera feeds, static images, and local video files.

Dependencies

• VolcEngine RTC SDK for iOS 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.