Getting Started Installation

Installation

Install the AIBuds SDK through CocoaPods. Start with the complete SDK unless you already know which product capabilities your app needs.

Prerequisites

• iOS 13.0 or later
• Xcode 26.0 or later
• CocoaPods 1.16.0 or later

Choose an Installation

Recommended

Full Installation

Use AIBudsSDK/AllInOne to install device connectivity, AI services, voice assistant, media, diagnostics, and other optional SDK components together.

Smaller dependency set

Modular Installation

Select only the capabilities your product ships. CocoaPods installs the supporting SDK layers and third-party dependencies automatically.

Step 1: Add the SDK to Your Podfile

Every AIBudsSDK pod declaration must specify either the git source:

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

or a local SDK checkout:

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

The source is omitted from the examples below so you can use the form appropriate for your project.

Full

platform :ios, '13.0'

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

Modular

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

View complete module reference

# 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'

# 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'

# 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'

# 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'

Aggregate subspecs

# 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/*

Step 2: Add the Required Podfile Hooks

Copy this block into the Podfile once. It configures required dynamic frameworks, removes an unsupported private header import, and enables binary distribution compatibility.

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

Step 3: Install and Open the Workspace

Run CocoaPods, then open the generated workspace instead of the .xcodeproj file:

pod install
open YourProject.xcworkspace

Step 4: Add Permissions

Required for Device Connectivity

Add both Bluetooth usage descriptions to Info.plist:

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

AIBudsSDK.initialize returns false if either Bluetooth key is missing.

Add Only for Enabled Features

Feature	Additional configuration
Phone-side audio capture	Microphone usage description
Live streaming, Camera OTA, or media download over the device hotspot	Local Network usage description, Bonjour service, Access WiFi Information, and Hotspot Configuration
Background Bluetooth or AI conversations	Required Background Modes for the enabled behavior

View optional permission and entitlement snippets

Microphone

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

Local Network and Bonjour

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

Background Modes

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

Hotspot entitlements

Enable Access WiFi Information and Hotspot Configuration in the app target's Signing & Capabilities tab:

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

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

Step 5: Verify the Installation

• Build the generated .xcworkspace.
• Confirm your target can import the installed AIBuds frameworks.
• Confirm AIBudsSDK.initialize returns true after the required Bluetooth keys are present.
• Continue to Quick Start to initialize the SDK and connect a device.

If installation or initialization fails, use Common Issues for evidence-based checks before changing pod caches or lockfiles.