:exclamation:conrad is a reboot of mscstts. Instead of httr, which is superseded and not recommended, we use httr2 to perform HTTP requests to the Microsoft Cognitive Services Text to Speech REST API.

conrad serves as a client to the Microsoft Cognitive Services Text to Speech REST API. The Text to Speech REST API supports neural text to speech voices, which support specific languages and dialects that are identified by locale. Each available endpoint is associated with a region.

Before you use the text to speech REST API, a valid account must be registered at the Microsoft Azure Cognitive Services and you must obtain an API key. Without an API key, this package will not work.


Install the CRAN version:


Or install the development version from GitHub:

# install.packages("devtools")

Getting an API key

  1. Sign in/Create an Azure account on Microsoft Azure Cognitive Services.
  2. Click + Create a resource (below “Azure services” or click on the Hamburger button)
  3. Search for “Speech” and Click Create -> Speech
  4. Create a Resource group and a “Name”.
  5. Choose Pricing tier (you can choose the free version with Free F0)
  6. Click Review + create, review the Terms, and click Create.

If the deployment was successful, you should see :white_check_mark: Your deployment is complete on the next page.

  1. Under Next steps, click Go to resource
  2. Look on the left sidebar and under Resource Management, click Keys and Endpoint
  3. Copy either KEY 1 or KEY 2 to clipboard. Only one key is necessary to make an API call.

Once you complete these steps, you have successfully retrieved your API keys to access the API.

:warning: Remember your Location/Region, which you use to make calls to the API. Specifying a different region will lead to a HTTP 403 Forbidden response.

Setting your API key

You can set your API key in a number of ways:

  1. Edit ~/.Renviron and set MS_TTS_API_KEY = "YOUR_API_KEY"
  2. In R, use options(ms_tts_key = "YOUR_API_KEY").
  3. Set export MS_TTS_API_KEY=YOUR_API_KEY in .bash_profile/.bashrc if you’re using R in the terminal.
  4. Pass api_key = "YOUR_API_KEY" in arguments of functions such as ms_list_voices(api_key = "YOUR_API_KEY").

Get a list of voices

ms_list_voice() uses the endpoint to get a full list of voices for a specific region. It attaches a region prefix to this endpoint to get a list of voices for that region.

For example, to get a list of all the voices for the westus region, it uses the endpoint.

:warning: Be sure to specify the Speech resource region that corresponds to your API Key.

ms_list_voice(api_key = "YOUR_API_KEY", region = "westus")

Convert text to speech

ms_synthesize() uses the endpoint to convert text to speech. The endpoint requires Speech Synthesis Markup Language (SSML) to specify the language, gender, and full voice name.

:warning: Be sure to specify the Speech resource region that corresponds to your API Key.

# Convert text to speech
res <- ms_synthesize(script = "Hello world, this is a talking computer", region = "westus", gender = "Male")
# Returns hexadecimal representation of binary data

# Create file to store audio output
output_path <- tempfile(fileext = ".wav")
# Write binary data to output path
writeBin(res, con = output_path)
# Play audio in browser
play_audio(audio = output_path)

Get an access token

ms_get_token() makes a request to the issueToken endpoint to get an access token. The function require an API key and region as inputs. The access token is used to send requests to the API.

:warning: Be sure to specify the Speech resource region that corresponds to your API Key.

ms_get_token(api_key = "YOUR_API_KEY", region = "westus")

Major differences to mscstts

We believe that these improvements will greatly enhance the usability of the package and make it even more reliable in the long-term.


conrad wouldn’t be possible without prior work on mscstts by John Muschelli and httr2 by Hadley Wickham.