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

音量の設定

音量を直接指定するほか、設定可能な 3 チャンネルをまとめて更新したり、対応チャンネルをデバイス既定の幅で増減したりできます。

前提条件​

  • デバイスが接続済みで、操作可能な状態であること。
  • デバイスが DeviceVolumeControlAPI に準拠していること。
  • volumeSetCapability が .none ではないこと。
  • 直接指定する音量が 0〜100 の範囲内であること。

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

Swift
import AIBuds

プロトコル​

これらのメソッドは DeviceVolumeControlAPI で定義されています。

Swift
/// The protocol for device volume control API.
protocol DeviceVolumeControlAPI: DeviceAPI {
    /// Sets the volume for the specified type.
    /// - Parameters:
    ///   - volumeType: The volume type to adjust.
    ///   - value: the volume value (0–100)
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func setVolume(
        _ volumeType: DeviceVolumeType,
        value: Int,
        completion: AIBudsCompletionHandler?
    )

    /// Sets multiple volume levels at once.
    /// - Parameters:
    ///   - systemPrompt: The system prompt volume level. (0–100)
    ///   - media: The media playback volume level. (0–100)
    ///   - call: The call volume level. (0–100)
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func setVolumes(
        systemPrompt: Int,
        media: Int,
        call: Int,
        completion: AIBudsCompletionHandler?
    )

    /// Increases the specified volume channel by one step.
    /// - Parameters:
    ///   - volumeType: The volume channel to adjust.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func volumeUp(
        _ volumeType: DeviceVolumeType,
        completion: AIBudsCompletionHandler?
    )

    /// Decreases the specified volume channel by one step.
    /// - Parameters:
    ///   - volumeType: The volume channel to adjust.
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func volumeDown(
        _ volumeType: DeviceVolumeType,
        completion: AIBudsCompletionHandler?
    )
}

インスタンスメソッド​

メソッド用途
setVolume対応する 1 チャンネルを指定値に設定します。
setVolumesシステム音声、メディア、通話中の音量をまとめて設定します。
volumeUp対応チャンネルをデバイス既定の 1 段階分上げます。
volumeDown対応チャンネルをデバイス既定の 1 段階分下げます。

パラメータ​

パラメータ型説明
volumeTypeDeviceVolumeType.systemPrompt、.media、.call のいずれか。
valueInt / NSInteger0〜100 で指定する音量。
systemPromptInt / NSInteger0〜100 のシステム音声音量。
mediaInt / NSInteger0〜100 のメディア再生音量。
callInt / NSInteger0〜100 の通話中音量。
completionAIBudsCompletionHandler?コマンド完了時に呼び出される任意のコールバック。

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

名前型説明
successBool / BOOLコマンドが成功したかどうか。
errorNSError?失敗時の詳細。成功時は nil。

戻り値​

これらのメソッドは値を直接返しません。

使用例​

1 チャンネルを設定​

Swift
import AIBuds

guard let device = device as? DeviceVolumeControlAPI,
    device.volumeSetCapability != .none
else {
    print("Volume setting is unavailable")
    return
}

device.setVolume(.media, value: 60) { success, error in
    guard success else {
        print("Failed to set media volume: \(error?.localizedDescription ?? "Unknown error")")
        return
    }
    print("Media volume updated")
}

3 チャンネルをまとめて設定​

Swift
device.setVolumes(
    systemPrompt: 50,
    media: 60,
    call: 70
) { success, error in
    if !success {
        print(error?.localizedDescription ?? "Volume update failed")
    }
}

エラー処理​

呼び出し前に対応状況と指定値の範囲を確認します。UI を更新する前に success を確認し、失敗の詳細は error から取得してください。公開 API の仕様では、範囲外の値が自動補正されることは保証されません。

ベストプラクティス​

  1. スライダー入力を間引く: SDK Demo では、スライダー操作後に短時間待ってから値を送信します。
  2. ボタンには段階調整 API を使う: 増減幅をデバイスに任せる場合は volumeUp と volumeDown を使用します。
  3. ローカル再生音量を疑似的に設定しない: 現行の設定 API はローカル再生音量を受け付けません。
  4. 確定した状態を再取得する: 成功後は volumesInfo または didVolumesChanged で状態を更新します。

注意事項​

  • 設定可能な DeviceVolumeType は、システム音声、メディア、通話中の 3 種類です。
  • SDK に公開設定 API が追加されるまで、ローカル再生音量は読み取り専用です。対応追加時にこのページも更新してください。