Set Equalizer

Read the equalizer settings provided by the connected device, present them in your UI, and apply the setting the user selects.

Prerequisites

• The device is connected and ready.
• The device conforms to DeviceEqualizerAPI.
• Use a setting returned by the device whenever possible.

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

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

Protocol

Equalizer operations are defined by 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

Instance Method

Applies the specified equalizer setting to the device.

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;

Parameters

Parameter	Type	Description
equalizerSetting	EQSettingModel	The device setting to apply.
completion	AIBudsCompletionHandler?	Optional callback invoked when the operation finishes.

Callback Parameters:

Name	Type	Description
success	Bool / BOOL	Whether the selected setting was applied.
error	NSError?	Failure details, or nil on success.

Return Value

This method does not return a value directly. The result is provided through the completion callback.

Usage Examples

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");
      }];

Custom Settings

Use a custom slot reported by the connected device. Its gains.count supplies the device-specific band count, while minimumGain and maximumGain define the transport range of -12...12 dB. customSetting(index:gains:) maps the zero-based slot to a mode beginning at customModeStart and returns nil for invalid input.

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 is the band count used by built-in presets. Do not use it to override a different band count reported by the connected device.

Error Handling

Handle success == false and surface error when it is available. The public API does not define equalizer-specific error codes.