音量設定の対応状況と現在値

デバイスが対応する音量設定と、現在取得できる各音量を確認します。

前提条件

• デバイスが接続済みで、操作可能な状態であること。
• デバイスが DeviceVolumeControlAPI に準拠していること。

API リファレンス

フレームワーク

AIBuds.xcframework

インポート

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

プロトコル

Swift

Swift

/// The protocol for device volume control API.
protocol DeviceVolumeControlAPI: DeviceAPI {
    /// The device's volume-set capability.
    var volumeSetCapability: VolumeSetCapability { get }

    /// Current volumes information of the device, or `nil` if unavailable.
    var volumesInfo: VolumesInfoModel? { get }
}

Objective-C

Objective-C

/// The protocol for device volume control API.
@protocol AIBudsDeviceVolumeControlAPI <AIBudsDeviceAPI>
/// The device's volume-set capability.
@property(nonatomic, readonly) enum AIBudsVolumeSetCapability volumeSetCapability;

/// Current volumes information of the device, or `nil` if unavailable.
@property(nonatomic, readonly, strong) AIBudsVolumesInfoModel *_Nullable volumesInfo;
@end

プロパティ

プロパティ	型	説明
volumeSetCapability	VolumeSetCapability	音量設定への対応状況。
volumesInfo	VolumesInfoModel?	現在の音量。取得できない場合は nil。

対応状況の値

値	現在の SDK での意味
.none	音量を設定できません。
.common	システム音声、メディア、通話中の各音量を設定できます。
.advanced	現在値にはローカル再生音量も含まれます。ただし、ローカル再生音量を個別に設定する公開 API は現在ありません。

音量情報

プロパティ	型	範囲	説明
systemPromptVolume	NSNumber?	0–100	現在のシステム音声音量。
mediaVolume	NSNumber?	0–100	現在のメディア再生音量。
callVolume	NSNumber?	0–100	現在の通話中音量。
localPlaybackVolume	NSNumber?	0–100	現在のローカル再生音量。現行の公開 API では読み取り専用です。

使用例

Swift

Swift

import AIBuds

guard let device = device as? DeviceVolumeControlAPI else {
    print("Device does not support volume control")
    return
}

print("Capability: \(device.volumeSetCapability)")

if let volumes = device.volumesInfo {
    print("System prompt: \(volumes.systemPromptVolume?.intValue.description ?? "Unavailable")")
    print("Media: \(volumes.mediaVolume?.intValue.description ?? "Unavailable")")
    print("Call: \(volumes.callVolume?.intValue.description ?? "Unavailable")")
    print("Local playback: \(volumes.localPlaybackVolume?.intValue.description ?? "Unavailable")")
}

Objective-C

Objective-C

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

id<AIBudsDeviceVolumeControlAPI> device = (id<AIBudsDeviceVolumeControlAPI>)self.device;
if ([device conformsToProtocol:@protocol(AIBudsDeviceVolumeControlAPI)]) {
    AIBudsVolumesInfoModel *volumes = device.volumesInfo;
    NSLog(@"System prompt: %@", volumes.systemPromptVolume);
    NSLog(@"Media: %@", volumes.mediaVolume);
    NSLog(@"Call: %@", volumes.callVolume);
    NSLog(@"Local playback: %@", volumes.localPlaybackVolume);
}

エラー処理

これらのプロパティには完了ハンドラーがありません。プロトコル非対応、モデルが nil の場合、各チャンネル値が nil の場合を区別し、独自の既定値に置き換えないでください。

ベストプラクティス

1. 任意値として扱う: nil を 0 として表示しないでください。
2. 対応状況に応じて UI を切り替える: .none の場合は、すべての音量設定 UI を非表示にします。
3. 更新を監視する: 最新値が必要な場合は、didVolumesChanged デリゲートコールバックで表示を更新します。

注意事項

• SDK は getVolumeControlSupport や Result ベースの問い合わせではなく、同期プロパティを公開しています。
• ローカル再生音量は現在取得できますが、個別には設定できません。