음성 합성 마크업 언어(SSML)

음성 합성 마크업 언어(SSML)를 Text-to-Speech 요청으로 전송하여 두문자어, 날짜, 시간, 약어 또는 검열되어야 하는 텍스트의 오디오 형식과 끊어 읽기에 대한 세부정보를 입력해 오디오 응답을 상세하게 맞춤설정할 수 있습니다. 자세한 내용과 코드 샘플은 Text-to-Speech SSML 튜토리얼을 참조하세요.

다음은 SSML 마크업의 예시로, 이 텍스트를 Text-to-Speech로 합성해 보겠습니다.

<speak>
  Here are <say-as interpret-as="characters">SSML</say-as> samples.
  I can pause <break time="3s"/>.
  I can play a sound
  <audio src="https://www.example.com/MY_MP3_FILE.mp3">didn't get your MP3 audio file</audio>.
  I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
  Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.
  Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.
  I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.
  Finally, I can speak a paragraph with two sentences.
  <p><s>This is sentence one.</s><s>This is sentence two.</s></p>
</speak>

다음은 SSML 예시 문서를 합성한 텍스트입니다.

Here are S S M L samples. I can pause [3 second pause]. I can play a sound [audio file plays].
I can speak in cardinals. Your number is ten.
Or I can speak in ordinals. You are tenth in line.
Or I can even speak in digits. The digits for ten are one oh.
I can also substitute phrases, like the World Wide Web Consortium.
Finally, I can speak a paragraph with two sentences. This is sentence one. This is sentence two.

Text-to-Speech는 사용 가능한 SSML 태그의 일부를 지원하며 이 주제에서는 지원되는 태그를 설명합니다.

Text-to-Speech를 사용하여 SSML 입력으로 오디오 데이터를 만드는 방법에 대한 자세한 내용은 음성 오디오 파일 만들기를 참조하세요.

SSML 사용 팁

구현에 따라 Text-to-Speech로 보내는 SSML 페이로드에서 따옴표를 이스케이프 처리해야 할 수 있습니다. 다음 예시에서는 JSON 객체 내에 포함된 SSML 입력 형식 지정 방법을 보여줍니다.

"{
    'input':{
     'ssml':'<speak>The <say-as interpret-as=\"characters\">SSML</say-as>
          standard <break time=\"1s\"/>is defined by the
          <sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>'
    },
    'voice':{
      'languageCode':'en-us',
      'name':'en-US-Standard-B',
      'ssmlGender':'MALE'
    },
    'audioConfig':{
      'audioEncoding':'MP3'
    }
  }"

예약 문자

오디오로 변환할 텍스트에 SSML 예약 문자를 사용하지 마세요. SSML 예약 문자를 사용해야 하는 경우 이스케이프 코드를 사용하여 문자가 코드로 읽혀지지 않도록 방지하세요. 다음 표에서는 예약된 SSML 문자와 연관된 이스케이프 코드를 보여줍니다.

문자	이스케이프 코드
"	`"`
&	`&`
'	`'`
<	`<`
>	`>`

음성 선택

VoiceSelectionParams 객체에 음성을 설정할 수 있습니다. VoiceSelectionParams 객체 사용을 보여주는 코드 샘플을 보려면 Text-to-Speech SSML 가이드를 참조하세요.

<voice> 태그를 사용하여 여러 음성으로 SSML을 읽을 수 있지만 VoiceSelectionParams 이름을 호환되는 음성으로 설정해야 합니다.

요청된 음성 유형	<voice> 태그에서 지원되는 음성 유형
요청된 음성 유형	Neural2	Studio	Wavenet	뉴스	표준
Neural2	✔	✔			✔
Studio	✔	✔			✔
Wavenet			✔	✔	✔
표준	✔	✔			✔
뉴스			✔	✔	✔

SSML 요소 지원

다음 섹션에서는 작업에 사용할 수 있는 SSML 요소와 옵션을 설명합니다.

`<speak>`

SSML 응답의 루트 요소.

speak 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

<speak>
  my SSML content
</speak>

`<break>`

단어 사이의 끊어 읽기 또는 기타 운율적 경계를 제어하는 빈 요소. 토큰 쌍 간에 <break> 사용은 선택사항입니다. 이 요소가 단어 사이에 없으면 음성 중지는 언어적 맥락에 따라 자동으로 결정됩니다.

break 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

속성

속성 설명

속성	설명
`time`	초나 밀리초 단위로 음성 중지의 길이를 설정합니다(예: '3s' 또는 '250ms').
`strength`	출력 음성의 운율적 중지의 강도를 상대적 용어로 설정합니다. 유효한 값은 'x-weak', 'weak', 'medium', 'strong', 'x-strong'입니다. 'none' 값은 운율적 중지 경계가 출력되어서는 안 됨을 나타내며, 설정된 값이 없을 경우 프로세서가 생성하는 운율적 중지를 방지하는 데 사용할 수 있습니다. 다른 값은 토큰 사이의 점증적인(단조 비감소) 중지 강도를 나타냅니다. 일반적으로 중지 경계가 뚜렷하면 끊어 읽기가 됩니다.

time

초나 밀리초 단위로 음성 중지의 길이를 설정합니다(예: '3s' 또는 '250ms').

strength

출력 음성의 운율적 중지의 강도를 상대적 용어로 설정합니다. 유효한 값은 'x-weak', 'weak', 'medium', 'strong', 'x-strong'입니다. 'none' 값은 운율적 중지 경계가 출력되어서는 안 됨을 나타내며, 설정된 값이 없을 경우 프로세서가 생성하는 운율적 중지를 방지하는 데 사용할 수 있습니다. 다른 값은 토큰 사이의 점증적인(단조 비감소) 중지 강도를 나타냅니다. 일반적으로 중지 경계가 뚜렷하면 끊어 읽기가 됩니다.

예

다음 예시는 <break> 요소를 사용하여 단계간에 일시 중지하는 방법을 보여줍니다.

<speak>
  Step 1, take a deep breath. <break time="200ms"/>
  Step 2, exhale.
  Step 3, take a deep breath again. <break strength="weak"/>
  Step 4, exhale.
</speak>

`<say‑as>`

이 요소를 사용하면 요소 내에 포함 된 텍스트 구문 유형에 대한 정보를 나타낼 수 있습니다. 또한 포함된 텍스트 렌더링의 세부 수준을 지정하는 데도 도움이 됩니다.

<say‑as> 요소에는 값을 말하는 형식을 결정하는 필수 속성인 interpret-as가 있습니다. 특정 interpret-as 값에 따라 선택적 속성 인 format 및 detail을 사용할 수 있습니다.

예시

interpret-as 속성은 다음 값을 지원합니다.

currency
다음 예시는 'forty two dollars and one cent'라고 말합니다. 언어 속성이 누락된 경우 현재 언어가 사용됩니다.
```
<speak>
 <say-as interpret-as='currency' language='en-US'>$42.01</say-as>
</speak>
 
```
telephone
W3C SSML 1.0 say-as attribute values WG 메모에서 interpret-as='telephone' 설명을 참조하세요.

다음 예시는 '18002021212'로 말합니다. 'google:style' 속성이 생략된 경우 문자 O가 0으로 표시됩니다.

'google:style='zero-as-zero' 속성은 현재 EN 언어로만 작동합니다.
```
 <speak>
 <say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as>
 </speak>
 
```
verbatim 또는 spell-out
다음 예는 한 글자씩 철자를 말합니다.
```
<speak>
 <say-as interpret-as="verbatim">abcdefg</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
date
format 속성은 일련의 날짜 필드 문자 코드입니다. format에서 지원되는 필드 문자 코드는 각각 연도, 월, 일에 해당하는 {y, m, d}입니다. 연도, 월, 일에 필드 코드가 한 번씩 표시될 경우 예상 자릿수는 각각 4자리, 2자리, 2자리입니다. 필드 코드가 반복될 경우 예상 자릿수는 코드의 반복 횟수입니다. 날짜 텍스트의 필드는 구두점 또는 공백으로 구분될 수 있습니다.

detail 속성은 날짜를 읽는 방식을 제어합니다. detail='1'의 경우 월이나 연도 필드 중 하나와 일 필드가 필수 항목이지만 월과 연도 필드 둘 다 입력해도 됩니다. 이는 3개 미만의 필드가 지정될 경우 기본값입니다. 말하는 형식은 '{몇 월}의 {며칠째 날}, {몇 년도}'(영어 기준)입니다.

다음 예는 '9월의 열째 날, 1960년' 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="date" format="yyyymmdd" detail="1">
 1960-09-10
 </say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.

다음 예는 '9월의 열째 날' 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="date" format="dm">10-9</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.

detail='2'의 경우 일, 월, 연도 필드가 필요하며, 세 필드가 모두 입력된 경우 기본값에 해당합니다. 말하는 형식은 '{몇 월} {며칠째 날}, {몇 년도}'(영어 기준)입니다.

다음 예는 '9월 열째 날, 1960년' 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="date" format="dmy" detail="2">
 10-9-1960
 </say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
characters
다음 예는 한 글자씩 말합니다.
```
<speak>
 <say-as interpret-as="characters">can</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
cardinal
다음 예시는 숫자를 기수 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="cardinal">12345</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
ordinal
다음 예는 숫자를 서수 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="ordinal">1</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
fraction
다음 예는 숫자를 분수 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="fraction">5+1/2</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
expletive 또는 bleep
다음 예시는 텍스트가 검열된 것처럼 삐 소리가 납니다.
```
<speak>
 <say-as interpret-as="expletive">censor this</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
unit
숫자에 따라 단위를 단수 또는 복수로 변환합니다. 다음 예는 단수형 단위를 복수형으로 말합니다.
```
<speak>
 <say-as interpret-as="unit">10 foot</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.
time
다음 예는 '2시 30분 P.M.' 형식으로 말합니다.
```
<speak>
 <say-as interpret-as="time" format="hms12">2:30pm</say-as>
</speak>
 
```
브라우저에서 HTML5 Audio 요소를 지원하지 않습니다.

format 속성은 일련의 시간 필드 문자 코드입니다. format에서 지원되는 필드 문자 코드는 각각 시간, 분, 초, 시간대, 12시간제, 24시간제에 해당하는 {h, m, s, Z, 12, 24}입니다. 시간, 분, 초에 필드 코드가 한 번씩 표시될 경우 예상 자릿수는 각각 1자리, 2자리, 2자리입니다. 필드 코드가 반복될 경우 예상 자릿수는 코드의 반복 횟수입니다. 시간 텍스트의 필드는 구두점 또는 공백으로 구분될 수 있습니다. 시간, 분, 초가 이 형식으로 지정되지 않거나 일치하는 자릿수가 없을 경우 필드 값이 0으로 취급됩니다. 기본 format은 'hms12'입니다.

detail 속성은 시간을 말하는 형식을 12시간제 또는 24시간제로 지정합니다. detail='1' 또는detail이 누락되어 있고 시간 형식이 24시간인 경우 말하는 형식은 24시간제입니다. detail='2' 또는 detail이 누락되어 있고 시간 형식이 12시간인 경우 말하는 형식은 12시간제입니다.

say-as 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

`<audio>`

합성된 음성 출력과 함께 녹음된 오디오 파일의 삽입과 기타 오디오 형식의 삽입을 지원합니다.

속성

속성	필수	기본값	값
`src`	예	해당 사항 없음	오디오 미디어 소스를 참조하는 URI. 지원되는 프로토콜은 `https`입니다.
`clipBegin`	아니요	0	재생 시작 지점을 결정하며, 오디오 소스의 시작 부분에 삽입되는 오프셋 값인 TimeDesignation. 이 값이 오디오 소스의 실제 지속 시간보다 크거나 같을 경우 오디오가 삽입되지 않습니다.
`clipEnd`	아니요	무한대	재생 종료 지점을 결정하며, 오디오 소스의 시작 부분에 삽입되는 오프셋 값인 TimeDesignation. 오디오 소스의 실제 지속 시간이 이 값보다 작으면 지정된 시간에 재생이 종료됩니다. `clipBegin`이 `clipEnd`보다 크거나 같으면 오디오가 삽입되지 않습니다.
`speed`	아니요	100%	정상 입력 속도 대비 출력 재생 속도의 비율을 백분율로 표현한 값. 양의 실수 다음에 %가 오는 형식입니다. 현재 지원되는 범위는 [50%(저속 - 0.5배속), 200%(고속 - 2배속)]입니다. 이 범위를 벗어나는 값은 이 범위에 맞게 조정되거나 조정되지 않을 수 있습니다.
`repeatCount`	아니요	`repeatDur`이 설정된 경우 1 또는 10	`clipBegin` 또는 `clipEnd`로 잘라낸 후 오디오를 삽입할 횟수를 지정하는 실수. 소수 반복은 지원되지 않으므로 가장 가까운 정수로 값이 반올림됩니다. 0은 유효한 값이 아니므로 지정되지 않은 것으로 취급되며 이 경우 기본값이 설정됩니다.
`repeatDur`	아니요	무한대	소스의 `clipBegin`, `clipEnd`, `repeatCount`, `speed` 속성이 처리된 후 삽입되는 오디오의 지속 시간(일반적인 재생 시간과 다름)을 제한하는 TimeDesignation. 처리된 오디오의 지속 시간이 이 값보다 작으면 지정된 시간에 재생이 종료됩니다.
`soundLevel`	아니요	+0dB	`soundLevel` 데시벨을 사용하여 오디오의 사운드 레벨을 조정합니다. 최대 범위는 +/-40dB이지만 실제 범위는 실질적으로 더 작으며, 전체 범위에서 출력 품질이 좋지 않을 수 있습니다.

다음은 현재 오디오에 지원되는 설정입니다.

형식: MP3(MPEG v2)
- 초당 24K 샘플
- 초당 24K~96K 비트, 고정 속도
형식: Ogg의 Opus
- 초당 24K 샘플(초광대역)
- 초당 24K~96K 비트, 고정 속도
형식(지원 중단됨): WAV(RIFF)
- PCM 16비트 부호 Little Endian
- 초당 24K 샘플
모든 형식에 해당:
- 단일 채널이 권장되지만 스테레오가 허용됩니다.
- 최대 지속 시간: 240초. 이보다 오랜 시간 동안 오디오를 재생하려면 미디어 응답을 구현하는 것이 좋습니다.
- 파일 크기 제한: 5MB
- 소스 URL은 HTTPS 프로토콜을 사용해야 합니다.
- 오디오를 가져올 때 UserAgent는 'Google-Speech-Actions'입니다.

<audio> 요소의 콘텐츠는 선택사항이며 오디오 파일을 재생할 수 없거나 출력 기기가 오디오를 지원하지 않는 경우에 사용됩니다. 내용에는 <desc> 요소가 포함될 수 있으며, 이 경우 해당 요소의 텍스트 내용이 화면에 표시됩니다. 자세한 내용은 응답 체크리스트의 녹음된 오디오 섹션을 참조하세요.

또한 src URL은 https URL이어야 합니다(Google Cloud Storage는 https URL의 오디오 파일을 호스팅할 수 있음).

미디어 응답을 자세히 알아보려면 응답 가이드의 미디어 응답 섹션을 참조하세요.

audio 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

<speak>
  <audio src="cat_purr_close.ogg">
    <desc>a cat purring</desc>
    PURR (sound didn't load)
  </audio>
</speak>

`,<s>`

문장과 단락 요소입니다.

p 및 s 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

<p><s>This is sentence one.</s><s>This is sentence two.</s></p>

권장사항

특히 prosody를 변경하는 SSML 요소가 포함된 경우 전체 문장을 래핑하려면 <s> ... </s> 태그를 사용합니다(예: <audio>, <break>, <emphasis>, <par>, <prosody>, <say-as>, <seq>, ).
음성 내 구분을 들을 수 있도록 충분하게 길게 하려면 <s> ... </s> 태그를 사용하여 문장 사이에 줄 바꿈을 삽입합니다.

``

alias 속성 값의 텍스트는 포함된 텍스트의 발음을 대체한다는 것을 나타냅니다.

sub 요소를 사용하여 읽기 어려운 단어의 쉬운 발음을 제공할 수도 있습니다. 마지막 예시는 이 사용 사례를 일본어 버전으로 설명합니다.

sub 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예시

<sub alias="World Wide Web Consortium">W3C</sub>

<sub alias="にっぽんばし">日本橋</sub>

``

텍스트 또는 태그 시퀀스에 마커를 배치하는 빈 요소입니다. 시퀀스의 특정 위치를 참조하거나 비동기 알림에 사용되는 출력 스트림에 마커를 삽입하는 데 사용할 수 있습니다.

참고: mark 요소를 사용할 경우 다음 가이드라인을 따르세요.

SSML의 시작 또는 끝 근처에 커스텀 표시를 추가하는 대신 START 및 END 표시를 사용합니다.
SSML에 연속 마크를 추가하지 마세요. 빠른 연속 표시는 이벤트를 생성하지 못할 수 있습니다. 또한 표시 사이에 오디오가 생성되지 않으면 이벤트가 생성되지 않습니다. 예를 들어 다음을 피하세요.
Sentence 1. Sentence 2.

참고: 편의를 위해 대화형 캔버스 응답에 START 및 END 이벤트를 자동으로 가져옵니다. 이러한 마크는 W3 사양에 포함되지 않습니다.

mark 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

<speak>
Go from <mark name="here"/> here, to <mark name="there"/> there!
</speak>

`<prosody>`

요소에 포함된 텍스트의 높낮이, 말하기 속도, 볼륨을 맞춤설정하는 데 사용됩니다. 현재 rate, pitch, volume 속성이 지원됩니다.

W3 사양에 따라 rate 및 volume 속성을 설정할 수 있습니다. pitch 속성 값을 설정하는 데 세 가지 옵션이 있습니다.

참고: <prosody> 태그는 전체 문장에서만 사용되어야 합니다. 문장 내에 단어를 포함하면 음성이 원치 않게 일시중지될 수 있습니다.

속성	설명
`name`	각 표시의 문자열 ID입니다.

옵션	설명
친척	상대 값(예: 'low', 'medium', 'high' 등)을 지정합니다. 여기서 'medium'은 기본 높낮이입니다.
반음	'+Nst' 또는 '-Nst'를 각각 사용하여 'N' 반음씩 높낮이를 올리거나 내립니다. '+/-' 및 'st'는 필수입니다.
비율	'+N%' 또는 '-N%'를 각각 사용하여 'N' 퍼센트씩 높낮이를 올리거나 내립니다. '%'는 필수이지만 '+/-'는 선택사항입니다.

prosody 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

다음 예시에서는 <prosody> 요소를 사용하여 정상보다 2반음 낮추어 느리게 말합니다.

<prosody rate="slow" pitch="-2st">Can you hear me now?</prosody>

`<emphasis>`

요소에 포함된 텍스트에서 강세를 추가하거나 제거하는 데 사용됩니다. <emphasis> 요소는 <prosody>와 유사하게 음성을 수정하지만 개별 음성 속성을 설정할 필요가 없습니다.

참고: <emphasis> 태그는 전체 문장에서만 사용되어야 합니다. 문장 내에 단어를 포함하면 음성이 원치 않게 일시중지될 수 있습니다.

이 요소는 다음의 유효한 값을 사용하여 선택적 'level' 속성을 지원합니다.

strong
moderate
none
reduced

emphasis 요소에 대한 자세한 내용은 W3 사양을 참조하세요.

예

다음 예시에서는 <emphasis> 요소를 사용하여 공지합니다.

<emphasis level="moderate">This is an important announcement</emphasis>

`<par>`

여러 미디어 요소를 한 번에 재생할 수 있게 해주는 병렬 미디어 컨테이너입니다. 유일하게 허용되는 콘텐츠는 <par>, <seq>, <media> 요소 한 개 이상으로 구성된 세트입니다. <media> 요소의 순서는 중요하지 않습니다.

하위 요소가 다른 시작 시간을 지정하지 않으면 요소의 암묵적 시작 시간은 <par> 컨테이너의 시작 시간과 동일합니다. 하위 요소의 begin 또는 end 속성에 설정된 오프셋 값이 있으면 요소의 오프셋은 <par> 컨테이너의 시작 시간을 기준으로 합니다. 루트 <par> 요소의 경우 begin 속성이 무시되며, 시작 시간은 SSML 음성 합성 프로세스에서 루트 <par> 요소(즉, 사실상 '0' 시간)의 출력 생성을 시작하는 시간입니다.

예

<speak>
  <par>
    <media xml:id="question" begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media xml:id="answer" begin="question.end+2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media begin="answer.end-0.2s" soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </par>
</speak>

`<seq>`

미디어 요소를 하나씩 재생할 수 있게 해주는 순차적 미디어 컨테이너입니다. 유일하게 허용되는 콘텐츠는 <seq>, <par>, <media> 요소 한 개 이상으로 구성된 세트입니다. 미디어 요소의 순서는 렌더링되는 순서와 같습니다.

하위 요소의 begin 및 end 속성은 오프셋 값으로 설정될 수 있습니다(아래의 시간 사양 참조). 이러한 하위 요소의 오프셋 값은 시퀀스에서 이전 요소의 끝 지점을 기준으로 합니다. 시퀀스의 첫 번째 요소의 경우 <seq> 컨테이너의 시작 지점을 기준으로 합니다.

예

<speak>
  <seq>
    <media begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media begin="2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </seq>
</speak>

`<media>`

<par> 또는 <seq> 요소 내 미디어 레이어를 나타냅니다. <media> 요소에서 허용되는 콘텐츠는 SSML <speak> 또는 <audio> 요소입니다. 다음 표에서는 <media> 요소의 유효한 속성을 설명합니다.

속성

속성	필수	기본값	값
xml:id	아니요	값 없음	이 요소의 고유한 XML 식별자. 인코딩된 항목은 지원되지 않습니다. 허용되는 식별자 값은 정규 표현식 `"([-_#]\|\p{L}\|\p{D})+"`와 일치합니다. 자세한 내용은 XML-ID를 참조하세요.
begin	아니요	0	이 미디어 컨테이너의 시작 시간. 루트 미디어 컨테이너 요소(기본값 '0'과 동일하게 취급됨)이면 무시됩니다. 유효한 문자열 값은 아래의 시간 사양 섹션을 참조하세요.
end	아니요	값 없음	이 미디어 컨테이너의 종료 시간에 대한 사양. 유효한 문자열 값은 아래의 시간 사양 섹션을 참조하세요.
repeatCount	아니요	1	미디어 삽입 횟수를 지정하는 실수. 소수 반복은 지원되지 않으므로 가장 가까운 정수로 값이 반올림됩니다. 0은 유효한 값이 아니므로 지정되지 않은 것으로 취급되며 이 경우 기본값이 설정됩니다.
repeatDur	아니요	값 없음	삽입된 미디어의 지속 시간을 제한하는 TimeDesignation. 미디어의 지속 시간이 이 값보다 작으면 지정된 시간에 재생이 종료됩니다.
soundLevel	아니요	+0dB	`soundLevel` 데시벨을 사용하여 오디오의 사운드 레벨을 조정합니다. 최대 범위는 +/-40dB이지만 실제 범위는 실질적으로 더 작으며, 전체 범위에서 출력 품질이 좋지 않을 수 있습니다.
fadeInDur	아니요	0초	미디어가 무음에서 시작해 선택적으로 지정된 `soundLevel`로 페이드 인하는 TimeDesignation. 미디어의 지속 시간이 이 값보다 작으면 재생 종료 시 페이드 인이 중지되고 사운드 레벨이 지정된 사운드 레벨에 도달하지 않습니다.
fadeOutDur	아니요	0초	미디어가 선택적으로 지정된 `soundLevel`에서 시작해 무음이 될 때까지 페이드 아웃하는 TimeDesignation. 미디어의 지속 시간이 이 값보다 작으면 재생 종료 시 무음에 도달할 수 있도록 사운드 레벨이 더 낮은 값으로 설정됩니다.

시간 사양

<media> 요소와 미디어 컨테이너(<par> 및 <seq> 요소)의 `begin`과 `end` 속성 값에 사용되는 시간 사양은 오프셋 값(예: +2.5s) 또는 syncbase 값(예: foo_id.end-250ms)입니다.

오프셋 값 - 시간 오프셋 값은 정규 표현식 "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"와 일치하는 값을 허용하는 SMIL Timecount 값입니다.
첫 번째 숫자 문자열은 십진수의 전체 부분이고 두 번째 숫자 문자열은 십진수의 소수 부분입니다. 기본 기호(예: '(+|-)?')는 '+'입니다. 단위 값은 각각 시, 분, 초, 밀리초에 해당합니다. 단위의 기본값은 's'(초)입니다.
Syncbase 값 - syncbase 값은 정규 표현식 "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"와 일치하는 값을 허용하는 SMIL syncbase 값입니다.
숫자와 단위는 오프셋 값과 같은 방식으로 해석됩니다.

`<phoneme>`

<phoneme> 태그를 사용하여 단어의 커스텀 발음을 인라인으로 생성할 수 있습니다. Text-to-Speech에는 IPA 및 X-SAMPA 음성 기호가 사용됩니다. 지원되는 언어 및 음소 목록은 음소 페이지를 참조하세요.

<phoneme> 태그를 한 번씩 적용하여 단일 단어의 음성을 지정합니다.

  <phoneme alphabet="ipa" ph="ˌmænɪˈtoʊbə">manitoba</phoneme>
  <phoneme alphabet="x-sampa" ph='m@"hA:g@%ni:'>mahogany</phoneme>

강세 표시

스크립트에는 최대 3개의 강세를 표시할 수 있습니다.

주 강세: IPA의 경우 /ˈ/, X-SAMPA의 경우에는 /"/로 표시됩니다.
부 강세: IPA의 경우 /ˌ/, X-SAMPA의 경우에는 /%/로 표시됩니다.
강세 없음: 기호 또는 특정 표기법으로 표시되지 않습니다.

일부 언어는 강세가 3개 미만이거나 강세 표시가 전혀 사용되지 않을 수 있습니다. 해당 언어에 사용 가능한 강세를 보려면 음소 페이지를 참조하세요. 강세 표시는 강세가 있는 각 음절의 시작 부분에 배치됩니다. 예를 들어 미국 영어에서는 다음과 같습니다.

예시 단어	IPA	X-SAMPA
water	ˈwɑːtɚ	"wA:t@`
underwater	ˌʌndɚˈwɑːtɚ	%Vnd@"wA:t@

포괄적 표기와 협소적 표기

일반적으로 표기는 포괄적이고 자연적인 음성으로 표현하는 것이 좋습니다. 예를 들어 미국 영어에서는 탄설음을 사용하는 대신 모음 사이에 오는 /t/를 표기합니다.

예시 단어	IPA	X-SAMPA
butter	ˈbʌɾɚ 대신 ˈbʌtɚ	"bV4@` 대신 "bVt@`

일부 경우에는 음성 표현을 사용함으로써 TTS 결과가 부자연스럽게 들릴 수 있습니다(예: 일련의 음소가 해부학적으로 발음하기 어려운 경우).

이에 대한 한 가지 예로 영어에서 /s/의 동화현상이 있습니다. 이러한 경우에는 그러한 동화현상을 표기에 반영해야 합니다.

예시 단어	IPA	X-SAMPA
고양이	ˈkæts	"k{ts
개	ˈdɑːgs 대신 ˈdɑːgz	"dA:gs 대신 "dA:gz

절감

모든 음절은 하나(그리고 단 하나)의 모음을 포함해야 합니다. 즉 음절 자음 사용을 피하고 대신 이를 약화된 모음으로 표기해야 합니다. 예를 들면 다음과 같습니다.

예시 단어	IPA	X-SAMPA
kitten	ˈkɪtn 대신 ˈkɪtən	"kitn 대신 "kIt@n
kettle	ˈkɛtl 대신 ˈkɛtəl	"kEtl 대신 "kEt@l

음절 구분

선택적으로 /./를 사용하여 음절 경계를 지정할 수 있습니다. 각 음절은 하나(그리고 단 하나)의 모음을 포함해야 합니다. 예를 들면 다음과 같습니다.

예시 단어	IPA	X-SAMPA
가독성	ˌɹiː.də.ˈbɪ.lə.tiː	%r\i:.d@."bI.l@.ti:

커스텀 발음 사전

phoneme 태그를 사용하여 발음을 인라인으로 제공하는 대신 음성 합성 RPC에 커스텀 발음 사전을 제공하세요. 커스텀 발음 사전이 요청에 포함된 경우 SSML phoneme 태그에 따라 입력 텍스트가 자동으로 조정됩니다.

예를 들어 텍스트 입력과 커스텀 발음이 포함된 다음 요청은 아래 표시된 SSML에 맞게 자동으로 변환됩니다.

원래 입력:

input: {
  text: 'Hello world! It is indeed a beautiful world!',
  custom_pronunciations: {
    pronunciations: {
      phrase: 'world'
      phonetic_encoding: PHONETIC_ENCODING_IPA
      pronunciation: 'wɜːld'
    }
  }
}

변환된 입력:

input: {
  ssml: '<speak>Hello <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>! It is indeed a beautiful <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>!</speak>'
}

기간

Text-to-Speech는 <say-as interpret-as="duration">을 지원하여 기간을 올바르게 인식할 수 있습니다. 예를 들어 다음 예시는 "five hours and thirty minutes"로 음성 변환됩니다.

<say-as interpret-as="duration" format="h:m">5:30</say-as>

형식 문자열에는 다음 값이 지원됩니다.

약어	값
h	시간
m	분
s	초
ms	밀리초

`<voice>`

<voice> 태그를 사용하면 단일 SSML 요청에 음성을 두 가지 이상 사용할 수 있습니다. 다음 예시에서 기본 음성은 남자 영어 음성입니다. 이 음성에서는 여자 음성으로 프랑스어로 발음되는 "qu'est-ce qui t'amène ici"를 제외하고 모든 단어가 기본 언어(영어) 및 성별(남성)로 합성됩니다.

<speak>And then she asked, <voice language="fr-FR" gender="female">qu'est-ce qui
t'amène ici</voice><break time="250ms"/> in her sweet and gentle voice.</speak>

또는 language 또는 gender를 지정하는 대신 <voice> 태그를 사용하여 개별 음성(지원되는 음성 페이지의 음성 이름)을 지정할 수 있습니다.

<speak>The dog is friendly<voice name="fr-CA-Wavenet-B">mais la chat est
mignon</voice><break time="250ms"/> said a pet shop
owner</speak>

<voice> 태그를 사용할 때 Text-to-Speech는 name(사용하려는 음성 이름) 또는 다음 속성의 조합이 입력되기를 예상합니다. 세 가지 속성 모두 선택사항이지만 name을 제공하지 않을 경우 최소한 셋 중 하나를 제공해야 합니다.

gender: "male", "female", "neutral" 중 하나입니다.
variant: 구성에 따라 사용할 수 있는 음성이 여러 개인 경우 결정자로 사용됩니다.
language: 원하는 언어입니다. 제공된 <voice> 태그에 언어를 하나만 지정할 수 있습니다. 언어는 BCP-47 형식으로 지정합니다. 지원되는 음성 및 언어 페이지의 언어 코드 열에서 해당 언어의 BCP-47 코드를 찾을 수 있습니다.

또한 두 가지 추가 태그인 required 및 ordering을 사용하여 gender, variant, language 속성의 상대적 우선순위를 제어할 수 있습니다.

required: 속성이 required로 지정되었고 올바르게 구성되지 않았으면 요청이 실패합니다.
ordering: ordering 태그가 필수가 아닌 선호 속성으로 간주된 다음에 나열되는 모든 속성입니다. 선호 속성에 대해 Text-to-Speech API는 ordering 태그 다음에 나열된 순서로 가능한 부분까지 최대한 선호 속성을 적용합니다. 선호 속성이 잘못 구성되었으면 Text-to-Speech가 잘못된 음성을 반환할 수 있더라도, 잘못된 구성이 삭제됩니다.

required 및 ordering 태그를 사용하는 구성 예시:

<speak>And there it was <voice language="en-GB" gender="male" required="gender"
ordering="gender language">a flying bird </voice>roaring in the skies for the
first time.</speak>

<speak>Today is supposed to be <voice language="en-GB" gender="female"
ordering="language gender">Sunday Funday.</voice></speak>

`<lang>`

<lang>을 사용하면 동일한 SSML 요청 내에서 여러 언어로 텍스트를 포함할 수 있습니다. <voice> 태그를 사용하여 음성을 명시적으로 변경하지 않는 한 모든 언어가 동일한 음성을 합성됩니다. xml:lang 문자열에는 도착어가 BCP-47 형식(이 값은 지원되는 음성 테이블에서 "언어 코드"로 나열됨)으로 포함되어야 합니다. 다음 예시에서 "chat"는 기본 언어(영어) 대신 프랑스어로 음성 변환됩니다.

<speak>The french word for cat is <lang xml:lang="fr-FR">chat</lang></speak>

Text-to-Speech는 가능한 부분까지 최대한으로 <lang> 태그를 지원합니다. 동일한 SSML 요청에 지정되었더라도 모든 언어 조합이 동일한 품질 결과를 생성하지는 않습니다. 일부 경우에는 언어 조합으로 인해 감지할 수 있지만 미묘하거나 부정적으로 인식되는 효과를 발생시킬 수 있습니다. 알려진 문제:

간지 문자를 사용하는 일본어는 <lang> 태그가 지원되지 않습니다. 입력은 한자로 음역되고 읽혀집니다.
아랍어, 히브리어, 페르시아어와 같은 셈족 어군의 언어는 <lang> 태그가 지원되지 않으며 무음 처리됩니다. 이러한 언어를 사용하고 싶으면 <voice> 태그를 사용해서 원하는 언어로 발음되는(가능한 경우) 음성으로 전환하는 것이 좋습니다.

SSML 타임포인트

Text-to-Speech API는 생성된 오디오 데이터에서 타임포인트 사용을 지원합니다. 타임포인트는 스크립트의 지정된 지점에 해당하는 타임스탬프입니다. 생성된 오디오의 시작 부분부터 초 단위로 측정됩니다.  태그를 사용하여 스크립트에 타임포인트를 설정할 수 있습니다. 오디오가 생성되면 API는 오디오 시작 부분과 타임포인트 간의 타임스탬프를 반환합니다.

타임포인트를 설정하려면 두 단계를 수행해야 합니다.

스크립트에서 타임스탬프를 설정하려는 시점에  SSML 태그를 추가합니다.
TimepointType을 SSML_MARK로 설정합니다. 이 필드가 설정되지 않으면 기본적으로 타임포인트가 반환되지 않습니다.

다음 예시는 두 가지 타임포인트를 반환합니다.

timepoint_1: "Mark" 단어가 생성된 오디오에 나타나는 시간(초)을 나타냅니다.
timepoint_2: "see" 단어가 생성된 오디오에 나타나는 시간(초)을 나타냅니다.

<speak>Hello <mark name="timepoint_1"/> Mark. Good to <mark
name="timepoint_2"/> see you.</speak>

스타일

다음 음성은 여러 스타일로 말할 수 있습니다.

en-US-Neural2-F
en-US-Neural2-J

<google:style> 태그를 사용하여 사용할 스타일을 제어합니다. 전체 문장에만 태그를 사용합니다.

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

<speak><google:style name="lively">Hello I'm so happy today!</google:style></speak>

name 필드는 다음 값을 지원합니다.

apologetic
calm
empathetic
firm
lively

음성 합성 마크업 언어(SSML)

SSML 사용 팁

예약 문자

음성 선택

SSML 요소 지원

<speak>

예

<break>

속성

예

<say‑as>

예시

<audio>

속성

예

<p>,<s>

예

권장사항

<sub>

예시

<mark>

예

<prosody>

예

<emphasis>

예

<par>

예

<seq>

예

<media>

속성