设置均衡器

读取已连接设备提供的均衡器设置，在 UI 中展示，并应用用户选择的设置。

前置条件

• 设备已连接且就绪。
• 设备符合 DeviceEqualizerAPI。
• 尽可能使用设备返回的设置。

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

协议

均衡器操作由 DeviceEqualizerAPI 定义。

Swift

Swift

/// The protocol for device API that supports equalizer.
protocol DeviceEqualizerAPI: DeviceAPI {
    /// All available preset and custom equalizer settings reported by the device.
    var allEQSettings: [EQSettingModel] { get }

    /// The currently active equalizer setting.
    var eqSetting: EQSettingModel? { get }

    /// Applies the specified equalizer setting to the device.
    /// - Parameters:
    ///   - equalizerSetting: The equalizer configuration to be applied.
    ///   - completion: A closure that is invoked when the operation completes.
    ///     - success: `true` if the setting was successfully applied; otherwise `false`.
    ///     - error: An `NSError` object if an error occurs during the operation; otherwise `nil`.
    func setEqualizer(
        _ equalizerSetting: EQSettingModel,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

Objective-C

/// The protocol for device API that supports equalizer.
@protocol AIBudsDeviceEqualizerAPI <AIBudsDeviceAPI>
/// All available preset and custom equalizer settings reported by the device.
@property(nonatomic, readonly, copy) NSArray<AIBudsEQSettingModel *> *_Nonnull allEQSettings;

/// The currently active equalizer setting.
@property(nonatomic, readonly, strong) AIBudsEQSettingModel *_Nullable eqSetting;

/// Applies the specified equalizer setting to the device.
/// - Parameters:
///   - equalizerSetting: The equalizer configuration to be applied.
///   - completion: A closure that is invoked when the operation completes.
///     - success: `true` if the setting was successfully applied; otherwise `false`.
///     - error: An `NSError` object if an error occurs during the operation; otherwise `nil`.
- (void)setEqualizer:(AIBudsEQSettingModel *_Nonnull)equalizerSetting
      withCompletion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

将指定的均衡器设置应用到设备。

Swift

Swift

/// Applies the specified equalizer setting to the device.
/// - Parameters:
///   - equalizerSetting: The equalizer configuration to be applied.
///   - completion: A closure that is invoked when the operation completes.
///     - success: `true` if the setting was successfully applied; otherwise `false`.
///     - error: An `NSError` object if an error occurs during the operation; otherwise `nil`.
func setEqualizer(
    _ equalizerSetting: EQSettingModel,
    completion: AIBudsCompletionHandler?
)

Objective-C

Objective-C

/// Applies the specified equalizer setting to the device.
/// - Parameters:
///   - equalizerSetting: The equalizer configuration to be applied.
///   - completion: A closure that is invoked when the operation completes.
///     - success: `true` if the setting was successfully applied; otherwise `false`.
///     - error: An `NSError` object if an error occurs during the operation; otherwise `nil`.
- (void)setEqualizer:(AIBudsEQSettingModel *_Nonnull)equalizerSetting
      withCompletion:(AIBudsCompletionHandler _Nullable)completion;

参数

参数	类型	描述
equalizerSetting	EQSettingModel	要应用的设备设置。
completion	AIBudsCompletionHandler?	操作结束时调用的可选回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	所选设置是否已应用。
error	NSError?	失败详情；成功时为 nil。

返回值

该方法不直接返回值，结果通过完成回调提供。

使用示例

Swift

Swift

import AIBuds
import AIBudsFoundation

guard let device = device as? DeviceEqualizerAPI else {
    print("Device does not support equalizer")
    return
}

guard let selectedSetting = device.allEQSettings.first else {
    print("The device did not provide an equalizer setting")
    return
}

device.setEqualizer(selectedSetting) { success, error in
    guard success else {
        print("Failed to apply equalizer: \(error?.localizedDescription ?? "Unknown error")")
        return
    }
    print("Equalizer applied: \(selectedSetting.name ?? "Unnamed setting")")
}

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

id<AIBudsDeviceEqualizerAPI> device = (id<AIBudsDeviceEqualizerAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceEqualizerAPI)]) {
    NSLog(@"Device does not support equalizer");
    return;
}

AIBudsEQSettingModel *selectedSetting = device.allEQSettings.firstObject;
if (selectedSetting == nil) {
    NSLog(@"The device did not provide an equalizer setting");
    return;
}

[device setEqualizer:selectedSetting
      withCompletion:^(BOOL success, NSError *_Nullable error) {
          if (!success) {
              NSLog(@"Failed to apply equalizer: %@", error.localizedDescription);
              return;
          }
          NSLog(@"Equalizer applied: %@", selectedSetting.name ?: @"Unnamed setting");
      }];

自定义设置

使用已连接设备上报的自定义槽位。其 gains.count 提供设备特定的 band 数量，minimumGain 和 maximumGain 定义 -12...12 dB 的传输范围。customSetting(index:gains:) 将从零开始的槽位映射为从 customModeStart 起始的模式，并在输入无效时返回 nil。

Swift

Swift

// A returned custom setting identifies a slot and its supported band count.
guard let reportedSetting = device.allEQSettings.first(where: \.isCustom),
    let slot = reportedSetting.customIndex?.intValue
else {
    return
}

// Supply one gain per reported band. Every value must be within -12...12 dB.
let gains = Array(repeating: 0, count: reportedSetting.gains.count)
guard let customSetting = EQSettingModel.customSetting(index: slot, gains: gains) else {
    return
}

device.setEqualizer(customSetting, completion: nil)

Objective-C

Objective-C

// A returned custom setting identifies a slot and its supported band count.
AIBudsEQSettingModel *reportedSetting = nil;
for (AIBudsEQSettingModel *setting in device.allEQSettings) {
    if (setting.isCustom) {
        reportedSetting = setting;
        break;
    }
}
if (reportedSetting.customIndex == nil) {
    return;
}

// Supply one gain per reported band. Every value must be within -12...12 dB.
NSMutableArray<NSNumber *> *gains = [NSMutableArray array];
for (NSUInteger index = 0; index < reportedSetting.gains.count; index++) {
    [gains addObject:@0];
}

AIBudsEQSettingModel *customSetting =
    [AIBudsEQSettingModel customSettingWithIndex:reportedSetting.customIndex.integerValue
                                           gains:gains];
if (customSetting == nil) {
    return;
}

[device setEqualizer:customSetting withCompletion:nil];

defaultBandCount 是内置预设使用的 band 数量。不要用它覆盖已连接设备上报的不同 band 数量。

错误处理

处理 success == false，并在 error 可用时向用户报告。公开 API 未定义均衡器专用错误码。