Generate narration with Text-To-Speech technology. 

Generate narration with Text-To-Speech technology

james-hu

tts-narrator

import { DefaultCliConsole, Flags } from '@handy-common-utils/oclif-utils';

import { MultiRange } from 'multi-integer-range';

import { NarrationParagraph, NarrationScript } from './narration-script';

import { AudioGenerationOptions, TtsService } from './tts-service';

 * CLI flags that are required/used by the ScriptProcessor.

export declare const scriptProcessorFlags: {

    debug: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    quiet: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    service: flags.IOptionFlag<string | undefined>;

    'subscription-key': flags.IOptionFlag<string | undefined>;

    'subscription-key-env': flags.IOptionFlag<string | undefined>;

    region: flags.IOptionFlag<string | undefined>;

    play: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    interactive: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    overwrite: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    'dry-run': import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    ssml: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;

    chapters: flags.IOptionFlag<string | undefined>;

    sections: flags.IOptionFlag<string | undefined>;

    protected flags: Flags<typeof scriptProcessorFlags>;

    protected cliConsole: DefaultCliConsole;

    protected audioGenerationOptions: AudioGenerationOptions | undefined;

    protected chapterRange: MultiRange | undefined;

    protected sectionRange: MultiRange | undefined;

    constructor(scriptFilePath: string, flags: Flags<typeof scriptProcessorFlags>);

    constructor(scriptFilePath: string, flags: Flags<typeof scriptProcessorFlags>, cliConsole?: DefaultCliConsole);

    protected hash(ssml: string, _paragraph: NarrationParagraph): string;

    protected loadScript(): Promise<void>;

    protected initialiseTtsServiceIfNeeded(): Promise<void>;

    protected determineAudioFilePath(ssmlHash: string, _paragraph: NarrationParagraph): Promise<string>;

    protected processGeneratedAudioFile(audioFilePath: string): Promise<string>;

    run(reconstructedcommandLine?: string): Promise<void>;

    runWithoutCatch(reconstructedcommandLine?: string): Promise<void>;

//# sourceMappingURL=script-processor.d.ts.map

Object.defineProperty(exports, "__esModule", { value: true });

exports.ScriptProcessor = exports.scriptProcessorFlags = exports.TtsServiceType = void 0;

/* eslint-disable @typescript-eslint/explicit-module-boundary-types */

const fs = (0, tslib_1.__importStar)(require("fs"));

const path_1 = (0, tslib_1.__importDefault)(require("path"));

const murmurhash = (0, tslib_1.__importStar)(require("murmurhash"));

const prompts_1 = (0, tslib_1.__importDefault)(require("prompts"));

const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));

const command_1 = require("@oclif/command");

const oclif_utils_1 = require("@handy-common-utils/oclif-utils");

const multi_integer_range_1 = require("multi-integer-range");

const azure_tts_service_1 = require("./azure-tts-service");

const narration_script_1 = require("./narration-script");

const audio_utils_1 = require("./audio-utils");

})(TtsServiceType = exports.TtsServiceType || (exports.TtsServiceType = {}));

    debug: command_1.flags.boolean({ char: 'd', description: 'output debug information' }),

    quiet: command_1.flags.boolean({ char: 'q', description: 'output warn and error information only' }),

    service: command_1.flags.string({ char: 's', options: Object.entries(TtsServiceType).map(([_name, value]) => value), description: 'text-to-speech service to use' }),

    'subscription-key': command_1.flags.string({ char: 'k', description: 'Azure Speech service subscription key' }),

    'subscription-key-env': command_1.flags.string({ description: 'Name of the environment variable that holds the subscription key' }),

    region: command_1.flags.string({ char: 'r', description: 'region of the text-to-speech service' }),

    play: command_1.flags.boolean({ char: 'p', default: true, allowNo: true, description: 'play generated audio' }),

    interactive: command_1.flags.boolean({ char: 'i', default: false, description: 'wait for key press before entering each section' }),

    overwrite: command_1.flags.boolean({ char: 'o', default: false, description: 'always overwrite previously generated audio files' }),

    'dry-run': command_1.flags.boolean({ default: false, description: 'don\'t try to generate or play audio' }),

    ssml: command_1.flags.boolean({ default: false, exclusive: ['quiet'], description: 'display generated SSML' }),

    chapters: command_1.flags.string({ description: 'list of chapters to process, examples: "1-10,13,15", "4-"' }),

    sections: command_1.flags.string({ description: 'list of sections to process, examples: "1-10,13,15", "5-"' }),

    constructor(scriptFilePath, flags, cliConsole) {

        this.scriptFilePath = scriptFilePath;

        this.cliConsole = (0, oclif_utils_1.cliConsoleWithColour)(this.flags, chalk_1.default);

        this.cliConsole = cliConsole !== null && cliConsole !== void 0 ? cliConsole : (0, oclif_utils_1.cliConsoleWithColour)(this.flags, chalk_1.default);

        const hashNumber = murmurhash.v3(ssml, 2894);

        this._script = await (0, narration_script_1.loadScript)(this.scriptFilePath);

        this.cliConsole.debug(`Loaded script from ${this.scriptFilePath}`);

        const chapterRangeFlag = this.flags.chapters;

                this.chapterRange = new multi_integer_range_1.MultiRange(chapterRangeFlag);

                throw new Error(`Invalid chapter range '${chapterRangeFlag}': ${error}`);

        const sectionRangeFlag = this.flags.sections;

                this.sectionRange = new multi_integer_range_1.MultiRange(sectionRangeFlag);

                throw new Error(`Invalid section range '${sectionRangeFlag}': ${error}`);

    async initialiseTtsServiceIfNeeded() {

            const ttsServiceType = (_a = this.flags.service) !== null && _a !== void 0 ? _a : this._script.settings.service;

                case TtsServiceType.Azure:

                    this.ttsService = new azure_tts_service_1.AzureTtsService();

                    this.audioGenerationOptions = {

                        subscriptionKey: (_b = this.flags['subscription-key']) !== null && _b !== void 0 ? _b : (this.flags['subscription-key-env'] ? process.env[this.flags['subscription-key-env']] : undefined),

                        serviceRegion: this.flags.region,

                    throw new Error(`Unknown TTS service: ${ttsServiceType}`);

    async determineAudioFilePath(ssmlHash, _paragraph) {

        const audioFileFolder = this._script.scriptFilePath.split('.').slice(0, -1).join('.') + '.tts';

        if (!fs.existsSync(audioFileFolder)) {

            fs.mkdirSync(audioFileFolder, { recursive: true });

        const audioFilePath = path_1.default.join(audioFileFolder, `${ssmlHash}.mp3`);

    async processGeneratedAudioFile(audioFilePath) {

    async run(reconstructedcommandLine) {

            await this.runWithoutCatch(reconstructedcommandLine);

            this.cliConsole.error(error.message);

            this.cliConsole.debug(error);

    async runWithoutCatch(reconstructedcommandLine) {

            this.cliConsole.debug(`Executing command line: ${reconstructedcommandLine}`);

        for (const chapter of this._script.chapters) {

            const chapterIndex = chapter.index;

            if (!this.chapterRange || this.chapterRange.has(chapterIndex)) {

                this.cliConsole.debug(`Entering chapter [${chapterIndex}] ${chapter.key}`);

                for (const section of chapter.sections) {

                    const sectionIndex = section.index;

                    if (!this.sectionRange || this.sectionRange.has(sectionIndex)) {

                        this.cliConsole.debug(`Entering section [${chapterIndex}-${sectionIndex}] ${section.key}`);

                        for (const paragraph of section.paragraphs) {

                            const paragraphIndex = paragraph.index;

                            // wait for user key press if needed

                            if (paragraphIndex === 1 && this.flags.interactive) {

                                const response = await (0, prompts_1.default)({

                                    initial: true,

                                    message: `Press ENTER to continue or CTRL-C to abort => [${chapterIndex}-${sectionIndex}] ${section.key}`,

                                    name: 'r',

                                    type: 'confirm',

                                if (response.r === undefined) { // CTRL-C

                                    return;

                            this.cliConsole.debug(`Entering paragraph [${chapterIndex}-${sectionIndex}-${paragraphIndex}] ${paragraph.key}`);

                            this.cliConsole.debug(`Processing: ${paragraph.text}`);

                            // generate SSML and its hash

                            await this.initialiseTtsServiceIfNeeded(); // initialise in first use

                            const ssml = await this.ttsService.generateSSML(paragraph);

  "description": "Generate narration with Text-To-Speech technology",

    "prepare": "shx rm -rf dist api-docs && tsc && es-check",

    "preversion": "generate-api-docs-and-update-readme && ./bin/run --update-readme.md && git add README.md"

    "@handy-common-utils/dev-dependencies": "^1.0.20",

    "typedoc-plugin-remove-references": "^0.0.5"

    "@handy-common-utils/oclif-utils": "^1.0.7",

    "@handy-common-utils/promise-utils": "^1.1.1",

    "microsoft-cognitiveservices-speech-sdk": "^1.18.1",

  "homepage": "https://github.com/james-hu/tts-narrator#readme",

    "url": "git+https://github.com/james-hu/tts-narrator.git"

    "url": "https://github.com/james-hu/tts-narrator/issues"

[![Version](https://img.shields.io/npm/v/tts-narrator.svg)](https://npmjs.org/package/tts-narrator)

[![Downloads/week](https://img.shields.io/npm/dw/tts-narrator.svg)](https://npmjs.org/package/tts-narrator)

[![CI](https://github.com/james-hu/tts-narrator/actions/workflows/ci.yml/badge.svg)](https://github.com/james-hu/tts-narrator/actions/workflows/ci.yml)

The input is a script file in YAML format.

Example script files can be found under [test/fixtures](test/fixtures).

The script file is structured in this way:

  * `voice`: voice settings at script level

  * each chapter can contain settings and multiple sections:

    * `settings`: chapter level voice settings that can override script level voice settings

      * 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](https://www.npmjs.com/package/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](https://www.npmjs.com/package/speaker) as a dependency in your project.

When running on MacOS, to avoid `illegal hardware instruction` issue, try `npm i speaker --mpg123-backend=openal`

  -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

  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

• **new ScriptProcessor**(`scriptFilePath`, `flags`)

• **new ScriptProcessor**(`scriptFilePath`, `flags`, `cliConsole?`)

| `cliConsole?` | `CliConsole`<`fn`, `fn`, `fn`, `fn`\> |

• `Protected` **\_script**: [`NarrationScript`](#classesnarrationscriptmd)

• `Protected` **audioGenerationOptions**: `undefined` \| [`AudioGenerationOptions`](#interfacesaudiogenerationoptionsmd)

• `Protected` **chapterRange**: `undefined` \| `MultiRange`

• `Protected` **cliConsole**: `CliConsole`<`fn`, `fn`, `fn`, `fn`\>

• `Protected` **scriptFilePath**: `string`

• `Protected` **sectionRange**: `undefined` \| `MultiRange`

• `Protected` **ttsService**: [`TtsService`](#interfacesttsservicemd)

• `get` **script**(): [`NarrationScript`](#classesnarrationscriptmd)

[`NarrationScript`](#classesnarrationscriptmd)

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

| `_paragraph` | [`NarrationParagraph`](#classesnarrationparagraphmd) |

▸ `Protected` **hash**(`ssml`, `_paragraph`): `string`

▸ `Protected` **initialiseTtsServiceIfNeeded**(): `Promise`<`void`\>

		@@ -44,6 +44,6 @@ "use strict";
		class ScriptProcessor {
		constructor(scriptFilePath, flags) {
		constructor(scriptFilePath, flags, cliConsole) {
		this.scriptFilePath = scriptFilePath;
		this.flags = flags;
		this.cliConsole = (0, oclif_utils_1.cliConsoleWithColour)(this.flags, chalk_1.default);
		this.cliConsole = cliConsole !== null && cliConsole !== void 0 ? cliConsole : (0, oclif_utils_1.cliConsoleWithColour)(this.flags, chalk_1.default);
		}
		@@ -50,0 +50,0 @@ hash(ssml, _paragraph) {

		{
		"name": "tts-narrator",
		"version": "1.0.16",
		"version": "1.0.17",
		"description": "Generate narration with Text-To-Speech technology",
		@@ -5,0 +5,0 @@ "main": "dist/types.js",

		@@ -1068,3 +1068,3 @@ # tts-narrator

		• new ScriptProcessor(`scriptFilePath`, `flags`)
		• new ScriptProcessor(`scriptFilePath`, `flags`, `cliConsole?`)

		@@ -1077,2 +1077,3 @@ ###### Parameters
		\| `flags` \| `Object` \|
		\| `cliConsole?` \| `CliConsole`<`fn`, `fn`, `fn`, `fn`\> \|

		@@ -1079,0 +1080,0 @@ #### Properties

		@@ -36,3 +36,3 @@ import { flags } from '@oclif/command';
		protected sectionRange: MultiRange \| undefined;
		constructor(scriptFilePath: string, flags: Flags<typeof scriptProcessorFlags>);
		constructor(scriptFilePath: string, flags: Flags<typeof scriptProcessorFlags>, cliConsole?: DefaultCliConsole);
		protected hash(ssml: string, _paragraph: NarrationParagraph): string;
		@@ -39,0 +39,0 @@ protected loadScript(): Promise<void>;

Improved metrics