Set Volume

Set an explicit volume level, update all three writable channels together, or move one supported channel by a device-defined step.

Prerequisites

• The device is connected and ready.
• The device conforms to DeviceVolumeControlAPI.
• volumeSetCapability is not .none.
• Explicit volume values are between 0 and 100.

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

Protocol

The methods are defined by 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

Instance Methods

Method	Purpose
setVolume	Set one supported channel to an explicit value.
setVolumes	Set system-prompt, media, and call values together.
volumeUp	Increase one supported channel by one device-defined step.
volumeDown	Decrease one supported channel by one device-defined step.

Parameters

Parameter	Type	Description
volumeType	DeviceVolumeType	.systemPrompt, .media, or .call.
value	Int / NSInteger	Explicit level from 0 through 100.
systemPrompt	Int / NSInteger	System-prompt level from 0 through 100.
media	Int / NSInteger	Media-playback level from 0 through 100.
call	Int / NSInteger	In-call level from 0 through 100.
completion	AIBudsCompletionHandler?	Optional callback invoked when the command finishes.

Callback Parameters:

Name	Type	Description
success	Bool / BOOL	Whether the command succeeded.
error	NSError?	Failure details, or nil on success.

Return Value

These methods return no value directly.

Usage Examples

Set One Channel

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

Set Three Channels Together

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);
                            }
                        }];

Error Handling

Validate capability and explicit ranges before calling. Check success before updating UI, and use error for failure details. The API does not clamp out-of-range values in its public contract.

Best Practices

1. Debounce Sliders: The SDK Demo waits briefly after slider movement before sending an explicit value.
2. Use Step APIs for Buttons: Use volumeUp and volumeDown when the device should choose the step size.
3. Do Not Fake Local Playback Writes: No current setter accepts a local-playback value.
4. Refresh Confirmed State: Use volumesInfo or didVolumesChanged after success.

Notes

• The three writable DeviceVolumeType cases are system prompt, media, and call.
• Local-playback volume remains read-only until the SDK introduces a public write API; update this page when that support is added.