Ses Düzeyini Ayarlama

Doğrudan bir ses düzeyi ayarlayın, yazılabilir üç kanalı birlikte güncelleyin veya desteklenen bir kanalı cihazın tanımladığı adımla değiştirin.

Ön Koşullar

• Cihaz bağlı ve hazırdır.
• Cihaz DeviceVolumeControlAPI protokolüne uyar.
• volumeSetCapability, .none değildir.
• Doğrudan ses düzeyi değerleri 0-100 arasındadır.

API Referansı

Framework

AIBuds.xcframework

İçe Aktarma

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

Protokol

Yöntemler DeviceVolumeControlAPI tarafından tanımlanır.

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

Örnek Yöntemleri

Yöntem	Amaç
setVolume	Desteklenen bir kanalı doğrudan bir değere ayarlar.
setVolumes	Sistem bildirimi, medya ve görüşme değerlerini birlikte ayarlar.
volumeUp	Desteklenen kanalı cihazın tanımladığı bir adım artırır.
volumeDown	Desteklenen kanalı cihazın tanımladığı bir adım azaltır.

Parametreler

Parametre	Tür	Açıklama
volumeType	DeviceVolumeType	.systemPrompt, .media veya .call.
value	Int / NSInteger	0-100 arasında doğrudan düzey.
systemPrompt	Int / NSInteger	0-100 arasında sistem bildirimi düzeyi.
media	Int / NSInteger	0-100 arasında medya oynatma düzeyi.
call	Int / NSInteger	0-100 arasında görüşme düzeyi.
completion	AIBudsCompletionHandler?	Komut tamamlandığında çağrılan isteğe bağlı callback.

Callback Parametreleri:

Ad	Tür	Açıklama
success	Bool / BOOL	Komutun başarılı olup olmadığı.
error	NSError?	Hata ayrıntıları; başarılıysa nil.

Dönüş Değeri

Bu yöntemler doğrudan değer döndürmez.

Kullanım Örnekleri

Tek Kanalı Ayarlama

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

Üç Kanalı Birlikte Ayarlama

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

Hata Yönetimi

Çağrıdan önce yeteneği ve açık aralıkları doğrulayın. Arayüzü güncellemeden önce success değerini denetleyin; hata ayrıntıları için error kullanın. Genel API sözleşmesi aralık dışı değerleri sınırlamaz.

En İyi Uygulamalar

1. Kaydırıcıları Seyreltin: SDK Demo'su açık değeri göndermeden önce kaydırıcı hareketinden sonra kısa süre bekler.
2. Düğmeler İçin Adım API'lerini Kullanın: Adım boyutunu cihaz belirleyecekse volumeUp ve volumeDown kullanın.
3. Yerel Oynatma Yazmasını Taklit Etmeyin: Mevcut ayarlayıcıların hiçbiri yerel oynatma değeri kabul etmez.
4. Doğrulanan Durumu Yenileyin: Başarıdan sonra volumesInfo veya didVolumesChanged kullanın.

Notlar

• Yazılabilir üç DeviceVolumeType case'i sistem bildirimi, medya ve görüşmedir.
• SDK genel bir yazma API'si sunana kadar yerel oynatma sesi salt okunur kalır; destek eklendiğinde bu sayfayı güncelleyin.