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
-
- each paragraph can contain settings and text:
-
- each section can contain settings and multiple paragraphs:
-
- each chapter can contain settings and multiple sections:
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
azure-tts-service.AzureTtsService
-
↳
AzureTtsService
• new AzureTtsService()
▸ 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
>
▸ generateSSML(paragraph
): Promise
<string
>
Name | Type |
---|---|
paragraph |
NarrationParagraph |
Promise
<string
>
▸ 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
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
• 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
• get
settings(): VoiceSettings
▸ getSectionByKey(key
): undefined
| NarrationSection
Name | Type |
---|---|
key |
string |
undefined
| NarrationSection
narration-script.NarrationParagraph
• 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
• get
settings(): VoiceSettings
• get
text(): string
string
narration-script.NarrationScript
• 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
▸ export(): Script
▸ getChapterByKey(key
): undefined
| NarrationChapter
Name | Type |
---|---|
key |
string |
undefined
| NarrationChapter
narration-script.NarrationSection
• 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
• get
settings(): VoiceSettings
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
▸ 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
• 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
>
▸ generateSSML(paragraph
): Promise
<string
>
Name | Type |
---|---|
paragraph |
NarrationParagraph |
Promise
<string
>
▸ 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
-
↳
AzureAudioGenerationOptions
Property | Description |
---|---|
outputFilePath: string
|
Inherited from AudioGenerationOptions.outputFilePath |
Optional serviceRegion: string
|
|
Optional subscriptionKey: string
|
narration-script.NarrationScriptFile.Chapter
Property | Description |
---|---|
Optional key: string
|
|
sections: Section [] |
|
Optional settings: VoiceSettings
|
narration-script.NarrationScriptFile.Paragraph
Property | Description |
---|---|
Optional key: string
|
|
Optional settings: VoiceSettings
|
|
text: string
|
narration-script.NarrationScriptFile.Script
Property | Description |
---|---|
chapters: Chapter [] |
|
settings: ScriptSettings
|
narration-script.NarrationScriptFile.Section
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
Property | Description |
---|---|
outputFilePath: string
|
tts-service.TtsService
▸ 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
>
narration-script.NarrationScriptFile
▸ 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
>
• 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 > |
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