AI 오디오 녹음

AI 오디오 녹음 서비스 세션을 시작하고 연결된 기기의 녹음을 조정하며, 실시간 음성 인식 결과와 세션 이벤트 및 최종 녹음 보고서를 받습니다.

이 콜백 모델에서 사용하는 AIAudioRecordingEventType 수명 주기는 AI 세션 이벤트를 참고하세요.

Animated workflow

AI 오디오 녹음 세션 수명 주기

기기 오디오보다 AI 서비스를 먼저 시작하고 두 수명 주기를 함께 관리한 뒤 서비스 보고서 콜백으로 마무리합니다.

01호스트 앱

H

세션 설정

녹음 장면, 언어, 오프라인 동작, 화자 분리를 선택합니다.

02AI 서비스

S

AI 서비스 시작

서비스 제공자가 처리하는 AI 오디오 녹음 세션을 먼저 만듭니다.

03호스트 앱

H

세션 유지

onStartSuccess에서 받은 세션을 전체 수명 주기 동안 보관합니다.

04기기

D

기기 오디오 시작

서비스가 시작되면 연결된 기기에 녹음 오디오 전송을 요청합니다.

05AI 서비스 → 앱

%

실시간 결과 처리

음성 인식 결과를 표시하고 세션 이벤트와 실행 오류를 처리합니다.

음성 인식 + 이벤트

06기기

D

기기 오디오 중지

사용자가 세션을 끝내면 기기 녹음을 중지합니다.

07AI 서비스

S

AI 서비스 중지

현재 AIBudsAISDK 오디오 녹음 세션을 중지합니다.

08최종 콜백

✓

최종 보고서 수신

onFinish로 전달된 AIAudioRecordingReportModel을 처리합니다.

09호스트 앱

H

세션 해제

보관한 세션을 정리하고 UI를 대기 상태로 되돌립니다.

↳시작 실패와 실행 중인 세션의 오류는 서로 다른 콜백으로 전달됩니다.

사전 요구 사항

• AIBudsAISDK가 초기화되어 있고 등록된 AI 서비스 제공자가 선택되어 있습니다.
• 필요한 경우 서비스 제공자 인증이 완료되어 있습니다.
• 기기가 연결되어 있고 DeviceAudioRecordingAPI를 준수합니다.
• 선택한 제공자가 AIAudioRecordingServiceAPI를 지원합니다.

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds AI 오디오 녹음 구현” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/implement-aibuds-ai-audio-recording을 읽고 지침을 따르세요. 이 스킬로 “AIBuds AI 오디오 녹음 구현”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기↗

API Reference

프레임워크

AIBudsAI.xcframework

Import

Swift

Swift

import AIBuds
import AIBudsAI
import AIBudsAIFoundation

Objective-C

Objective-C

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

선언

Swift

Swift

/// Starts an AI audio recording session.
/// - Parameters:
///   - config: The session configuration.
///   - onStartSuccess: Called with the started session.
///   - onStartFailure: Called when the session cannot start.
///   - onTranscript: Called when speech is transcribed.
///   - onEvent: Called for session-level events.
///   - onError: Called when the running session encounters an error.
///   - onFinish: Called with the completed session report.
public static func startAIAudioRecording(_ config: AIAudioRecordingSessionConfig = .default,
                                   onStartSuccess: ((_ session: AIAudioRecordingSessionConvertible) -> Void)? = nil,
                                   onStartFailure: ((_ error: Error) -> Void)? = nil,
                                     onTranscript: ((_ transcriptData: StreamSpeechASRModel) -> Void)? = nil,
                                          onEvent: ((_ event: AIAudioRecordingEventModel) -> Void)? = nil,
                                          onError: ((_ error: NSError) -> Void)? = nil,
                                         onFinish: ((_ report: AIAudioRecordingReportModel) -> Void)? = nil) -> Void

/// Stops the current AI audio recording service session.
public static func stopAIAudioRecording()

Objective-C

Objective-C

/// Starts an AI audio recording session.
/// - Parameters:
///   - config: The session configuration.
///   - onStartSuccess: Called with the started session.
///   - onStartFailure: Called when the session cannot start.
///   - onTranscript: Called when speech is transcribed.
///   - onEvent: Called for session-level events.
///   - onError: Called when the running session encounters an error.
///   - onFinish: Called with the completed session report.
+ (void)startAIAudioRecordingWithConfig:(AIBudsAIAudioRecordingSessionConfig * _Nonnull)config
                         onStartSuccess:(void (^ _Nullable)(id <AIBudsAIAudioRecordingSessionConvertible> _Nonnull))onStartSuccess
                         onStartFailure:(void (^ _Nullable)(NSError * _Nonnull))onStartFailure
                           onTranscript:(void (^ _Nullable)(AIBudsStreamSpeechASRModel * _Nonnull))onTranscript
                                onEvent:(void (^ _Nullable)(AIBudsAIAudioRecordingEventModel * _Nonnull))onEvent
                                onError:(void (^ _Nullable)(NSError * _Nonnull))onError
                               onFinish:(void (^ _Nullable)(AIBudsAIAudioRecordingReportModel * _Nonnull))onFinish;

/// Stops the current AI audio recording service session.
+ (void)stopAIAudioRecording;

startAIAudioRecording과 stopAIAudioRecording을 참고하세요.

설정

AIAudioRecordingSessionConfig는 다음 설정을 제공합니다.

속성	설명
recordingScene	.onSite와 같은 녹음 장면입니다.
allowRecordingWhileOffline	네트워크를 사용할 수 없을 때 서비스 시작을 허용할지 여부입니다. 기본값은 false입니다.
enableSpeakerDiarization	화자 분리를 사용할지 여부입니다. 기본값은 false입니다.
languageForSpeechInput	선택적 음성 언어 식별자입니다. 생략하면 SDK가 앱의 현지화 언어를 사용합니다.

사용 예제

기기가 AI 녹음 오디오를 보내기 전에 AI 서비스 세션을 시작해야 합니다. 사용자가 녹음을 끝내거나 오류가 발생하면 양쪽을 모두 중지하세요.

Swift

Swift

let config = AIAudioRecordingSessionConfig(
    recordingScene: .onSite,
    allowRecordingWhileOffline: true,
    enableSpeakerDiarization: true,
    languageForSpeechInput: "en-US"
)

AIBudsAISDK.startAIAudioRecording(
    config,
    onStartSuccess: { session in
        currentSession = session

        guard let recordingDevice = device as? DeviceAudioRecordingAPI else {
            AIBudsAISDK.stopAIAudioRecording()
            return
        }

        recordingDevice.startAIAudioRecording(.onSite) { success, error in
            if !success {
                print(error?.localizedDescription ?? "Device recording failed")
                AIBudsAISDK.stopAIAudioRecording()
            }
        }
    },
    onStartFailure: { error in
        print("Session start failed: \(error)")
    },
    onTranscript: { transcript in
        print(transcript.transcript ?? "")
    },
    onEvent: { event in
        print(event)
    },
    onError: { error in
        print(error.localizedDescription)
    },
    onFinish: { report in
        currentSession = nil
        print(report)
    }
)

Objective-C

Objective-C

AIBudsAIAudioRecordingSessionConfig *config =
    [[AIBudsAIAudioRecordingSessionConfig alloc] initWithRecordingScene:AIBudsRecordingSceneOnSite
                                             allowRecordingWhileOffline:YES
                                               enableSpeakerDiarization:YES
                                                 languageForSpeechInput:@"en-US"];

[AIBudsAISDK startAIAudioRecordingWithConfig:config
    onStartSuccess:^(id<AIBudsAIAudioRecordingSessionConvertible> session) {
        self.currentSession = session;
        id<AIBudsDeviceAudioRecordingAPI> recordingDevice =
            (id<AIBudsDeviceAudioRecordingAPI>)self.device;

        if (![recordingDevice conformsToProtocol:@protocol(AIBudsDeviceAudioRecordingAPI)]) {
            [AIBudsAISDK stopAIAudioRecording];
            return;
        }

        [recordingDevice startAIAudioRecordingWithScene:AIBudsRecordingSceneOnSite
                                             completion:^(BOOL success, NSError *error) {
                                                 if (!success) {
                                                     NSLog(@"%@",
                                                           error.localizedDescription
                                                               ?: @"Device recording failed");
                                                     [AIBudsAISDK stopAIAudioRecording];
                                                 }
                                             }];
    }
    onStartFailure:^(NSError *error) {
        NSLog(@"Session start failed: %@", error);
    }
    onTranscript:^(AIBudsStreamSpeechASRModel *transcript) {
        NSLog(@"%@", transcript.transcript ?: @"");
    }
    onEvent:^(AIBudsAIAudioRecordingEventModel *event) {
        NSLog(@"%@", event);
    }
    onError:^(NSError *error) {
        NSLog(@"%@", error.localizedDescription);
    }
    onFinish:^(AIBudsAIAudioRecordingReportModel *report) {
        self.currentSession = nil;
        NSLog(@"%@", report);
    }];

중지하려면 연결된 기기의 stopAIAudioRecording(_:completion:)을 호출하고 보관한 세션을 정리한 뒤 AIBudsAISDK.stopAIAudioRecording()을 호출합니다.

참고

• 최종 콜백은 로컬 녹음 파일 경로가 아니라 AIAudioRecordingReportModel을 반환합니다.
• 작업이 진행되는 동안 onStartSuccess에서 반환한 세션을 유지합니다.
• onStartFailure는 시작 실패를, onError는 세션 시작 후 오류를 전달합니다.
• SDK는 이 AI 서비스에 isRecording() 메서드를 제공하지 않습니다. 앱 상태에서 보관한 세션을 추적하세요.