chrome.tts

설명

chrome.tts API를 사용하여 합성 텍스트 음성 변환 (TTS)을 재생합니다. 확장 프로그램이 음성 엔진을 구현할 수 있도록 하는 관련 ttsEngine API도 참고하세요.

Chrome은 운영체제에서 제공하는 음성 합성 기능을 사용하여 Windows (SAPI 5 사용), Mac OS X, ChromeOS에서 이 기능을 제공합니다. 모든 플랫폼에서 사용자는 대체 음성 엔진으로 등록되는 확장 프로그램을 설치할 수 있습니다.

권한

tts

개념 및 사용법

음성 생성

말하려면 확장 프로그램에서 speak()번으로 전화를 거세요. 예를 들면 다음과 같습니다.

chrome.tts.speak('Hello, world.');

즉시 말하지 않으려면 stop()를 호출하면 됩니다.

chrome.tts.stop();

속도, 높낮이 등 음성의 다양한 속성을 제어하는 옵션을 제공할 수 있습니다. 예를 들면 다음과 같습니다.

chrome.tts.speak('Hello, world.', {'rate': 2.0});

또한 해당 언어 (및 해당하는 경우 지역 방언)를 지원하는 신시사이저가 선택되도록 언어를 지정하는 것이 좋습니다.

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

기본적으로 speak()를 호출할 때마다 진행 중인 음성을 중단하고 즉시 말합니다. 호출이 방해를 받는지 확인하려면 isSpeaking()를 호출하면 됩니다. 또한 enqueue 옵션을 사용하여 이 발화가 현재 발화가 완료될 때 말할 발화 대기열에 추가되도록 할 수 있습니다.

chrome.tts.speak('Speak this first.');
chrome.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

모든 옵션에 대한 자세한 설명은 tts.speak()에서 확인할 수 있습니다. 일부 음성 엔진은 모든 옵션을 지원하지 않습니다.

오류를 포착하고 speak()를 올바르게 호출하고 있는지 확인하려면 인수를 사용하지 않는 콜백 함수를 전달합니다. 콜백 내에서 runtime.lastError를 확인하여 오류가 있는지 확인합니다.

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

엔진이 음성 생성을 시작하기 전에 즉시 콜백이 반환됩니다. 콜백의 목적은 음성을 합성하고 출력하는 과정에서 발생할 수 있는 모든 오류를 포착하는 것이 아니라 TTS API 사용 시 발생하는 구문 오류를 사용자에게 알리는 것입니다. 이러한 오류를 포착하려면 다음 섹션에서 설명하는 이벤트 리스너를 사용해야 합니다.

이벤트 수신 대기

합성된 음성의 상태에 관한 실시간 정보를 더 많이 얻으려면 다음과 같이 옵션에서 이벤트 리스너를 speak()에 전달합니다.

chrome.tts.speak(
  utterance,
  {
    onEvent: function(event) {
      console.log('Event ' + event.type + ' at position ' + event.charIndex);
      if (event.type == 'error') {
        console.log('Error: ' + event.errorMessage);
      }
    }
  },
  callback
);

각 이벤트에는 이벤트 유형, 발화와 관련된 현재 음성의 문자 색인, 오류 이벤트의 경우 선택적 오류 메시지가 포함됩니다. 이벤트 유형은 다음과 같습니다.

  • 'start': 엔진이 발화를 말하기 시작했습니다.
  • 'word': 단어 경계에 도달했습니다. event.charIndex를 사용하여 현재 음성 위치를 확인합니다.
  • 'sentence': 문장 경계에 도달했습니다. event.charIndex를 사용하여 현재 음성 위치를 확인합니다.
  • 'marker': SSML 마커에 도달했습니다. event.charIndex를 사용하여 현재 음성 위치를 확인합니다.
  • 'end': 엔진이 발화 말하기를 완료했습니다.
  • 'interrupted': 이 발화가 speak() 또는 stop()의 다른 호출로 인해 중단되었으며 완료되지 않았습니다.
  • 'cancelled': 이 발화는 대기열에 추가되었지만 speak() 또는 stop()의 다른 호출로 인해 취소되어 전혀 발화되지 않았습니다.
  • 'error': 엔진 관련 오류가 발생하여 이 발화를 말할 수 없습니다. 자세한 내용은 event.errorMessage를 확인하세요.

4가지 이벤트 유형('end', 'interrupted', 'cancelled', 'error')은 최종 유형입니다. 이러한 이벤트 중 하나가 수신되면 이 발화는 더 이상 말하지 않으며 이 발화의 새 이벤트는 수신되지 않습니다.

일부 음성은 일부 이벤트 유형을 지원하지 않을 수 있으며, 어떤 음성은 이벤트를 전혀 전송하지 못할 수 있습니다. 특정 이벤트를 전송하지 않는 한 음성을 사용하지 않으려면 옵션 객체의 requiredEventTypes 멤버에 필요한 이벤트를 전달하거나 getVoices()를 사용하여 요구사항을 충족하는 음성을 선택합니다. 둘 다 다음에 설명되어 있습니다.

SSML 마크업

이 API에서 사용되는 발화에는 SSML(음성 합성 마크업 언어)을 사용한 마크업이 포함될 수 있습니다. SSML을 사용하는 경우 speak()의 첫 번째 인수는 문서 조각이 아닌 XML 헤더와 최상위 <speak> 태그가 있는 완전한 SSML 문서여야 합니다.

예를 들면 다음과 같습니다.

chrome.tts.speak(
  '<?xml version="1.0"?>' +
  '<speak>' +
  '  The <emphasis>second</emphasis> ' +
  '  word of this sentence was emphasized.' +
  '</speak>'
);

모든 음성 엔진이 모든 SSML 태그를 지원하는 것은 아니며 일부는 SSML을 전혀 지원하지 않을 수도 있습니다. 하지만 모든 엔진은 지원하지 않는 SSML을 무시하고 기본 텍스트를 읽어야 합니다.

음성 선택

기본적으로 Chrome은 사용자가 말하고자 하는 각 발화에 가장 적합한 음성을 언어에 따라 선택합니다. 대부분의 Windows, Mac OS X, ChromeOS 시스템에서 운영체제에서 제공하는 음성 합성은 하나 이상의 언어로 모든 텍스트를 말할 수 있어야 합니다. 하지만 일부 사용자는 운영체제 및 다른 Chrome 확장 프로그램으로 구현된 음성 엔진에서 다양한 음성을 사용할 수 있습니다. 이러한 경우 커스텀 코드를 구현하여 적절한 음성을 선택하거나 사용자에게 선택 목록을 제공할 수 있습니다.

모든 음성 목록을 가져오려면 getVoices()를 호출하여 TtsVoice 객체의 배열을 인수로 수신하는 함수를 전달합니다.

chrome.tts.getVoices(
  function(voices) {
    for (var i = 0; i < voices.length; i++) {
      console.log('Voice ' + i + ':');
      console.log('  name: ' + voices[i].voiceName);
      console.log('  lang: ' + voices[i].lang);
      console.log('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

유형

EventType

Chrome 54 이상

enum

TtsEvent

발화 상태를 전달하기 위한 TTS 엔진의 이벤트입니다.

속성

  • charIndex

    number 선택사항

    발화에 있는 현재 문자의 색인입니다. 단어 이벤트의 경우 한 단어가 끝나고 다음 단어가 시작되기 전에 이벤트가 실행됩니다. charIndex는 텍스트에서 다음에 말할 단어의 시작 부분을 나타냅니다.

  • errorMessage

    문자열 선택사항

    이벤트 유형이 error인 경우 오류 설명입니다.

  • length

    number 선택사항

    Chrome 74 이상

    발화에서 다음 부분의 길이입니다. 예를 들어 word 이벤트에서 다음에 말할 단어의 길이입니다. 음성 엔진에서 설정하지 않으면 -1로 설정됩니다.

  • 유형

    EventType

    유형은 음성이 시작된 즉시 start, 단어 경계에 도달하면 word, 문장 경계에 도달하면 sentence, SSML 표시 요소에 도달하면 marker, 발화 끝에 도달하면 end, 발화가 끝나기 전에 중지되거나 중단되면 interrupted, 합성되기 전에 대기열에서 삭제되면 cancelled, 기타 오류가 발생할 때 error일 수 있습니다. 음성을 일시중지할 때 특정 발화가 중간에 일시중지되면 pause 이벤트가 실행되고, 발화가 말을 재개하면 resume 이벤트가 실행됩니다. 발화 사이에 음성이 일시중지되면 일시중지 및 다시 시작 이벤트가 실행되지 않을 수 있습니다.

TtsOptions

Chrome 77 이상

TTS 엔진의 음성 옵션입니다.

속성

  • desiredEventTypes

    string[] 선택사항

    수신하려는 TTS 이벤트 유형입니다. 누락된 경우 모든 이벤트 유형이 전송될 수 있습니다.

  • 큐에 추가

    부울 선택사항

    true인 경우 TTS가 이미 진행 중이면 이 발화를 큐에 추가합니다. false인 경우 (기본값) 현재 음성을 중단하고 이 새로운 발화를 말하기 전에 음성 대기열을 플러시합니다.

  • extensionId

    문자열 선택사항

    사용할 음성 엔진의 확장 프로그램 ID입니다(알려진 경우).

  • gender

    VoiceGender 선택사항

    Chrome 77부터 지원 중단됨

    성별은 지원 중단되었으며 무시됩니다.

    합성된 음성의 음성 성별입니다.

  • lang

    문자열 선택사항

    합성에 사용할 언어이며 언어-지역 형식입니다. 예: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • 투구

    number 선택사항

    0과 2 사이의 피치를 말합니다. 0이 가장 낮고 2가 가장 높습니다. 1.0은 음성의 기본 높낮이에 해당합니다.

  • 요금

    number 선택사항

    이 음성의 기본 속도에 따른 말하기 속도입니다. 1.0이 기본 속도이며 일반적으로 분당 약 180~220단어입니다. 2.0은 기본 속도의 2배이며 0.5는 절반입니다. 0.1 미만 또는 10.0 이상의 값은 엄격하게 허용되지 않지만 많은 음성이 최소 및 최대 속도를 추가로 제한합니다. 예를 들어 특정 음성은 값을 3.0보다 크게 지정해도 실제로는 보통 3배보다 빠르지 않을 수 있습니다.

  • requiredEventTypes

    string[] 선택사항

    음성이 지원해야 하는 TTS 이벤트 유형입니다.

  • voiceName

    문자열 선택사항

    합성에 사용할 음성의 이름입니다. 비어 있는 경우 사용 가능한 음성을 사용합니다.

  • 볼륨

    number 선택사항

    말하기 볼륨은 0부터 1까지이며 0은 가장 낮고 1은 가장 높고 기본값은 1.0입니다.

  • onEvent

    void 선택사항

    이 함수는 발화를 말하는 과정에서 발생하는 이벤트와 함께 호출됩니다.

    onEvent 함수는 다음과 같습니다. 

    (event: TtsEvent)=> {...}

    • event

      TtsEvent

      이 발화의 상태를 나타내는 텍스트 음성 변환 엔진의 업데이트 이벤트입니다.

TtsVoice

음성 합성에 사용할 수 있는 음성에 관한 설명입니다.

속성

  • eventTypes

    EventType[] 선택사항

    이 음성이 전송할 수 있는 모든 콜백 이벤트 유형입니다.

  • extensionId

    문자열 선택사항

    이 음성을 제공하는 확장 프로그램의 ID입니다.

  • gender

    VoiceGender 선택사항

    Chrome 70부터 지원 중단됨

    성별은 지원 중단되었으며 무시됩니다.

    이 음성의 성별입니다.

  • lang

    문자열 선택사항

    이 음성이 지원하는 언어로서 언어-지역 형식입니다. 예: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • 리모컨

    부울 선택사항

    true인 경우 합성 엔진은 원격 네트워크 리소스입니다. 지연 시간이 길어지고 대역폭 비용이 발생할 수 있습니다.

  • voiceName

    문자열 선택사항

    음성 이름입니다.

VoiceGender

Chrome 54 이상 Chrome 70부터 지원 중단됨

성별은 지원 중단되었으며 무시됩니다.

enum

방법

getVoices()

프로미스 
chrome.tts.getVoices(
  callback?: function,
)

사용 가능한 모든 음성의 배열을 가져옵니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (voices: TtsVoice[])=>void

    • 목소리

      TtsVoice[]

      음성 합성에 사용할 수 있는 음성을 나타내는 tts.TtsVoice 객체의 배열입니다.

반환 값

  • Promise<TtsVoice[]>

    Chrome 101 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

isSpeaking()

프로미스 
chrome.tts.isSpeaking(
  callback?: function,
)

엔진이 현재 말하고 있는지 확인합니다. Mac OS X에서는 Chrome에서 음성이 시작되지 않았더라도 시스템 음성 엔진이 말할 때마다 결과가 true입니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (speaking: boolean)=>void

    • 말하기

      boolean

      말하면 true, 그렇지 않으면 false입니다.

반환 값

  • Promise<boolean>

    Chrome 101 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

pause()

chrome.tts.pause()

잠재적으로 발화 도중에 음성 합성을 일시중지합니다. 재개 또는 중지를 호출하면 음성 일시중지가 해제됩니다.

resume()

chrome.tts.resume()

음성이 일시중지된 경우 중단된 부분부터 다시 말합니다.

speak()

프로미스 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

텍스트 음성 변환 엔진을 사용하여 텍스트를 읽습니다.

매개변수

  • 발화

    문자열

    음성 텍스트이며 일반 텍스트 또는 올바른 형식의 완전한 SSML 문서입니다. SSML을 지원하지 않는 음성 엔진은 태그를 제거하고 텍스트를 말합니다. 텍스트의 최대 길이는 32,768자(영문 기준)입니다.

  • 옵션

    TtsOptions 선택사항

    음성 옵션입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 101 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

stop()

chrome.tts.stop()

현재 음성을 중지하고 대기 중인 발화의 큐를 플러시합니다. 또한 음성이 일시중지된 경우 다음번 통화 시 일시중지가 해제됩니다.

이벤트

onVoicesChanged

Chrome 124 이상 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

getVoices에서 반환되는 tts.TtsVoice 목록이 변경되었을 때 호출됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    ()=>void