본문으로 건너뛰기

음량 설정

음량을 직접 설정하거나 설정 가능한 세 채널을 함께 변경하고, 지원되는 한 채널을 기기가 정한 단계만큼 조절합니다.

사전 요구 사항​

  • 기기가 연결되어 사용할 수 있는 상태입니다.
  • 기기가 DeviceVolumeControlAPI를 준수합니다.
  • volumeSetCapability이 .none이 아닙니다.
  • 직접 설정할 음량 값이 0부터 100 사이입니다.

API 참고​

프레임워크​

AIBuds.xcframework

가져오기​

Swift
import AIBuds

프로토콜​

메서드는 DeviceVolumeControlAPI에 정의되어 있습니다.

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?
    )
}

인스턴스 메서드​

메서드용도
setVolume지원되는 채널 하나를 지정한 값으로 설정합니다.
setVolumes시스템 안내음, 미디어 및 통화 음량을 함께 설정합니다.
volumeUp채널 하나를 기기가 정한 한 단계만큼 높입니다.
volumeDown채널 하나를 기기가 정한 한 단계만큼 낮춥니다.

매개변수​

매개변수타입설명
volumeTypeDeviceVolumeType.systemPrompt, .media 또는 .call입니다.
valueInt / NSInteger0부터 100까지의 지정 음량입니다.
systemPromptInt / NSInteger0부터 100까지의 시스템 안내음 음량입니다.
mediaInt / NSInteger0부터 100까지의 미디어 재생 음량입니다.
callInt / NSInteger0부터 100까지의 통화 음량입니다.
completionAIBudsCompletionHandler?명령이 끝날 때 호출되는 선택적 콜백입니다.

콜백 매개변수:

이름타입설명
successBool / BOOL명령 성공 여부입니다.
errorNSError?실패 상세 정보이며 성공하면 nil입니다.

반환 값​

이 메서드는 값을 직접 반환하지 않습니다.

사용 예제​

채널 하나 설정​

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

세 채널 함께 설정​

Swift
device.setVolumes(
    systemPrompt: 50,
    media: 60,
    call: 70
) { success, error in
    if !success {
        print(error?.localizedDescription ?? "Volume update failed")
    }
}

오류 처리​

호출 전에 지원 수준과 값 범위를 검증하세요. UI를 변경하기 전에 success를 확인하고 실패 상세 정보는 error에서 확인하세요. 공개 API는 범위를 벗어난 값을 자동으로 제한한다고 보장하지 않습니다.

권장 사항​

  1. 슬라이더 debounce: SDK Demo는 슬라이더가 움직인 뒤 잠시 기다렸다가 값을 전송합니다.
  2. 버튼에는 단계 API 사용: 기기가 단계 크기를 정해야 하면 volumeUp과 volumeDown을 사용하세요.
  3. 로컬 재생 설정 임의 구현 금지: 현재 setter는 로컬 재생 음량을 받지 않습니다.
  4. 확정 상태 갱신: 성공 후 volumesInfo 또는 didVolumesChanged를 사용하세요.

참고​

  • 설정 가능한 세 DeviceVolumeType case는 시스템 안내음, 미디어 및 통화입니다.
  • SDK에 공개 설정 API가 추가될 때까지 로컬 재생 음량은 읽기 전용입니다. 지원이 추가되면 이 페이지를 갱신하세요.