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

Creates a speech synthesizer.

## Syntax

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

### Parameters

*speechSynthesizer*   \_Out\_\
Type: XSpeechSynthesizerHandle\*

The handle to the created speech synthesizer.

### Return value

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

Returns **S\_OK** if successful; otherwise, returns an error code. For a list of error codes, see [Error Codes](/reference/errorcodes).

## Remarks

<Note>This function isn't safe to call on a time-sensitive thread. For more information, see [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

Use this function to create and receive the handle to a new speech synthesizer instance, which provides access to the functionality of an installed speech synthesis engine, or *voice*.

By default, a new speech synthesizer instance uses the current system voice. To enumerate and get information about the voices installed on the current device, use the [XSpeechSynthesizerEnumerateInstalledVoices](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerenumerateinstalledvoices) function along with the [XSpeechSynthesizerInstalledVoicesCallback](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerinstalledvoicescallback) callback function. For each installed voice, the [XSpeechSynthesizerVoiceInformation](/reference/system/xspeechsynthesizer/structs/xspeechsynthesizervoiceinformation) structure provides the voice ID, description, display text, gender, language, and other information. Invoke [XSpeechSynthesizerSetCustomVoice](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizersetcustomvoice) to use a different installed voice, or invoke [XSpeechSynthesizerSetDefaultVoice](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizersetdefaultvoice) to use the current system voice again.

After creating a speech synthesizer handle and specifying a voice, use the [XSpeechSynthesizerCreateStreamFromText](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizercreatestreamfromtext) function to create a speech synthesizer stream and to synthesize speech from plain text. Use the [XSpeechSynthesizerGetStreamDataSize](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizergetstreamdatasize) and [XSpeechSynthesizerGetStreamData](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizergetstreamdata) functions to get the audio data for the synthesized speech from the speech synthesizer stream, then use the [XSpeechSynthesizerCloseStreamHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosestreamhandle) function to close the speech synthesizer stream after all outstanding asynchronous operations are completed.

Use the [XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle) function to close the speech synthesizer and to release system resources after you're done using the speech synthesizer.

To prevent memory leaks, call the [XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle) function to close a speech synthesizer handle after you've completed all operations that are using the handle.

The following example demonstrates how to synthesize speech from plain text by using a speech synthesizer and an installed voice, and how to synthesize audio data with a speech synthesizer stream. The **XSpeechSynthesizerCreate** and **XSpeechSynthesizerSetCustomVoice** functions create a speech synthesizer instance and, optionally, assign a custom voice to it if a voice ID is specified in *voiceId*. Then, the **XSpeechSynthesizerCreateStreamFromText** function creates a speech synthesizer stream and synthesizes speech from the plain text specified in *textToSpeak*. After the stream is created, the **XSpeechSynthesizerGetStreamDataSize** and **XSpeechSynthesizerGetStreamData** functions retrieve the audio data for the synthesized speech to be played from the stream. Finally, after the playing of audio data is completed, the **XSpeechSynthesizerCloseStreamHandle** and **XSpeechSynthesizerCloseHandle** functions close the speech synthesizer stream and speech synthesizer.

```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;
}
```

## Requirements

**Header:** XSpeechSynthesizer.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [Text-to-speech](/build/console-features/text-to-speech/text-to-speech)
* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

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


## Related topics

- [XSpeechSynthesizerCreateStreamFromSsml](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizercreatestreamfromssml.md)
- [XSpeechSynthesizerCreateStreamFromText](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizercreatestreamfromtext.md)
- [XSpeechSynthesizerCloseHandle](/reference/system/xspeechsynthesizer/functions/xspeechsynthesizerclosehandle.md)
- [XSpeechSynthesizer](/reference/system/xspeechsynthesizer/xspeechsynthesizer_members.md)
- [Text-to-speech](/build/console-features/text-to-speech/text-to-speech.md)