वॉल्यूम सेट करें

कोई निश्चित वॉल्यूम स्तर सेट करें, लिखे जा सकने वाले तीनों channels को एक साथ बदलें, या किसी समर्थित channel को डिवाइस द्वारा तय एक step बढ़ाएँ या घटाएँ।

आवश्यकताएँ

• डिवाइस कनेक्टेड और ready है।
• डिवाइस DeviceVolumeControlAPI के अनुरूप है।
• volumeSetCapability का मान .none नहीं है।
• दिए गए वॉल्यूम मान 0 से 100 के बीच हैं।

API संदर्भ

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds

Objective-C

Objective-C

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

प्रोटोकॉल

Methods 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

Instance विधियाँ

Method	उद्देश्य
setVolume	किसी समर्थित channel को निश्चित मान पर सेट करता है।
setVolumes	system-prompt, media और call के मान एक साथ सेट करता है।
volumeUp	समर्थित channel को डिवाइस के तय एक step से बढ़ाता है।
volumeDown	समर्थित channel को डिवाइस के तय एक step से घटाता है।

पैरामीटर

Parameter	Type	विवरण
volumeType	DeviceVolumeType	.systemPrompt, .media या .call।
value	Int / NSInteger	0 से 100 तक निश्चित स्तर।
systemPrompt	Int / NSInteger	0 से 100 तक system-prompt स्तर।
media	Int / NSInteger	0 से 100 तक media-playback स्तर।
call	Int / NSInteger	0 से 100 तक in-call स्तर।
completion	AIBudsCompletionHandler?	Command समाप्त होने पर चलने वाला optional callback।

Callback पैरामीटर:

नाम	Type	विवरण
success	Bool / BOOL	Command सफल हुआ या नहीं।
error	NSError?	विफलता का विवरण; सफलता पर nil।

Return मान

ये methods सीधे कोई मान return नहीं करते।

उपयोग के उदाहरण

एक Channel सेट करें

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

तीनों Channels एक साथ सेट करें

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

त्रुटि प्रबंधन

Call करने से पहले capability और स्पष्ट ranges validate करें। UI अपडेट करने से पहले success जाँचें और विफलता के लिए error उपयोग करें। Public contract के अनुसार API out-of-range values को clamp नहीं करता।

श्रेष्ठ अभ्यास

1. Sliders को Debounce करें: SDK Demo निश्चित मान भेजने से पहले slider movement के बाद थोड़ी देर प्रतीक्षा करता है।
2. Buttons के लिए Step APIs उपयोग करें: Step size डिवाइस को चुनना हो तो volumeUp और volumeDown उपयोग करें।
3. Local Playback Write का भ्रम न दें: मौजूदा कोई setter local-playback value स्वीकार नहीं करता।
4. पुष्ट स्थिति Refresh करें: सफलता के बाद volumesInfo या didVolumesChanged उपयोग करें।

नोट्स

• लिखे जा सकने वाले तीन DeviceVolumeType cases system prompt, media और call हैं।
• SDK में public write API आने तक local-playback volume read-only रहेगा; support जुड़ने पर यह पेज अपडेट करें।