メインコンテンツまでスキップ

イコライザーの設定

接続中のデバイスが提供するイコライザー設定を取得して UI に表示し、ユーザーが選択した設定を適用します。

前提条件​

  • デバイスが接続済みで、操作可能な状態であること。
  • デバイスが DeviceEqualizerAPI に準拠していること。
  • 可能な限り、デバイスから返された設定を使用すること。

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

Swift
import AIBuds
import AIBudsFoundation

プロトコル​

イコライザー操作は DeviceEqualizerAPI で定義されています。

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

インスタンスメソッド​

指定したイコライザー設定をデバイスへ適用します。

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

パラメータ​

パラメータ型説明
equalizerSettingEQSettingModelデバイスへ適用する設定。
completionAIBudsCompletionHandler?処理完了時に呼び出される任意のコールバック。

コールバックのパラメータ:

名前型説明
successBool / BOOL選択した設定が適用されたかどうか。
errorNSError?失敗時の詳細。成功時は nil。

戻り値​

このメソッドは値を直接返しません。結果は完了コールバックに渡されます。

使用例​

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

カスタム設定​

接続中のデバイスが通知するカスタムスロットを使用します。gains.count はデバイス固有のバンド数を示し、minimumGain と maximumGain は -12...12 dB の送信範囲を定義します。customSetting(index:gains:) は 0 始まりのスロットを customModeStart から始まるモードへ変換し、入力が無効な場合は nil を返します。

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)

defaultBandCount は組み込みプリセットで使用するバンド数です。接続中のデバイスが異なるバンド数を通知した場合に、その値を上書きする目的では使用しないでください。

エラー処理​

success == false を処理し、error がある場合は内容を提示します。公開 API ではイコライザー固有のエラーコードは定義されていません。