SSML (Dialogflow)

Zwracając odpowiedź do Asystenta Google, możesz użyć w odpowiedzi podzbioru języka syntezy mowy (SSML). Za pomocą SSML możesz sprawić, że odpowiedzi na pytania będą wyglądały jak naturalne. Poniżej znajdziesz przykład znaczników SSML i sposób ich odczytu przez Asystenta Google.

function saySSML(conv) {
  const ssml = '<speak>' +
    'Here are <say-as interpret-as="characters">SSML</say-as> samples. ' +
    'I can pause <break time="3" />. ' +
    'I can play a sound <audio src="https://www.example.com/MY_WAVE_FILE.wav">your wave file</audio>. ' +
    'I can speak in cardinals. Your position is <say-as interpret-as="cardinal">10</say-as> in line. ' +
    '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. Your position in line is <say-as interpret-as="digits">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>';
  conv.ask(ssml);
}

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "<speak>Here are <say-as interpret-as=\"characters\">SSML</say-as> samples. I can pause <break time=\"3\" />. I can play a sound <audio src=\"https://www.example.com/MY_WAVE_FILE.wav\">your wave file</audio>. I can speak in cardinals. Your position is <say-as interpret-as=\"cardinal\">10</say-as> in line. 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. Your position in line is <say-as interpret-as=\"digits\">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>"
              }
            }
          ]
        }
      }
    }
  ]
}

Dźwięk

SSML jest obsługiwany w symulatorze działań, ale nie w symulatorze Dialogflow.

Adresy URL w SSML

Gdy definiujesz odpowiedź SSML zawierającą tylko adres URL, ampersandy w tym adresie URL mogą powodować problemy z powodu formatowania XML. Aby mieć pewność, że adres URL jest prawidłowy, zastąp wystąpienia & wartością &.

Nawet jeśli odpowiedź SSML zawiera tylko adres URL, Actions on Google wymaga wyświetlanego tekstu odpowiedzi. Ponieważ tekst w tagu <audio> nie jest wypowiadany przez Asystenta, aby spełnić to wymaganie, możesz wstawić w tagu <audio> tekst wypełnienia lub krótki opis. Asystent nie będzie odczytywać tekstu w tagu <audio> po odtworzeniu dźwięku. Jest zgodny z wymogami Actions on Google dotyczącymi wyświetlania tekstu SSML.

Oto przykład odpowiedzi SSML na problem:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  </audio>
</speak>

W powyższym przykładzie kod & nie zmienia się w prawidłowe formatowanie XML.

Poprawiona wersja tej samej odpowiedzi SSML wygląda tak:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&amp;token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  text
  </audio>
</speak>

Obsługa elementów SSML

W sekcjach poniżej opisano elementy i opcje SSML, których można używać w działaniach.

<speak>

Element główny odpowiedzi SSML.

Aby dowiedzieć się więcej o elemencie speak, zapoznaj się ze specyfikacją W3.

Przykład

<speak>
  my SSML content
</speak>

<break>

Pusty element, który wstrzymuje i zmienia proporcje między słowami. Użycie <break> do pary tokenów jest opcjonalne. Jeśli ten element nie występuje między słowami, podział jest określany automatycznie na podstawie języka.

Aby dowiedzieć się więcej o elemencie break, zapoznaj się ze specyfikacją W3.

Atrybuty

Przykład

Poniższy przykład pokazuje, jak za pomocą elementu <break> wstrzymywać przerwy między krokami:

<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>

Ten element pozwala wskazać informacje o typie konstrukcji tekstu zawartej w elemencie. Pomaga też określić poziom szczegółowości renderowania tekstu.

Element <say‑as> ma wymagany atrybut interpret-as, który określa sposób odczytywania wartości. W zależności od konkretnej wartości interpret-as mogą być używane atrybuty opcjonalne format i detail.

Przykłady

Atrybut interpret-as obsługuje następujące wartości:

• currency

  W przykładzie poniżej sformułowano „czterdzieści dwa dolary i jeden grosz”. Jeśli pominiesz atrybut język, używany będzie język lokalny.

  <speak>
    <say-as interpret-as='currency' language='en-US'>$42.01</say-as>
  </speak>
      

• telephone

  Zapoznaj się z opisem interpret-as='telephone' w notatce WGC SSML 1.0, wartości atrybutów.

  W dalszej części przykładu piszemy „jeden osiem zero zero dwa zero dwa jeden dwa dwa”. Jeśli pominiesz atrybut „google:style”, jego wartość będzie wynosić 0.

  Atrybut „google:style='zero-as-zero'” działa obecnie tylko w języku angielskim.

        <speak>
          <say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as>
        </speak>
      

• verbatim lub spell-out

  Poniższy przykład pisowni to litera:

  <speak>
    <say-as interpret-as="verbatim">abcdefg</say-as>
  </speak>
      

• date

  Atrybut format jest sekwencją kodów znaków pola daty. Obsługiwane kody znaków w polach format to odpowiednio {y, m, d} w przypadku roku, miesiąca i dnia (miesiąca). Jeśli kod pola jest wyświetlany raz w roku, miesiącu lub dniu, liczba cyfr musi wynosić odpowiednio 4, 2 i 2. Jeśli kod pola się powtarza, liczba oczekiwanych cyfr to liczba powtórzeń kodu. Pola w tekście daty mogą być rozdzielone przecinkami lub spacjami.

  Atrybut detail określa wypowiadaną datę. W przypadku detail='1' wymagane są tylko pola dnia i 1 miesiąc lub rok, ale obie mogą zostać wypełnione. Jest to ustawienie domyślne, gdy mniej niż 3 pola mają podane wszystkie wartości. Wersja wypowiadana: „{ordinal day} z {month}, {year}”.

  Oto przykład: „Dziesięć września, dziewięćdziesiąt sześć”:

  <speak>
    <say-as interpret-as="date" format="yyyymmdd" detail="1">
      1960-09-10
    </say-as>
  </speak>
      

  Oto przykład: „dziesiąty września”:

  <speak>
    <say-as interpret-as="date" format="dm">10-9</say-as>
  </speak>
      

  W polu detail='2' wymagane są pola dnia, miesiąca i roku. Jeśli zostaną wypełnione wszystkie 3 pola, będzie to ustawienie domyślne. Wyporządzony formularz to „{month} {ordinal day}, {year}”.

  Ten przykład brzmi: „10 września, 19 sześciu”:

  <speak>
    <say-as interpret-as="date" format="dmy" detail="2">
      10-9-1960
    </say-as>
  </speak>
      

• characters

  Przykładowy wyraz „C A N”:

  <speak>
    <say-as interpret-as="characters">can</say-as>
  </speak>
      

• cardinal

  Na przykład ten przykład brzmi „Dwunaście trzydzieści pięćdziesiąt pięć” (w przypadku języka angielskiego w USA) lub „Dwunaście tysięcy trzystu czterdzieści pięć (w języku angielskim w Wielkiej Brytanii)”:

  <speak>
    <say-as interpret-as="cardinal">12345</say-as>
  </speak>
      

• ordinal

  Ten przykład jest odczytywany jako „pierwszy”:

  <speak>
    <say-as interpret-as="ordinal">1</say-as>
  </speak>
      

• fraction

  W przykładzie poniżej pięć i półtora:

  <speak>
    <say-as interpret-as="fraction">5+1/2</say-as>
  </speak>
      

• expletive lub bleep

  Ten przykład brzmi jak dźwięk ocenzurowany:

  <speak>
    <say-as interpret-as="expletive">censor this</say-as>
  </speak>
      

• unit

  Konwertuje jednostki na liczbę pojedynczą lub mnogą w zależności od liczby. Oto przykład: „10 stóp”:

  <speak>
    <say-as interpret-as="unit">10 foot</say-as>
  </speak>
      

• time

  Ten przykład brzmi „Dwudziesta trzydzieści”:

  <speak>
    <say-as interpret-as="time" format="hms12">2:30pm</say-as>
  </speak>
      

  Atrybut format jest sekwencją kodów znaków pola czasu. Obsługiwane kody znaków w polach format to {h,m, s, Z, 12, 24} (godzina, minuta, godzina), godzina (12 godzin) i 24 godziny. Jeśli kod pola jest wyświetlany raz na godzinę, minutę lub sekundę, liczba cyfr wynosi odpowiednio 1, 2 i 2. Jeśli kod pola się powtarza, liczba oczekiwanych cyfr to liczba powtórzeń kodu. Pola w tekście czasu mogą być rozdzielone przecinkami lub spacjami. Jeśli format godziny, minut lub sekund nie został określony w formacie lub nie ma pasujących cyfr, pole jest traktowane jako wartość zerowa. Domyślny format to „hms12”.

  Atrybut detail określa, czy odczytywany czas jest 12-godzinny czy 24-godzinny. Wypowiedzi są zapisywane w formacie 24-godzinnym, jeśli czas detail='1' jest pominięty, a format detail jest pominięty, a format godziny to 24-godzinny. Czas wypowiadany jest 12 godzin, jeśli właściwość detail='2' lub detail została pominięta, a format godziny to 12 godzin.

Aby dowiedzieć się więcej o elemencie say-as, zapoznaj się ze specyfikacją W3.

<audio>

Obsługuje wstawianie nagrań z plików audio i innych formatów audio w połączeniu z syntezacją mowy.

Atrybuty

Oto obecnie obsługiwane ustawienia dźwięku:

• Format: MP3 (MPEG w wersji 2)
  • 24 tys. próbek na sekundę
  • 24K ~ 96 tys. bitów na sekundę, stała szybkość
• Format: Opus w Ogg
  • 24 tys. próbek na sekundę (superszerokopasmowy)
  • 24–96 tys. bitów na sekundę, stała szybkość
• Format (wycofany): WAV (RIFF)
  • 16-bitowy PCM z podpisem małym, endi
  • 24 tys. próbek na sekundę
• Wszystkie formaty:
  • Preferowany jest jeden kanał, ale dźwięk stereo jest dopuszczalny.
  • Maksymalny czas trwania: 240 sekund. Jeśli chcesz odtwarzać dźwięk przez dłuższy czas, rozważ wdrożenie odpowiedzi multimedialnej.
  • Limit rozmiaru pliku: 5 megabajtów.
  • Źródłowy adres URL musi używać protokołu HTTPS.
  • Nasz klient użytkownika podczas pobierania dźwięku to „Google-Speech-Actions”.

Element <audio> jest opcjonalny i jest używany, jeśli nie można odtworzyć pliku audio lub urządzenie wyjściowe nie obsługuje dźwięku. Treść może zawierać element <desc>, który służy do wyświetlania tekstu zawartego w elemencie. Więcej informacji znajdziesz w sekcji Nagrane dźwięki na liście kontrolnej odpowiedzi.

Adres URL src musi też być adresem https (Google Cloud Storage może hostować Twoje pliki audio pod adresem URL https).

Więcej informacji o odpowiedziach z mediów znajdziesz w sekcji Response media (Odpowiedzi multimedialne) w przewodniku „Responses” (Odpowiedzi).

Aby dowiedzieć się więcej o elemencie audio, zapoznaj się ze specyfikacją W3.

Przykład

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

<p>,<s>

Elementy zdań i akapitu.

Więcej informacji o elementach p i s znajdziesz w specyfikacji W3.

Przykład

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

Sprawdzone metody

• Używaj tagów <s>...</s> do zawijania całych zdań, zwłaszcza jeśli zawierają one elementy SSML, które zmieniają prozodię (czyli <audio>, <break>, <emphasis>, <par>, <prosody>, <say-as>, <seq> i <sub>).
• Jeśli przerwa w mówieniu ma być wystarczająco długa, by można ją było usłyszeć, użyj tagów <s>...</s> i umieść ją między zdaniami.

<sub>

Określ, że tekst w wartości atrybutu aliasu zastępuje tekst wpisany w wymowie.

Aby ułatwić sobie wymowę trudnego do odczytania słowa, możesz też użyć elementu sub. Ostatni przykład poniżej pokazuje przykład użycia w języku japońskim.

Aby dowiedzieć się więcej o elemencie sub, zapoznaj się ze specyfikacją W3.

Przykłady

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

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

<mark>

Pusty element, który umieszcza znacznik w sekwencji tekstowej lub tagu. Można odwoływać się do konkretnej lokalizacji w sekwencji lub wstawić znacznik do strumienia wyjściowego w celu powiadomienia asynchronicznego.

Aby dowiedzieć się więcej o elemencie mark, zapoznaj się ze specyfikacją W3.

Przykład

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

<prosody>

Służy do dostosowywania tonacji, szybkości wypowiedzi i głośności tekstu zawartego w elemencie. Obecnie obsługiwane są atrybuty rate, pitch i volume.

Atrybuty rate i volume można ustawić zgodnie ze specyfikacją W3. Wartość atrybutu pitch można ustawić na 3 sposoby:

Aby dowiedzieć się więcej o elemencie prosody, zapoznaj się ze specyfikacją W3.

Przykład

W tym przykładzie użyto elementu <prosody>, aby mówić wolniej o 2 półtony poniżej normalnego poziomu:

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

<emphasis>

Służy do dodawania lub usuwania podkreślenia tekstu zawartego w elemencie. Element <emphasis> modyfikuje mowę podobnie jak <prosody>, ale nie musi ustawiać poszczególnych atrybutów mowy.

Ten element obsługuje opcjonalny atrybut „level” z tymi prawidłowymi wartościami:

• strong
• moderate
• none
• reduced

Aby dowiedzieć się więcej o elemencie emphasis, zapoznaj się ze specyfikacją W3.

Przykład

W przykładzie poniżej użyto elementu <emphasis> do opublikowania ogłoszenia:

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

<par>

Równoległy kontener mediów, który umożliwia jednoczesne odtwarzanie wielu elementów multimedialnych. Jedyną dozwoloną zawartością jest zestaw elementów <par>, <seq> i <media>. Kolejność elementów <media> nie jest istotna.

Domyślny czas rozpoczęcia elementu podrzędnego jest taki sam jak czas trwania kontenera <par>, chyba że element podrzędny określa inną godzinę rozpoczęcia. Jeśli element podrzędny ma ustawioną wartość przesunięcia dla atrybutu begin lub end, przesunięcie elementu będzie zależeć od czasu rozpoczęcia kontenera <par>. W przypadku głównego elementu <par> atrybut początkowy jest ignorowany, a czas rozpoczęcia to moment, w którym proces syntezy mowy SSML zaczyna generować dane wyjściowe dla głównego elementu <par> (czyli w rzeczywistości).

Przykład

<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>

Sekwencyjny kontener multimediów, który umożliwia odtwarzanie multimediów jeden po drugim. Jedyną dozwoloną zawartością jest zestaw elementów <seq>, <par> i <media>. Kolejność elementów multimedialnych odpowiada kolejności ich renderowania.

Atrybuty begin i end elementów podrzędnych można ustawić na wartości przesunięcia (patrz Specyfikacja czasu poniżej). Wartości przesunięcia tych elementów podrzędnych będą zależne od końca poprzedniego elementu w sekwencji lub w przypadku pierwszego elementu w sekwencji względem początku jego kontenera <seq>.

Przykład

<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>

Reprezentuje warstwę multimediów w elemencie <par> lub <seq>. Dozwolony element elementu <media> to element SSML: <speak> lub <audio>. Poniższa tabela zawiera prawidłowe atrybuty elementu <media>.

Atrybuty

Specyfikacja czasu

Specyfikacja czasu używana w przypadku wartości atrybutów „start” i „end” w elementach <media> i kontenerach multimediów (elementy <par> i <seq>) to wartość przesunięcia (na przykład +2.5s) lub wartość synchronizacji (np. foo_id.end-250ms).

• Wartość przesunięcia – wartość przesunięcia czasu to wartość SMIL, która zezwala na wartości pasujące do wyrażenia regularnego: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

  Pierwsza cyfra ciągu jest częścią części dziesiętnej, a druga część dziesiętna. Domyślny znak (np. „(+|-)?”) to „+”. Wartości jednostek odpowiadają odpowiednio godzinom, minutom, sekundom i milisekundom. Wartością domyślną jednostek jest „s” (sekundy).

• Wartość bazy danych – wartość synchronizacji bazy SMIL, która zezwala na wartości pasujące do wyrażenia regularnego: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

  Cyfry i jednostki są interpretowane tak samo jak wartość przesunięcia.

Symulator TTS

Konsola Actions zawiera symulator TTS, którego możesz używać do testowania SSML z dowolnym z powyższych elementów. Symulator zamiany tekstu na mowę znajdziesz w konsoli, klikając Symulator > Dźwięk. Wpisz tekst i SSML w symulatorze, a potem kliknij Aktualizuj i posłuchaj, by usłyszeć dane wyjściowe zamiany tekstu na mowę.

Możesz też kliknąć przycisk pobierania, aby zapisać plik .mp3 z danymi wyjściowymi TTS.