오프라인 음성 어시스턴트 모드 조회 및 설정

현재 활성화된 오프라인 음성 어시스턴트 모드를 확인하고, 기기가 지원하는 모드로 변경합니다.

사전 요구 사항

• 기기가 연결되어 있고 OnDeviceVoiceAssistantAPI를 지원해야 합니다.
• onDeviceVoiceAssistantCapability이 .none이 아니어야 합니다.
• 설정할 모드가 기기의 지원 기능과 호환되어야 하며 .unknown이면 안 됩니다.

API Reference

프레임워크

AIBuds.xcframework

선언

Swift

Swift

/// The protocol for the on-device voice assistant API.
protocol OnDeviceVoiceAssistantAPI: DeviceAPI {
    /// The current mode of the on-device voice assistant.
    var onDeviceVoiceAssistantMode: OnDeviceVoiceAssistantMode { get }

    /// Sets the mode of the on-device voice assistant.
    /// - Parameters:
    ///   - mode: The desired mode to set.
    ///   - completion: Called when the operation completes.
    ///     - success: `true` when the operation succeeds.
    ///     - error: Error details on failure; otherwise `nil`.
    func setOnDeviceVoiceAssistantMode(_ mode: OnDeviceVoiceAssistantMode,
                                   completion: AIBudsCompletionHandler?)
}

Objective-C

Objective-C

/// The protocol for the on-device voice assistant API.
@protocol AIBudsOnDeviceVoiceAssistantAPI <AIBudsDeviceAPI>
/// The current mode of the on-device voice assistant.
@property(nonatomic, readonly) AIBudsOnDeviceVoiceAssistantMode onDeviceVoiceAssistantMode;

/// Sets the mode of the on-device voice assistant.
/// - Parameters:
///   - mode: The desired mode to set.
///   - completion: Called when the operation completes.
///     - success: `YES` when the operation succeeds.
///     - error: Error details on failure; otherwise `nil`.
- (void)setOnDeviceVoiceAssistantMode:(enum AIBudsOnDeviceVoiceAssistantMode)mode
                           completion:(AIBudsCompletionHandler _Nullable)completion;
@end

onDeviceVoiceAssistantMode, setOnDeviceVoiceAssistantMode 및 OnDeviceVoiceAssistantMode를 참고하세요.

호환 모드

지원 기능	표시할 모드
.none	모드 제어 UI를 표시하지 않음
.keywordWakeup	.disabled, .basic
.common	.disabled, .basic, .advanced

사용 예제

Swift

Swift

guard let voiceAssistant = device as? OnDeviceVoiceAssistantAPI else {
    print("On-device voice assistant is not supported")
    return
}

print("Current mode: \(voiceAssistant.onDeviceVoiceAssistantMode)")

guard voiceAssistant.onDeviceVoiceAssistantCapability == .common else {
    print("Advanced mode is not supported")
    return
}

voiceAssistant.setOnDeviceVoiceAssistantMode(.advanced) { success, error in
    guard success else {
        print(error?.localizedDescription ?? "Unable to change mode")
        return
    }
    print("Mode changed to advanced")
}

Objective-C

Objective-C

id<AIBudsOnDeviceVoiceAssistantAPI> voiceAssistant =
    (id<AIBudsOnDeviceVoiceAssistantAPI>)self.device;

if (![voiceAssistant conformsToProtocol:@protocol(AIBudsOnDeviceVoiceAssistantAPI)]) {
    NSLog(@"On-device voice assistant is not supported");
    return;
}

NSLog(@"Current mode: %ld", (long)voiceAssistant.onDeviceVoiceAssistantMode);

if (voiceAssistant.onDeviceVoiceAssistantCapability !=
    AIBudsOnDeviceVoiceAssistantCapabilityCommon) {
    NSLog(@"Advanced mode is not supported");
    return;
}

[voiceAssistant
    setOnDeviceVoiceAssistantMode:AIBudsOnDeviceVoiceAssistantModeAdvanced
                       completion:^(BOOL success, NSError *error) {
                           if (!success) {
                               NSLog(@"%@", error.localizedDescription ?: @"Unable to change mode");
                               return;
                           }
                           NSLog(@"Mode changed to advanced");
                       }];

참고

• .unknown은 현재 모드를 확인할 수 없는 상태를 뜻하므로 설정할 모드로 전송하면 안 됩니다.
• 성공 콜백은 요청이 정상적으로 처리되었음을 확인합니다. 기기 속성 또는 모드 변경 delegate 콜백을 기준으로 UI를 갱신하세요.
• .advanced에는 통화 상태 음성 제어가 포함되므로 .common 기능을 지원하는 기기에서만 제공하세요.