Архитектура

AIBuds SDK iOS состоит из модульных компонентов с чётко разделёнными обязанностями. Понимание связей между модулями поможет устанавливать только необходимые части SDK и расширять его собственными плагинами.

Общая схема архитектуры

SDK организован по слоям: верхние слои зависят от нижних, а на большинстве уровней часть для работы с устройством (слева) соответствует AI-части (справа).

Схема системы

Архитектура AIBuds SDK iOS

Ваше приложение

iOS-приложение, которое подключается к устройству AIBuds

AIBudsAllInOneНеобязательно

Дополнительная обёртка для упрощённой интеграции

Функциональные модули

Audio · VoiceAssistant · LiveStream · CrashReporter · AIBudsAIDashboard

AIBudsSDK

Ядро для устройств

AIBudsAISDK

Ядро AI

ABMateSDK(BLE)

Уровень протокола обмена по Core Bluetooth

StarBurst / MagicHelper

Интеграционные обёртки сторонних AI-сервисов

• StarBurst AI (ByteDance)
• MltCloud AI (Meilc)

AIBudsFoundation

Модели данных устройств

AIBudsAIFoundation

Модели данных AI

AIBudsLog

Общий модуль журналирования

AIBudsXLFacilityНеобязательно

Необязательный плагин журналирования

Общая структура AIBuds SDK iOS.

Слои сверху вниз: приложение → удобная обёртка → функциональные модули → ядро SDK (устройства и AI) → плагины протоколов → базовые модели данных → общее журналирование.

Модель устройства

Любое устройство, с которым работает SDK, представлено единым протоколом — DeviceConvertible (AIBudsDeviceConvertible в Objective-C). Через этот объект приложение получает идентификаторы и состояние устройства, а также выполняет операции жизненного цикла (connect, disconnect, unpair, save). Операции вызываются у самого экземпляра устройства, а не у глобального менеджера. DeviceConvertible поддерживает NSSecureCoding, поэтому объект можно архивировать и восстанавливать между запусками приложения.

Отдельный протокол FoundDeviceConvertible (AIBudsFoundDeviceConvertible) описывает устройство, только что найденное при сканировании. Он содержит данные Core Bluetooth (central + peripheral + advertisementData + RSSI), но ещё не пригоден для сохранения. Вызовите AIBudsSDK.makeStorableDeviceFromDiscovered(_:), чтобы получить сохраняемый объект DeviceConvertible.

Жизненный цикл устройства

Жизненный цикл устройства

От обнаружения по Bluetooth до готовности принимать команды.

СканированиеПоиск устройств по Bluetooth

01Рядом

D

Обнаружено

Сканер обнаружил устройство по его рекламным пакетам.

AIBudsSDK.makeStorableDeviceFromDiscovered(_:)Создать сохраняемую модель

02Локально

S

Готово к сохранению

Данные устройства приведены к формату для локального хранения.

StoredDevicesMgr.addDevice

03Сохранено

P

Сохранено

Устройство остаётся доступным после перезапуска приложения.

device.connect(ConnectParams)

04Выполняется

C

Подключение

Выполняются аутентификация и согласование параметров.

deviceDidReadyВызов делегата

05В сети

R

Готово

Устройство готово принимать команды.

ДоступноГотово принимать команды

Устройство проходит пять состояний: обнаружено при сканировании → преобразовано в сохраняемый объект → записано в хранилище → подключается → подключено и готово.

StoredDevicesMgr (AIBudsStoredDevicesMgr) управляет списком сохранённых устройств — addDevice, removeDevice, allDevices, findDevice(byMacAddr:), findDevice(byPeripheral:). При запуске вызовите loadDevicesInBackground, чтобы восстановить сохранённые устройства, включая кандидатов на автоподключение.

Протоколы возможностей

Устройства поддерживают разные наборы функций, поэтому каждая возможность описана отдельным протоколом, а не единым громоздким интерфейсом. Все такие протоколы наследуют общий маркер DeviceAPI (AIBudsDeviceAPI):

Протокол	Возможность
DeviceInfoAPI	Заряд, возможности, аппаратная конфигурация, язык, хранилище, число медиафайлов, синхронизация и установка времени
DeviceCommonAPI	Сброс настроек и выключение
DeviceFindAPI	Поиск устройства и остановка поиска
DeviceWorkModeAPI / DeviceWorkStateAPI	Режим и состояние работы
DeviceVolumeControlAPI	Получение и установка громкости
DeviceEqualizerAPI	Настройки эквалайзера
DeviceANCAPI	Режим ANC, усиление, прозрачность и плавное переключение
DeviceWearDetectionAPI	Поддержка и состояние распознавания ношения
DeviceTWSAPI	Состояние подключения TWS
DeviceMusicControlAPI	Воспроизведение, пауза, переключение треков и громкость
DeviceAudioRecordingAPI	Обычная и AI-запись звука, максимальная длительность
DeviceCameraAPI	Фото, видео и прошивка камеры
DeviceRemoteShutterAPI	Синхронизация дистанционного затвора
DeviceFileImportAPI	Получение, импорт и удаление медиафайлов
DeviceOtaAPI / DeviceCameraOtaAPI	Обновление прошивки
DeviceAppsAPI	Запуск и остановка приложений устройства
DeviceServiceAuthAPI	Повторная авторизация сервисов и передача результата
DevicePhysicalOperationsAPI	Назначение функций физическим действиям
LiveStreamingAPI	Прямые трансляции RTSP и JPEG
OnDeviceVoiceAssistantAPI	Офлайн-голосовой помощник

Для вызова возможности приведите устройство к соответствующему протоколу и проверьте результат: если нужного оборудования нет, приведение типа завершится неудачей.

Swift

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

Objective-C

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

Делегаты

SDK предлагает два уровня делегирования — выберите подходящий по области получаемых событий.

• DeviceDelegate (AIBudsDeviceDelegate) — для отдельного устройства. Назначьте его через device.delegate = self, чтобы получать события подключения именно этого устройства (didStartConnectingDevice, didConnectedToDevice, didFailToConnectDevice, device:didDisconnectWithError:, deviceDidReady) и изменения его состояния (заряд, режим работы, ANC, EQ, ношение, TWS, громкость, хранилище, число медиафайлов и другие). Все методы объявлены как @objc optional: реализуйте только нужные обработчики.
• SDKDelegate (AIBudsSDKDelegate) — глобальный. Он передаётся в AIBudsSDK.initialize(...delegate:), дублирует события подключения всех устройств и сообщает о состоянии сканирования (onScanningStatusChanged:).

Обычно SDKDelegate используют для задач уровня приложения (сканирование и общий интерфейс подключения), а DeviceDelegate — на экране конкретного устройства.

Основные синглтоны

Синглтон	Область	Основные точки входа
AIBudsSDK	Устройства	initialize(bleSDKs:configuration:delegate:), startScanning, stopScanning, isScanning(), makeStorableDeviceFromDiscovered(_:), сеттеры плагинов AI и голосового помощника
AIBudsAISDK	AI	initialize(aiSDKs:), setAIServiceVendor(_:), startAIChat, startAIAudioRecording, startSimultaneousInterpretation, translateText, summary, recognizeVoice, synthesizeText

Операции с устройством (подключение, отключение и отправка команд) не относятся к этим синглтонам — они вызываются непосредственно у DeviceConvertible.

Поставщик AI-сервисов

AI-возможности предоставляются подключаемым поставщиком сервисов. Выбранный поставщик представлен перечислением AIServiceVendor (AIBudsAIServiceVendor):

Вариант	Поставщик сервисов
.none	Поставщик не выбран
.starBurst	Сервис StarBurst AI (ByteDance)
.mltcloud	Сервис MltCloud AI (Meilc)

Имена вариантов полностью соответствуют открытому Swift API: в .starBurst используется заглавная B, а .mltcloud записывается только строчными буквами.

Сменить поставщика во время выполнения можно через AIBudsAISDK.setAIServiceVendor(_:). Вызов должен произойти до первого обращения к AI-сервису.

Параметры подключения

ConnectParams (AIBudsConnectParams) содержит всё необходимое для device.connect(_:), в том числе параметры авторизации AI, с которыми SDK выполняет аутентификацию у поставщиков AI-сервисов во время установки соединения:

• userId — идентификатор конечного пользователя на стороне поставщика AI-сервисов.
• aiAuthParams (AIAuthParams / AIBudsAIAuthParams) — хранит учётные данные для каждого поставщика:
  • starburst (StarBurstAIAuthParams): productId, необязательный ppeEnv
  • mltcloud (MltCloudAIAuthParams): channelId

Swift

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

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];

Справочник модулей

Базовый слой

AIBudsLog

Основной модуль журналирования, используемый во всём AIBuds SDK. Остальные модули записывают журналы через него. Все реализации LogService поддерживают протокол LogService, поэтому стандартную реализацию можно заменить собственной, если она лучше подходит приложению.

Стандартный сервис поддерживает четыре назначения вывода: console, oslogger, file и xlfacility (для последнего нужен дополнительный плагин).

AIBudsXLFacility

Необязательный плагин, который направляет журналы через XLFacility. По сравнению с обычной записью в файл XLFacility упрощает экспорт, поиск и удаление устаревших журналов, поэтому этот вариант рекомендуется для рабочих сборок.

AIBudsFoundation

Модели данных, определения типов и вспомогательные структуры для обмена с устройствами. Это общий словарь, на который опираются SDK устройств и приложение.

AIBudsAIFoundation

Аналог AIBudsFoundation для AI: здесь определены базовые модели данных и типы, общие для всех поставщиков AI-сервисов.

Слой ядра SDK

AIBudsSDK

Ядро обмена с устройствами. Через этот модуль выполняется большинство операций: сканирование, подключение, отправка команд и получение событий.

ABMateSDK

Плагин протокола BLE, который сейчас используется AIBudsSDK. Поскольку протоколы подключаются как плагины, для обмена по BLE необходимо установить ABMateSDK. При появлении других протоколов можно будет загрузить вариант, подходящий конкретному устройству.

AIBudsAISDK

Ядро AI-функций. Через систему плагинов оно координирует работу нескольких поставщиков AI-сервисов: поставщика можно сменить во время выполнения, после чего вызовы направляются к соответствующим возможностям.

Плагины поставщиков AI-сервисов

AIBudsStarBurst

Плагин-посредник для StarBurst AI (ByteDance). Оборачивает возможности поставщика и предоставляет их через интерфейс AIBudsAISDK.

AIBudsMagicHelper

Плагин-посредник для MltCloud AI (Meilc). Оборачивает возможности поставщика и предоставляет их через интерфейс AIBudsAISDK.

Функциональные модули

AIBudsAudio

Возможности для работы со звуком: запись, воспроизведение и обнаружение голосовой активности (VAD).

AIBudsVoiceAssistant

Плагин авторизации офлайн-голосового помощника. Обрабатывает локальное распознавание фразы активации и голосовых команд. Для работы нужна авторизация сервиса, которую выполняет этот промежуточный модуль.

AIBudsLiveStream

SDK для прямых трансляций с устройства. Получает поток RTSP с устройства, предоставляет видеоплеер и отправляет поток на конечную точку RTMP для вещания.

AIBudsCrashReporter

SDK для сбора отчётов о сбоях. Перехватывает сбои приложения, сохраняет отчёт локально и передаёт путь к файлу в обработчик, чтобы приложение могло загрузить его на сервер или обработать иным способом.

AIBudsAIDashboard

Диагностическая панель AI-сервисов, доступная по локальной сети. Она позволяет просматривать записи AI, сеансы синхронного перевода, AI-диалоги и другие данные. Для каждой записи доступны сведения об устройстве, параметры запуска, передаваемый звук, события сеанса и основные ошибки, что упрощает анализ отклонений.

Удобная интеграция

AIBudsAllInOne

Поскольку настройка инициализации при модульной архитектуре может быть объёмной, AIBudsAllInOne предоставляет разумную конфигурацию по умолчанию и позволяет инициализировать все компоненты одним вызовом — удобно, когда особая схема установки не требуется.

Модель плагинов

Расширяемость SDK обеспечивают четыре вида плагинов. Каждый реализует чётко определённый протокол, поэтому можно создать собственный плагин — например, для нестандартного протокола BLE или внутреннего поставщика AI-сервисов — и загрузить его вместе со встроенными плагинами либо вместо них:

Тип плагина	Протокол	Где загружается	Пример
Протокол BLE	BleConnectSDK	AIBudsSDK.initialize(bleSDKs:...)	ABMateSDK
Поставщик AI	AIConnectSDK	AIBudsAISDK.initialize(aiSDKs:...)	StarBurstSDK, MagicHelperSDK
Мост AI/голоса	StarBurstBridgePlugin, MltCloudBridgePlugin, OnDeviceVoiceAssistantBridgePlugin	AIBudsSDK.setStarBurstAIPlugin(...) / setMltCloudAIPlugin(...) / setOnDeviceVoiceAssistantPlugin(...)	Реализация вашего плагина авторизации
Система журналирования	LogService	AIBudsLogSDK.setXLFacilityPlugin(...)	AIBudsXLFacility