tts-narrator
TypeScript icon, indicating that this package has built-in type declarations

2.3.2 • Public • Published

tts-narrator

Generate narration with Text-To-Speech technology

Version Downloads/week CI

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

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

API

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}`);

tts-narrator

Modules

Classes

Class: AzureTtsService

azure-tts-service.AzureTtsService

Hierarchy

Constructors

constructor

new AzureTtsService(options?)

Parameters
Name Type
options? Omit<AzureAudioGenerationOptions, "outputFilePath">
Overrides

BaseTtsService.constructor

Properties

Property Description
Protected Optional options: Omit<AzureAudioGenerationOptions, "outputFilePath">

Methods

buildMsttsExpressAsStartTag

Protected buildMsttsExpressAsStartTag(msttsExpressAsSettings): string

Parameters
Name Type
msttsExpressAsSettings Object
msttsExpressAsSettings.role? string
msttsExpressAsSettings.style? string
msttsExpressAsSettings.styleDegree? string
Returns

string

Inherited from

BaseTtsService.buildMsttsExpressAsStartTag


buildProsodyStartTag

Protected buildProsodyStartTag(prosodySettings): string

Parameters
Name Type
prosodySettings Object
prosodySettings.pitch? string
prosodySettings.rate? string
prosodySettings.volume? string
Returns

string

Inherited from

BaseTtsService.buildProsodyStartTag


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 | Pick<AzureAudioGenerationOptions, "outputFilePath">
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

Class: NarrationChapter

narration-script.NarrationChapter

Implements

Constructors

constructor

new NarrationChapter(chapter, index, script)

Parameters
Name Type
chapter Chapter
index number
script NarrationScript

Properties

Property Description
Protected chapter: Chapter
index: number
script: NarrationScript
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

Class: NarrationParagraph

narration-script.NarrationParagraph

Implements

Constructors

constructor

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

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

Properties

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

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

Class: NarrationScript

narration-script.NarrationScript

Implements

Constructors

constructor

new NarrationScript(script, scriptFilePath)

Parameters
Name Type
script Script
scriptFilePath string

Properties

Property Description
chapters: NarrationChapter[] Implementation of

Script.chapters
Protected script: Script
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

Class: NarrationSection

narration-script.NarrationSection

Implements

Constructors

constructor

new NarrationSection(section, index, chapter, script)

Parameters
Name Type
section Section
index number
chapter NarrationChapter
script NarrationScript

Properties

Property Description
chapter: NarrationChapter
index: number
paragraphs: NarrationParagraph[] Implementation of

Section.paragraphs
script: NarrationScript
Protected section: Section

Accessors

key

get key(): string

Returns

string

Implementation of

Section.key


settings

get settings(): VoiceSettings

Returns

VoiceSettings

Implementation of

Section.settings

Class: ScriptProcessor

script-processor.ScriptProcessor

Hierarchy

Constructors

constructor

new ScriptProcessor(scriptFilePath, flags, cliConsole?)

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

Properties

Property Description
Protected _chalk: undefined | null | Chalk & ChalkFunction & {}
Protected _prompts: undefined | null | typeof prompts
Protected _script: NarrationScript
Protected audioGenerationOptions: undefined | Omit<AudioGenerationOptions, "outputFilePath">
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

Accessors

chalk

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

chalk, or null caused by library not available

Returns

undefined | null | typeof prompts


prompts

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

prompts function, or null caused by library not available

Returns

undefined | null | typeof prompts


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>


loadScriptIfNeeded

Protected loadScriptIfNeeded(): 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>

Class: TtsNarrator

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}`);

Hierarchy

Constructors

constructor

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

Constructor

Parameters
Name Type Default value Description
ttsService TtsService undefined The TTS service to be used for generating audio
audioFileFolder string undefined The folder that generated audio files will be placed
options? Partial<Object & FlagOutput & {}> undefined Optional settings
cliConsole LineLogger<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void> silentLogger Optional logger
Overrides

ScriptProcessor.constructor

Properties

Property Description
Protected _chalk: undefined | null | Chalk & ChalkFunction & {} Inherited from

ScriptProcessor._chalk
Protected _prompts: undefined | null | typeof prompts Inherited from

ScriptProcessor._prompts
Protected _script: NarrationScript Inherited from

ScriptProcessor._script
Protected audioFileFolder: string The folder that generated audio files will be placed
Protected audioGenerationOptions: undefined | Omit<AudioGenerationOptions, "outputFilePath"> Inherited from

ScriptProcessor.audioGenerationOptions
Protected chapterRange: undefined | MultiRange Inherited from

ScriptProcessor.chapterRange
Protected cliConsole: LineLogger<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void> Inherited from

ScriptProcessor.cliConsole
Protected flags: Object & FlagOutput & {} Inherited from

ScriptProcessor.flags
Protected scriptFilePath: string Inherited from

ScriptProcessor.scriptFilePath
Protected sectionRange: undefined | MultiRange Inherited from

ScriptProcessor.sectionRange
Protected ttsService: TtsService Inherited from

ScriptProcessor.ttsService

Accessors

chalk

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

chalk, or null caused by library not available

Returns

undefined | null | typeof prompts

Inherited from

ScriptProcessor.chalk


prompts

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

prompts function, or null caused by library not available

Returns

undefined | null | typeof prompts

Inherited from

ScriptProcessor.prompts


script

get script(): NarrationScript

Returns

NarrationScript

Inherited from

ScriptProcessor.script

Methods

determineAudioFilePath

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

Parameters
Name Type
ssmlHash string
_paragraph NarrationParagraph
Returns

Promise<string>

Overrides

ScriptProcessor.determineAudioFilePath


hash

Protected hash(ssml, _paragraph): string

Parameters
Name Type
ssml string
_paragraph NarrationParagraph
Returns

string

Inherited from

ScriptProcessor.hash


initialiseTtsServiceIfNeeded

Protected initialiseTtsServiceIfNeeded(): Promise<void>

Returns

Promise<void>

Inherited from

ScriptProcessor.initialiseTtsServiceIfNeeded


loadScriptIfNeeded

Protected loadScriptIfNeeded(): Promise<void>

Returns

Promise<void>

Inherited from

ScriptProcessor.loadScriptIfNeeded


narrate

narrate(script): Promise<void>

Generate narration for the script

Parameters
Name Type Description
script NarrationScript the input script which will also be modified for recording audioFilePath
Returns

Promise<void>

nothing


parseRanges

Protected parseRanges(): void

Returns

void

Inherited from

ScriptProcessor.parseRanges


processGeneratedAudioFile

Protected processGeneratedAudioFile(audioFilePath): Promise<string>

Parameters
Name Type
audioFilePath string
Returns

Promise<string>

Inherited from

ScriptProcessor.processGeneratedAudioFile


run

run(reconstructedCommandLine?): Promise<void>

Parameters
Name Type
reconstructedCommandLine? string
Returns

Promise<void>

Inherited from

ScriptProcessor.run


runWithoutCatch

runWithoutCatch(reconstructedCommandLine?): Promise<void>

Parameters
Name Type
reconstructedCommandLine? string
Returns

Promise<void>

Inherited from

ScriptProcessor.runWithoutCatch

Class: export=

tts-narrator-cli.export=

Hierarchy

  • Command

    export=

Constructors

constructor

new export=(argv, config)

Parameters
Name Type
argv string[]
config Config
Inherited from

Command.constructor

Properties

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

Methods

run

run(): Promise<void>

Returns

Promise<void>

Overrides

Command.run

Class: BaseTtsService

tts-service.BaseTtsService

Hierarchy

Implements

Constructors

constructor

new BaseTtsService()

Methods

buildMsttsExpressAsStartTag

Protected buildMsttsExpressAsStartTag(msttsExpressAsSettings): string

Parameters
Name Type
msttsExpressAsSettings Object
msttsExpressAsSettings.role? string
msttsExpressAsSettings.style? string
msttsExpressAsSettings.styleDegree? string
Returns

string


buildProsodyStartTag

Protected buildProsodyStartTag(prosodySettings): string

Parameters
Name Type
prosodySettings Object
prosodySettings.pitch? string
prosodySettings.rate? string
prosodySettings.volume? string
Returns

string


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

Enums

Enumeration: TtsServiceType

tts-service.TtsServiceType

Enumeration Members

Azure

Azure = "azure"

Interfaces

Interface: AzureAudioGenerationOptions

azure-tts-service.AzureAudioGenerationOptions

Hierarchy

Properties

Property Description
outputFilePath: string Inherited from

AudioGenerationOptions.outputFilePath
Optional serviceRegion: string
Optional subscriptionKey: string

Interface: Chapter

narration-script.NarrationScriptFile.Chapter

Implemented by

Properties

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

Interface: Paragraph

narration-script.NarrationScriptFile.Paragraph

Implemented by

Properties

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

Interface: Script

narration-script.NarrationScriptFile.Script

Implemented by

Properties

Property Description
chapters: Chapter[]
settings: ScriptSettings

Interface: Section

narration-script.NarrationScriptFile.Section

Implemented by

Properties

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

Interface: ScriptSettings

narration-script.ScriptSettings

Properties

Property Description
Optional service: Azure
Optional voice: VoiceSettings

Interface: VoiceSettings

narration-script.VoiceSettings

Properties

Property Description
Optional effect: string Voice effect, corresponding to speak.voice#effect in SSML.
Optional language: string Language, corresponding to speak#xml:lang in SSML.
Optional msttsExpressAs: Object Corresponding to speak.voice.mstts:express-as in SSML.
Type declaration

Optional name: string Voice name, corresponding to speak.voice#name in SSML.
Optional prosody: Object Corresponding to speak.voice.prosody in SSML.
Type declaration

Interface: AudioGenerationOptions

tts-service.AudioGenerationOptions

Hierarchy

Properties

Property Description
outputFilePath: string

Interface: TtsService

tts-service.TtsService

Implemented by

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>

Modules

Module: audio-utils

Functions

getAudioFileDuration

getAudioFileDuration(filePath): Promise<number>

Parameters
Name Type
filePath string
Returns

Promise<number>


playMp3File

playMp3File(filePath, infoLogger): Promise<void>

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

Promise<void>

Module: azure-tts-service

Classes

Interfaces

Module: index

References

AudioGenerationOptions

Re-exports AudioGenerationOptions


AzureAudioGenerationOptions

Re-exports AzureAudioGenerationOptions


AzureTtsService

Re-exports AzureTtsService


BaseTtsService

Re-exports BaseTtsService


NarrationChapter

Re-exports NarrationChapter


NarrationParagraph

Re-exports NarrationParagraph


NarrationScript

Re-exports NarrationScript


NarrationScriptFile

Re-exports NarrationScriptFile


NarrationSection

Re-exports NarrationSection


ScriptProcessor

Re-exports ScriptProcessor


ScriptSettings

Re-exports ScriptSettings


TtsNarrator

Re-exports TtsNarrator


TtsService

Re-exports TtsService


TtsServiceType

Re-exports TtsServiceType


VoiceSettings

Re-exports VoiceSettings


getAudioFileDuration

Re-exports getAudioFileDuration


loadScript

Re-exports loadScript


playMp3File

Re-exports playMp3File


saveScript

Re-exports saveScript

Namespace: NarrationScriptFile

narration-script.NarrationScriptFile

Interfaces

Module: narration-script

Namespaces

Classes

Interfaces

Functions

loadScript

loadScript(scriptFilePath): Promise<NarrationScript>

Parameters
Name Type
scriptFilePath string
Returns

Promise<NarrationScript>


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>

Module: script-processor

Classes

Module: script-processor-flags

Type Aliases

ScriptProcessorFlags

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

Variables

scriptProcessorFlags

Const scriptProcessorFlags: Object

CLI flags that are required/used by the ScriptProcessor.

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

Module: tts-narrator

Classes

Module: tts-narrator-cli

Classes

Module: tts-service

Enumerations

Classes

Interfaces

Package Sidebar

Install

npm i tts-narrator

Weekly Downloads

81

Version

2.3.2

License

Apache-2.0

Unpacked Size

112 kB

Total Files

32

Last publish

Collaborators

  • james-hu