이퀄라이저 설정

연결된 기기가 제공하는 이퀄라이저 설정을 읽어 UI에 표시하고 사용자가 선택한 설정을 적용합니다.

사전 요구 사항

기기가 연결되어 사용할 수 있는 상태입니다.
기기가 DeviceEqualizerAPI를 준수합니다.
가능하면 기기가 반환한 설정을 사용합니다.

API 참고

프레임워크

AIBuds.xcframework

가져오기

Swift
Objective-C

import AIBuds
import AIBudsFoundation

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

프로토콜

이퀄라이저 동작은 DeviceEqualizerAPI에 정의되어 있습니다.

Swift
Objective-C

/// 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?
    )
}

/// 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
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`.
func setEqualizer(
    _ equalizerSetting: EQSettingModel,
    completion: AIBudsCompletionHandler?
)

/// 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`입니다.

반환 값

이 메서드는 값을 직접 반환하지 않습니다. 결과는 completion 콜백으로 전달됩니다.

사용 예제

Swift
Objective-C

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

#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는 기기별 밴드 수를 제공하고 minimumGain과 maximumGain은 -12...12 dB 전송 범위를 정의합니다. customSetting(index:gains:)은 0부터 시작하는 슬롯을 customModeStart에서 시작하는 모드에 매핑하며 입력이 유효하지 않으면 nil을 반환합니다.

Swift
Objective-C

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

// 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는 기본 preset에서 사용하는 밴드 수입니다. 연결된 기기가 다른 밴드 수를 보고하면 이 값으로 덮어쓰지 마세요.

오류 처리

success == false를 처리하고 error가 있으면 표시하세요. 공개 API에는 이퀄라이저 전용 오류 코드가 정의되어 있지 않습니다.

사전 요구 사항​

API 참고​

프레임워크​

가져오기​

프로토콜​

인스턴스 메서드​

매개변수​

반환 값​

사용 예제​

사용자 설정​

오류 처리​