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
-
- 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
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
tts-narrator
Table of contents
Namespaces
Enumerations
Classes
- AzureTtsService
- BaseTtsService
- NarrationChapter
- NarrationParagraph
- NarrationScript
- NarrationSection
- ScriptProcessor
Interfaces
Variables
Functions
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
-
↳
AzureTtsService
Table of contents
Constructors
Methods
- buildSpeakStartTag
- buildVoiceStartTag
- generateAudio
- generateSSML
- generateSsmlWithoutValidation
- validateXML
Constructors
constructor
• new AzureTtsService()
Inherited from
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
generateSSML
▸ generateSSML(paragraph
): Promise
<string
>
Parameters
Name | Type |
---|---|
paragraph |
NarrationParagraph |
Returns
Promise
<string
>
Inherited from
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
tts-narrator / BaseTtsService
Class: BaseTtsService
Hierarchy
-
BaseTtsService
Implements
Table of contents
Constructors
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
generateSSML
▸ generateSSML(paragraph
): Promise
<string
>
Parameters
Name | Type |
---|---|
paragraph |
NarrationParagraph |
Returns
Promise
<string
>
Implementation of
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
Table of contents
Constructors
Properties
Accessors
Methods
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
Accessors
key
• get
key(): string
Returns
string
Implementation of
settings
• get
settings(): VoiceSettings
Returns
Implementation of
Methods
getSectionByKey
▸ getSectionByKey(key
): undefined
| NarrationSection
Parameters
Name | Type |
---|---|
key |
string |
Returns
undefined
| NarrationSection
tts-narrator / NarrationParagraph
Class: NarrationParagraph
Implements
Table of contents
Constructors
Properties
Accessors
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
settings
• get
settings(): VoiceSettings
Returns
Implementation of
text
• get
text(): string
Returns
string
Implementation of
tts-narrator / NarrationScript
Class: NarrationScript
Implements
Table of contents
Constructors
Properties
Accessors
Methods
Constructors
constructor
• new NarrationScript(script
, scriptFilePath
)
Parameters
Name | Type |
---|---|
script |
Script |
scriptFilePath |
string |
Properties
chapters
• chapters: NarrationChapter
[]
Implementation of
script
• Protected
script: Script
scriptFilePath
• scriptFilePath: string
Accessors
settings
• get
settings(): ScriptSettings
Returns
Implementation of
Methods
export
▸ export(): Script
Returns
getChapterByKey
▸ getChapterByKey(key
): undefined
| NarrationChapter
Parameters
Name | Type |
---|---|
key |
string |
Returns
undefined
| NarrationChapter
tts-narrator / NarrationSection
Class: NarrationSection
Implements
Table of contents
Constructors
Properties
Accessors
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
script
• script: NarrationScript
section
• Protected
section: Section
Accessors
key
• get
key(): string
Returns
string
Implementation of
settings
• get
settings(): VoiceSettings
Returns
Implementation of
tts-narrator / ScriptProcessor
Class: ScriptProcessor
Table of contents
Constructors
Properties
Accessors
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
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
Table of contents
Enumeration members
Enumeration members
Azure
• Azure = "azure"
Interfaces
tts-narrator / AudioGenerationOptions
Interface: AudioGenerationOptions
Hierarchy
-
AudioGenerationOptions
Table of contents
Properties
Properties
outputFilePath
• outputFilePath: string
tts-narrator / AzureAudioGenerationOptions
Interface: AzureAudioGenerationOptions
Hierarchy
-
↳
AzureAudioGenerationOptions
Table of contents
Properties
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
Table of contents
Properties
Properties
key
• Optional
key: string
sections
• sections: Section
[]
settings
• Optional
settings: VoiceSettings
tts-narrator / NarrationScriptFile / Paragraph
Interface: Paragraph
NarrationScriptFile.Paragraph
Implemented by
Table of contents
Properties
Properties
key
• Optional
key: string
settings
• Optional
settings: VoiceSettings
text
• text: string
tts-narrator / NarrationScriptFile / Script
Interface: Script
NarrationScriptFile.Script
Implemented by
Table of contents
Properties
Properties
chapters
• chapters: Chapter
[]
settings
• settings: ScriptSettings
tts-narrator / NarrationScriptFile / Section
Interface: Section
NarrationScriptFile.Section
Implemented by
Table of contents
Properties
Properties
key
• Optional
key: string
paragraphs
• paragraphs: Paragraph
[]
settings
• Optional
settings: VoiceSettings
tts-narrator / ScriptSettings
Interface: ScriptSettings
Table of contents
Properties
Properties
service
• Optional
service: Azure
voice
• Optional
voice: VoiceSettings
tts-narrator / TtsService
Interface: TtsService
Implemented by
Table of contents
Methods
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
Table of contents
Properties
Properties
language
• Optional
language: string
name
• Optional
name: string
Modules
tts-narrator / NarrationScriptFile