본문 바로가기

Daum Developers

서비스

뉴톤(Newtone)-모바일(iOS) SDK

목차

소개

OS Native 앱 개발 시 Daum Developers의 뉴톤 기능을 사용할 수 있습니다.

요구 사항

  • Xcode 7.0 이상
  • iOS Deployment Target : iOS 7.0 이상

APIKey 발급

이 API를 사용하기 위해서는 App을 생성 후 APIKey를 발급받아야 합니다. (콘솔)

콘솔에서 App 생성 후 플랫폼(android, iOS 등)마다 APIKey를 추가할 수 있습니다.

앱의 Bundle ID는 Info.plist 파일의 Bundle Identifier 프로퍼티에 설정됩니다.

[[NSBundle mainBundle] bundleIdentifier] 메소드를 이용해도 Bundle ID 를 확인할 수 있습니다.

뉴톤 API SDK 설치 및 framework 추가

  1. iOS용 뉴톤 API SDK는 라이브러리 버전별로 받을 수 있습니다.
    압축해제 하시면 라이브러리(lib)뿐만 아니라, 레퍼런스(doc), 샘플코드도 포함되어 있습니다.
    
  2. 우선 SDK 내부의 DaumSpeechRecognizer.embeddedframework를 애플리케이션 프로젝트로 복사합니다.
  3. 프로젝트 Build Phases의 Link Binary With Libraries에 +버튼을 누르고 DaumSpeechRecognizer framework를 추가합니다.
  4. DaumSpeechRecognizer Framework 사용을 위해서는 iOS에서 제공하는 아래 framework들을 추가해야 합니다. 해당 framework 들은 오디오 세션과 관련된 부분의 상태를 확인하고 제어하기 위해 필요합니다.
iOS framework
AudioToolbox
SystemConfiguration
AVFoundation
MediaPlayer

MediaPlayer를 추가하게 되면 뉴톤 API에서는 MPMusicPlayerController로 iPod이 재생여부를 확인하여 음성인식 실행 전에 iPod을 pause 시킨 뒤, 음성인식이 종료된 후 다시 play 합니다. 추가하지 않으면 음성인식에는 영향이 없으나 음성인식 종료 후 앱에서 별도의 AudioSession Category를 설정하지 않았을 경우 SoloAmbientSound로 설정합니다. 추가하고자 하는 Target의 설정에서 “Build Phases” 탭의 “Link Binary With Libraries” 항목 하단에 나타나는 + 버튼을 사용하여 추가할 수 있습니다.

추가하고자 하는 Target의 설정에서 “Build Phases” 탭의 “Link Binary With Libraries” 항목 하단에 나타나는 + 버튼을 사용하여 추가할 수 있습니다. libstdc++6.tbd, libiconv.tbd 도 추가합니다.

Resize icon

추가하고자 하는 Framework의 이름을 검색하고 Add 버튼을 눌러 framework를 Target에 추가합니다.

Resize icon

위 과정을 반복하여 DaumSpeech framework이 사용하는 모든 framework들을 Target에 추가합니다. 아래 이미지는 모든 framework들이 추가된 후의 상태입니다.

Resize icon

라이브러리 import

뉴톤 API 라이브러리는 DaumSpeechRecognizer.h를 import함으로써 접근이 가능합니다.

#import <DaumSpeech/DaumSpeechRecognizer.h>

iOS용 뉴톤 API에서는 클래스명 앞에 모두 MT라는 prefix가 붙습니다.
여기서 MT는 Mobile Toolkit를 의미하고, Daum Developers의 모바일 API의 표준 prefix입니다.

뉴톤 기능 가능여부 체크

현재 사용하는 iOS 기기가 음성 인식이 가능한지 여부를 체크합니다.

BOOL available = [[MTSpeechRecognizer sharedInstance] isRecordingAvailable];

iOS 7 이상에서는 앱에서 마이크를 사용하고자 할 경우 마이크 접근허용을 묻는 메시지가 나타납니다.

마이크 접근허용 승인이 되어있는지를 확인합니다.

isRecordingAvailable에서도 체크를 하지만 마이크 접근허용 거부에 대한 별도의 처리를 원한다면 아래 코드로 확인할 수 있습니다.

BOOL grantedPermission = [[MTSpeechRecognizer sharedInstance] isGrantedRecordingPermission];      

뉴톤 기능 Client 인스턴스 생성하기

음성 인식을 위한 Client 인스턴스를 생성하려면 먼저 정보를 NSDictionary의 key/value 형태로 생성합니다.

SpeechRecognizerConfigKeyApiKey 는 반드시 지정해야 합니다.

그리고 설정을 위한 Dictionary 정보를 가지고 MTSpeechRecognizerClient 인스턴스를 생성하면 됩니다.

뉴톤 기능 설정을 위한 Key는 아래 표를 참고하세요.

설정 Key 설명
SpeechRecognizerConfigKeyApiKey [required] NSString 발급받은 Api Key.
SpeechRecognizerConfigKeyServiceType [optional] NSString 음성 인식에서 지원하는 서비스 타입으로 웹검색/연속어/지도 검색을 제공.
- SpeechRecognizerServiceTypeWeb : 웹 검색 키워드 검색어 인식에 최적화. 포탈 검색에 많이 사용되는 텍스트들에 인식 최적화 되어 있다.(default)
- SpeechRecognizerServiceTypeLocal : 지도 검색으로 장소명 검색어 인식에 최적화.
- SpeechRecognizerServiceTypeDictation : 연속어 인식으로 문장 인식에 최적화. 15초 이내의 한 문장 정도 인식에 사용하면 된다.
- SpeechRecognizerServiceTypeWord : 고립어 인식으로 단어 인식에 최적화. UserDictionary 에 설정된 단어들 중에서만 인식한다.
SpeechRecognizerConfigKeyRecgTimeout [optional] NSNumber (integer) 녹음에서 인식까지의 전체 세션 타임 아웃으로 default는 30초(sec).
SpeechRecognizerConfigKeyServerRecgTimeout [optional] NSNumber (integer) 음성 입력 후에 서버에서 결과를 인식하기까지의 타임아웃으로 default는 10(sec).
NSDictionary *config = @{SpeechRecognizerConfigKeyApiKey : @"발급받은 api Key", SpeechRecognizerConfigKeyServiceType : SpeechRecognizerServiceTypeWeb};

if ([self.selectedServiceType isEqualToString:SpeechRecognizerServiceTypeWord]) {
    [config setObject:@"수지\n태연\n현아\n아이유\n효린" forKey:SpeechRecognizerConfigKeyUserDictionary];
}

MTSpeechRecognizerClient *speechRecognizerClient = [[MTSpeechRecognizerClient alloc] initWithConfig:config];

뉴톤 기능 delegate 설정하기

뉴톤 기능 중에 발생하는 진행상태, audio level, 결과 및 에러 등에 대한 다양한 이벤트를 callback 메서드를 구현하여 처리할 수 있습니다.

callback 메서드를 받기 위해서는 MTSpeechRecognizerDelegate 프로토콜의 delegate 메서드들을 구현하면 됩니다.

delegate 를 지정하는 방법은 SpeechRecognizerClient의 delegate 속성을 이용하면 됩니다.

SpeechRecognizerViewController.h
// 아래와 같이 delegate를 받을 header 파일에 <MTSpeechRecognizerDelegate>를 선언합니다.
@interface SpeechRecognizerViewController : UIViewController <MTSpeechRecognizerDelegate>
SpeechRecognizerViewController.m
// 앞서 생성한 뉴톤 기능 Client에 delegate를 설정합니다.
speechRecognizerClient.delegate = self;

결과값 이용하기

MTSpeechRecognizerDelegate에는 총 7개의 메서드가 있습니다.

우선 [SpeechRecognizerClient startRecording]이 실행된 이후에 음성 입력을 감지하면 감지된 음성에 대한 결과를 경우에 따라 두가지 callback을 통해 얻을 수 있습니다.

onPartialResult

onPartialResult: 는 완전히 음성이 종료되기 이전에 현재까지 인식된 음성데이터 문자열을 알려줍니다.

이 데이터는 서버에 질의해 데이터를 보정하는 과정을 거치지 않으므로, 다소 부정확할 수 있습니다.

중간 인식 결과가 발생할 때마다 호출되므로 여러번 호출될 수 있습니다.

- (void) onPartialResult:(NSString *)partialResult {
  // 뉴톤 기능 중 중간 결과가 있을 때 호출됩니다.
}

Resize icon

onResults:confidences:marked:

onResults:confidences:marked: 는 음성 입력이 종료된 것으로 판단하거나 [SpeechRecognizerClient startRecording] 을 호출한 후에 서버에 질의하는 과정까지 마치고 나면 호출됩니다.

인식된 문자열은 신뢰도가 높은 값부터 순서대로 results 파라미터를 통해 String* 타입으로 얻을 수 있습니다.

신뢰도는 confidences 파라미터를 통해 얻을 수 있으며 높은 값부터 순서대로 Number* 값입니다.

신뢰도값은 항상 0과 같거나 0보다 큰 정수이며, 문자열 목록과 같은 개수입니다.

marked 파라미터는 results의 신뢰도가 가장 높은 0번째 data가 신뢰할 만한 값인지의 여부입니다.

- (void) onResults:(NSArray *)results confidences:(NSArray *)confidences marked:(BOOL)marked {
  // 음성 인식이 성공적으로 끝났을때 호출됩니다.
}

Resize icon

오류 처리 및 기타 이벤트 처리

onError:message:

결과를 얻기 위한 delegate 메서드 말고도 다양한 delegate 메서드가 존재합니다.

onError 메서드는 이름에서 알 수 있듯이 에러가 발생했을 때 호출됩니다.

SpeechRecognizerClient 에서 다양한 에러 코드에 대응하는 MTSpeechRecognizerError enum 값을 알려줍니다.

- (void) onError: (MTSpeechRecognizerError) errorCode message:(NSString *) message {
  // 뉴톤 기능 중 에러가 발생했을 때 호출됩니다.
}

뉴톤 기능 에러코드

뉴톤 API는 아래와 같은 에러코드를 전달합니다. MTSpeechRecognizerError enum 값입니다.

Error Code 설명
MTSpeechRecognizerErrorInitialize 초기화 실패.
MTSpeechRecognizerErrorNoMic 음성입력이 불가능하거나 마이크 접근이 허용되지 않았을 경우.
MTSpeechRecognizerErrorNetwork 네트워크에 의한 실패.
MTSpeechRecognizerErrorAudio Audio session 초기화 실패.
MTSpeechRecognizerErrorGlobalTimeout 음성 입력에서 결과인식까지의 타임아웃이 발생한 경우.
MTSpeechRecognizerErrorRecognitionTimeout 뉴톤 기능에 타임아웃이 발생한 경우.
MTSpeechRecognizerErrorRecognition 뉴톤 기능에 실패한 경우.
MTSpeechRecognizerErrorAuthentication 인증에 실패한 경우.
MTSpeechRecognizerServerAllowedRequestsExcess 음성 인식 요청 허용 횟수 초과.
MTSpeechRecognizerServerError 음성 서버 내부 오류.
MTSpeechRecognizerUnsupprtService 음성서버에서 지원하지 않는 서비스 코드.
MTSpeechRecognizerUserDictEmpty 사용자사전이 꼭 필요한 서비스에서 사용자사전이 비어있는 오류.

기타 이벤트

onReady 메서드는 MTSpeechRecognizerClient의 startRecording이 수행된 후에 오디오 세션 등의 초기화 이후에 호출욉니다. 여러가지 초기화 작업을 성공적으로 마치고 나면 가장 먼저 호출되는 delegate 메서드입니다.

onBeginningOfSpeech 메서드는 사용자가 말하기 시작하는 것으로 판단될 때 호출되는 delegate 메서드입니다. 사용자가 말을 하지 않은 상태에서 에러가 발생하면 이 메서드는 호출되지 않습니다.

onEndOfSpeech 메서드는 사용자가 말하는 것을 끝마친 것으로 판단될 때 호출되는 delegate 메서드입니다.

사용자가 너무 오랜 시간을 말하여 앱이 지정한 시간 내에 음성을 인식하지 못하였거나 인식 중에 오류가 발생했을 때는 호출되지 않습니다.

onEndOfSpeech 이후에는 음성데이터를 서버에 전송하여 값을 보정하고 후보 인식 목록과 신뢰도를 조회하는 과정을 거칩니다.

onAudioLevel: 메서드는 음성이 입력되는 도중에 입력되는 음성의 크기를 dB(데시벨)로 판별한 후 재가공을 거친 상대값을 알려줍니다. 0과 1 사이의 float 값입니다.

Resize icon

- (void) onReady {
  // 음성 인식을 위한 준비가 완료되었을 때 호출됩니다.
}

- (void) onBeginningOfSpeech {
  // 녹음 시작이될 때 호출됩니다.
}

- (void) onEndOfSpeech {
  // 녹음 후 분석 중일때 호출됩니다.
}

- (void) onAudioLevel: (float) level {
  // 음성 audio level. (0 ~ 1)
}

뉴톤 기능 시작하기

음성 인식을 시작하는 방법은 간단합니다.

아래와 같이 [MTSpeechRecognizerClient startRecording] 메서드를 호출합니다.

[speechRecognizerClient startRecording];

뉴톤 기능 중지하기

뉴톤 기능을 중지하는 방법은 [MTSpeechRecognizerClient cancelRecording] 메서드와 [MTSpeechRecognizerClient stopRecording] 메서드, 두가지가 있습니다.

cancelRecording 은 음성 인식을 취소하며 이후로 진행되는 동작은 없습니다.

stopRecording 은 음성 인식을 멈추지만, startRecording을 실행한 이후부터 stopRecording을 실행할 때까지의 음성데이터를 이용해 음성 인식을 진행합니다.

따라서, stopRecording은 실행된 이후에 MTSpeechRecognizerDelegate의 onResults:confidences:marked 또는 onError:message 가 호출되게 됩니다.

[speechRecognizerClient stopRecording];

// or

[speechRecognizerClient cancelRecording];

SDK에서 제공하는 기본 UI 사용하기]

뉴톤 API SDK에서 제공하는 기능을 직접 이용하는 방법 말고도 제공되는 기본 UI를 통해 간편하게 사용자에게 UI를 제공할 수 있습니다. 간결하게 UI를 구성할 수 있도록 샘플 프로젝트의 리소스와 예제 코드를 이용할 수 있습니다.

기본 UI에서 많은 커스터마이징이 필요하다면 별도로 제작하는 것이 바람직합니다.

framework 추가

뉴톤 기능 UI 사용을 위해서는 다음 프레임워크들을 추가로 설정해주어야 합니다.

iOS framework
CoreGraphics
QuartzCore
MediaPlayer (optional)

MediaPlayer를 추가하게 되면 뉴톤 API에서는 MPMusicPlayerController로 iPod이 재생여부를 확인하여 뉴톤 기능 실행 전에 iPod을 pause 시킨 뒤, 음성 인식이 종료된 후 다시 play 합니다.

추가하지 않으면 음성 인식에는 영향이 없으나 뉴톤 기능 종료 후 앱에서 별도의 AudioSession Category를 설정하지 않았을 경우 SoloAmbientSound로 설정합니다.

환경설정 - resource bundle 추가

뉴톤 API SDK에서 제공하는 UI를 사용하기 위해서는 우선, 이미지들이 포함된 리소스 파일을 추가해야 합니다.

프로젝트 Build Phases의 Copy Bundle Resources에 +버튼을 누르고 DaumSpeechResources.bundle을 추가합니다.

Resize icon

custom strings 파일 적용

뉴톤 API SDK에서 기본으로 설정된 strings 파일을 사용하려면 resource bundle을 추가한 것과 같은 방법으로 SpeechRecognizerDefault.strings를 추가합니다.

원한다면 strings 파일을 생성해서 뉴톤 기능 화면에서 사용되는 가이드나 하단 팁을 원하는 문구로 적용할 수 있습니다.

strings 파일은 제공되는 압축파일에 포함된 SpeechRecognizerDefault.strings을 참고하여 변경된 문구를 적용합니다.

Key 이름은 변경하지 말고 해당하는 Key에 대한 모든 문구가 설정되어야 합니다.

Resize icon

NSDictionary 타입의 config를 생성할 때, SpeechRecognizerConfigKeyCustomStringsName 설정 키의 value로 strings 확장자를 제외한 파일의 이름을 설정해줍니다.

NSDictionary *config = @{SpeechRecognizerConfigKeyApiKey : @"발급받은 api Key",
                         // ...
                SpeechRecognizerConfigKeyCustomStringsName : @”SpeechRecognizerDefault”};

뉴톤 기능 화면 생성 및 로드

NSDictionary의 key/value 형태로 생성한 config 정보와 뉴톤 기능 화면을 로드할 view의 frame을 입력하여 뉴톤 기능 화면을 생성합니다. 뉴톤 기능 화면을 로드할 view는 전체화면 크기를 권장합니다. 부모뷰에 addSubview를 해준 다음 show 메서드를 호출해야 표시됩니다.

MTSpeechRecognizerView *speechRecognizerView = [[MTSpeechRecognizerView alloc]     initWithFrame:self.view.frame withConfig:config];

speechRecognizerView.delegate = self; // view의 delegate 설정

[self.view addSubview:speechRecognizerView];
[speechRecognizerView show];

뉴톤 기능 뷰 delegate 설정

뉴톤 API SDK는 뷰에서 결과와 에러에 대한 callback을 delegate method로 전달합니다.

delegate method 구현을 위한 protocol은 MTSpeechRecognizerViewDelegate 입니다.

SpeechRecognizerViewController.h
// 아래와 같이 delegate를 받을 header 파일에 <MTSpeechRecognizerViewDelegate>를 선언합니다.
@interface SpeechRecognizerViewController : UIViewController <MTSpeechRecognizerViewDelegate> 
// ...
SpeechRecognizerViewController.m
// 음성 인식이 성공적으로 끝났을 때 호출됩니다.
- (void) onResults:(NSArray *)results confidences:(NSArray *)confidences marked:(BOOL)marked {
  // results : 뉴톤 기능 결과 리스트로 신뢰도 순으로 정렬.
  // confidences : results 각각의 결과에 대한 신뢰도 값 리스트.
  // marked : results의 신뢰도가 가장 높은 0번째 data가 신뢰할 만한 값인지의 여부.
}

// 뉴톤 기능 중 에러가 발생했을 때 호출됩니다.
- (void) onError: (MTSpeechRecognizerError) errorCode message:(NSString *) message {
  // ...
}

iOS 7 이상에서는 앱에서 마이크를 사용하고자 할 경우 마이크 접근허용을 묻는 메시지가 뜹니다.

만약 마이크 접근 설정이 거부되어 있다면 음성 인식을 시작할 때 다음과 같은 에러 alert으로 안내합니다.

Resize icon

후보단어 표시 생략하기

기본 UI를 통한 구현은 기본적으로 높은 신뢰도를 가지지 못한 결과 목록을 얻었을 때 사용자에게 말한 내용을 판단하도록 거치는 과정이 있습니다.

이 과정을 생략하거나 다른 방법으로 안내를 하려면 SpeechRecognizerConfigKeyShowSuggestView 설정 키로 서제스트 화면을 보일지 여부를 설정할 수 있습니다.

이 값을 NO 로 설정하여 후보단어 표시를 생략하였고, 신뢰도가 높지 못한 결과가 나왔을 때만 onResults:confidences:marked: 메서드에서 marked 파라미터의 값이 false가 됩니다.

default 설정은 YES입니다.

NSDictionary *config = @{// ...
              SpeechRecognizerConfigKeyShowSuggestView : @(NO)};

MTSpeechRecognizerView *speechRecognizerView = [[MTSpeechRecognizerView alloc]     initWithFrame:self.view.frame withConfig:config];

추가 설명

서비스 모드 설명

서비스 모드란 음성인식 도메인이고, 각 도메인에 더 특화되어 있다.

서비스 모드 도메인 종류

서비스 모드 도메인 설명
Dictation 받아쓰기 모드이며 일반적인 문장, 대화체 인식에 사용
Local 주소, 지역명 인식에 사용(예 : 카카오맵 앱 음성 인식)
Web or Search 웹 검색에 사용 (예 : 다음 앱 음성 인식)
Word 명령어 인식에 사용

Word 모드에서 User Dict (사용자 사전) 설명

user dict (사용자 사전) 에 단어들을 넣어놓고 인식하면 그 단어들중에서만 인식 된다. user dict 에는 한단어 이상 반드시 들어가야 한다. (user dict 가 비워져있으면 에러 반환된다.) 그외 서비스 모드에서는 사용자 사전 안에 있는 텍스트들을 좀 더 가중치를 줘서 인식한다. 최대 허용 사이즈 : 약 3000 단어 정도

api 사용 방식

비동기적으로 사용해야 함

message queue, event handler 등을 사용해 비동기적으로 처리하고 onPartialResult, onError 등의 이벤트 호출 함수 안에서 또 다시 음성 api 함수를 재호출하지 않는다.

예 : onInactive (ios 라이브러리 경우 onFinished) 호출 안에서 startListening 재 호출 하는 경우 지양

stop (stopRecording 또는 stopListening) 과 cancel 호출 의 차이

stop : stop 이 호출된 시점까지 인식된다. (서버의 인식 결과를 기다림) cancel : cancel 이 호촐되면 바로 취소된다. (서버의 인식 결과를 기다리지 않고 취소됨)

종료시 마지막으로 호출되는 이벤트 함수

에러 발생시 : onError 정상 종료시 : onInacitive

이중 실행 금지

ios, android 음성 라이브러리는 기본적으로 이중 또는 다중 실행을 지원하지 않는다. 중복 실행시 여러 버그의 원인이 된다.

이용 가능 횟수

apikey 신청후 테스트 용도로 사용시 하루 100 회 까지 가능하다. 개인 실명 또는 회사 법인 확인 절차 이후 하루 20000 회 까지 가능하다. (인식 합성 모두 이용시 총 요청 횟수는 20000 회 까지 가능하다.)

카카오 이미지 표시 의무

개인 또는 법인이 상업적 용도로 사용시 아래 카카오(powered by kakao) 이미지를 음성 인식 라이브러리를 사용하고 있을때 표시하여야 한다. 폰 화면 상에서 위치는 상하 좌우측 또는 중간에 표시한다. 이미지 사이즈는 최소 가로 102 픽셀, 세로 15 픽셀 이상이어야 한다. (더 크게 표시할 경우 가로 세로 배율 유지)

Resize icon

Miscellaneous

ios 9.0, xcode 7.0 이상에서 Enable bitcode 를 지원합니다. 내부적으로 사용하는 AVAudioSession 옵션이 ios 버전별로 지원합니다. ios 8.0 이상에서 AVAudioSessionCategoryOptionAllowBluetooth, 9.0 이상에서 AVAudioSessionCategoryOptionInterruptSpokenAudioAndMixWithOthers 를 지원합니다. ios 10.0 이상에서 앱을 빌드할 때 Info.Plist 에서 Privacy - Microphone Usage Description 설정을 추가해줘야 합니다.

이용사례

좋은 사례를 갤러리에 올려주시면, 검토 후 추가하겠습니다.