본문 바로가기

Daum Developers

서비스

뉴톤톡(Newtone Talk) - 모바일(Android) SDK

목차

소개

안드로이드 앱 개발시 Daum Developers에서 제공하는 뉴톤톡 SDK를 활용하여 텍스트를 음성으로 합성하는 기능을 추가할 수 있습니다.

요구 사항

  • minimum OS 버전 : android 2.3 (API Level 10)
  • target OS 버전 : android 6.0 (API Level 23)
  • 개발툴 : android studio (IntelliJ)
  • ver 2.2 부터 eclipse를 지원하지 않습니다.

APIKey 발급

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

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

안드로이드 앱의 package name은 AndroidManifest.xml 파일 내 manifest 엘리먼트의 package 속성을 통해 알 수 있습니다.

뉴톤 API SDK 설치하기

안드로이드용 뉴톤톡 SDK는 라이브러리 버전별로 받을 수 있습니다.

제공되는 zip 압축파일을 해제하면 개발에 필요한 라이브러리(lib)와 레퍼런스(doc), 샘플코드가 포함되어 있습니다.

안드로이드 뉴톤톡 SDK는 aar 패키징된 파일로 제공됩니다. 해당 파일은 다운 받으신 압축파일을 푼 후, daum-speech-openapi-x.x 폴더 안에서 확인 할 수 있습니다.

Resize icon

제공된 SDK를 본인의 프로젝트 안에 추가하려면 다음의 순서대로 진행하면 됩니다.

  1. android studio에서 현재 작업 중인 프로젝트를 연 다음, File -> New -> New Module... 순으로 메뉴를 선택합니다.

Resize icon

  1. 나타나는 대화창의 다양한 옵션 중에서 Import .JAR/.AAR Package를 선택합니다.

Resize icon

  1. File -> project Structure... 에서 app module의 dependencies에 daum-speech-openapi-5.0을 추가합니다. Resize icon

이후 해당 aar 파일의 위치를 지정해주면 라이브러리 설치는 완료 됩니다.

permission 설정하기

뉴톤 기능을 이용하기 위해서는 몇가지 permission을 설정해야만 합니다. AndroidManifest.xml 파일에는 다음과 같은 permission 들을 설정합니다. (bluetooth는 선택사항입니다.)

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />

라이브러리 초기화 및 해제

뉴톤톡 기능을 이용하려면 먼저 라이브러리 초기화를 해줘야 합니다.

뉴톤톡 기능을 이용하는 TextToSpeechActivity의 onCreate()에서 라이브러리를 초기화 하는 함수인 initializeLibrary()를 아래와 같이 호출합니다.

public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      TextToSpeechManager.getInstance().initializeLibrary(getApplicationContext());
 }

라이브러리를 해제할 경우에는 다음과 같이 합니다.

public void onDestroy() {
      super.onDestroy();
      TextToSpeechManager.getInstance().finalizeLibrary();
}

클라이언트 인스턴스 생성 및 기본설정

음성합성을 사용하기 위해서는 뉴톤톡 클래스의 인스턴스 생성 및 발급받은 apikey, 서비스 모드 등을 설정해야 합니다.

뉴톤톡 기능의 설정과 실행은 TextToSpeechClient를 통해 이용할 수 있습니다.

TextToSpeechClient 인스턴스는 TextToSpeechClient.Builder 를 통해 생성합니다.

private TextToSpeechClient ttsClient;

...

    ttsClient = new TextToSpeechClient.Builder()
            .setApiKey(APIKEY)              // 발급받은 api key
            .setSpeechMode(TextToSpeechClient.NEWTONE_TALK_1)            // 음성합성방식
            .setSpeechSpeed(1.0)            // 발음 속도(0.5~4.0)
            .setSpeechVoice(TextToSpeechClient.VOICE_WOMAN_READ_CALM)  //TTS 음색 모드 설정(여성 차분한 낭독체)
            .setListener(this)
            .build();
설정 Key 설명
setApiKey(String) [required] 발급받은 Api Key.
setSpeechMode(String) TextToSpeechClient.NEWTONE_TALK_1 : 통계적 합성 방식 (기존)
- 기존에 뉴톤톡 API로 제공되던 통계적 합성 방식은 음성의 통계적 특성을 분석하여 모델을 만들고 이를 이용하여 합성하는 방식으로, 녹음된 데이터에 없는 합성음을 안정적으로 합성해 낼 수 있어서 다양한 분야에 적용되어도 일관된 품질의 합성음을 생성해 낼 수 있고 음색 변환 등 다양한 응용에 적용할 수 있습니다. 일반적으로 편집 합성 방식에 비해 음질이 떨어집니다.
TextToSpeechClient.NEWTONE_TALK_2 : 편집 합성 방식
- 새롭게 추가된 편집 합성 방식은 통계적 특성을 이용하는 것이 아니라 녹음된 음성 데이터 자체를 이용하여 필요한 음소들을 발췌하여 합성하는 방식입니다. 장점으로는 데이터 자체를 이용하므로 녹음에 사용된 문장과 동일한 영역의 문장들에 대해서는 통계적 합성 방식보다 자연스러운 음성을 만들어 낼 수 있습니다. 단점으로는 녹음 데이터에 없는 영역의 문장에서는 음질이 저하되는 단점이 있습니다. (예를 들어 대화체 음색을 이용하여 낭독체 문장을 합성하는 경우). 편집 합성 방식에서는 통계적 합성 방식과 달리 합성 속도 변경 기능은 제공하지 않습니다.
setSpeechSpeed(double) 발음속도 0.5 ~ 4.0 (1이 보통속도, 크면 빠르게, 작으면 느리게)
setSpeechVoice(String) TextToSpeechClient.VOICE_WOMAN_READ_CALM : 여성 차분한 낭독체
TextToSpeechClient.VOICE_MAN_READ_CALM : 남성 차분한 낭독체
TextToSpeechClient.VOICE_WOMAN_DIALOG_BRIGHT : 여성 밝은 대화체
TextToSpeechClient.VOICE_MAN_DIALOG_BRIGHT : 남성 밝은 대화체

뉴톤톡 리스너 구현

음성합성은 multi thread 기반으로 동작하며 음성합성이 진행되는 과정에 따라 이벤트들이 호출되고 그에 따른 동작들을 구현해주면 됩니다. 음성인식과 달리 음성합성은 중간 결과가 없기 때문에, onFinished와 onError이벤트 밖에 없어서 비교적 구현이 간단합니다.

음성합성의 callback을 받기위해서 TextToSpeechListener를 구현해 줍니다.

모든 callback 함수는 UI thread가 아닌 background thread에서 호출될 수 있기 때문에, UI와 관련된 작업은 Activity.runOnUiThread(Runnable) 이나 Handler.post(Runnable)을 통해 비동기로 호출해야 합니다.

onError는 뉴톤톡 중에 에러가 발생한 경우 호출됩니다.

onFinished는 음성합성이 완료된 뒤에 호출됩니다.

//net.daum.mf.speech.api.TextToSpeechListener
    @Override
    public void onError(int code, String message) { //에러처리
        handleError(code);
    }

    @Override
    public void onFinished() { //음성합성이 종료될 때 호출된다.
        int intSentSize = ttsClient.getSentDataSize();      //세션 중에 전송한 데이터 사이즈
        int intRecvSize = ttsClient.getReceivedDataSize();  //세션 중에 전송받은 데이터 사이즈

        final String strInacctiveText = "handleFinished() SentSize : " + intSentSize + "     RecvSize : " + intRecvSize;

        Log.i(TAG, strInacctiveText);
    }

뉴톤톡 실행 하기

음성합성을 위한 텍스트를 넣고 play() 시키면 동작됩니다.

play 함수에 텍스트를 파라미터로 전달하거나 미리 텍스트를 세팅한 후 플레이 할 수도 있습니다.

//boolean net.daum.mf.speech.api.TextToSpeechClient.play(String)
//boolean net.daum.mf.speech.api.TextToSpeechClient.play()
//boolean net.daum.mf.speech.api.TextToSpeechClient.setSpeechText(String)

예)
String strText = "안녕하세요"
ttsClient.play(strText);

// 또는
ttsClient.setSpeechText(strText);   //뉴톤톡 하고자 하는 문자열을 미리 세팅.
ttsClient.play();       //세팅된 문자열을 합성하여 재생.

합성된 음성이 재생되는 것을 중지시키려면 stop()을 사용합니다.

//void net.daum.mf.speech.api.TextToSpeechClient.stop()

예)
ttsClient.stop();
합성된 음성이 재생중인지 확인하려면 isPlaying()을 사용합니다. 반환값이 True이면 재생중입니다.
//boolean net.daum.mf.speech.api.TextToSpeechClient.isPlaying()

예)
ttsClient.isPlaying();    

뉴톤톡 리스너에서 오류 처리

onError

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

TextToSpeechClient 에서 다양한 에러 코드에 대응하는 ERROR_ 로 시작하는 code 값들을 확인할 수 있습니다.

@Override
public void onError(int errorCode, String errorMsg) {
    //TODO implement interface DaumTextToSpeechListener method
}

뉴톤톡 에러코드

뉴톤 API는 아래와 같은 에러코드를 전달합니다. TextToSpeechClient에서 ERROR_ 로 시작하는 static int 값들을 참고할 수 있습니다.

Error Code 설명
ERROR_NONE 정상 (오류가 아님.)
ERROR_NETWORK 네트워크 오류가 발생한 경우.
ERROR_NETWORK_TIMEOUT 네트워크 타임아웃이 발생한 경우. (클라이언트에서 SOCKET READ TIMEOUT 5초 초과)
ERROR_CLIENT_INETRNAL 클라이언트 내부 오류가 발생한 경우.
ERROR_SERVER_INTERNAL 서버에서 오류가 발생한 경우.
ERROR_SERVER_TIMEOUT 서버 최대 접속시간 초과.(세션 30초 초과 또는 서버에서 SOCKET READ TIMEOUT 5초 초과)
ERROR_SERVER_AUTHENTICATION APPID 또는 APPKEY가 틀려서 인증이 실패한 경우.
ERROR_SERVER_SPEECH_TEXT_BAD 뉴톤톡 텍스트 오류 (처리과정을 거친 후 문자열의 길이가 0 또는 문자열의 길이가 0이상이지만 발음할 수 없는 문자로 구성된 경우. (^^, ----, (), [], !!!!! ) 등.)
ERROR_SERVER_SPEECH_TEXT_EXCESS 뉴톤톡 최대 허용 길이 초과.(합성 길이가 30초 이상이거나 100byte이상 길이의 단어가 포함되어 있는 경우.)
ERROR_SERVER_SPEECH_TEXT_FORBIDDEN 뉴톤톡 금칙어 오류.
ERROR_SERVER_ALLOWED_REQUESTS_EXCESS 뉴톤톡 서비스 최대 허용 횟수 초과.
ERROR_UNSUPPORTED_SERVICE 음성합성 서비스 모드 오류.
ERROR_UNKNOWN 알 수 없는 오류.

기타 이벤트

onFinished 메서드는 TextToSpeechClient의 합성된 음성의 재생이 종료된 이후에 호출됩니다.

여러가지 합성음 작업을 성공적으로 마치고 나면 가장 마지막에 호출되는 메서드입니다.

@Override
public void onFinished() {
    //TODO implement interface DaumTextToSpeechListener method
}

뉴톤 시작하기

Newtone을 시작하는 방법은 간단합니다.

아래와 같이 SpeechRecognizerClient의 startRecording() 메서드를 호출합니다.

파라미터로 입력하는 boolean 값은 현재 재생되고 있는 음악 등 배경 소리를 음소거(mute)할지 지정하는 값입니다. 값이 true면 음소거를 합니다.

음소거를 했을 경우 음성 인식이 종료되면 음소거가 종료됩니다.

client.startRecording(true);

뉴톤톡 기본 내부 규칙

1. 표준어 및 한글 사용

  • "Daum Developers 음성 합성 엔진"은 한국어 문장 합성기로, 영어 문장은 합성이 불가능합니다.
    • 다만 흔히 사용하는 영어 단어, 약어, 유명인 이름, 기업명 등은 예외적으로 한국식 발음으로 읽습니다.
  • 사투리나 은어, 비속어, 오타등은 합성음이 부자연스러울 수 있습니다.
  • URL -> "링크", 이메일 주소->"이메일 주소" 라는 발음으로 변환됩니다.
  • 미리 정의된 "ㅋㅋ", "ㅎㅎ" 등의 대화체 단어는 아래와 같이 합성됩니다.
단어 합성음
ㅎㅎ 흐흐 (3개 이상부터 "흐흐흐"로 통일)
ㅋㅋ 크크 (3개 이상부터 "크크크"로 통일)
ㅇㅋ 오케이
ㅇㅇ
ㄴㄴ
ㅃㅇ 빠이
ㅎㅇ 하이

2. 적절한 문장 부호 사용

  • 쉼표, 마침표, 느낌표, 물음표 등의 문장부호를 적절하게 사용합니다.
  • 특히 쉼표를 이용하여, 합성음에서의 인위적인 끊어읽기를 유도할 수 있습니다.

3. 특수기호

  • 흔히 쓰이는 특수기호를 제외하고는, 합성시 무시됩니다.
  • 마침표(.), 물음표(?), 탭(\t). 뉴라인(\n)을 기준으로 문장을 분리합니다.
  • 한글 자소, 한자 및 외래어등은 합성시 무시됩니다.
  • 흔히 사용되는 특수기호는 다음과 같습니다.
특수기호 합성음
$ 달러
¥
£ 파운드
유로
°
섭씨
화씨

4. 허용하지 않는 문장

  • 피싱에 사용될 가능성이 높은 문장
  • 음란성 문장