아키텍처

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의 전체 구조를 확인합니다.

위에서 아래 순서로 앱 → 통합 래퍼 → 기능 모듈 → Core SDK(기기 영역 + AI 영역) → 프로토콜 플러그인 → Foundation 데이터 모델 → 공통 로깅 계층으로 이어집니다.

기기 모델

SDK가 다루는 모든 기기는 하나의 프로토콜인 DeviceConvertible (Objective-C에서는 AIBudsDeviceConvertible)로 표현됩니다. 앱은 이 객체를 통해 기기 식별 정보와 상태를 읽고 수명 주기 작업(connect, disconnect, unpair, save)을 수행합니다. 작업은 관리 싱글턴이 아니라 기기 인스턴스에서 직접 호출합니다. DeviceConvertible은 NSSecureCoding을 준수하므로 앱 실행 사이에 보관하고 복원할 수 있습니다.

별도 프로토콜인 FoundDeviceConvertible (Objective-C에서는 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:)를 알립니다.

일반적으로 앱 수준 작업(스캔, 전역 연결 UI)에는 SDKDelegate를 사용하고, 특정 기기를 관리하는 화면에는 DeviceDelegate를 사용합니다.

Core 싱글턴

싱글턴	범위	주요 진입점
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) 열거형으로 표현됩니다.

Case	서비스 제공자
.none	선택한 서비스 제공자 없음
.starBurst	StarBurst AI(ByteDance) 서비스
.mltcloud	MltCloud AI(Meilc) 서비스

Case 표기는 공개 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];

모듈 구성

Foundation 계층

AIBudsLog

AIBuds SDK 전체에서 사용하는 Core 로깅 모듈입니다. 다른 모든 모듈은 이 모듈을 통해 로그를 기록합니다. 모든 로그 구현은 LogService 프로토콜을 준수하므로 기본 구현이 적합하지 않다면 자체 LogService를 연결할 수 있습니다.

기본 로그 서비스는 네 가지 출력 대상인 console, oslogger, file, xlfacility를 지원합니다. 마지막 항목에는 추가 플러그인이 필요합니다.

AIBudsXLFacility

로그 출력을 XLFacility로 전달하는 선택적 로그 플러그인입니다. 일반 파일 출력보다 로그 내보내기, 검색, 만료 로그 삭제가 훨씬 편리하므로 운영 환경에 권장되는 로그 대상입니다.

AIBudsFoundation

기기 통신과 관련된 데이터 모델, 형식 정의, 보조 데이터 구조를 제공합니다. 기기 SDK와 앱이 함께 사용하는 공통 용어 계층으로 이해할 수 있습니다.

AIBudsAIFoundation

AIBudsFoundation과 비슷하지만 AI 영역을 담당합니다. 모든 AI 서비스 제공자가 공통으로 사용하는 기본 데이터 모델과 형식을 정의합니다.

Core SDK 계층

AIBudsSDK

기기 통신 Core SDK입니다. 스캔, 연결, 명령 전송, 이벤트 수신 등 기기 관련 기능 대부분이 이 모듈을 통해 호출됩니다.

ABMateSDK

현재 AIBudsSDK에서 사용하는 BLE 통신 프로토콜 플러그인입니다. 프로토콜을 플러그인으로 불러오므로 BLE 통신이 필요할 때 ABMateSDK를 설치합니다. 향후 다른 프로토콜을 지원하면 기기에 맞는 구현을 선택하여 불러올 수 있습니다.

AIBudsAISDK

AI 기능 Core SDK입니다. 플러그인 시스템을 통해 여러 AI 서비스 제공자를 조정합니다. 실행 중 제공자를 바꾸면 내부 호출이 해당 제공자의 기능으로 전달됩니다.

AI 서비스 제공자 플러그인

AIBudsStarBurst

**StarBurst AI (ByteDance)**용 미들웨어 플러그인입니다. 서비스 제공자의 AI 기능을 래핑하여 AIBudsAISDK 인터페이스로 제공합니다.

AIBudsMagicHelper

**MltCloud AI (Meilc)**용 미들웨어 플러그인입니다. 서비스 제공자의 AI 기능을 래핑하여 AIBudsAISDK 인터페이스로 제공합니다.

기능 모듈

AIBudsAudio

녹음, 재생, 음성 활동 감지(Voice Activity Detection, VAD) 등 오디오 기능을 제공합니다.

AIBudsVoiceAssistant

오프라인 음성 인증 플러그인입니다. 기기의 깨우기 명령과 음성 명령 인식을 처리합니다. 서비스 인증이 필요하며 이 미들웨어가 인증을 중계합니다.

AIBudsLiveStream

기기 라이브 스트리밍 SDK입니다. 기기에서 RTSP 스트림을 가져와 대응하는 동영상 플레이어를 제공하고, 송출을 위해 스트림을 RTMP 엔드포인트로 전달합니다.

AIBudsCrashReporter

앱 충돌 로그 수집 SDK입니다. 충돌을 수집해 로컬 디렉터리에 저장하고 충돌 파일 경로를 콜백으로 전달하므로 앱에서 서버에 업로드하거나 필요한 방식으로 처리할 수 있습니다.

AIBudsAIDashboard

AI 서비스 진단 대시보드입니다. 로컬 네트워크에서 AI 녹음, 동시통역 세션, AI 대화 등 AI 관련 기록을 확인할 수 있습니다. 각 기록에서 연결된 기기 정보, 시작 매개변수, 처리 중인 오디오 데이터, 세션 이벤트, 주요 오류를 확인하여 이상 동작을 더 쉽게 분석할 수 있습니다.

통합 모듈

AIBudsAllInOne

모듈형 아키텍처에서는 SDK 초기화 설정이 다소 복잡할 수 있습니다. AIBudsAllInOne은 합리적인 기본 구성을 묶어 한 번의 호출로 전체 SDK를 초기화할 수 있게 합니다. 사용자 지정 설치가 필요하지 않을 때 적합합니다.

플러그인 모델

SDK는 네 종류의 플러그인으로 확장됩니다. 각 플러그인은 명확한 프로토콜을 준수하므로 자체 BLE 프로토콜 플러그인이나 전용 AI 서비스 제공자 등을 구현하여 내장 구현과 함께 또는 내장 구현 대신 불러올 수 있습니다.

플러그인 유형	프로토콜	로드하는 API	예시
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