安装

通过 CocoaPods 安装 AIBuds SDK。如果您尚未明确应用需要哪些产品能力，建议先安装完整 SDK。

环境要求

iOS 13.0 或更高版本
Xcode 26.0 或更高版本
CocoaPods 1.16.0 或更高版本

选择安装方式

完整安装

使用 AIBudsSDK/AllInOne 一次安装设备连接、AI 服务、语音助手、媒体、诊断及其他可选 SDK 组件。

更少的依赖项

模块化安装

仅选择产品实际提供的功能。CocoaPods 会自动安装其依赖的 SDK 层和第三方依赖项。

AI 辅助安装

使用 AI 编程助手集成

选择安装方式，然后在项目工作区中将精简提示词粘贴给 AI 编程助手。

使用 AIBudsSDK/AllInOne 安装完整 SDK。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/integrate-aibuds-sdk，使用 AIBudsSDK/AllInOne 将完整的 AIBuds SDK 集成到当前 iOS 项目，并完成验证。

浏览 AIBuds Skills

第 1 步：将 SDK 添加到 Podfile

每条 AIBudsSDK pod 声明都必须指定 Git 源：

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

或指定 SDK 的本地检出目录：

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

以下示例省略了源配置，请根据项目实际情况选择合适的形式。

完整安装
模块化安装

platform :ios, '13.0'

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

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

查看完整模块参考

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

聚合 subspec

# 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 中。它会配置所需的动态 Framework、移除不受支持的私有头文件导入，并启用二进制分发兼容性。

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，然后打开生成的 Workspace，而不是 .xcodeproj 文件：

pod install
open YourProject.xcworkspace

第 4 步：添加权限

设备连接必需配置

在 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 都会返回 false。

仅为已启用的功能添加配置

功能	附加配置
iPhone 端音频采集	麦克风用途说明
通过设备热点进行直播、Camera OTA 或媒体下载	本地网络用途说明、Bonjour 服务、Access WiFi Information 和 Hotspot Configuration
后台蓝牙或 AI 对话	已启用行为所需的 Background Modes

查看可选权限和 Entitlement 配置片段

麦克风

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

本地网络和 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>

后台模式

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

热点 Entitlement

在应用 Target 的 Signing & Capabilities 标签页中启用 Access WiFi Information 和 Hotspot Configuration：

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

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

第 5 步：验证安装

构建生成的 .xcworkspace。
确认 Target 可以导入已安装的 AIBuds Framework。
添加必需的蓝牙权限键后，确认 AIBudsSDK.initialize 返回 true。
继续阅读快速开始，初始化 SDK 并连接设备。

如果安装或初始化失败，请先参考常见问题进行针对性检查，再考虑修改 Pod 缓存或锁文件。

环境要求​

选择安装方式​

完整安装

模块化安装

第 1 步：将 SDK 添加到 Podfile​

第 2 步：添加必需的 Podfile Hook​

第 3 步：安装并打开 Workspace​

第 4 步：添加权限​

设备连接必需配置​

仅为已启用的功能添加配置​

第 5 步：验证安装​