음량 지원 수준 및 현재 값 확인

기기의 음량 설정 지원 수준과 현재 제공되는 음량 값을 읽습니다.

사전 요구 사항

• 기기가 연결되어 사용할 수 있는 상태입니다.
• 기기가 DeviceVolumeControlAPI를 준수합니다.

API 참고

프레임워크

AIBuds.xcframework

가져오기

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

프로토콜

Swift

Swift

/// The protocol for device volume control API.
protocol DeviceVolumeControlAPI: DeviceAPI {
    /// The device's volume-set capability.
    var volumeSetCapability: VolumeSetCapability { get }

    /// Current volumes information of the device, or `nil` if unavailable.
    var volumesInfo: VolumesInfoModel? { get }
}

Objective-C

Objective-C

/// The protocol for device volume control API.
@protocol AIBudsDeviceVolumeControlAPI <AIBudsDeviceAPI>
/// The device's volume-set capability.
@property(nonatomic, readonly) enum AIBudsVolumeSetCapability volumeSetCapability;

/// Current volumes information of the device, or `nil` if unavailable.
@property(nonatomic, readonly, strong) AIBudsVolumesInfoModel *_Nullable volumesInfo;
@end

속성

속성	타입	설명
volumeSetCapability	VolumeSetCapability	음량 설정 지원 수준입니다.
volumesInfo	VolumesInfoModel?	현재 음량 값이며 사용할 수 없으면 nil입니다.

지원 수준 값

값	현재 SDK에서의 의미
.none	음량을 설정할 수 없습니다.
.common	시스템 안내음, 미디어 및 통화 음량을 설정할 수 있습니다.
.advanced	현재 스냅샷에서 로컬 재생 음량도 확인할 수 있지만 공개된 로컬 재생 setter는 아직 없습니다.

음량 정보

속성	타입	범위	설명
systemPromptVolume	NSNumber?	0–100	현재 시스템 안내음 음량입니다.
mediaVolume	NSNumber?	0–100	현재 미디어 재생 음량입니다.
callVolume	NSNumber?	0–100	현재 통화 음량입니다.
localPlaybackVolume	NSNumber?	0–100	현재 로컬 재생 음량이며 공개 API에서는 읽기만 가능합니다.

사용 예제

Swift

Swift

import AIBuds

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

print("Capability: \(device.volumeSetCapability)")

if let volumes = device.volumesInfo {
    print("System prompt: \(volumes.systemPromptVolume?.intValue.description ?? "Unavailable")")
    print("Media: \(volumes.mediaVolume?.intValue.description ?? "Unavailable")")
    print("Call: \(volumes.callVolume?.intValue.description ?? "Unavailable")")
    print("Local playback: \(volumes.localPlaybackVolume?.intValue.description ?? "Unavailable")")
}

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)]) {
    AIBudsVolumesInfoModel *volumes = device.volumesInfo;
    NSLog(@"System prompt: %@", volumes.systemPromptVolume);
    NSLog(@"Media: %@", volumes.mediaVolume);
    NSLog(@"Call: %@", volumes.callVolume);
    NSLog(@"Local playback: %@", volumes.localPlaybackVolume);
}

오류 처리

이 속성에는 completion handler가 없습니다. 프로토콜 미지원, nil 모델 및 개별 채널의 nil 값을 임의의 기본값으로 바꾸지 말고 처리하세요.

권장 사항

1. 선택적 값 유지: nil을 0으로 표시하지 마세요.
2. 지원 수준에 따라 UI 결정: .none이면 모든 설정 UI를 숨기세요.
3. 변경 관찰: 실시간 값이 필요하면 didVolumesChanged delegate 콜백에서 갱신하세요.

참고

• SDK는 getVolumeControlSupport 또는 Result 기반 조회 대신 동기식 속성을 제공합니다.
• 현재 로컬 재생 음량은 읽을 수 있지만 별도로 설정할 수 없습니다.