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 settingssections
: array of sections
- each section can contain settings and multiple paragraphs:
settings
: section level voice settings that can override upper level voice settingsparagraphs
: array of paragraphs
- each paragraph can contain settings and text:
settings
: paragraph level voice settings that can override upper level voice settingstext
: 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
Overrides
BaseTtsService.constructor
Properties
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
Returns
string
Overrides
BaseTtsService.buildSpeakStartTag
buildVoiceStartTag
▸ Protected
buildVoiceStartTag(voiceSettings
): string
Parameters
Returns
string
Inherited from
BaseTtsService.buildVoiceStartTag
generateAudio
▸ generateAudio(ssml
, options
): Promise
<any
>
Parameters
Returns
Promise
<any
>
Overrides
BaseTtsService.generateAudio
generateSSML
▸ generateSSML(paragraph
): Promise
<string
>
Parameters
Returns
Promise
<string
>
Inherited from
BaseTtsService.generateSSML
generateSsmlWithoutValidation
▸ Protected
generateSsmlWithoutValidation(paragraph
): Object
Parameters
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
Properties
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
Returns
undefined
| NarrationSection
Class: NarrationParagraph
narration-script.NarrationParagraph
Implements
Constructors
constructor
• new NarrationParagraph(paragraph
, index
, section
, chapter
, script
)
Parameters
Properties
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
Accessors
settings
• get
settings(): ScriptSettings
Returns
ScriptSettings
Implementation of
Script.settings
Methods
export
▸ export(): Script
Returns
Script
getChapterByKey
▸ getChapterByKey(key
): undefined
| NarrationChapter
Parameters
Returns
undefined
| NarrationChapter
Class: NarrationSection
narration-script.NarrationSection
Implements
Constructors
constructor
• new NarrationSection(section
, index
, chapter
, script
)
Parameters
Properties
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
Returns
Promise
<string
>
hash
▸ Protected
hash(ssml
, _paragraph
): string
Parameters
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
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
Returns
Promise
<string
>
Overrides
ScriptProcessor.determineAudioFilePath
hash
▸ Protected
hash(ssml
, _paragraph
): string
Parameters
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
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
Returns
string
buildVoiceStartTag
▸ Protected
buildVoiceStartTag(voiceSettings
): string
Parameters
Returns
string
generateAudio
▸ generateAudio(_ssml
, _options
): Promise
<void
>
Parameters
Returns
Promise
<void
>
Implementation of
TtsService.generateAudio
generateSSML
▸ generateSSML(paragraph
): Promise
<string
>
Parameters
Returns
Promise
<string
>
Implementation of
TtsService.generateSSML
generateSsmlWithoutValidation
▸ Protected
generateSsmlWithoutValidation(paragraph
): Object
Parameters
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
Interface: Chapter
narration-script.NarrationScriptFile.Chapter
Implemented by
Properties
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
Interface: Section
narration-script.NarrationScriptFile.Section
Implemented by
Properties
Interface: ScriptSettings
narration-script.ScriptSettings
Properties
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
Returns
Promise
<void
>
generateSSML
▸ generateSSML(paragraph
): Promise
<string
>
Parameters
Returns
Promise
<string
>
Modules
Module: audio-utils
Functions
getAudioFileDuration
▸ getAudioFileDuration(filePath
): Promise
<number
>
Parameters
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
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