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

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

• audio-utils
• azure-tts-service
• index
• narration-script
• script-processor
• tts-service
• types

azure-tts-service.AzureTtsService

• BaseTtsService

  ↳ AzureTtsService

• new AzureTtsService()

BaseTtsService.constructor

▸ Protected buildSpeakStartTag(voiceSettings): string

Name	Type
voiceSettings	VoiceSettings

string

BaseTtsService.buildSpeakStartTag

---

▸ Protected buildVoiceStartTag(voiceSettings): string

Name	Type
voiceSettings	VoiceSettings

string

BaseTtsService.buildVoiceStartTag

---

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

Name	Type
ssml	string
options	AzureAudioGenerationOptions

Promise<any>

BaseTtsService.generateAudio

---

▸ generateSSML(paragraph): Promise<string>

Name	Type
paragraph	NarrationParagraph

Promise<string>

BaseTtsService.generateSSML

---

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Name	Type
paragraph	NarrationParagraph

Object

Name	Type
lineOffset	number
ssml	string

BaseTtsService.generateSsmlWithoutValidation

---

▸ Protected validateXML(xml, lineOffset): void

Name	Type
xml	string
lineOffset	number

void

BaseTtsService.validateXML

index.export=

• Command

  ↳ export=

• new export=(argv, config)

Name	Type
argv	string[]
config	Config

Command.constructor

Property	Description
Static args: Object	Type declaration
Static description: string = 'Generate narration with Text-To-Speech technology'	Overrides Command.description
Static examples: string[]	Overrides Command.examples
Static flags: Object	Type declaration
Static id: string = ' '	Overrides Command.id

▸ run(): Promise<void>

Promise<void>

Command.run

narration-script.NarrationChapter

• Chapter

• new NarrationChapter(chapter, index, script)

Name	Type
chapter	Chapter
index	number
script	NarrationScript

Property	Description
Protected chapter: Chapter
index: number
script: NarrationScript
sections: NarrationSection[]	Implementation of Chapter.sections

• get key(): string

string

Chapter.key

---

• get settings(): VoiceSettings

VoiceSettings

Chapter.settings

▸ getSectionByKey(key): undefined | NarrationSection

Name	Type
key	string

undefined | NarrationSection

narration-script.NarrationParagraph

• Paragraph

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

Name	Type
paragraph	Paragraph
index	number
section	NarrationSection
chapter	NarrationChapter
script	NarrationScript

Property	Description
Optional audioFilePath: string	Path of the generated audio file. Only for in-memory processing, not supposed to be stored in file.
chapter: NarrationChapter
index: number
Protected paragraph: Paragraph
script: NarrationScript
section: NarrationSection

• 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)

Name	Type
script	Script
scriptFilePath	string

Property	Description
chapters: NarrationChapter[]	Implementation of Script.chapters
Protected script: Script
scriptFilePath: string

• get settings(): ScriptSettings

ScriptSettings

Script.settings

▸ export(): Script

Script

---

▸ getChapterByKey(key): undefined | NarrationChapter

Name	Type
key	string

undefined | NarrationChapter

narration-script.NarrationSection

• Section

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

Name	Type
section	Section
index	number
chapter	NarrationChapter
script	NarrationScript

Property	Description
chapter: NarrationChapter
index: number
paragraphs: NarrationParagraph[]	Implementation of Section.paragraphs
script: NarrationScript
Protected section: Section

• get key(): string

string

Section.key

---

• get settings(): VoiceSettings

VoiceSettings

Section.settings

script-processor.ScriptProcessor

• new ScriptProcessor(scriptFilePath, flags, cliConsole?)

Name	Type
scriptFilePath	string
flags	Object & FlagOutput & {}
cliConsole?	LineLogger<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>

Property	Description
Protected _script: NarrationScript
Protected audioGenerationOptions: undefined | AudioGenerationOptions
Protected chapterRange: undefined | MultiRange
Protected cliConsole: LineLogger<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
Protected flags: Object & FlagOutput & {}
Protected scriptFilePath: string
Protected sectionRange: undefined | MultiRange
Protected ttsService: TtsService

• get script(): NarrationScript

NarrationScript

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

Name	Type
ssmlHash	string
_paragraph	NarrationParagraph

Promise<string>

---

▸ Protected hash(ssml, _paragraph): string

Name	Type
ssml	string
_paragraph	NarrationParagraph

string

---

▸ Protected initialiseTtsServiceIfNeeded(): Promise<void>

Promise<void>

---

▸ Protected loadScript(): Promise<void>

Promise<void>

---

▸ Protected parseRanges(): void

void

---

▸ Protected processGeneratedAudioFile(audioFilePath): Promise<string>

Name	Type
audioFilePath	string

Promise<string>

---

▸ run(reconstructedcommandLine?): Promise<void>

Name	Type
reconstructedcommandLine?	string

Promise<void>

---

▸ runWithoutCatch(reconstructedcommandLine?): Promise<void>

Name	Type
reconstructedcommandLine?	string

Promise<void>

tts-service.BaseTtsService

• BaseTtsService

  ↳ AzureTtsService

• TtsService

• new BaseTtsService()

▸ Protected buildSpeakStartTag(voiceSettings): string

Name	Type
voiceSettings	VoiceSettings

string

---

▸ Protected buildVoiceStartTag(voiceSettings): string

Name	Type
voiceSettings	VoiceSettings

string

---

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

Name	Type
_ssml	string
_options	AudioGenerationOptions

Promise<void>

TtsService.generateAudio

---

▸ generateSSML(paragraph): Promise<string>

Name	Type
paragraph	NarrationParagraph

Promise<string>

TtsService.generateSSML

---

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Name	Type
paragraph	NarrationParagraph

Object

Name	Type
lineOffset	number
ssml	string

---

▸ Protected validateXML(xml, lineOffset): void

Name	Type
xml	string
lineOffset	number

void

script-processor.TtsServiceType

• Azure = "azure"

azure-tts-service.AzureAudioGenerationOptions

• AudioGenerationOptions

  ↳ AzureAudioGenerationOptions

Property	Description
outputFilePath: string	Inherited from AudioGenerationOptions.outputFilePath
Optional serviceRegion: string
Optional subscriptionKey: string

narration-script.NarrationScriptFile.Chapter

• NarrationChapter

Property	Description
Optional key: string
sections: Section[]
Optional settings: VoiceSettings

narration-script.NarrationScriptFile.Paragraph

• NarrationParagraph

Property	Description
Optional key: string
Optional settings: VoiceSettings
text: string

narration-script.NarrationScriptFile.Script

• NarrationScript

Property	Description
chapters: Chapter[]
settings: ScriptSettings

narration-script.NarrationScriptFile.Section

• NarrationSection

Property	Description
Optional key: string
paragraphs: Paragraph[]
Optional settings: VoiceSettings

narration-script.ScriptSettings

Property	Description
Optional service: Azure
Optional voice: VoiceSettings

narration-script.VoiceSettings

Property	Description
Optional language: string
Optional name: string

tts-service.AudioGenerationOptions

• AudioGenerationOptions

  ↳ AzureAudioGenerationOptions

Property	Description
outputFilePath: string

tts-service.TtsService

• BaseTtsService

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

Name	Type
ssml	string
options	AudioGenerationOptions

Promise<void>

---

▸ generateSSML(paragraph): Promise<string>

Name	Type
paragraph	NarrationParagraph

Promise<string>

▸ getAudioFileDuration(filePath): Promise<number>

Name	Type
filePath	string

Promise<number>

---

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

Name	Type
filePath	string
infoLogger	(msg: string) => void

Promise<void>

• AzureTtsService

• AzureAudioGenerationOptions

• export=

narration-script.NarrationScriptFile

• Chapter
• Paragraph
• Script
• Section

• NarrationScriptFile

• NarrationChapter
• NarrationParagraph
• NarrationScript
• NarrationSection

• ScriptSettings
• VoiceSettings

▸ loadScript(scriptFilePath): Promise<NarrationScript>

Name	Type
scriptFilePath	string

Promise<NarrationScript>

---

▸ saveScript(script): Promise<void>

Name	Type
script	NarrationScript

Promise<void>

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

Name	Type
script	Script
scriptFilePath	string

Promise<void>

• TtsServiceType

• ScriptProcessor

• Const scriptProcessorFlags: Object

CLI flags that are required/used by the ScriptProcessor.

Name	Type
chapters	OptionFlag<undefined | string, CustomOptions>
debug	BooleanFlag<boolean>
dry-run	BooleanFlag<boolean>
interactive	BooleanFlag<boolean>
overwrite	BooleanFlag<boolean>
play	BooleanFlag<boolean>
quiet	BooleanFlag<boolean>
region	OptionFlag<undefined | string, CustomOptions>
sections	OptionFlag<undefined | string, CustomOptions>
service	OptionFlag<undefined | string, CustomOptions>
ssml	BooleanFlag<boolean>
subscription-key	OptionFlag<undefined | string, CustomOptions>
subscription-key-env	OptionFlag<undefined | string, CustomOptions>

• BaseTtsService

• AudioGenerationOptions
• TtsService

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 TtsService

---

Re-exports TtsServiceType

---

Re-exports VoiceSettings

---

Re-exports getAudioFileDuration

---

Re-exports loadScript

---

Re-exports playMp3File

---

Re-exports saveScript

---

Re-exports scriptProcessorFlags