> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XSpeechSynthesizerCreate

> XSpeechSynthesizerCreate

# XSpeechSynthesizerCreate

创建语音合成器。

## 语法

```cpp theme={null}
HRESULT XSpeechSynthesizerCreate(  
         XSpeechSynthesizerHandle* speechSynthesizer  
)  
```

### 参数

*speechSynthesizer*   \_Out\_\
类型：XSpeechSynthesizerHandle\*

所创建语音合成器的句柄。

### 返回值

类型：[HRESULT](https://learn.microsoft.com/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)

如果成功，则返回 **S\_OK**；否则返回错误代码。有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。

## 备注

<Note>此函数在时间敏感型线程上调用不安全。有关详细信息，请参阅[时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

使用此函数创建新的语音合成器实例并接收其句柄，该实例提供对已安装语音合成引擎（即*语音*）功能的访问。

默认情况下，新的语音合成器实例使用当前系统语音。若要枚举并获取当前设备上已安装语音的信息，请使用 [XSpeechSynthesizerEnumerateInstalledVoices](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerenumerateinstalledvoices) 函数以及 [XSpeechSynthesizerInstalledVoicesCallback](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerinstalledvoicescallback) 回调函数。对于每个已安装的语音，[XSpeechSynthesizerVoiceInformation](/reference/system/xspeechsynthesizer/structs/xspeechsynthesizervoiceinformation) 结构提供语音 ID、说明、显示文本、性别、语言和其他信息。调用 [XSpeechSynthesizerSetCustomVoice](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizersetcustomvoice) 使用不同的已安装语音，或调用 [XSpeechSynthesizerSetDefaultVoice](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizersetdefaultvoice) 重新使用当前系统语音。

在创建语音合成器句柄并指定语音后，使用 [XSpeechSynthesizerCreateStreamFromText](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizercreatestreamfromtext) 函数来创建语音合成器流并从纯文本合成语音。使用 [XSpeechSynthesizerGetStreamDataSize](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizergetstreamdatasize) 和 [XSpeechSynthesizerGetStreamData](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizergetstreamdata) 函数从语音合成器流中获取所合成语音的音频数据，然后在所有未完成的异步操作完成后使用 [XSpeechSynthesizerCloseStreamHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosestreamhandle) 函数关闭语音合成器流。

在完成使用语音合成器后，使用 [XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle) 函数关闭语音合成器并释放系统资源。

为防止内存泄漏，在完成使用句柄的所有操作后，请调用 [XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle) 函数关闭语音合成器句柄。

以下示例演示如何使用语音合成器和已安装的语音从纯文本合成语音，以及如何使用语音合成器流合成音频数据。**XSpeechSynthesizerCreate** 和 **XSpeechSynthesizerSetCustomVoice** 函数会创建语音合成器实例，并且如果在 *voiceId* 中指定了语音 ID，则可选择性地为其分配自定义语音。然后，**XSpeechSynthesizerCreateStreamFromText** 函数会创建语音合成器流并从 *textToSpeak* 中指定的纯文本合成语音。在创建流之后，**XSpeechSynthesizerGetStreamDataSize** 和 **XSpeechSynthesizerGetStreamData** 函数会从流中检索所合成语音的音频数据以进行播放。最后，音频数据播放完成后，**XSpeechSynthesizerCloseStreamHandle** 和 **XSpeechSynthesizerCloseHandle** 函数会关闭语音合成器流和语音合成器。

```cpp theme={null}
HRESULT Game::SynthesizeSpeech(
    const char* textToSpeak,
    const char* voiceId)
{
    // Create a new speech synthesizer.
    XSpeechSynthesizerHandle ssHandle = nullptr;
    if (FAILED(XSpeechSynthesizerCreate(&ssHandle))) { return E_FAIL; }

    // If a voice ID was specified, attempt to set the speech synthesizer to
    // use the specified voice. Note that voiceId has a default value of nullptr, 
    // as specified in its function declaration.
    if (voiceId != nullptr) 
    {
        if (FAILED(XSpeechSynthesizerSetCustomVoice(ssHandle, voiceId))) { return E_FAIL; }
    }

    // Create a new speech synthesizer stream from the specified text.
    XSpeechSynthesizerStreamHandle ssStreamHandle = nullptr;
    if (FAILED(XSpeechSynthesizerCreateStreamFromText(ssHandle, textToSpeak, &ssStreamHandle))) { return E_FAIL; }

    // Get the size of the buffer needed for the audio data from our stream.
    size_t bufferSize;
    if (FAILED(XSpeechSynthesizerGetStreamDataSize(ssStreamHandle, &bufferSize))) { return E_FAIL; }

    // Define the buffer, then retrieve the audio data from our stream.
    std::vector<char> streamData;
    streamData.resize(bufferSize);
    if (FAILED(XSpeechSynthesizerGetStreamData(ssStreamHandle, bufferSize, streamData.data(), &bufferSize))) { return E_FAIL; }

    // We now have audio data from the speech synthesizer stream, so let's play it. 
    // For the purposes of this example, the sound is played synchronously, so that we don't
    // risk having an outstanding asynchronous operation when we close the stream.
    PlaySoundW(reinterpret_cast<LPCWSTR>(streamData.data()), nullptr, SND_MEMORY);

    // We're done with the speech synthesizer stream, so let's close it.
    if (FAILED(XSpeechSynthesizerCloseStreamHandle(ssStreamHandle))) { return E_FAIL; }

    // We're done with the speech synthesizer, so let's close that, too.
    if (FAILED(XSpeechSynthesizerCloseHandle(ssHandle))) { return E_FAIL; }

    return S_OK;
}
```

## 要求

**头文件：** XSpeechSynthesizer.h

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 概念文档

* [文本转语音](/build/console-features/text-to-speech/text-to-speech)
* [时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另请参阅

[XAccessibility](/reference/system/xaccessibility/xaccessibility_members)\
[XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle)\
[XSpeechSynthesizer](/reference/system/xspeechsynthesizer/xspeechsynthesizer_members)