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')이 최종입니다. 후(After) 수신된 이벤트 중 하나가 수신되면 이 발화는 더 이상 말하지 않으며 이 발화의 새 이벤트도 음성이 수신됩니다

일부 음성은 이벤트 유형을 지원하지 않을 수도 있으며, 이벤트를 전혀 전송하지 않는 음성이 있을 수도 있습니다. 만약 사용하지 않으려는 경우 옵션 객체의 requiredEventTypes 멤버를 선택하거나 getVoices()을 사용하여 맞춤설정할 수 있습니다 두 가지 모두 다음에 설명되어 있습니다.

SSML 마크업

이 API에서 사용되는 발언에는 음성 합성 마크업 언어(Speech Synthesis Markup Language)를 사용하는 마크업이 포함될 수 있습니다. (SSML). SSML을 사용하는 경우 speak()의 첫 번째 인수는 문서 프래그먼트가 아닌 XML 헤더 및 최상위 <speak> 태그여야 합니다.

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

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 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

열거형

"시작"

"end"

"단어"

"sentence"

"마커"

"중단됨"

'취소됨'

"오류"

"일시중지"

"Resume"

TtsEvent

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

속성

  • charIndex

    숫자 선택사항

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

  • errorMessage

    문자열(선택사항)

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

  • 길이

    숫자 선택사항

    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 (선택사항)

    <ph type="x-smartling-placeholder"></ph> Chrome 77 이후 지원 중단됨

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

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

  • lang

    문자열(선택사항)

    합성에 사용되는 언어로, language-region 형식입니다. 예: 'en', 'en-US', 'en-GB', 'zh-CN'.

  • 투구

    숫자 선택사항

    말하기 음조는 0과 2 사이로, 0이 가장 낮고 2가 가장 높습니다. 1.0은 음성의 기본 높낮이에 해당합니다.

  • 요금

    숫자 선택사항

    이 음성의 기본 속도를 기준으로 한 말하기 속도입니다. 1.0이 기본 속도이며 일반적으로 분당 180~220단어입니다. 2.0은 기본 속도의 2배이며 0.5는 절반입니다. 0.1보다 작거나 10.0보다 큰 값은 엄격하게 허용되지 않지만, 대다수의 음성에서는 최소 및 최대 비율을 추가로 제한할 수 있습니다. 예를 들어 3.0보다 큰 값을 지정해도 특정 음성이 실제로 3배 이상 빠르게 말하지 않을 수 있습니다.

  • requiredEventTypes

    string[] 선택사항

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

  • voiceName

    문자열(선택사항)

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

  • 볼륨

    숫자 선택사항

    말하기 볼륨은 0 이상 1 이하입니다. 0이 가장 낮고 1이 가장 높으며 1이 가장 높으며 기본값은 1.0입니다.

  • onEvent

    void 선택사항

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

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

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

    • event

      TtsEvent

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

TtsVoice

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

속성

  • eventTypes

    EventType[] 선택사항

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

  • extensionId

    문자열(선택사항)

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

  • gender

    VoiceGender (선택사항)

    <ph type="x-smartling-placeholder"></ph> Chrome 70 이후 지원 중단됨

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

    이 음성의 성별입니다.

  • lang

    문자열(선택사항)

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

  • 리모컨

    불리언 선택사항

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

  • voiceName

    문자열(선택사항)

    음성 이름입니다.

VoiceGender

Chrome 54 이상 에서 확인하세요. Chrome 70 이후 지원 중단됨

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

열거형

"남성"

"여성"

메서드

getVoices()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.tts.getVoices(
  callback?: function,
)

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

매개변수

  • 콜백

    함수 선택사항

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

    (voices: TtsVoice[]) => void

    • 목소리

      TtsVoice[]

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

반환 값

  • Promise&lt;TtsVoice[]&gt;

    Chrome 101 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

isSpeaking()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.tts.isSpeaking(
  callback?: function,
)

엔진이 현재 말하는지 확인합니다. Mac OS X에서는 Chrome에서 음성을 시작하지 않은 경우에도 시스템 음성 엔진이 말할 때마다 결과가 true입니다.

매개변수

  • 콜백

    함수 선택사항

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

    (speaking: boolean) => void

    • 말하기

      부울

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

반환 값

  • Promise&lt;boolean&gt;

    Chrome 101 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

pause()

chrome.tts.pause()

발화 중간에 음성 합성을 일시중지합니다. 다시 시작하거나 중지하면 음성의 일시중지가 해제됩니다.

resume()

chrome.tts.resume()

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

speak()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

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

매개변수

  • 발화

    문자열

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

  • 옵션

    TtsOptions 선택사항

    음성 옵션입니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • 프로미스<void>

    Chrome 101 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

stop()

chrome.tts.stop()

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

이벤트

onVoicesChanged

Chrome 124 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

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

매개변수

  • 콜백

    함수

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

    () => void