アーキテクチャ

AIBuds SDK iOS は、それぞれの役割が明確に定義されたモジュール群で構成されています。 モジュール同士の関係を理解すると、必要なものだけを導入し、独自のプラグインで SDK を拡張しやすくなります。

アーキテクチャ概要

SDK は階層構造になっており、上位層は下位層に依存します。多くの階層で、 デバイス側（左）と AI 側（右）が対応しています。

システム構成

AIBuds SDK iOS アーキテクチャ

アプリ

AIBuds デバイスに接続する iOS アプリ

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（Objective-C では AIBudsDeviceConvertible）は、 アプリがデバイスの識別情報や状態を読み取り、ライフサイクル操作 （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

準備完了

デバイスがコマンドを受信できる状態です。

利用可能コマンドを受信可能

デバイスは、スキャンで検出 → 保存可能なデバイスへ変換 → ストレージへ保存 → 接続中 → 接続および準備完了、という 5 つの状態を遷移します。

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 には 2 種類のデリゲートがあります。必要なイベントの範囲に合わせて選択してください。

• DeviceDelegate（AIBudsDeviceDelegate）— デバイス単位。 device.delegate = self を設定すると、そのデバイスの接続ライフサイクルイベント （didStartConnectingDevice、didConnectedToDevice、 didFailToConnectDevice、device:didDisconnectWithError:、deviceDidReady）や、 バッテリー、動作モード、ANC、EQ、装着状態、TWS、音量、ストレージ、 メディア件数などの状態変化を受け取れます。すべてのメソッドは @objc optional なので、必要なコールバックだけ実装します。
• SDKDelegate（AIBudsSDKDelegate）— 全体。 AIBudsSDK.initialize(...delegate:) に渡すと、すべてのデバイスの接続イベントと、 スキャン状態（onScanningStatusChanged:）を受け取れます。

一般的には、スキャンや全体の接続 UI などアプリ単位の処理に 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	星芒 AI（字節跳動）
.mltcloud	駱方案 AI（美楽創）

ケース名は公開 Swift API と同じ表記です。.starBurst は大文字の B を使用し、 .mltcloud はすべて小文字です。

AIBudsAISDK.setAIServiceVendor(_:) で実行時にプロバイダーを切り替えられます。 このメソッドは AI サービスを使用する前に呼び出してください。

接続パラメータ

ConnectParams（AIBudsConnectParams）には、device.connect(_:) に必要な情報がまとめられています。 特に、接続ハンドシェイク中に SDK が AI サービスを認証するための 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 を組み込めます。

標準ログサービスは 4 つの出力先に対応しています。console、 oslogger、file、xlfacility です（最後の出力先には追加プラグインが必要です）。

AIBudsXLFacility

ログ出力を XLFacility に送る任意のログプラグインです。 通常のファイル出力よりも、ログの書き出し、検索、期限切れログの削除が容易なため、 本番環境で推奨される出力先です。

AIBudsFoundation

デバイス通信に関するデータモデル、型定義、補助データ構造を提供します。 デバイス SDK とアプリの双方が使用する共通の語彙に相当します。

AIBudsAIFoundation

AIBudsFoundation と同様の役割を AI 領域で担い、 すべての AI サービスで使用する基本データモデルと型定義を提供します。

コア SDK 層

AIBudsSDK

デバイス通信のコア SDK です。スキャン、接続、コマンド送信、イベント受信など、 デバイスに関する多くの機能はこのモジュールを通じて呼び出します。

ABMateSDK

AIBudsSDK が現在使用している BLE 通信プロトコルプラグインです。 プロトコルはプラグインとして読み込まれるため、BLE 通信が必要な場合に ABMateSDK を導入します。 今後ほかのプロトコルに対応した場合は、デバイスに合うものを読み込めます。

AIBudsAISDK

AI 機能のコア SDK です。プラグインシステムで複数の AI サービスプロバイダーを統合し、 実行時にプロバイダーを切り替えると、呼び出しが対応するサービス機能へ振り分けられます。

AI サービスプラグイン

AIBudsStarBurst

**星芒 AI（字節跳動）**向けのミドルウェアプラグインです。サービスの AI 機能をラップし、 AIBudsAISDK インターフェースから利用できるようにします。

AIBudsMagicHelper

**駱方案 AI（美楽創）**向けのミドルウェアプラグインです。サービスの AI 機能をラップし、 AIBudsAISDK インターフェースから利用できるようにします。

機能モジュール

AIBudsAudio

録音、再生、音声区間検出（VAD）などの音声機能を提供します。

AIBudsVoiceAssistant

オフライン音声認証プラグインです。デバイス上のウェイクワードと音声コマンド認識を扱います。 サービス認証が必要で、このミドルウェアが認証処理を仲介します。

AIBudsLiveStream

デバイス向けライブストリーミング SDK です。デバイスから RTSP ストリームを取得し、 対応する動画プレーヤーを提供するとともに、配信用の RTMP エンドポイントへストリームを送信します。

AIBudsCrashReporter

クラッシュログ収集 SDK です。アプリのクラッシュを検出してローカルディレクトリへ保存し、 クラッシュファイルのパスをコールバックで返します。アプリ側でサーバーへアップロードするなど、 必要な処理を行えます。

AIBudsAIDashboard

AI サービス分析用のダッシュボードです。ローカルネットワーク経由で表示でき、 AI 録音、同時通訳セッション、AI 対話などの記録を確認できます。 各記録では、関連するデバイス情報、起動パラメータ、処理中の音声データ、 セッションイベント、主要なエラーを確認でき、問題分析に役立ちます。

統合モジュール

AIBudsAllInOne

モジュール構成では SDK の初期化設定が複雑になりやすいため、AIBudsAllInOne は 実用的な標準設定をまとめています。1 回の呼び出しですべてを初期化できるため、 個別の導入構成が不要な場合に適しています。

プラグインモデル

SDK の拡張性は 4 種類のプラグインによって実現されています。それぞれ明確なプロトコルに準拠するため、 独自の 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