查看音量能力与级别

读取设备的音量设置能力和当前可用的音量级别。

前置条件

• 设备已连接且就绪。
• 设备支持 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	当前快照还可报告本地播放音量；目前没有公开的本地播放音量设置方法。

音量信息

属性	类型	范围	描述
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 显示为零。
2. 根据能力决定 UI：当值为 .none 时隐藏全部写入控件。
3. 监听更新：需要实时值时，在 didVolumesChanged 代理回调中刷新。

注意事项

• SDK 提供同步属性，而不是 getVolumeControlSupport 或基于 Result 的查询。
• 当前可以读取本地播放音量，但不能单独写入。