设置音量

设置明确的音量级别、同时更新三个可写通道，或按设备定义的步长调整一个受支持通道。

前置条件

• 设备已连接且就绪。
• 设备支持 DeviceVolumeControlAPI。
• volumeSetCapability 不为 .none。
• 明确设置的音量值位于 0 到 100。

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

这些方法由 DeviceVolumeControlAPI 定义。

Swift

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

Objective-C

Objective-C

/// The protocol for device volume control API.
@protocol AIBudsDeviceVolumeControlAPI <AIBudsDeviceAPI>
/// 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.
- (void)setVolumeWithType:(enum AIBudsDeviceVolumeType)volumeType
                    value:(NSInteger)value
               completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)setVolumesWithSystemPrompt:(NSInteger)systemPrompt
                             media:(NSInteger)media
                              call:(NSInteger)call
                        completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)volumeUpWithType:(enum AIBudsDeviceVolumeType)volumeType
              completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)volumeDownWithType:(enum AIBudsDeviceVolumeType)volumeType
                completion:(AIBudsCompletionHandler _Nullable)completion;
@end

实例方法

方法	用途
setVolume	将一个受支持通道设置为明确值。
setVolumes	同时设置系统提示音、媒体和通话音量。
volumeUp	按设备定义的一个步长提高受支持通道。
volumeDown	按设备定义的一个步长降低受支持通道。

参数

参数	类型	描述
volumeType	DeviceVolumeType	.systemPrompt、.media 或 .call。
value	Int / NSInteger	0 到 100 的明确级别。
systemPrompt	Int / NSInteger	0 到 100 的系统提示音级别。
media	Int / NSInteger	0 到 100 的媒体播放级别。
call	Int / NSInteger	0 到 100 的通话中级别。
completion	AIBudsCompletionHandler?	命令结束时调用的可选回调。

回调参数：

名称	类型	描述
success	Bool / BOOL	命令是否成功。
error	NSError?	失败详情；成功时为 nil。

返回值

这些方法不直接返回值。

使用示例

设置一个通道

Swift

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

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)] &&
    device.volumeSetCapability != AIBudsVolumeSetCapabilityNone) {
    [device setVolumeWithType:AIBudsDeviceVolumeTypeMedia
                        value:60
                   completion:^(BOOL success, NSError *_Nullable error) {
                       if (!success) {
                           NSLog(@"Failed to set media volume: %@", error.localizedDescription);
                           return;
                       }
                       NSLog(@"Media volume updated");
                   }];
}

同时设置三个通道

Swift

Swift

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

Objective-C

Objective-C

[device setVolumesWithSystemPrompt:50
                             media:60
                              call:70
                        completion:^(BOOL success, NSError *_Nullable error) {
                            if (!success) {
                                NSLog(@"%@", error.localizedDescription);
                            }
                        }];

错误处理

调用前验证能力和明确的取值范围。更新 UI 前检查 success，并通过 error 获取失败详情。公开 API 契约未说明会截断越界值。

最佳实践

1. 为滑块防抖：SDK Demo 在滑块移动后短暂等待，再发送明确值。
2. 按钮使用步进 API：需要设备决定步长时，使用 volumeUp 和 volumeDown。
3. 不要伪造本地播放写入：当前没有设置方法接受本地播放音量值。
4. 刷新确认后的状态：成功后使用 volumesInfo 或 didVolumesChanged。

注意事项

• DeviceVolumeType 的三个可写 case 是系统提示音、媒体和通话。
• 在 SDK 提供公开写入 API 前，本地播放音量仍为只读；支持加入后需更新本页。