控制音乐播放

向已连接设备发送播放、曲目切换、静音和播放音量命令。

前置条件

• 设备已连接且就绪。
• 设备支持 DeviceMusicControlAPI。
• 明确设置的音量值位于 0 到 100。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“控制 AIBuds 音乐播放”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/control-aibuds-music，使用该技能在当前 iOS 项目中完成“控制 AIBuds 音乐播放”，并验证结果。

查看官方技能↗

API 参考

框架

AIBuds.xcframework

导入

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

协议

这些命令由 DeviceMusicControlAPI 定义。

Swift

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

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

实例方法

方法	用途
playMusic	开始或继续播放。
pauseMusic	暂停播放。
playNextMusic	切换到下一首。
playPreviousMusic	切换到上一首。
musicVolumeUp	将播放音量提高一个步长。
musicVolumeDown	将播放音量降低一个步长。
mute	静音播放。
unmute	取消播放静音。
setMusicVolume	将播放音量设置为 0 到 100。

参数

参数	类型	描述
volume	Int / NSInteger	0 到 100 的目标播放音量。
completion	AIBudsCompletionHandler?	可选完成回调。

回调参数：

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

返回值

这些方法不直接返回值。

使用示例

播放

Swift

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

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

播放音量

Swift

Swift

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

Objective-C

Objective-C

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

错误处理

每条命令都应检查 success，并通过 error 获取失败详情。调用前验证明确的音量值；公开契约不保证截断越界值。

最佳实践

1. 使用准确的 SDK 名称：不要替换为通用的 play、pause、nextTrack 或 previousTrack 方法。
2. 为明确音量设置防抖：SDK Demo 延迟滑块写入，避免快速发送命令。
3. 区分音量 API：播放相关控制使用本协议；分类设备通道使用 DeviceVolumeControlAPI。
4. 成功后更新 UI：命令仅被发送时，不要假设已经成功。

注意事项

• 该协议不包含停止命令或单独的支持属性。
• 曲目元数据和队列内容不属于该 API。