tts-narrator

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

CLI

USAGE
  $ tts-narrator [FILE]

ARGUMENTS
  FILE  path to the script file (.yml)

OPTIONS
  -d, --debug                                  output debug information
  -h, --help                                   show CLI help

  -i, --interactive                            wait for key press before
                                               entering each section

  -k, --subscription-key=subscription-key      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=region                          region of the text-to-speech
                                               service

  -s, --service=azure                          text-to-speech service to use

  -v, --version                                show CLI version

  --chapters=chapters                          list of chapters to process,
                                               examples: "1-10,13,15", "4-"

  --dry-run                                    don't try to generate or play
                                               audio

  --sections=sections                          list of sections to process,
                                               examples: "1-10,13,15", "5-"

  --ssml                                       display generated SSML

  --subscription-key-env=subscription-key-env  Name of the environment variable
                                               that holds the subscription key

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

API

tts-narrator

Variables

scriptProcessorFlags

• Const scriptProcessorFlags: Object

CLI flags that are required/used by the ScriptProcessor.

Type declaration

Name	Type
`chapters`	`IOptionFlag`<`undefined` \| `string`>
`debug`	`IBooleanFlag`<`boolean`>
`dry-run`	`IBooleanFlag`<`boolean`>
`interactive`	`IBooleanFlag`<`boolean`>
`overwrite`	`IBooleanFlag`<`boolean`>
`play`	`IBooleanFlag`<`boolean`>
`quiet`	`IBooleanFlag`<`boolean`>
`region`	`IOptionFlag`<`undefined` \| `string`>
`sections`	`IOptionFlag`<`undefined` \| `string`>
`service`	`IOptionFlag`<`undefined` \| `string`>
`ssml`	`IBooleanFlag`<`boolean`>
`subscription-key`	`IOptionFlag`<`undefined` \| `string`>
`subscription-key-env`	`IOptionFlag`<`undefined` \| `string`>

Functions

getAudioFileDuration

▸ getAudioFileDuration(filePath): Promise<number>

Parameters

Name	Type
`filePath`	`string`

Returns

Promise<number>

loadScript

▸ loadScript(scriptFilePath): Promise<NarrationScript>

Parameters

Name	Type
`scriptFilePath`	`string`

Returns

Promise<NarrationScript>

playMp3File

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

Parameters

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

Returns

Promise<void>

saveScript

▸ saveScript(script): Promise<void>

Parameters

Name	Type
`script`	`NarrationScript`

Returns

Promise<void>

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

Parameters

Name	Type
`script`	`Script`
`scriptFilePath`	`string`

Returns

Promise<void>

Classes

tts-narrator / AzureTtsService

Class: AzureTtsService

Hierarchy

BaseTtsService

↳ AzureTtsService

Constructors

constructor

Constructors

constructor

• new AzureTtsService()

Inherited from

BaseTtsService.constructor

Methods

buildSpeakStartTag

▸ Protected buildSpeakStartTag(voiceSettings): string

Parameters

Name	Type
`voiceSettings`	`VoiceSettings`

Returns

string

Overrides

BaseTtsService.buildSpeakStartTag

buildVoiceStartTag

▸ Protected buildVoiceStartTag(voiceSettings): string

Parameters

Name	Type
`voiceSettings`	`VoiceSettings`

Returns

string

Inherited from

BaseTtsService.buildVoiceStartTag

generateAudio

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

Parameters

Name	Type
`ssml`	`string`
`options`	`AzureAudioGenerationOptions`

Returns

Promise<any>

Overrides

BaseTtsService.generateAudio

generateSSML

▸ generateSSML(paragraph): Promise<string>

Parameters

Name	Type
`paragraph`	`NarrationParagraph`

Returns

Promise<string>

Inherited from

BaseTtsService.generateSSML

generateSsmlWithoutValidation

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Parameters

Name	Type
`paragraph`	`NarrationParagraph`

Returns

Object

Name	Type
`lineOffset`	`number`
`ssml`	`string`

Inherited from

BaseTtsService.generateSsmlWithoutValidation

validateXML

▸ Protected validateXML(xml, lineOffset): void

Parameters

Name	Type
`xml`	`string`
`lineOffset`	`number`

Returns

void

Inherited from

BaseTtsService.validateXML

tts-narrator / BaseTtsService

Class: BaseTtsService

Hierarchy

BaseTtsService

↳ AzureTtsService

Implements

TtsService

Constructors

constructor

Methods

buildSpeakStartTag
buildVoiceStartTag
generateAudio
generateSSML
generateSsmlWithoutValidation
validateXML

Constructors

constructor

• new BaseTtsService()

Methods

buildSpeakStartTag

▸ Protected buildSpeakStartTag(voiceSettings): string

Parameters

Name	Type
`voiceSettings`	`VoiceSettings`

Returns

string

buildVoiceStartTag

▸ Protected buildVoiceStartTag(voiceSettings): string

Parameters

Name	Type
`voiceSettings`	`VoiceSettings`

Returns

string

generateAudio

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

Parameters

Name	Type
`_ssml`	`string`
`_options`	`AudioGenerationOptions`

Returns

Promise<void>

Implementation of

TtsService.generateAudio

generateSSML

▸ generateSSML(paragraph): Promise<string>

Parameters

Name	Type
`paragraph`	`NarrationParagraph`

Returns

Promise<string>

Implementation of

TtsService.generateSSML

generateSsmlWithoutValidation

▸ Protected generateSsmlWithoutValidation(paragraph): Object

Parameters

Name	Type
`paragraph`	`NarrationParagraph`

Returns

Object

Name	Type
`lineOffset`	`number`
`ssml`	`string`

validateXML

▸ Protected validateXML(xml, lineOffset): void

Parameters

Name	Type
`xml`	`string`
`lineOffset`	`number`

Returns

void

tts-narrator / NarrationChapter

Class: NarrationChapter

Implements

Chapter

Constructors

constructor

Properties

chapter
index
script
sections

Accessors

key
settings

Methods

getSectionByKey

Constructors

constructor

• new NarrationChapter(chapter, index, script)

Parameters

Name	Type
`chapter`	`Chapter`
`index`	`number`
`script`	`NarrationScript`

Properties

chapter

• Protected chapter: Chapter

index

• index: number

script

• script: NarrationScript

sections

• sections: NarrationSection[]

Implementation of

Chapter.sections

Accessors

key

• get key(): string

Returns

string

Implementation of

Chapter.key

settings

• get settings(): VoiceSettings

Returns

VoiceSettings

Implementation of

Chapter.settings

Methods

getSectionByKey

▸ getSectionByKey(key): undefined | NarrationSection

Parameters

Name	Type
`key`	`string`

Returns

undefined | NarrationSection

tts-narrator / NarrationParagraph

Class: NarrationParagraph

Implements

Paragraph

Constructors

constructor

Properties

audioFilePath
chapter
index
paragraph
script
section

Accessors

key
settings
text

Constructors

constructor

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

Parameters

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

Properties

audioFilePath

• Optional audioFilePath: string

Path of the generated audio file. Only for in-memory processing, not supposed to be stored in file.

chapter

• chapter: NarrationChapter

index

• index: number

paragraph

• Protected paragraph: Paragraph

script

• script: NarrationScript

section

• section: NarrationSection

Accessors

key

• get key(): string

Returns

string

Implementation of

Paragraph.key

settings

• get settings(): VoiceSettings

Returns

VoiceSettings

Implementation of

Paragraph.settings

text

• get text(): string

Returns

string

Implementation of

Paragraph.text

tts-narrator / NarrationScript

Class: NarrationScript

Implements

Script

Constructors

constructor

Properties

chapters
script
scriptFilePath

Accessors

settings

Methods

export
getChapterByKey

Constructors

constructor

• new NarrationScript(script, scriptFilePath)

Parameters

Name	Type
`script`	`Script`
`scriptFilePath`	`string`

Properties

chapters

• chapters: NarrationChapter[]

Implementation of

Script.chapters

script

• Protected script: Script

scriptFilePath

• scriptFilePath: string

Accessors

settings

• get settings(): ScriptSettings

Returns

ScriptSettings

Implementation of

Script.settings

Methods

export

▸ export(): Script

Returns

Script

getChapterByKey

▸ getChapterByKey(key): undefined | NarrationChapter

Parameters

Name	Type
`key`	`string`

Returns

undefined | NarrationChapter

tts-narrator / NarrationSection

Class: NarrationSection

Implements

Section

Constructors

constructor

Properties

chapter
index
paragraphs
script
section

Accessors

key
settings

Constructors

constructor

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

Parameters

Name	Type
`section`	`Section`
`index`	`number`
`chapter`	`NarrationChapter`
`script`	`NarrationScript`

Properties

chapter

• chapter: NarrationChapter

index

• index: number

paragraphs

• paragraphs: NarrationParagraph[]

Implementation of

Section.paragraphs

script

• script: NarrationScript

section

• Protected section: Section

Accessors

key

• get key(): string

Returns

string

Implementation of

Section.key

settings

• get settings(): VoiceSettings

Returns

VoiceSettings

Implementation of

Section.settings

tts-narrator / ScriptProcessor

Class: ScriptProcessor

Constructors

constructor

Properties

_script
audioGenerationOptions
chapterRange
cliConsole
flags
scriptFilePath
sectionRange
ttsService

Accessors

script

Methods

determineAudioFilePath
hash
initialiseTtsServiceIfNeeded
loadScript
parseRanges
processGeneratedAudioFile
run
runWithoutCatch

Constructors

constructor

• new ScriptProcessor(scriptFilePath, flags, cliConsole?)

Parameters

Name	Type
`scriptFilePath`	`string`
`flags`	`Object`
`cliConsole?`	`CliConsole`<`fn`, `fn`, `fn`, `fn`>

Properties

_script

• Protected _script: NarrationScript

audioGenerationOptions

• Protected audioGenerationOptions: undefined | AudioGenerationOptions

chapterRange

• Protected chapterRange: undefined | MultiRange

cliConsole

• Protected cliConsole: CliConsole<fn, fn, fn, fn>

flags

• Protected flags: Object

scriptFilePath

• Protected scriptFilePath: string

sectionRange

• Protected sectionRange: undefined | MultiRange

ttsService

• Protected ttsService: TtsService

Accessors

script

• get script(): NarrationScript

Returns

NarrationScript

Methods

determineAudioFilePath

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

Parameters

Name	Type
`ssmlHash`	`string`
`_paragraph`	`NarrationParagraph`

Returns

Promise<string>

hash

▸ Protected hash(ssml, _paragraph): string

Parameters

Name	Type
`ssml`	`string`
`_paragraph`	`NarrationParagraph`

Returns

string

initialiseTtsServiceIfNeeded

▸ Protected initialiseTtsServiceIfNeeded(): Promise<void>

Returns

Promise<void>

loadScript

▸ Protected loadScript(): Promise<void>

Returns

Promise<void>

parseRanges

▸ Protected parseRanges(): void

Returns

void

processGeneratedAudioFile

▸ Protected processGeneratedAudioFile(audioFilePath): Promise<string>

Parameters

Name	Type
`audioFilePath`	`string`

Returns

Promise<string>

run

▸ run(reconstructedcommandLine?): Promise<void>

Parameters

Name	Type
`reconstructedcommandLine?`	`string`

Returns

Promise<void>

runWithoutCatch

▸ runWithoutCatch(reconstructedcommandLine?): Promise<void>

Parameters

Name	Type
`reconstructedcommandLine?`	`string`

Returns

Promise<void>

Enums

tts-narrator / TtsServiceType

Enumeration: TtsServiceType

Enumeration members

Azure

Enumeration members

Azure

• Azure = "azure"

Interfaces

tts-narrator / AudioGenerationOptions

Interface: AudioGenerationOptions

Hierarchy

AudioGenerationOptions

↳ AzureAudioGenerationOptions

Properties

outputFilePath

Properties

outputFilePath

• outputFilePath: string

tts-narrator / AzureAudioGenerationOptions

Interface: AzureAudioGenerationOptions

Hierarchy

AudioGenerationOptions

↳ AzureAudioGenerationOptions

Properties

outputFilePath
serviceRegion
subscriptionKey

Properties

outputFilePath

• outputFilePath: string

Inherited from

AudioGenerationOptions.outputFilePath

serviceRegion

• Optional serviceRegion: string

subscriptionKey

• Optional subscriptionKey: string

tts-narrator / NarrationScriptFile / Chapter

Interface: Chapter

NarrationScriptFile.Chapter

Implemented by

NarrationChapter

Properties

key
sections
settings

Properties

key

• Optional key: string

sections

• sections: Section[]

settings

• Optional settings: VoiceSettings

tts-narrator / NarrationScriptFile / Paragraph

Interface: Paragraph

NarrationScriptFile.Paragraph

Implemented by

NarrationParagraph

Properties

key
settings
text

Properties

key

• Optional key: string

settings

• Optional settings: VoiceSettings

text

• text: string

tts-narrator / NarrationScriptFile / Script

Interface: Script

NarrationScriptFile.Script

Implemented by

NarrationScript

Properties

chapters
settings

Properties

chapters

• chapters: Chapter[]

settings

• settings: ScriptSettings

tts-narrator / NarrationScriptFile / Section

Interface: Section

NarrationScriptFile.Section

Implemented by

NarrationSection

Properties

key
paragraphs
settings

Properties

key

• Optional key: string

paragraphs

• paragraphs: Paragraph[]

settings

• Optional settings: VoiceSettings

tts-narrator / ScriptSettings

Interface: ScriptSettings

Properties

service
voice

Properties

service

• Optional service: Azure

voice

• Optional voice: VoiceSettings

tts-narrator / TtsService

Interface: TtsService

Implemented by

BaseTtsService

Methods

generateAudio
generateSSML

Methods

generateAudio

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

Parameters

Name	Type
`ssml`	`string`
`options`	`AudioGenerationOptions`

Returns

Promise<void>

generateSSML

▸ generateSSML(paragraph): Promise<string>

Parameters

Name	Type
`paragraph`	`NarrationParagraph`

Returns

Promise<string>

tts-narrator / VoiceSettings

Interface: VoiceSettings

Properties

language
name

Properties

language

• Optional language: string

name

• Optional name: string

Modules

tts-narrator / NarrationScriptFile

Namespace: NarrationScriptFile

Interfaces

Chapter
Paragraph
Script
Section

tts-narrator

tts-narrator

CLI

API

tts-narrator

Table of contents

Namespaces

Enumerations

Classes

Interfaces

Variables

Functions

Variables

scriptProcessorFlags

Type declaration

Functions

getAudioFileDuration

Parameters

Returns

loadScript

Parameters

Returns

playMp3File

Parameters

Returns

saveScript

Parameters

Returns

Parameters

Returns

Classes

Class: AzureTtsService

Hierarchy

Table of contents

Constructors

Methods

Constructors

constructor

Inherited from

Methods

buildSpeakStartTag

Parameters

Returns

Overrides

buildVoiceStartTag

Parameters

Returns

Inherited from

generateAudio

Parameters

Returns

Overrides

generateSSML

Parameters

Returns

Inherited from

generateSsmlWithoutValidation

Parameters

Returns

Inherited from

validateXML

Parameters

Returns

Inherited from

Class: BaseTtsService

Hierarchy

Implements

Table of contents

Constructors

Methods

Constructors

constructor

Methods

buildSpeakStartTag

Parameters

Returns

buildVoiceStartTag

Parameters

Returns

generateAudio