설치

AIBuds SDK는 CocoaPods로 설치합니다. 앱에 필요한 기능이 정해지지 않았다면 전체 설치부터 시작하세요.

요구 사항

• iOS 13.0 이상
• Xcode 26.0 이상
• CocoaPods 1.16.0 이상

설치 방식 선택

권장

전체 설치

AIBudsSDK/AllInOne으로 기기 연결, AI 서비스, 음성 어시스턴트, 미디어, 진단 및 기타 선택 SDK 구성 요소를 함께 설치합니다.

최소 의존성

모듈별 설치

제품에서 사용할 기능만 선택합니다. 필요한 SDK 계층과 타사 의존성은 CocoaPods가 자동으로 설치합니다.

AI 지원 설정

AI 코딩 어시스턴트로 통합

설치 방식을 선택한 다음 프로젝트 작업 공간에서 간결한 프롬프트를 AI 어시스턴트에 붙여 넣으세요.

AIBudsSDK/AllInOne으로 전체 SDK를 설치합니다.

https://docs-aibuds.github.io/ko/skills/integrate-aibuds-sdk을 읽고 지침을 따르세요. AIBudsSDK/AllInOne을 이 iOS 프로젝트에 통합하고 검증하세요.

AIBuds Skills 보기↗

1단계: Podfile에 SDK 추가

각 AIBudsSDK Pod 선언에는 Git 소스:

Ruby

:git => 'https://github.com/topstepsmart/AIBuds-SDK-iOS.git'

또는 로컬 SDK 경로를 지정해야 합니다:

Ruby

:path => '../AIBuds-SDK-iOS'

아래 예제에서는 source 지정을 생략했습니다. 프로젝트에 맞는 형식을 추가하세요.

전체 설치

Ruby

platform :ios, '13.0'

target 'YourTargetName' do
  pod 'AIBudsSDK/AllInOne'
end

모듈별 설치

Ruby

platform :ios, '13.0'

target 'YourTargetName' do
  # Device connectivity.
  pod 'AIBudsSDK/ABMate'

  # Choose one AI provider.
  pod 'AIBudsSDK/AI/StarBurst'
  # pod 'AIBudsSDK/AI/MltCloud'

  # Add only the optional capabilities your product enables.
  # pod 'AIBudsSDK/VoiceAssistant'      # On-device voice assistant
  # pod 'AIBudsSDK/LiveStream'          # RTSP playback and RTMP streaming
  # pod 'AIBudsSDK/VideoStabilization'  # Imported six-axis video
  # pod 'AIBudsSDK/FitCloudProOTA'      # FitCloud Pro OTA devices
  # pod 'AIBudsSDK/JieliOTA'            # Jieli single-bank OTA devices
  # pod 'AIBudsSDK/Log/XLFacility'      # Persistent logs
  # pod 'AIBudsSDK/AI/Dashboard'        # Local AI diagnostics
  # pod 'AIBudsSDK/CrashReporter'       # Persisted crash reports
end

전체 모듈 목록 보기

Ruby

# Installing only AIBudsSDK selects Core.
# It does not include ABMate, an AI provider, or optional features.
pod 'AIBudsSDK'

# Base SDK types, Bluetooth orchestration, models, and protocols.
# Includes: Foundation, Log/Core
pod 'AIBudsSDK/Core'

# ABMate BLE device communication.
# Includes: Core, GCDWebServer, libopus
pod 'AIBudsSDK/ABMate'

# Shared audio-session and voice-activity processing for AI.
# Includes: Core, tenVad
pod 'AIBudsSDK/Audio'

# Core logging without the XLFacility backend.
# Includes: zipzap
pod 'AIBudsSDK/Log/Core'

# Persistent logging and local log-browser integration.
# Includes: Log/Core, iOSLogBrowserSDK
pod 'AIBudsSDK/Log/XLFacility'

Ruby

# Optional OTA protocol plugins. Install only the implementations required by
# your devices, then register each plugin before connecting a device.
pod 'AIBudsSDK/FitCloudProOTA'
pod 'AIBudsSDK/JieliOTA'

Ruby

# AI facade, sessions, reports, and provider routing.
# Includes: AI/Foundation, Core, WCDB.swift
pod 'AIBudsSDK/AI/Core'

# StarBurst AI services.
# Includes: AI/Core, Audio, StarBurst SDK, LAME, libopus, libogg
pod 'AIBudsSDK/AI/StarBurst'

# MLTCloud AI services.
# Includes: AI/Core, Audio, MagicHelper, Microsoft Speech, LAME, libopus, libogg
pod 'AIBudsSDK/AI/MltCloud'

# Local AI diagnostic dashboard.
# Includes: AI/Core, WCDB.swift, GCDWebServer, YYWebImage, iOSLogBrowserSDK
pod 'AIBudsSDK/AI/Dashboard'

Ruby

# On-device voice assistant authentication bridge.
# Includes: Core, MZEncryptSDK, OpenSSL
pod 'AIBudsSDK/VoiceAssistant'

# Persisted crash-report capture and access.
# Includes: CrashReporter framework
pod 'AIBudsSDK/CrashReporter'

# Native RTSP playback and RTMP streaming.
# Includes: Log, FFmpeg, LiveStream resource bundle
pod 'AIBudsSDK/LiveStream'

# Post-processing for imported six-axis video.
# Includes: Core, bundled AWEISIMG implementation
pod 'AIBudsSDK/VideoStabilization'

여러 기능을 묶은 subspec

Ruby

# Log/Core + Log/XLFacility
pod 'AIBudsSDK/Log'

# AI/Foundation + AI/Core + both providers + AI/Dashboard
pod 'AIBudsSDK/AI'

# Log + ABMate + FitCloudProOTA + JieliOTA + AI + VoiceAssistant
# + CrashReporter + LiveStream + VideoStabilization
pod 'AIBudsSDK/AllInOne'

# Do not normally select these implementation layers directly:
# AIBudsSDK/Foundation
# AIBudsSDK/AI/Foundation
# AIBudsSDK/ThirdParty/*

2단계: 필수 Podfile hook 추가

다음 블록을 Podfile에 한 번만 추가하세요. 필요한 dynamic framework를 설정하고, 지원되지 않는 private header import를 제거하며, 바이너리 배포 호환성을 활성화합니다.

Ruby

dynamic_frameworks = ['AFNetworking', 'WCDB.swift', 'WCDBOptimizedSQLCipher', 'SocketRocket']
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if dynamic_frameworks.include?(pod.name)
      def pod.static_framework?; false; end
      def pod.build_type; Pod::BuildType.dynamic_framework; end
    end
  end
end

def patch_private_header(installer, pod_subdir_pairs)
  pod_subdir_pairs.each do |pod_name, sub_dir|
    target_dir = sub_dir ? File.join(installer.sandbox.pod_dir(pod_name), sub_dir) : installer.sandbox.pod_dir(pod_name)
    puts target_dir
    next unless Dir.exist?(target_dir)

    private_header_import = '#import <netinet6/in6.h>'
    Dir.glob(File.join(target_dir, '**', '*.{h,m}')).each do |file_path|
      puts file_path
      next unless File.exist?(file_path)

      file_content = File.read(file_path)
      next unless file_content.include?(private_header_import)

      original_mode = File.stat(file_path).mode
      File.chmod(original_mode | 0o200, file_path)
      File.write(file_path, file_content.gsub(private_header_import, ''))
      File.chmod(original_mode, file_path)
      puts "patched #{pod_name} private header import: #{File.basename(file_path)}"
    end
  end
end

post_install do |installer|
  patch_private_header(installer, {'AFNetworking' => 'AFNetworking', 'Reachability' => nil })
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

3단계: 설치 후 workspace 열기

CocoaPods를 실행한 뒤 .xcodeproj가 아닌 생성된 workspace를 여세요:

BASH

pod install
open YourProject.xcworkspace

4단계: 권한 추가

기기 연결에 필요한 권한

Info.plist에 두 Bluetooth 사용 목적을 모두 추가하세요:

XML

<key>NSBluetoothWhileInUseUsageDescription</key>
<string>Your app needs Bluetooth access while in use to connect to AIBuds devices.</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Your app needs Bluetooth access to communicate with AIBuds devices.</string>

Bluetooth key 중 하나라도 없으면 AIBudsSDK.initialize는 false를 반환합니다.

사용하는 기능에만 추가할 항목

기능	추가 설정
iPhone에서 오디오 수집	마이크 사용 목적
라이브 스트리밍, Camera OTA 또는 기기 hotspot을 통한 미디어 다운로드	로컬 네트워크 사용 목적, Bonjour service, Access WiFi Information, Hotspot Configuration
백그라운드 Bluetooth 또는 AI 대화	사용하는 동작에 필요한 Background Modes

선택 권한 및 entitlement 예제 보기

마이크

XML

<key>NSMicrophoneUsageDescription</key>
<string>Your app needs microphone access for simultaneous interpretation and conversation translation.</string>

로컬 네트워크 및 Bonjour

XML

<key>NSLocalNetworkUsageDescription</key>
<string>Your app needs local network access to stream live video, perform device updates, and download recordings and photos.</string>

<key>NSBonjourServices</key>
<array>
  <string>_dummy._tcp</string>
</array>

백그라운드 모드

XML

<key>UIBackgroundModes</key>
<array>
  <string>bluetooth-central</string>
  <string>push-to-talk</string>
  <string>audio</string>
</array>

Hotspot entitlement

앱 타깃의 Signing & Capabilities에서 Access WiFi Information과 Hotspot Configuration을 활성화하세요:

XML

<key>com.apple.developer.networking.wifi-info</key>
<true/>

<key>com.apple.developer.networking.HotspotConfiguration</key>
<true/>

5단계: 설치 확인

• 생성된 .xcworkspace를 빌드합니다.
• 타깃에서 설치된 AIBuds framework를 가져올 수 있는지 확인합니다.
• 필수 Bluetooth key를 추가한 뒤 AIBudsSDK.initialize가 true를 반환하는지 확인합니다.
• 빠른 시작으로 이동해 SDK를 초기화하고 기기에 연결합니다.

설치 또는 초기화에 실패하면 Pod cache나 lockfile을 변경하기 전에 자주 발생하는 문제의 확인 절차를 따르세요.