Core Concepts Architecture

Architecture

The AIBuds SDK iOS is built as a collection of modular components, each with a clearly defined responsibility. Understanding how these modules fit together will help you install only what you need and extend the SDK with your own plugins.

Architecture at a Glance

The SDK is organized in layers — top layers depend on bottom layers, and the device side (left) mirrors the AI side (right) at most levels.

• Your App — Your iOS app which will connect to the AIBuds device
• AIBudsAllInOne — Optional Convenience Wrapper
• Feature Modules — Audio · VoiceAssistant · LiveStream · CrashReporter · AIBudsAIDashboard
• AIBudsSDK — Device core
• AIBudsAISDK — AI core
• ABMateSDK(BLE) — Core Bluetooth Communication Protocol Layer
• StarBurst / MagicHelper — Third-party AI Service Convenience Wrapper
• AIBudsFoundation — Device data models
• AIBudsAIFoundation — AI data models
• AIBudsLog — Cross-cutting logging module
• AIBudsXLFacility — Optional log plugin

Layers from top to bottom: your app → convenience wrapper → feature modules → core SDK (device side + AI side) → protocol plugins → foundation data models → cross-cutting logging.

Device Model

Every device the SDK touches is represented by one protocol — DeviceConvertible (AIBudsDeviceConvertible in Objective-C). It is the single handle through which your app reads device identity and state, and through which it performs lifecycle operations (connect, disconnect, unpair, save). Operations are called on the device instance itself, not through a manager singleton. DeviceConvertible conforms to NSSecureCoding, so it can be archived and restored across app launches.

A separate protocol, FoundDeviceConvertible (AIBudsFoundDeviceConvertible), describes a device that has just been discovered by scanning — it wraps the Core Bluetooth trio (central + peripheral + advertisementData + RSSI) but is not yet storable. Convert it with AIBudsSDK.makeStorableDeviceFromDiscovered(_:) to get a DeviceConvertible you can persist.

Device lifecycle

1. Discovered — The scanner has found an advertising device.
2. Storable — The device is normalized for local storage.
3. Persisted — The device remains available across launches.
4. Connecting — Authentication and negotiation are underway.
5. Ready — The device can now receive commands.

The device flows through five states: discovered by scanning → converted to a storable device → persisted to storage → connecting → connected and ready.

StoredDevicesMgr (AIBudsStoredDevicesMgr) owns the persisted device list — addDevice, removeDevice, allDevices, findDevice(byMacAddr:), findDevice(byPeripheral:). Call loadDevicesInBackground on launch to restore previously saved devices (including auto-reconnect candidates).

Capability Protocols

Not every device supports every feature, so capabilities are modeled as individual protocols rather than one monolithic device interface. They all conform to a common marker, DeviceAPI (AIBudsDeviceAPI):

Protocol	Capability
DeviceInfoAPI	Battery, capabilities, hardware configuration, language, storage, media count, sync/set time
DeviceCommonAPI	Factory reset, power off
DeviceFindAPI	Find device / stop find
DeviceWorkModeAPI / DeviceWorkStateAPI	Work mode / work state
DeviceVolumeControlAPI	Volume get / set
DeviceEqualizerAPI	Equalizer settings
DeviceANCAPI	ANC mode, gain, transparency, fade
DeviceWearDetectionAPI	Wear detection capability and status
DeviceTWSAPI	TWS connection status
DeviceMusicControlAPI	Play / pause / next / previous / volume
DeviceAudioRecordingAPI	Normal & AI audio recording, max duration
DeviceCameraAPI	Photo / video capture, camera firmware
DeviceRemoteShutterAPI	Remote shutter sync
DeviceFileImportAPI	Media file fetch / import / delete
DeviceOtaAPI / DeviceCameraOtaAPI	Firmware update
DeviceAppsAPI	Device applications start / stop
DeviceServiceAuthAPI	Service auth retry & result reporting
DevicePhysicalOperationsAPI	Physical operation key mapping
LiveStreamingAPI	RTSP / JPEG live streaming
OnDeviceVoiceAssistantAPI	On-device voice assistant

To call a capability, cast the device to the corresponding protocol and check for conformance — a device that lacks the hardware simply fails the cast:

Swift

if let info = device as? DeviceInfoAPI {
    info.setDeviceTime(Date()) { success, statusCode, error in
        // ...
    }
}

if let anc = device as? DeviceANCAPI {
    anc.setAncMode(.ancOn) { _ in }
}

Objective-C

if ([device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)device;
    [info setDeviceTime:[NSDate date]
             completion:^(BOOL success, NSNumber *statusCode, NSError *error){
                 // ...
             }];
}

Delegates

The SDK has two layers of delegation — choose the one that matches the scope of the events you need.

• DeviceDelegate (AIBudsDeviceDelegate) — per-device. Assign it via device.delegate = self to receive that specific device's connection lifecycle events (didStartConnectingDevice, didConnectedToDevice, didFailToConnectDevice, device:didDisconnectWithError:, deviceDidReady) and its state-change events (battery, work mode, ANC, EQ, wear status, TWS, volumes, storage, media count, and many more). All methods are @objc optional — implement only the callbacks you need.
• SDKDelegate (AIBudsSDKDelegate) — global. Passed to AIBudsSDK.initialize(...delegate:), it mirrors the connection events across all devices and also reports scanning status (onScanningStatusChanged:).

A common setup is to use SDKDelegate for app-level concerns (scanning, global connection UI) and DeviceDelegate for the screen that owns a specific device.

Core Singletons

Singleton	Scope	Key entry points
AIBudsSDK	Device side	initialize(bleSDKs:configuration:delegate:), startScanning, stopScanning, isScanning(), makeStorableDeviceFromDiscovered(_:), AI/voice plugin setters
AIBudsAISDK	AI side	initialize(aiSDKs:), setAIServiceVendor(_:), startAIChat, startAIAudioRecording, startSimultaneousInterpretation, translateText, summary, recognizeVoice, synthesizeText

Device operations (connect, disconnect, send commands) are not on these singletons — they are called on the DeviceConvertible instance directly.

AI Service Provider

AI capabilities are supplied by a pluggable service provider. The selected provider is represented by the AIServiceVendor (AIBudsAIServiceVendor) enum:

Case	Service Provider
.none	No provider selected
.starBurst	StarBurst AI (ByteDance)
.mltcloud	MltCloud AI (Meilc)

The case spelling follows the public Swift API exactly: .starBurst uses an uppercase B, while .mltcloud is entirely lowercase.

Switch providers at runtime with AIBudsAISDK.setAIServiceVendor(_:). This must be called before any AI service is used.

Connection Parameters

ConnectParams (AIBudsConnectParams) packages everything device.connect(_:) needs for a connection — most notably the AI auth parameters that let the SDK authenticate with your AI providers during the connection handshake:

• userId — identifies the end user on the AI provider side.

• aiAuthParams (AIAuthParams / AIBudsAIAuthParams) — holds per-provider credentials:

  • starburst (StarBurstAIAuthParams): productId, optional ppeEnv
  • mltcloud (MltCloudAIAuthParams): channelId

  Swift

let params = ConnectParams()
let auth = AIAuthParams()

let starBurst = StarBurstAIAuthParams()
starBurst.productId = configs["STARBURST_PRODUCTID"]
auth.starburst = starBurst

let mltCloud = MltCloudAIAuthParams()
mltCloud.channelId = configs["MLTCLOUD_CHANNELID"]
auth.mltcloud = mltCloud

params.aiAuthParams = auth
params.userId = "199"

device.connect(params)

Objective-C

AIBudsConnectParams *params = [AIBudsConnectParams new];
AIBudsAIAuthParams *auth = [AIBudsAIAuthParams new];

AIBudsStarBurstAIAuthParams *starBurst = [AIBudsStarBurstAIAuthParams new];
starBurst.productId = configs[@"STARBURST_PRODUCTID"];
auth.starburst = starBurst;

AIBudsMltCloudAIAuthParams *mltCloud = [AIBudsMltCloudAIAuthParams new];
mltCloud.channelId = configs[@"MLTCLOUD_CHANNELID"];
auth.mltcloud = mltCloud;

params.aiAuthParams = auth;
params.userId = @"199";

[device connectWithParams:params];

Module Reference

Foundation Layer

AIBudsLog

The logging core module that runs through the entire AIBuds SDK. Every other module records logs through it. LogService is the protocol all log implementations conform to, so you can plug in your own LogService if the defaults don't suit you.

The default log service already supports four output destinations — console, oslogger, file, and xlfacility (the latter requires an additional plugin).

AIBudsXLFacility

An optional log plugin that routes log output through XLFacility. Compared with the plain file destination, XLFacility makes it much easier to export, query, and purge expired logs — this is the recommended log destination for production.

AIBudsFoundation

Data models, type definitions, and auxiliary data structures related to device communication. Think of it as the shared vocabulary that the device SDK and your app both rely on.

AIBudsAIFoundation

Similar to AIBudsFoundation, but scoped to AI-related business — it defines the base data models and type definitions used across all AI providers.

Core SDK Layer

AIBudsSDK

The device communication core SDK. Most device-related functionality — scanning, connecting, sending commands, receiving events — is invoked through this module.

ABMateSDK

The BLE communication protocol plugin currently used by AIBudsSDK. Because protocols are loaded as plugins, you install ABMateSDK when you need BLE communication. If additional protocols are supported in the future, you will be able to load the one that matches your device.

AIBudsAISDK

The AI functionality core SDK. It orchestrates multiple AI service providers through a plugin system — switch providers at runtime and the underlying calls route to the corresponding provider's capabilities.

AI Provider Plugins

AIBudsStarBurst

Middleware plugin for StarBurst AI (ByteDance). Wraps the provider's AI capabilities and exposes them through the AIBudsAISDK interface.

AIBudsMagicHelper

Middleware plugin for MltCloud AI (Meilc). Wraps the provider's AI capabilities and exposes them through the AIBudsAISDK interface.

Feature Modules

AIBudsAudio

Audio-related functionality: recording, playback, and Voice Activity Detection (VAD).

AIBudsVoiceAssistant

Offline voice authentication plugin. Handles on-device wake-word and voice command recognition. Requires service authorization, which is mediated through this middleware.

AIBudsLiveStream

Device live-streaming SDK. Pulls an RTSP stream from the device, provides a corresponding video player, and pushes the stream to an RTMP endpoint for broadcasting.

AIBudsCrashReporter

Crash log collection SDK. Captures app crashes, saves them to a local directory, and invokes a callback with the crash file path so your app can upload it to your server or handle it as needed.

AIBudsAIDashboard

A diagnostic dashboard for AI services. Viewable over the local network, it lets you inspect AI-related records — AI recordings, simultaneous interpretation sessions, AI conversations, and more. For each record you can see the associated device info, startup parameters, in-flight audio data, session events, and key errors, making it easier to analyze anomalies.

Convenience

AIBudsAllInOne

Because the modular architecture makes SDK initialization configuration somewhat involved, AIBudsAllInOne bundles a sane default configuration so you can initialize everything in one call — ideal when you don't need a custom installation.

Plugin Model

Four kinds of plugins drive the SDK's extensibility. Each conforms to a well-defined protocol, so you can write your own — for example, a custom BLE protocol plugin or a proprietary AI provider — and load it alongside or instead of the built-in ones:

Plugin type	Protocol	Loaded by	Example
BLE protocol	BleConnectSDK	AIBudsSDK.initialize(bleSDKs:...)	ABMateSDK
AI provider	AIConnectSDK	AIBudsAISDK.initialize(aiSDKs:...)	StarBurstSDK, MagicHelperSDK
AI / voice bridge	StarBurstBridgePlugin, MltCloudBridgePlugin, OnDeviceVoiceAssistantBridgePlugin	AIBudsSDK.setStarBurstAIPlugin(...) / setMltCloudAIPlugin(...) / setOnDeviceVoiceAssistantPlugin(...)	Your auth plugin implementation
Log backend	LogService	AIBudsLogSDK.setXLFacilityPlugin(...)	AIBudsXLFacility