使用 SSML 朗讀地址

這個教學課程會示範如何使用語音合成標記語言 (SSML) 朗讀地址文字檔案。您可以使用 SSML 標記標註文字字串，個人化 Text-to-Speech 產生的合成音訊。

純文字	純文字的 SSML 算繪
123 Street Ln	<speak>123 Street Ln</speak>
1 Number St	<speak>1 Number St</speak>
1 Piazza del Fibonacci	<speak>1 Piazza del Fibonacci</speak>

目標

使用 SSML 和 Text-to-Speech 用戶端程式庫，將合成語音要求傳送至 Text-to-Speech。

費用

如需費用資訊，請參閱 Text-to-Speech 定價頁面。

事前準備

確認在Google Cloud 控制台中有 Text-to-Speech 專案。
本教學課程可使用 Java、Node.js 或 Python。如果打算使用 Java，請下載並安裝 Maven；如要使用 Node.js，請下載 npm。

下載程式碼範例

如要下載程式碼範例，請根據您打算使用的程式設計語言，複製 Google Cloud GitHub 範例。

Java

本教學課程使用的程式碼，取自 Google Cloud Platform Java 範例存放區的 texttospeech/cloud-client/src/main/java/com/example/texttospeech/ 目錄。

如要下載這些程式碼並前往其所在位置，請在終端機執行下列指令。

git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
cd java-docs-samples/texttospeech/cloud-client/src/main/java/com/example/texttospeech/

Node.js

本教學課程使用的程式碼，取自 Google Cloud Platform Node.js 範例存放區的 texttospeech 目錄。

如要下載這些程式碼並前往其所在位置，請在終端機執行下列指令。

git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
cd texttospeech/

Python

本教學課程使用的程式碼，取自 Google Cloud Platform Python 範例存放區的 texttospeech/snippets 目錄。

如要下載這些程式碼並前往其所在位置，請在終端機執行下列指令。

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
cd samples/snippets

安裝用戶端程式庫

本教學課程使用 Text-to-Speech 用戶端程式庫。

Java

本教學課程使用下列依附元件。

<!--  Using libraries-bom to manage versions.
See https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-texttospeech</artifactId>
  </dependency>
</dependencies>

Node.js

在終端機執行下列指令。

npm install @google-cloud/text-to-speech

Python

在終端機執行下列指令。

pip install --upgrade google-cloud-texttospeech

設定 Google Cloud Platform 憑證

Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable applies only to your current shell session. If you want the variable to apply to future shell sessions, set the variable in your shell startup file, for example in the ~/.bashrc or ~/.profile file.

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

For PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

For command prompt:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Replace KEY_PATH with the path of the JSON file that contains your credentials.

匯入程式庫

本教學課程使用下列系統和用戶端程式庫。

Java

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Java API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

// Imports the Google Cloud client library
import com.google.cloud.texttospeech.v1.AudioConfig;
import com.google.cloud.texttospeech.v1.AudioEncoding;
import com.google.cloud.texttospeech.v1.SsmlVoiceGender;
import com.google.cloud.texttospeech.v1.SynthesisInput;
import com.google.cloud.texttospeech.v1.SynthesizeSpeechResponse;
import com.google.cloud.texttospeech.v1.TextToSpeechClient;
import com.google.cloud.texttospeech.v1.VoiceSelectionParams;
import com.google.common.html.HtmlEscapers;
import com.google.protobuf.ByteString;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

Node.js

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Node.js API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

// Imports the Google Cloud client library
const textToSpeech = require('@google-cloud/text-to-speech');

// Import other required libraries
const fs = require('fs');
//const escape = require('escape-html');
const util = require('util');

Python

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Python API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import html

from google.cloud import texttospeech

使用 Text-to-Speech API

以下函式會接收 SSML 標記的文字字串，以及 MP3 檔案名稱，接著根據 SSML 標記文字生成合成音訊，再將合成音訊儲存為 MP3 格式，並依參數命名檔案。

整個 SSML 輸入內容只能由單一語音朗讀。您可以在 VoiceSelectionParams 物件中設定語音。

Java

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Java API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * Generates synthetic audio from a String of SSML text.
 *
 * <p>Given a string of SSML text and an output file name, this function calls the Text-to-Speech
 * API. The API returns a synthetic audio version of the text, formatted according to the SSML
 * commands. This function saves the synthetic audio to the designated output file.
 *
 * @param ssmlText String of tagged SSML text
 * @param outFile String name of file under which to save audio output
 * @throws Exception on errors while closing the client
 */
public static void ssmlToAudio(String ssmlText, String outFile) throws Exception {
  // Instantiates a client
  try (TextToSpeechClient textToSpeechClient = TextToSpeechClient.create()) {
    // Set the ssml text input to synthesize
    SynthesisInput input = SynthesisInput.newBuilder().setSsml(ssmlText).build();

    // Build the voice request, select the language code ("en-US") and
    // the ssml voice gender ("male")
    VoiceSelectionParams voice =
        VoiceSelectionParams.newBuilder()
            .setLanguageCode("en-US")
            .setSsmlGender(SsmlVoiceGender.MALE)
            .build();

    // Select the audio file type
    AudioConfig audioConfig =
        AudioConfig.newBuilder().setAudioEncoding(AudioEncoding.MP3).build();

    // Perform the text-to-speech request on the text input with the selected voice parameters and
    // audio file type
    SynthesizeSpeechResponse response =
        textToSpeechClient.synthesizeSpeech(input, voice, audioConfig);

    // Get the audio contents from the response
    ByteString audioContents = response.getAudioContent();

    // Write the response to the output file
    try (OutputStream out = new FileOutputStream(outFile)) {
      out.write(audioContents.toByteArray());
      System.out.println("Audio content written to file " + outFile);
    }
  }
}

Node.js

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Node.js API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * Generates synthetic audio from a String of SSML text.
 *
 * Given a string of SSML text and an output file name, this function
 * calls the Text-to-Speech API. The API returns a synthetic audio
 * version of the text, formatted according to the SSML commands. This
 * function saves the synthetic audio to the designated output file.
 *
 * ARGS
 * ssmlText: String of tagged SSML text
 * outfile: String name of file under which to save audio output
 * RETURNS
 * nothing
 *
 */
async function ssmlToAudio(ssmlText, outFile) {
  // Creates a client
  const client = new textToSpeech.TextToSpeechClient();

  // Constructs the request
  const request = {
    // Select the text to synthesize
    input: {ssml: ssmlText},
    // Select the language and SSML Voice Gender (optional)
    voice: {languageCode: 'en-US', ssmlGender: 'MALE'},
    // Select the type of audio encoding
    audioConfig: {audioEncoding: 'MP3'},
  };

  // Performs the Text-to-Speech request
  const [response] = await client.synthesizeSpeech(request);
  // Write the binary audio content to a local file
  const writeFile = util.promisify(fs.writeFile);
  await writeFile(outFile, response.audioContent, 'binary');
  console.log('Audio content written to file ' + outFile);
}

Python

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Python API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def ssml_to_audio(ssml_text: str) -> None:
    """
    Generates SSML text from plaintext.
    Given a string of SSML text and an output file name, this function
    calls the Text-to-Speech API. The API returns a synthetic audio
    version of the text, formatted according to the SSML commands. This
    function saves the synthetic audio to the designated output file.

    Args:
        ssml_text: string of SSML text
    """

    # Instantiates a client
    client = texttospeech.TextToSpeechClient()

    # Sets the text input to be synthesized
    synthesis_input = texttospeech.SynthesisInput(ssml=ssml_text)

    # Builds the voice request, selects the language code ("en-US") and
    # the SSML voice gender ("MALE")
    voice = texttospeech.VoiceSelectionParams(
        language_code="en-US", ssml_gender=texttospeech.SsmlVoiceGender.MALE
    )

    # Selects the type of audio file to return
    audio_config = texttospeech.AudioConfig(
        audio_encoding=texttospeech.AudioEncoding.MP3
    )

    # Performs the text-to-speech request on the text input with the selected
    # voice parameters and audio file type
    response = client.synthesize_speech(
        input=synthesis_input, voice=voice, audio_config=audio_config
    )

    # Writes the synthetic audio to the output file.
    with open("test_example.mp3", "wb") as out:
        out.write(response.audio_content)
        print("Audio content written to file " + "test_example.mp3")

個人化合成語音

以下函式會接收文字檔的名稱，並將檔案內容轉換為 SSML 標記的文字字串。

Java

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Java API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * Generates SSML text from plaintext.
 *
 * <p>Given an input filename, this function converts the contents of the input text file into a
 * String of tagged SSML text. This function formats the SSML String so that, when synthesized,
 * the synthetic audio will pause for two seconds between each line of the text file. This
 * function also handles special text characters which might interfere with SSML commands.
 *
 * @param inputFile String name of plaintext file
 * @return a String of SSML text based on plaintext input.
 * @throws IOException on files that don't exist
 */
public static String textToSsml(String inputFile) throws Exception {

  // Read lines of input file
  String rawLines = new String(Files.readAllBytes(Paths.get(inputFile)));

  // Replace special characters with HTML Ampersand Character Codes
  // These codes prevent the API from confusing text with SSML tags
  // For example, '<' --> '&lt;' and '&' --> '&amp;'
  String escapedLines = HtmlEscapers.htmlEscaper().escape(rawLines);

  // Convert plaintext to SSML
  // Tag SSML so that there is a 2 second pause between each address
  String expandedNewline = escapedLines.replaceAll("\\n", "\n<break time='2s'/>");
  String ssml = "<speak>" + expandedNewline + "</speak>";

  // Return the concatenated String of SSML
  return ssml;
}

Node.js

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Node.js API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * Generates SSML text from plaintext.
 *
 * Given an input filename, this function converts the contents of the input text file
 * into a String of tagged SSML text. This function formats the SSML String so that,
 * when synthesized, the synthetic audio will pause for two seconds between each line
 * of the text file. This function also handles special text characters which might
 * interfere with SSML commands.
 *
 * ARGS
 * inputfile: String name of plaintext file
 * RETURNS
 * a String of SSML text based on plaintext input
 *
 */
function textToSsml(inputFile) {
  let rawLines = '';
  // Read input file
  try {
    rawLines = fs.readFileSync(inputFile, 'utf8');
  } catch (e) {
    console.log('Error:', e.stack);
    return;
  }

  // Replace special characters with HTML Ampersand Character Codes
  // These codes prevent the API from confusing text with SSML tags
  // For example, '<' --> '&lt;' and '&' --> '&amp;'
  let escapedLines = rawLines;
  escapedLines = escapedLines.replace(/&/g, '&amp;');
  escapedLines = escapedLines.replace(/"/g, '&quot;');
  escapedLines = escapedLines.replace(/</g, '&lt;');
  escapedLines = escapedLines.replace(/>/g, '&gt;');

  // Convert plaintext to SSML
  // Tag SSML so that there is a 2 second pause between each address
  const expandedNewline = escapedLines.replace(/\n/g, '\n<break time="2s"/>');
  const ssml = '<speak>' + expandedNewline + '</speak>';

  // Return the concatenated String of SSML
  return ssml;
}

Python

如要瞭解如何安裝及使用 Text-to-Speech 的用戶端程式庫，請參閱「Text-to-Speech 用戶端程式庫」。詳情請參閱 Text-to-Speech Python API 參考文件。

如要進行 Text-to-Speech 驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def text_to_ssml(inputfile: str) -> str:
    """
    Generates SSML text from plaintext.
    Given an input filename, this function converts the contents of the text
    file into a string of formatted SSML text. This function formats the SSML
    string so that, when synthesized, the synthetic audio will pause for two
    seconds between each line of the text file. This function also handles
    special text characters which might interfere with SSML commands.

    Args:
        inputfile: name of plaintext file
    Returns: SSML text based on plaintext input
    """

    # Parses lines of input file
    with open(inputfile) as f:
        raw_lines = f.read()

    # Replace special characters with HTML Ampersand Character Codes
    # These Codes prevent the API from confusing text with
    # SSML commands
    # For example, '<' --> '&lt;' and '&' --> '&amp;'

    escaped_lines = html.escape(raw_lines)

    # Convert plaintext to SSML
    # Wait two seconds between each address
    ssml = "<speak>{}</speak>".format(
        escaped_lines.replace("\n", '\n<break time="2s"/>')
    )

    # Return the concatenated string of ssml script
    return ssml

全面整合

這個程式會使用下列輸入內容。

123 Street Ln, Small Town, IL 12345 USA
1 Jenny St & Number St, Tutone City, CA 86753
1 Piazza del Fibonacci, 12358 Pisa, Italy

將上述文字傳遞至 text_to_ssml()，會產生下列標記文字。

<speak>123 Street Ln, Small Town, IL 12345 USA
<break time="2s"/>1 Jenny St &amp; Number St, Tutone City, CA 86753
<break time="2s"/>1 Piazza del Fibonacci, 12358 Pisa, Italy
<break time="2s"/></speak>

執行程式碼

如要生成合成語音的音訊檔案，請在指令列執行以下程式碼。

Java

Linux 或 MacOS

在 java-docs-samples/texttospeech/cloud-client/ 目錄中，於指令列執行下列指令。

$ mvn clean package

Windows

在 java-docs-samples/texttospeech/cloud-client/ 目錄中，於指令列執行下列指令。

$ mvn clean package

Node.js

Linux 或 MacOS

在 hybridGlossaries.js 檔案中，取消註解 TODO (developer) 註解排除的變數。

在下列指令中，將 projectId 替換為您的 Google Cloud 專案 ID。在 nodejs-docs-samples/texttospeech 目錄中，於指令列執行下列指令。

$ node ssmlAddresses.js projectId

Windows

在 hybridGlossaries.js 檔案中，取消註解 TODO (developer) 註解排除的變數。

在下列指令中，將 projectId 替換為您的 Google Cloud 專案 ID。在 nodejs-docs-samples/texttospeech 目錄中，於指令列執行下列指令。

$env: C:/Node.js/node.exe C: ssmlAddresses.js projectId

Python

Linux 或 MacOS

在 python-docs-samples/texttospeech/snippets 目錄中，於指令列執行下列指令。

$ python ssml_addresses.py

Windows

在 python-docs-samples/texttospeech/snippets 目錄中，於指令列執行下列指令。

$env: C:/Python3/python.exe C: ssml_addresses.py

檢查輸出內容

這個程式會輸出合成語音的 example.mp3 音訊檔案。

Java

前往 java-docs-samples/texttospeech/cloud-client/resources/ 目錄。

檢查 resources 目錄是否有 example.mp3 檔案。

Node.js

前往 nodejs-docs-samples/texttospeech/resources/ 目錄。

檢查 resources 目錄是否有 example.mp3 檔案。

Python

前往 python-docs-samples/texttospeech/snippets/resources。

檢查 resources 目錄是否有 example.mp3 檔案。

聆聽下列音訊片段，確認 example.mp3 檔案的音效是否相同。

疑難排解

如果忘記在指令列中設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數，會產生下列錯誤訊息：
```
The Application Default Credentials are not available.
```
如果將不存在的檔案名稱傳遞給 text_to_ssml()，會產生下列錯誤訊息：
```
IOError: [Errno 2] No such file or directory
```
將包含 None 的 ssml_text 參數傳遞給 ssml_to_audio()，會產生下列錯誤訊息：
```
InvalidArgument: 400 Invalid input type. Type has to be text or SSML
```
請務必從正確的目錄執行程式碼。

後續步驟

探索其他 SSML 標記。
瞭解如何搭配翻譯和視覺功能使用 SSML

清除所用資源

如要避免系統向 Google Cloud Platform 帳戶收取您在本教學課程中所用資源的相關費用，請前往Google Cloud 控制台刪除不需要的專案。

刪除專案

前往Google Cloud 控制台的「Projects」(專案) 頁面。
在專案清單中選取要刪除的專案，然後按一下「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下「Shut down」(關閉) 刪除專案。

使用 SSML 朗讀地址 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

下載程式碼範例

Java

Node.js

Python

安裝用戶端程式庫

Java

Node.js

Python

設定 Google Cloud Platform 憑證

Linux 或 macOS

Windows

匯入程式庫

Java

Node.js

Python

使用 Text-to-Speech API

Java

Node.js

Python

個人化合成語音

Java

Node.js

Python

全面整合

執行程式碼

Java

Linux 或 MacOS

Windows

Node.js

Linux 或 MacOS

Windows

Python

Linux 或 MacOS

Windows

檢查輸出內容

Java

Node.js

Python

疑難排解

後續步驟

清除所用資源

刪除專案

使用 SSML 朗讀地址