Title:	Client for the Microsoft's 'Cognitive Services Text to Speech REST' API
Version:	1.0.0.1
Description:	Convert text into synthesized speech and get a list of supported voices for a region. Microsoft's 'Cognitive Services Text to Speech REST' API https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/rest-text-to-speech?tabs=streaming supports neural text to speech voices, which support specific languages and dialects that are identified by locale.
URL:	https://github.com/fhdsl/conrad
BugReports:	https://github.com/fhdsl/conrad/issues
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.2.3
Depends:	R (≥ 2.10)
LazyData:	true
Imports:	httr2, jsonlite, magrittr
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-08-19 08:41:54 UTC; hornik
Repository:	CRAN
Date/Publication:	2024-08-19 09:00:56 UTC
Author:	Howard Baek [aut, cre, cph], John Muschelli [aut]
Maintainer:	Howard Baek <howardbaek.fh@gmail.com>

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Provide default voice when not provided

Description

If 'voice' argument is not supplied to ms_synthesize(), obtain full list of voices for a specified region and by default, use the first voice in that list.

Usage

ms_choose_voice(
  api_key = NULL,
  gender = c("Female", "Male"),
  language = "en-US",
  region = "westus"
)

Arguments

Value

List of gender, language, and full voice name

Examples

## Not run: 
# Default voice whose gender is Female, language is English, and region is 'westus'
ms_choose_voice(gender = "Female", language = "en-US", region = "westus")

## End(Not run)

Create Speech Synthesis Markup Language (SSML)

Description

Create Speech Synthesis Markup Language (SSML)

Usage

ms_create_ssml(
  script,
  voice = NULL,
  gender = c("Female", "Male"),
  language = "en-US",
  escape = FALSE
)

Arguments

Value

A character string of the text and SSML markup

Examples

ms_create_ssml("hey I really like things & dogs", escape = TRUE)
ms_create_ssml("hey I really like things")
ms_create_ssml('hey I <emphasis level="strong">really like</emphasis> things')
ms_create_ssml('hey I <emphasis level="strong">really like</emphasis> things',
escape = TRUE)

Find API Key for Microsoft Cognitive Services Text To Speech (TTS)

Description

Determines if option(ms_tts_key) is set or key is stored in an environment variable (MS_TTS_API_KEY, MS_TTS_API_KEY1, MS_TTS_API_KEY2). If not found, stops and returns an error. If found, returns the value.

Usage

ms_fetch_key(api_key = NULL, error = TRUE)

ms_exist_key(api_key = NULL)

ms_set_key(api_key)

ms_valid_key(api_key = NULL, region = "westus")

Arguments

Value

API key

Logical vector, indicating whether user has API key.

Logical vector, indicating whether API key is valid.

Functions

• ms_exist_key(): Does user have API key?

• ms_set_key(): Set API Key as a global option

• ms_valid_key(): Check whether API key is valid

Note

You can either set the API key using option(ms_tts_key) or have it accessible by api_key = Sys.getenv('MS_TTS_API_KEY")}, or \code{api_key = Sys.getenv('MS_TTS_API_KEY1")}, or \code{api_key = Sys.getenv('MS_TTS_API_KEY2")

Examples

res = ms_fetch_key(api_key = NULL, error = FALSE)


# Don't provide api key but fetch it programmatically
ms_exist_key(api_key = NULL)

# Provide api key XXX
ms_exist_key(api_key = "XXX")


# Set api key XXX
ms_set_key(api_key = "XXX")


# Check whether API key is valid in westus
ms_valid_key(region = "westus")

Get Microsoft Text To Speech (TTS) or Cognitive Services Token from API Key

Description

Get Microsoft Text To Speech (TTS) or Cognitive Services Token from API Key

Check if token has expired

Usage

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

ms_token_expired(token = NULL)

Arguments

Value

A list of the request and token

Logical vector, indicating whether token has expired

Examples

# Get token where region is westus
token = ms_get_token(region = "westus")


# Check if token XXX has expired
ms_token_expired(token = "XXX")

Get List of Voices for Specified Region

Description

Obtains a full list of voices for a specific region.

Usage

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

Arguments

Details

For more info, see Get a list of voices from the Microsoft documentation.

Value

A data.frame of the names and their long names.

Examples

# List voices for westus
ms_list_voice(region = "westus")

# List voices for eastus
ms_list_voice(region = "eastus")

Check if provided region is supported by Speech service

Description

If region is supported, this function returns the region. If not supported, throws a warning message.

Usage

ms_region(region = conrad::region)

Arguments

Value

Character vector of region

Examples

# Check if westus is supported
ms_region(region = "westus")
# Check if eastus is supported
ms_region(region = "eastus")

Convert Text to Speech

Description

Convert text to speech by using Speech Synthesis Markup Language (SSML)

Usage

ms_synthesize(
  script,
  region = "westus",
  api_key = NULL,
  token = NULL,
  gender = c("Female", "Male"),
  language = "en-US",
  voice = NULL,
  escape = FALSE
)

Arguments

Details

For more info, see Section Convert text to speech of the Microsoft documentation.

Value

An HTTP response in hexadecimal representation of binary data

Examples

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

# Create temporary 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)

# Delete temporary file
file.remove(output_path)

Retrieve Gender, Full Voice Name, and Language associated with provided Voice

Description

Verify whether given voice is compatible with specific region. If it is, provide the gender, full voice name, and language associated with given voice.

Usage

ms_use_voice(voice, api_key = NULL, region = "westus")

Arguments

Value

List of gender, language, and full voice name

Examples

## Not run: 
# Retrieve gender, full name, and language
ms_use_voice(voice = "Microsoft Server Speech Text to Speech Voice (en-US, JacobNeural)",
              region = "westus")

## End(Not run)

Play audio in a browser

Description

This uses HTML5 audio tags to play audio in your browser. Borrowed from googleLanguageR::gl_talk_player().

Usage

play_audio(audio = "output.wav", html = "player.html")

Arguments

Details

For more info, see this Mozilla documentation detailing the ⁠<audio>⁠ HTML element.

Value

No return value, called for side effects

Examples

## Not run: 
# Opens a browser with embedded audio
play_audio(audio = "output.wav")

## End(Not run)

Speech Service supported Region Identifier

Description

This character vector contains region identifiers that support text to speech.

Usage

region

Format

region

A character vector

Source

https://learn.microsoft.com/en-us/azure/cognitive-services/Speech-Service/regions