Настройка громкости

Задайте точный уровень, измените сразу три доступных для записи канала или сдвиньте один поддерживаемый канал на шаг устройства.

Предварительные условия

• Устройство подключено и готово к работе.
• Устройство поддерживает DeviceVolumeControlAPI.
• volumeSetCapability не равно .none.
• Точные значения громкости находятся в диапазоне от 0 до 100.

Справочник API

Фреймворк

AIBuds.xcframework

Импорт

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

Протокол

Методы определены протоколом DeviceVolumeControlAPI.

Swift

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

Objective-C

Objective-C

/// The protocol for device volume control API.
@protocol AIBudsDeviceVolumeControlAPI <AIBudsDeviceAPI>
/// 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.
- (void)setVolumeWithType:(enum AIBudsDeviceVolumeType)volumeType
                    value:(NSInteger)value
               completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)setVolumesWithSystemPrompt:(NSInteger)systemPrompt
                             media:(NSInteger)media
                              call:(NSInteger)call
                        completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)volumeUpWithType:(enum AIBudsDeviceVolumeType)volumeType
              completion:(AIBudsCompletionHandler _Nullable)completion;

/// 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.
- (void)volumeDownWithType:(enum AIBudsDeviceVolumeType)volumeType
                completion:(AIBudsCompletionHandler _Nullable)completion;
@end

Методы экземпляра

Метод	Назначение
setVolume	Задать точное значение одного поддерживаемого канала.
setVolumes	Вместе задать системные подсказки, медиа и звук звонка.
volumeUp	Увеличить один канал на шаг устройства.
volumeDown	Уменьшить один канал на шаг устройства.

Параметры

Параметр	Тип	Описание
volumeType	DeviceVolumeType	.systemPrompt, .media или .call.
value	Int / NSInteger	Точный уровень от 0 до 100.
systemPrompt	Int / NSInteger	Уровень системных подсказок от 0 до 100.
media	Int / NSInteger	Уровень воспроизведения медиа от 0 до 100.
call	Int / NSInteger	Уровень звука звонка от 0 до 100.
completion	AIBudsCompletionHandler?	Необязательный обработчик завершения команды.

Параметры обработчика:

Имя	Тип	Описание
success	Bool / BOOL	Успешно ли выполнена команда.
error	NSError?	Сведения об ошибке или nil при успехе.

Возвращаемое значение

Методы не возвращают значение напрямую.

Примеры использования

Настройка одного канала

Swift

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

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)] &&
    device.volumeSetCapability != AIBudsVolumeSetCapabilityNone) {
    [device setVolumeWithType:AIBudsDeviceVolumeTypeMedia
                        value:60
                   completion:^(BOOL success, NSError *_Nullable error) {
                       if (!success) {
                           NSLog(@"Failed to set media volume: %@", error.localizedDescription);
                           return;
                       }
                       NSLog(@"Media volume updated");
                   }];
}

Одновременная настройка трёх каналов

Swift

Swift

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

Objective-C

Objective-C

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

Обработка ошибок

До вызова проверьте возможность и диапазон точных значений. Перед обновлением интерфейса проверьте success, а детали ошибки получите из error. Открытый контракт API не гарантирует ограничение значений диапазоном.

Рекомендации

1. Ограничивайте частоту ползунков: Demo SDK делает небольшую паузу после перемещения перед отправкой точного значения.
2. Используйте пошаговые API для кнопок: применяйте volumeUp и volumeDown, когда шаг должно выбирать устройство.
3. Не имитируйте запись локальной громкости: ни один текущий сеттер не принимает такое значение.
4. Обновляйте подтверждённое состояние: после успеха используйте volumesInfo или didVolumesChanged.

Примечания

• Три доступных для записи варианта DeviceVolumeType: системные подсказки, медиа и звонок.
• Громкость локального воспроизведения остаётся только для чтения до появления открытого API записи; после его добавления обновите эту страницу.