Generate narration with Text-To-Speech technology

The input is a script file in YAML format. Example script files can be found under test/fixtures.

The script file is structured in this way:

• settings: script settings
  • voice: voice settings at script level
• chapters: array of chapter
  • each chapter can contain settings and multiple sections:
    • settings: chapter level voice settings that can override script level voice settings
    • sections: array of sections
      • each section can contain settings and multiple paragraphs:
        • settings: section level voice settings that can override upper level voice settings
        • paragraphs: array of paragraphs
          • each paragraph can contain settings and text:
            • settings: paragraph level voice settings that can override upper level voice settings
            • text: text content that needs to be converted into audio

The text field of a paragraph can be pure text, or an SSML fragment. Multi-line strings are supported.

It has command line flags --play and --no-play to control whether generated MP3s should be played back. This feature is supported by a dev dependency node-speaker. If you use it as a library in your project, and would like to have the play back capability, you need to install node-speaker as a dependency in your project.

When running on MacOS, to avoid illegal hardware instruction issue, try npm i speaker --mpg123-backend=openal

To use the CLI as an NPM package, you need to install it with all its optional dependencies, like this:

npm i -g --include=optional tts-narrator

USAGE
  $ tts-narrator   FILE[-h] [-v] [-d] [-s azure] [-k <value>]
    [--subscription-key-env <value>] [-r <value>] [-p] [-i] [-o] [--dry-run]
    [--ssml | -q] [--chapters <value>] [--sections <value>]

ARGUMENTS
  FILE  path to the script file (.yml)

FLAGS
  -d, --debug                         output debug information
  -h, --help                          Show help
  -i, --interactive                   wait for key press before entering each
                                      section
  -k, --subscription-key=<value>      Azure Speech service subscription key
  -o, --overwrite                     always overwrite previously generated
                                      audio files
  -p, --[no-]play                     play generated audio
  -q, --quiet                         output warn and error information only
  -r, --region=<value>                region of the text-to-speech service
  -s, --service=<option>              text-to-speech service to use
                                      <options: azure>
  -v, --version                       Show CLI version
      --chapters=<value>              list of chapters to process, examples:
                                      "1-10,13,15", "4-"
      --dry-run                       don't try to generate or play audio
      --sections=<value>              list of sections to process, examples:
                                      "1-10,13,15", "5-"
      --ssml                          display generated SSML
      --subscription-key-env=<value>  Name of the environment variable that
                                      holds the subscription key

DESCRIPTION
  Generate narration with Text-To-Speech technology

EXAMPLES
  $ tts-narrator myscript.yml --play --interactive --service azure --subscription-key-env TTS_SUBSCRIPTION_KEY --region australiaeast

  $ tts-narrator ./test/fixtures/script3.yml -s azure --ssml -r australiaeast --subscription-key-env=TTS_SUB_KEY  --no-play --interactive -d

  $ tts-narrator ./test/fixtures/script3.yml -s azure -r australiaeast --subscription-key-env=TTS_SUB_KEY --quiet

  $ tts-narrator ./test/fixtures/script3.yml

To use the NPM package as a dependency, you just need to install it normally, like this:

npm i tts-narrator

Example:

const ttsService = new AzureTtsService(...);
const ttsNarrator = new TtsNarrator(ttsService, './output-folder');
const script = await loadScript('./my-script.yml');
await ttsNarrator.narrate(script);
console.log(`One of the generated audio file is: ${script.chapters[0].sections[0].paragraphs[0].audioFilePath}`);

• audio-utils
• azure-tts-service
• index
• narration-script
• script-processor
• script-processor-flags
• tts-narrator
• tts-narrator-cli
• tts-service

azure-tts-service.AzureTtsService

• BaseTtsService

  ↳ AzureTtsService

• new AzureTtsService(options?)

BaseTtsService.constructor

▸ Protected buildMsttsExpressAsStartTag(msttsExpressAsSettings): string

string

BaseTtsService.buildMsttsExpressAsStartTag

▸ Protected buildProsodyStartTag(prosodySettings): string

string

BaseTtsService.buildProsodyStartTag

▸ Protected buildSpeakStartTag(voiceSettings): string

string

BaseTtsService.buildSpeakStartTag

▸ Protected buildVoiceStartTag(voiceSettings): string

string

BaseTtsService.buildVoiceStartTag

▸ generateAudio(ssml, options): Promise<any>

Promise<any>

BaseTtsService.generateAudio

▸ generateSSML(paragraph): Promise<string>

Promise<string>

BaseTtsService.generateSSML

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Object

BaseTtsService.generateSsmlWithoutValidation

▸ Protected validateXML(xml, lineOffset): void

void

BaseTtsService.validateXML

narration-script.NarrationChapter

• Chapter

• new NarrationChapter(chapter, index, script)

• get key(): string

string

Chapter.key

• get settings(): VoiceSettings

VoiceSettings

Chapter.settings

▸ getSectionByKey(key): undefined | NarrationSection

undefined | NarrationSection

narration-script.NarrationParagraph

• Paragraph

• new NarrationParagraph(paragraph, index, section, chapter, script)

• get key(): string

string

Paragraph.key

• get settings(): VoiceSettings

VoiceSettings

Paragraph.settings

• get text(): string

string

Paragraph.text

narration-script.NarrationScript

• Script

• new NarrationScript(script, scriptFilePath)

• get settings(): ScriptSettings

ScriptSettings

Script.settings

▸ export(): Script

Script

▸ getChapterByKey(key): undefined | NarrationChapter

undefined | NarrationChapter

narration-script.NarrationSection

• Section

• new NarrationSection(section, index, chapter, script)

• get key(): string

string

Section.key

• get settings(): VoiceSettings

VoiceSettings

Section.settings

script-processor.ScriptProcessor

• ScriptProcessor

  ↳ TtsNarrator

• new ScriptProcessor(scriptFilePath, flags, cliConsole?)

• Protected get chalk(): undefined | null | typeof prompts

chalk, or null caused by library not available

undefined | null | typeof prompts

• Protected get prompts(): undefined | null | typeof prompts

prompts function, or null caused by library not available

undefined | null | typeof prompts

• get script(): NarrationScript

NarrationScript

▸ Protected determineAudioFilePath(ssmlHash, _paragraph): Promise<string>

Promise<string>

▸ Protected hash(ssml, _paragraph): string

string

▸ Protected initialiseTtsServiceIfNeeded(): Promise<void>

Promise<void>

▸ Protected loadScriptIfNeeded(): Promise<void>

Promise<void>

▸ Protected parseRanges(): void

void

▸ Protected processGeneratedAudioFile(audioFilePath): Promise<string>

Promise<string>

▸ run(reconstructedCommandLine?): Promise<void>

Promise<void>

▸ runWithoutCatch(reconstructedCommandLine?): Promise<void>

Promise<void>

tts-narrator.TtsNarrator

Class for generating narration. Instance of this class can be used to generate narration audio for scripts by calling the narrate(...) method.

Example

const ttsService = new AzureTtsService(...);
const ttsNarrator = new TtsNarrator(ttsService, './output-folder');
const script = await loadScript('./my-script.yml');
await ttsNarrator.narrate(script);
console.log(`One of the generated audio file is: ${script.chapters[0].sections[0].paragraphs[0].audioFilePath}`);

• ScriptProcessor

  ↳ TtsNarrator

• new TtsNarrator(ttsService, audioFileFolder, options?, cliConsole?)

Constructor

ScriptProcessor.constructor

• Protected get chalk(): undefined | null | typeof prompts

chalk, or null caused by library not available

undefined | null | typeof prompts

ScriptProcessor.chalk

• Protected get prompts(): undefined | null | typeof prompts

prompts function, or null caused by library not available

undefined | null | typeof prompts

ScriptProcessor.prompts

• get script(): NarrationScript

NarrationScript

ScriptProcessor.script

▸ Protected determineAudioFilePath(ssmlHash, _paragraph): Promise<string>

Promise<string>

ScriptProcessor.determineAudioFilePath

▸ Protected hash(ssml, _paragraph): string

string

ScriptProcessor.hash

▸ Protected initialiseTtsServiceIfNeeded(): Promise<void>

Promise<void>

ScriptProcessor.initialiseTtsServiceIfNeeded

▸ Protected loadScriptIfNeeded(): Promise<void>

Promise<void>

ScriptProcessor.loadScriptIfNeeded

▸ narrate(script): Promise<void>

Generate narration for the script

Promise<void>

nothing

▸ Protected parseRanges(): void

void

ScriptProcessor.parseRanges

▸ Protected processGeneratedAudioFile(audioFilePath): Promise<string>

Promise<string>

ScriptProcessor.processGeneratedAudioFile

▸ run(reconstructedCommandLine?): Promise<void>

Promise<void>

ScriptProcessor.run

▸ runWithoutCatch(reconstructedCommandLine?): Promise<void>

Promise<void>

ScriptProcessor.runWithoutCatch

tts-narrator-cli.export=

• Command

  ↳ export=

• new export=(argv, config)

Command.constructor

▸ run(): Promise<void>

Promise<void>

Command.run

tts-service.BaseTtsService

• BaseTtsService

  ↳ AzureTtsService

• TtsService

• new BaseTtsService()

▸ Protected buildMsttsExpressAsStartTag(msttsExpressAsSettings): string

string

▸ Protected buildProsodyStartTag(prosodySettings): string

string

▸ Protected buildSpeakStartTag(voiceSettings): string

string

▸ Protected buildVoiceStartTag(voiceSettings): string

string

▸ generateAudio(_ssml, _options): Promise<void>

Promise<void>

TtsService.generateAudio

▸ generateSSML(paragraph): Promise<string>

Promise<string>

TtsService.generateSSML

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Object

▸ Protected validateXML(xml, lineOffset): void

void

tts-service.TtsServiceType

• Azure = "azure"

azure-tts-service.AzureAudioGenerationOptions

• AudioGenerationOptions

  ↳ AzureAudioGenerationOptions

narration-script.NarrationScriptFile.Chapter

• NarrationChapter

narration-script.NarrationScriptFile.Paragraph

• NarrationParagraph

narration-script.NarrationScriptFile.Script

• NarrationScript

narration-script.NarrationScriptFile.Section

• NarrationSection

narration-script.ScriptSettings

narration-script.VoiceSettings

tts-service.AudioGenerationOptions

• AudioGenerationOptions

  ↳ AzureAudioGenerationOptions

tts-service.TtsService

• BaseTtsService

▸ generateAudio(ssml, options): Promise<void>

Promise<void>

▸ generateSSML(paragraph): Promise<string>

Promise<string>

▸ getAudioFileDuration(filePath): Promise<number>

Promise<number>

▸ playMp3File(filePath, infoLogger): Promise<void>

Promise<void>

• AzureTtsService

• AzureAudioGenerationOptions

Re-exports AudioGenerationOptions

Re-exports AzureAudioGenerationOptions

Re-exports AzureTtsService

Re-exports BaseTtsService

Re-exports NarrationChapter

Re-exports NarrationParagraph

Re-exports NarrationScript

Re-exports NarrationScriptFile

Re-exports NarrationSection

Re-exports ScriptProcessor

Re-exports ScriptSettings

Re-exports TtsNarrator

Re-exports TtsService

Re-exports TtsServiceType

Re-exports VoiceSettings

Re-exports getAudioFileDuration

Re-exports loadScript

Re-exports playMp3File

Re-exports saveScript

narration-script.NarrationScriptFile

• Chapter
• Paragraph
• Script
• Section

• NarrationScriptFile

• NarrationChapter
• NarrationParagraph
• NarrationScript
• NarrationSection

• ScriptSettings
• VoiceSettings

▸ loadScript(scriptFilePath): Promise<NarrationScript>

Promise<NarrationScript>

▸ saveScript(script): Promise<void>

Promise<void>

▸ saveScript(script, scriptFilePath): Promise<void>

Promise<void>

• ScriptProcessor

Ƭ ScriptProcessorFlags: CommandOptions<{ flags: typeof scriptProcessorFlags }>["flags"]

• Const scriptProcessorFlags: Object

CLI flags that are required/used by the ScriptProcessor.

• TtsNarrator

• export=

• TtsServiceType

• BaseTtsService

• AudioGenerationOptions
• TtsService