Core Music Control Control

Control Music Playback

Send playback, track-navigation, muting, and playback-volume commands to a connected device.

Prerequisites

• The device is connected and ready.
• The device conforms to DeviceMusicControlAPI.
• Explicit volume values are between 0 and 100.

API Reference

Framework

AIBuds.xcframework

Import

Swift

import AIBuds

Objective-C

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

Protocol

The commands are defined by DeviceMusicControlAPI.

Swift

/// The protocol for device music control API.
protocol DeviceMusicControlAPI: DeviceAPI {
    /// Starts or resumes music playback.
    ///   - 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 playMusic(_ completion: AIBudsCompletionHandler?)

    /// Pauses the currently playing music.
    ///   - 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 pauseMusic(_ completion: AIBudsCompletionHandler?)

    /// Skips to the next track in the playback queue.
    ///   - 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 playNextMusic(_ completion: AIBudsCompletionHandler?)

    /// Returns to the previous track in the playback queue.
    ///   - 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 playPreviousMusic(_ completion: AIBudsCompletionHandler?)

    /// Increases the playback volume by one step.
    ///   - 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 musicVolumeUp(_ completion: AIBudsCompletionHandler?)

    /// Decreases the playback volume by one step.
    ///   - 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 musicVolumeDown(_ completion: AIBudsCompletionHandler?)

    /// Mutes the playback volume.
    ///   - 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 mute(_ completion: AIBudsCompletionHandler?)

    /// Unmutes the playback volume.
    ///   - 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 unmute(_ completion: AIBudsCompletionHandler?)

    /// Sets the playback volume to a specific level.
    /// - Parameters:
    ///   - volume: The desired 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 setMusicVolume(
        _ volume: Int,
        completion: AIBudsCompletionHandler?
    )
}

Objective-C

/// The protocol for device music control API.
@protocol AIBudsDeviceMusicControlAPI <AIBudsDeviceAPI>
/// Starts or resumes music playback.
///   - 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)playMusicWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Pauses the currently playing music.
///   - 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)pauseMusicWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Skips to the next track in the playback queue.
///   - 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)playNextMusicWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Returns to the previous track in the playback queue.
///   - 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)playPreviousMusicWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Increases the playback volume by one step.
///   - 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)musicVolumeUpWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Decreases the playback volume by one step.
///   - 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)musicVolumeDownWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Mutes the playback volume.
///   - 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)muteWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Unmutes the playback volume.
///   - 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)unmuteWithCompletion:(AIBudsCompletionHandler _Nullable)completion;

/// Sets the playback volume to a specific level.
/// - Parameters:
///   - volume: The desired 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)setMusicVolume:(NSInteger)volume completion:(AIBudsCompletionHandler _Nullable)completion;
@end

Instance Methods

Method	Purpose
playMusic	Start or resume playback.
pauseMusic	Pause playback.
playNextMusic	Move to the next track.
playPreviousMusic	Move to the previous track.
musicVolumeUp	Increase playback volume by one step.
musicVolumeDown	Decrease playback volume by one step.
mute	Mute playback.
unmute	Unmute playback.
setMusicVolume	Set playback volume from 0 through 100.

Parameters

Parameter	Type	Description
volume	Int / NSInteger	Desired playback volume from 0 through 100.
completion	AIBudsCompletionHandler?	Optional completion handler.

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

Playback

Swift

import AIBuds

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

device.playMusic { success, error in
    guard success else {
        print("Play failed: \(error?.localizedDescription ?? "Unknown error")")
        return
    }
    print("Playback command succeeded")
}

Objective-C

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

id<AIBudsDeviceMusicControlAPI> device = (id<AIBudsDeviceMusicControlAPI>)self.device;
if ([device conformsToProtocol:@protocol(AIBudsDeviceMusicControlAPI)]) {
    [device playMusicWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Play failed: %@", error.localizedDescription);
            return;
        }
        NSLog(@"Playback command succeeded");
    }];
}

Playback Volume

Swift

device.setMusicVolume(60) { success, error in
    if !success {
        print(error?.localizedDescription ?? "Volume update failed")
    }
}

Objective-C

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

Error Handling

Check success for every command and use error for failure details. Validate explicit volume values before calling; the public contract does not promise clamping.

Best Practices

1. Use Exact SDK Names: Do not substitute generic play, pause, nextTrack, or previousTrack methods.
2. Debounce Explicit Volume: The SDK Demo delays slider writes to avoid rapid commands.
3. Keep Volume APIs Distinct: Use this protocol for playback-oriented controls and DeviceVolumeControlAPI for typed device channels.
4. Update UI After Success: Do not assume a command succeeded when only dispatched.

Notes

• The protocol does not include a stop command or a separate support property.
• Track metadata and queue contents are outside this API.