음악 재생 제어

전송 playback, track-navigation, muting, 및 playback-volume commands connected device.

사전 요구 사항

• 기기 입니다 connected 및 ready.
• 기기 conforms DeviceMusicControlAPI.
• Explicit volume values 입니다 between 0 및 100.

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds 음악 재생 제어” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/control-aibuds-music을 읽고 지침을 따르세요. 이 스킬로 “AIBuds 음악 재생 제어”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기↗

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

프로토콜

commands 입니다 defined by 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	시작 또는 resume playback.
pauseMusic	재생을 일시 정지합니다.
playNextMusic	Move next track.
playPreviousMusic	Move previous track.
musicVolumeUp	재생 음량을 한 단계 높입니다.
musicVolumeDown	재생 음량을 한 단계 낮춥니다.
mute	재생 음소거를 켭니다.
unmute	재생 음소거를 해제합니다.
setMusicVolume	Set playback volume 에서 0 통해 100.

매개변수

매개변수	타입	설명
volume	Int / NSInteger	Desired playback volume 에서 0 통해 100.
completion	AIBudsCompletionHandler?	선택적 완료 핸들러.

콜백 Parameters:

이름	타입	설명
success	Bool / BOOL	Whether command succeeded.
error	NSError?	실패 details, 또는 nil on 성공.

반환값

These methods 반환 no value directly.

사용 예제

재생

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

재생 Volume

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 위한 every command 및 사용 error 위한 실패 details. Validate explicit volume values 전에 calling; public contract 하지 않습니다 promise clamping.

권장 사항

1. 사용 Exact SDK Names: 하지 마세요 substitute generic play, pause, nextTrack, 또는 previousTrack methods.
2. Debounce Explicit Volume: SDK Demo delays slider writes avoid rapid commands.
3. Keep Volume APIs Distinct: 사용 이 protocol 위한 playback-oriented controls 및 DeviceVolumeControlAPI 위한 typed device channels.
4. Update UI 후에 성공: 하지 마세요 assume command succeeded 때 만 dispatched.

참고

• protocol 하지 않습니다 include 중지 command 또는 separate support property.
• Track metadata 및 queue contents 입니다 outside 이 API.