echogarden 0.12.2 → 1.0.0

package/dist/utilities/WikipediaReader.js

@@ -2,11 +2,11 @@ import { splitToParagraphs, wordCharacterPattern } from '../nlp/Segmentation.js'
 import { Logger } from './Logger.js';
 export async function parseWikipediaArticle(articleName, language) {
     const logger = new Logger();
-    logger.startAsync("Fetching Wikipedia article");
+    logger.startAsync('Fetching Wikipedia article');
     const { default: wtf } = await import('wtf_wikipedia');
     const document = await wtf.fetch(articleName, language);
     if (!document) {
-        throw new Error("Error fetching Wikipedia article");
+        throw new Error('Error fetching Wikipedia article');
     }
     const sections = document.sections();
     const sectionsText = [];

package/dist/voice-activity-detection/AdaptiveGateVAD.d.ts

@@ -0,0 +1,28 @@
+import { RawAudio } from '../audio/AudioUtilities.js';
+import { BiquadFilter } from '../dsp/BiquadFilter.js';
+import { DecayingPeakEstimator } from '../dsp/DecayingPeakEstimator.js';
+import { LoudnessEstimator } from '../dsp/LoudnessEstimator.js';
+import { Timeline } from '../utilities/Timeline.js';
+export declare function detectVoiceActivity(rawAudio: RawAudio, options: AdaptiveGateVADOptions): Promise<Timeline>;
+export declare class AdaptiveGateVAD {
+    readonly sampleRate: number;
+    readonly channelCount: number;
+    readonly options: AdaptiveGateVADOptions;
+    channelHighpassFilters: BiquadFilter[];
+    channelLowpassFilters: BiquadFilter[];
+    loudnessEstimator: LoudnessEstimator;
+    minimumLoudnessEstimator: DecayingPeakEstimator;
+    maximumLoudnessEstimator: DecayingPeakEstimator;
+    constructor(sampleRate: number, channelCount: number, options: AdaptiveGateVADOptions);
+    process(sample: number, channelIndex: number): void;
+}
+export interface AdaptiveGateVADOptions {
+    lowCutoff?: number;
+    highCutoff?: number;
+    positiveAdaptationRate?: number;
+    negativeAdaptationRate?: number;
+    peakLoudnessDecay?: number;
+    backwardExtensionDuration?: number;
+    relativeThreshold?: number;
+}
+export declare const defaultAdaptiveGateOptions: AdaptiveGateVADOptions;

package/dist/voice-activity-detection/AdaptiveGateVAD.js

@@ -0,0 +1,138 @@
+import { getRawAudioDuration } from '../audio/AudioUtilities.js';
+import { createHighpassFilter, createLowpassFilter } from '../dsp/BiquadFilter.js';
+import { DecayingPeakEstimator } from '../dsp/DecayingPeakEstimator.js';
+import { LoudnessEstimator } from '../dsp/LoudnessEstimator.js';
+import { extendDeep } from '../utilities/ObjectUtilities.js';
+import { logToStderr } from '../utilities/Utilities.js';
+const log = logToStderr;
+export async function detectVoiceActivity(rawAudio, options) {
+    const channelCount = rawAudio.audioChannels.length;
+    const sampleCount = rawAudio.audioChannels[0].length;
+    const sampleRate = rawAudio.sampleRate;
+    const audioDuration = getRawAudioDuration(rawAudio);
+    options = extendDeep(defaultAdaptiveGateOptions, options);
+    const gateVAD = new AdaptiveGateVAD(sampleRate, channelCount, options);
+    const frameDuration = 0.01;
+    const frameRecords = [];
+    for (let sampleIndex = 0; sampleIndex < sampleCount; sampleIndex++) {
+        const timePosition = sampleIndex / sampleRate;
+        for (let channelIndex = 0; channelIndex < channelCount; channelIndex++) {
+            const sample = rawAudio.audioChannels[channelIndex][sampleIndex];
+            gateVAD.process(sample, channelIndex);
+        }
+        if (frameRecords.length == 0 ||
+            timePosition > frameRecords[frameRecords.length - 1].timePosition + frameDuration) {
+            const record = {
+                timePosition,
+                loudness: gateVAD.loudnessEstimator.currentLoudness,
+                minimumLoudness: gateVAD.minimumLoudnessEstimator.currentPeak,
+                maximumLoudness: gateVAD.maximumLoudnessEstimator.currentPeak,
+            };
+            frameRecords.push(record);
+            //log(`${timePosition.toFixed(3)}: loudness: ${record.loudness.toFixed(2)}dB, min: ${record.minimumLoudness.toFixed(2)}dB, max: ${record.maximumLoudness.toFixed(2)}dB dynamic range: ${record.dynamicRange.toFixed(2)}dB`)
+        }
+    }
+    const frameActive = [];
+    for (let i = 0; i < frameRecords.length; i++) {
+        frameActive[i] = false;
+    }
+    {
+        const backwardExtensionFrameCount = Math.floor(options.backwardExtensionDuration / frameDuration);
+        const relativeThreshold = options.relativeThreshold;
+        let extendedActivityStartIndex = frameRecords.length;
+        for (let i = frameRecords.length - 1; i >= 0; i--) {
+            const record = frameRecords[i];
+            const referenceLoudness = Math.max(record.maximumLoudness, -30);
+            let isActive = false;
+            if (i >= extendedActivityStartIndex) {
+                isActive = true;
+            }
+            if (record.loudness >= referenceLoudness + relativeThreshold) {
+                isActive = true;
+                extendedActivityStartIndex = Math.max(i - backwardExtensionFrameCount, 0);
+            }
+            frameActive[i] = isActive;
+        }
+    }
+    const timeline = [];
+    for (let i = 0; i < frameRecords.length; i++) {
+        const record = frameRecords[i];
+        const isActive = frameActive[i];
+        const activityText = isActive ? 'active' : 'inactive';
+        const startTime = record.timePosition;
+        const endTime = Math.min(startTime + frameDuration, audioDuration);
+        if (timeline.length == 0 || timeline[timeline.length - 1].text != activityText) {
+            timeline.push({
+                type: 'segment',
+                text: activityText,
+                startTime,
+                endTime,
+            });
+        }
+        else {
+            timeline[timeline.length - 1].endTime = endTime;
+        }
+    }
+    return timeline;
+}
+export class AdaptiveGateVAD {
+    sampleRate;
+    channelCount;
+    options;
+    channelHighpassFilters;
+    channelLowpassFilters;
+    loudnessEstimator;
+    minimumLoudnessEstimator;
+    maximumLoudnessEstimator;
+    constructor(sampleRate, channelCount, options) {
+        this.sampleRate = sampleRate;
+        this.channelCount = channelCount;
+        this.options = options;
+        this.channelHighpassFilters = [];
+        this.channelLowpassFilters = [];
+        for (let i = 0; i < this.channelCount; i++) {
+            this.channelHighpassFilters.push(createHighpassFilter(this.sampleRate, options.lowCutoff));
+            this.channelLowpassFilters.push(createLowpassFilter(this.sampleRate, options.highCutoff));
+        }
+        this.loudnessEstimator = new LoudnessEstimator({
+            sampleRate: this.sampleRate,
+            channelCount: this.channelCount,
+            positiveAdaptationRate: options.positiveAdaptationRate,
+            negativeAdaptationRate: options.negativeAdaptationRate,
+            initialEstimate: -60,
+            minimumLoudness: -60,
+            applyKWeighting: false,
+        });
+        const ticksPerSecond = this.sampleRate * this.channelCount;
+        this.minimumLoudnessEstimator = new DecayingPeakEstimator({
+            kind: 'minimum',
+            decayPerSecond: options.peakLoudnessDecay,
+            initialPeak: -60,
+        }, ticksPerSecond);
+        this.maximumLoudnessEstimator = new DecayingPeakEstimator({
+            kind: 'maximum',
+            decayPerSecond: options.peakLoudnessDecay,
+            initialPeak: -60,
+        }, ticksPerSecond);
+    }
+    process(sample, channelIndex) {
+        sample = this.channelHighpassFilters[channelIndex].filter(sample);
+        sample = this.channelLowpassFilters[channelIndex].filter(sample);
+        this.loudnessEstimator.process(sample, channelIndex);
+        const currentLoudness = this.loudnessEstimator.currentLoudness;
+        this.minimumLoudnessEstimator.process(currentLoudness);
+        if (currentLoudness >= -60) {
+            this.maximumLoudnessEstimator.process(currentLoudness);
+        }
+    }
+}
+export const defaultAdaptiveGateOptions = {
+    lowCutoff: 100,
+    highCutoff: 1000,
+    positiveAdaptationRate: 400.0,
+    negativeAdaptationRate: 10.0,
+    peakLoudnessDecay: 4.0,
+    backwardExtensionDuration: 0.2,
+    relativeThreshold: -15,
+};
+//# sourceMappingURL=AdaptiveGateVAD.js.map

package/dist/voice-activity-detection/AdaptiveGateVAD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdaptiveGateVAD.js","sourceRoot":"","sources":["../../src/voice-activity-detection/AdaptiveGateVAD.ts"],"names":[],"mappings":"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"}

package/dist/voice-activity-detection/SileroVAD.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="../../src/typings/Fillers.d.ts" />
 import Onnx from 'onnxruntime-node';
 import { RawAudio } from '../audio/AudioUtilities.js';
-export declare function detectVoiceActivity(rawAudio: RawAudio, modelPath: string, frameDuration?: 30 | 60 | 90): Promise<number[]>;
+export declare function detectVoiceActivity(rawAudio: RawAudio, modelPath: string, frameDuration: 30 | 60 | 90): Promise<number[]>;
 export declare class SileroVAD {
     session?: Onnx.InferenceSession;
     modelStateH: Onnx.Tensor;

package/dist/voice-activity-detection/SileroVAD.js

@@ -1,9 +1,9 @@
 import Onnx from 'onnxruntime-node';
 import { concatFloat32Arrays } from '../utilities/Utilities.js';
 let sileroVad;
-export async function detectVoiceActivity(rawAudio, modelPath, frameDuration = 30) {
+export async function detectVoiceActivity(rawAudio, modelPath, frameDuration) {
     if (rawAudio.sampleRate != 16000) {
-        throw new Error("Audio sample rate must be 16KHz");
+        throw new Error('Audio sample rate must be 16KHz');
     }
     const audioSamples = rawAudio.audioChannels[0];
     const frameLength = Math.floor(16000 * (frameDuration / 1000));
@@ -43,9 +43,9 @@ export class SileroVAD {
         //const inputs = { input: inputTensor, h0: this.modelStateH, c0: this.modelStateC }
         const inputs = { input: inputTensor, sr: this.modelSampleRate, h: this.modelStateH, c: this.modelStateC };
         const results = await this.session.run(inputs);
-        const probability = results["output"].data[0];
-        this.modelStateH = results["hn"];
-        this.modelStateC = results["cn"];
+        const probability = results['output'].data[0];
+        this.modelStateH = results['hn'];
+        this.modelStateC = results['cn'];
         return probability;
     }
     async initializeSession(modelPath) {

package/dist/voice-activity-detection/SileroVAD.js.map

@@ -1 +1 @@
-{"version":3,"file":"SileroVAD.js","sourceRoot":"","sources":["../../src/voice-activity-detection/SileroVAD.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SileroVAD.js","sourceRoot":"","sources":["../../src/voice-activity-detection/SileroVAD.ts"],"names":[],"mappings":"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"}

package/dist/voice-activity-detection/WebRtcVAD.d.ts

@@ -1,3 +1,3 @@
-import { RawAudio } from "../audio/AudioUtilities.js";
+import { RawAudio } from '../audio/AudioUtilities.js';
 export declare function detectVoiceActivity(rawAudio: RawAudio, frameDuration?: 10 | 20 | 30, mode?: 0 | 1 | 2 | 3): Promise<(0 | 1)[]>;
 export declare function fvad(samples: Int16Array, sampleRate: number, frameDuration: 10 | 20 | 30, mode: 0 | 1 | 2 | 3): Promise<any[]>;

package/dist/voice-activity-detection/WebRtcVAD.js

@@ -1,8 +1,8 @@
-import * as AudioBufferConversion from "../audio/AudioBufferConversion.js";
-import { WasmMemoryManager } from "../utilities/WasmMemoryManager.js";
+import * as AudioBufferConversion from '../audio/AudioBufferConversion.js';
+import { WasmMemoryManager } from '../utilities/WasmMemoryManager.js';
 export async function detectVoiceActivity(rawAudio, frameDuration = 10, mode = 0) {
     if (rawAudio.sampleRate != 16000) {
-        throw new Error("Audio sample rate must be 16KHz");
+        throw new Error('Audio sample rate must be 16KHz');
     }
     const frameClassifications = await fvad(AudioBufferConversion.float32ToInt16Pcm(rawAudio.audioChannels[0]), rawAudio.sampleRate, frameDuration, mode);
     return frameClassifications;
@@ -34,7 +34,7 @@ export async function fvad(samples, sampleRate, frameDuration, mode) {
         frameSamplesRef.view.set(frame);
         const fvadResult = fvad_process(instancePtr, frameSamplesRef.address, frameSampleCount);
         if (fvadResult == -1) {
-            throw new Error("fvad_process failed");
+            throw new Error('fvad_process failed');
         }
         result.push(fvadResult);
     }

package/docs/API.md

@@ -19,11 +19,11 @@ import * as Echogarden from 'echogarden'
 
 All methods, properties and arguments have TypeScript type information. You can use it to get more detailed and up-to-date type information that may not be covered in the documentation.
 
-### Related resources
+### Related pages
 * [Options reference](Options.md)
-* [A comprehensive list of all supported engines](Engines.md)
-* [A quick guide for using the command line interface](CLI.md)
-* [Guide for running and interfacing with a WebSocket server](Server.md)
+* [List of all supported engines](Engines.md)
+* [Quick guide for the command line interface](CLI.md)
+* [WebSocket server guide](Server.md)
 
 ## Synthesis
 
@@ -195,7 +195,7 @@ Detects language of text.
 
 ### `detectVoiceActivity(input, options)`
 
-Detects voice activity in audio (non real-time).
+Detects voice activity in audio (non-real-time).
 
 * `input`: Can be an audio file path (`string`), encoded audio (`Buffer` or `Uint8array`) or a raw audio object (`RawAudio`)
 * `options`: Voice activity detection options object
@@ -209,10 +209,10 @@ Detects voice activity in audio (non real-time).
 
 ## Speech denoising
 
-Tries to reduce background noise in spoken audio.
-
 ### `denoise(input, options)`
 
+Tries to reduce background noise in spoken audio.
+
 * `input`: Can be an audio file path (`string`), encoded audio (`Buffer` or `Uint8array`) or a raw audio object (`RawAudio`)
 * `options`: Denoising options object
 
@@ -223,6 +223,24 @@ Tries to reduce background noise in spoken audio.
 }
 ```
 
+## Source separation
+
+### `isolate(input, options)`
+
+Attempts to isolate an individual [audio stem](https://en.wikipedia.org/wiki/Stem_(audio)), like human voice, or one or more musical instruments (depending on model training), from the given waveform.
+
+* `input`: Can be an audio file path (`string`), encoded audio (`Buffer` or `Uint8array`) or a raw audio object (`RawAudio`)
+* `options`: Source separation options object
+
+#### Returns (via promise):
+```ts
+{
+	inputRawAudio: RawAudio
+	isolatedRawAudio: RawAudio
+	backgroundRawAudio: RawAudio
+}
+```
+
 ## Subtitles
 
 ### `timelineToSubtitles(timeline, options)`
@@ -256,7 +274,7 @@ Set a global option.
 
 Supported keys:
 
-* `'ffmpegPath'`: override FFMpeg executable path
+* `'ffmpegPath'`: override FFmpeg executable path
 * `'soxPath'`: override SoX executable path
 
 ### `getGlobalOption(key)`
@@ -265,7 +283,7 @@ Get a global option.
 
 Supported keys:
 
-* `'ffmpegPath'`: get FFMpeg executable path
+* `'ffmpegPath'`: get FFmpeg executable path
 * `'soxPath'`: get SoX executable path
 
 #### Returns:
@@ -274,5 +292,5 @@ The value associated with the given key.
 
 ## TODO
 
-Expose more methods that may be useful for developers, like phonemization, etc.
-
+* Expose more methods that may be useful for developers, like phonemization, etc.
+* Expose audio playback used in CLI, possibly with timeline synchronization support.

package/docs/CLI.md

@@ -8,13 +8,17 @@ echogarden [command] [one or more inputs..] [one or more outputs...] [options...
 
 Here's a quick tour of the main operations available via the CLI.
 
-Each command can accept one or more options, in the form `--[optionName]=[value]` (The `=` is required). A detailed reference of all the available options can be found [here](Options.md).
+Each command can accept one or more options, in the form `--[optionName]=[value]` (The `=` is required).
 
 **Keyboard shortcuts**:
 * While the program is running, you can press `esc` to exit immediately
 * When audio is playing, you can press `enter` to skip it
 
-## Text to speech
+### Related pages
+* [Options reference](Options.md)
+* [List of all supported engines](Engines.md)
+
+## Text-to-speech
 
 **Task**: given a text file, synthesize spoken audio for it.
 
@@ -58,7 +62,7 @@ Synthesize a Wikipedia article, in any of its language editions:
 echogarden speak-wikipedia "Psychologie" --language=fr
 ```
 
-## Speech to text
+## Speech-to-text
 
 **Task**: given an audio recording containing speech, find a textual transcription that best matches it.
 
@@ -72,7 +76,7 @@ This would transcribe the audio file `speech.mp3` and store the resulting transc
 echogarden transcribe speech.mp3 result.txt result.srt result.json
 ```
 
-## Speech to transcript alignment
+## Speech-to-transcript alignment
 
 **Task**: given an audio file and its transcript, try to approximate the timing of the start and end of each spoken word (and its subparts).
 
@@ -120,7 +124,7 @@ echogarden align speech.mp3 transcript.txt parts/[segment].m4a parts/[segment].s
 
 ### Splitting based on sentence boundaries (future)
 
-Splitting based on sentences, using a `[sentence]` placeholder, is currently on the to-do list. Please let me know if you find this feature important and I'll prioritize it.
+Splitting based on sentences, using a `[sentence]` placeholder, is currently on the to-do list. Please let me know if you find this feature important, and I'll prioritize it.
 
 ## Audio playback
 By default, audio isn't played in the terminal when an output file is specified, you can override this behavior by adding `--play`:
@@ -135,7 +139,7 @@ echogarden transcribe speech.mp3 --no-play
 
 ## File overwriting
 
-By default, the CLI doesn't overwrite existing files. If an output file `out.mp3` already exists, it will save it as `out (1).mp3`:
+By default, the CLI doesn't overwrite existing files. If an output file `out.mp3` already exists, it will save it as `out_001.mp3`.
 
 To have existing files be overwritten, you can pass the `--overwrite` option.
 
@@ -237,7 +241,7 @@ echogarden detect-voice-activity speech.mp3 timeline.json
 
 ### Speech denoising
 
-**Task**: try to reduce the amount of background noise in a spoken recording.
+**Task**: attempt to reduce the amount of background noise in a spoken recording.
 
 This would apply denoising and play the denoised audio:
 ```bash
@@ -249,6 +253,26 @@ This would apply denoising, and save the denoised audio to a file:
 echogarden denoise speech.mp3 denoised-speech.mp3
 ```
 
+### Source separation
+
+**Task**: try to isolate a vocal track (or other type of track, depending on model used), from the audio.
+
+This would apply source separation and play the isolated audio:
+```bash
+echogarden isolate voice-with-music.mp3
+```
+
+This would apply source separation, and save both the isolated and background audio:
+```bash
+echogarden isolate voice-with-music.mp3 voice-isolated.mp3
+```
+
+Written files would be:
+```
+voice-isolated.mp3
+voice-isolated.background.mp3
+```
+
 ## Information and lists
 
 ### `list-engines`

package/docs/Contributing.md

@@ -0,0 +1,38 @@
+# How to help
+
+So far, this project has been the solo work of a single person.
+
+However, there are many areas where contributions can be made.
+
+## Report any issue or bug you encounter
+
+First, check the issue tracker, as well as the [task list](Tasklist.md) to see if the problem is already known to me. The task list allows me to efficiently document and organize a large quantity of small issues, enhancements or ideas that would otherwise flood an issue tracker with lots of unimportant entries, be ignored, or forgotten entirely.
+
+If you find the issue you're encountering in the task list, you can still open an issue to discuss it. This allows me to know that someone cares about a particular issue, and I may give it higher priority.
+
+There might be some obvious errors that have gone unreported. Especially if:
+* You're using the macOS architecture: I don't have access to a macOS machine, so personally I did not and cannot perform testing on that platform.
+* You're using cloud services: There may be changes in the service that will require updating the code. I don't often test they work correctly, since my trial periods in Google, Microsoft and Amazon have all expired, thus testing requires me to use paid requests.
+
+In any case, please let me know if you get any unexpected error message or surprising behavior that you care about, and I'll try to prioritize it, if possible.
+
+## Report or help fix odd TTS pronunciations and other fail cases
+
+When you encounter an odd pronunciation in a VITS voice, there are several possible causes:
+
+1. An incorrect phonemization produced by the eSpeak engine. Fortunately, it can be overridden by adding a corrected pronunciation to an Echogarden lexicon. You can pass one or more custom lexicons files to the VITS engine via `vits.customLexiconPaths` and see if it solves the problem. The lexicon format is the same as in [this file](https://github.com/echogarden-project/echogarden/blob/main/data/lexicons/heteronyms.en.json) - you can use it as a reference.
+1. This word has multiple different pronunciations based on context (a heteronym). In that case, it may be possible resolve the pronunciations based on context, by using the preceding and succeeding words as indicators. This is supported by the lexicon in the `precededBy`, `notPrecededBy`, `succeededBy`, `notSucceededBy` properties.
+1. An issue with model training, which may need to be forwarded to the original authors.
+
+If the problem is serious, you can report it, and we'll see what we can do.
+
+## Fork and make changes to the codebase
+
+See guide for [setting up a development environment](Development.md).
+
+
+## Notes about licensing
+
+The code is currently licensed under GPL-3, mainly due to one of its core dependencies, `eSpeak-NG`, having this license.
+
+In the future, I may want to re-license parts (or all) of the code to a more permissive license like MIT, if that turns out to be possible. If you make an external contribution, I would appreciate if you also agree to license it under the MIT license, so a future transition would be easier.

package/docs/Development.md

@@ -1,33 +1,107 @@
-# How to help
+# Setting up a development environment
 
-So far, this project has been the solo work of a single person.
+Here's a quick guide on how to set up a development environment for making and testing changes to the Echogarden codebase.
 
-However, there are many areas where contributions can be made.
+**Related pages**:
+* [How to help](Contributing.md)
+* [Technical overview](Techincal.md)
+* [Node.js API reference](API.md)
 
-## Report any issue or bug you encounter
+## Quick start
 
-First, check the issue tracker, as well as the [task list](Tasklist.md) to see if the problem is already known to me. The task list allows me to efficiently document and organize a large quantity of small issues, enhancements or ideas that would otherwise flood an issue tracker with lots of unimportant entries, be ignored, or forgotten entirely.
+* Fork or clone the repository (`git clone https://github.com/echogarden-project/echogarden`)
+* Ensure you have [Node.js](https://nodejs.org/en/download) installed
+* Ensure you have TypeScript installed (`npm install typescript -g`)
+* Run `npm install` in the project base directory
+* Compile using `tsc .` at the project base directory
 
-If you find the issue you're encountering in the task list, you can still open an issue to discuss it. This allows me to know that someone cares about a particular issue, and I may give it higher priority.
+## Auto-compiling in Visual Studio Code
 
-There might be some obvious errors that have gone unreported. Especially if:
-* You're using the macOS platform: I don't have access to a macOS machine, and thus almost no real testing has been done over that platform.
-* You're using cloud services: There may be changes in the service that will require updating the code. I don't often test they work correctly, since my trial periods in Google, Microsoft and Amazon have all expired, thus testing requires me to use payed requests.
+Create the `.vscode` subdirectory at the project base directory
 
-In any case, please let me know if you get any unexpected error message or surprising behavior that you care about, and I'll try to prioritize it, if possible.
+Add a `.vscode/tasks.json` file to run the TypeScript compiler in watch mode:
+```json
+{
+	// See http://go.microsoft.com/fwlink/?LinkId=733558
+	// for the documentation about the tasks.json format
+	"version": "2.0.0",
+	"command": "tsc.cmd",
+	"args": [
+		"-w",
+		"-p",
+		"."
+	],
+	"problemMatcher": "$tsc-watch",
+	"isBackground": true,
+	"tasks": [
+		{
+			"label": "node",
+			"type": "shell",
+			"command": "tsc",
+			"args": [
+				"-w",
+				"-p",
+				"."
+			],
+			"isBackground": true,
+			"problemMatcher": "$tsc-watch",
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+		}
+	]
+}
+```
 
-## Report or help fix odd TTS pronunciations and other fail cases
+## Running the local code
 
-When you encounter an odd pronunciation in a VITS voice, there are several possible causes:
+In the project directory, type:
 
-1. An incorrect phonemization produced by the eSpeak engine. Fortunately, it can be overridden by adding a corrected pronunciation to an Echogarden lexicon. You can pass one or more custom lexicons files to the VITS engine via `vits.customLexiconPaths` and see if it solves the problem. The lexicon format is the same as in [this file](https://github.com/echogarden-project/echogarden/blob/main/data/lexicons/heteronyms.en.json) - you can use it as a reference.
-1. This word has multiple different pronunciations based on context (a heteronym). In that case, it may be possible resolve the pronunciations based on context, by using the preceding and succeeding words as indicators. This is supported by the lexicon in the `precededBy`, `notPrecededBy`, `succeededBy`, `notSucceededBy` properties.
-1. An issue with model training, which may need to be forwarded to the original authors.
+```
+npx echogarden speak "Hello World!"
+```
 
-If the problem is serious, you can report it and we'll see what we can do.
+Adding `npx` would start the CLI directly from the local code.
 
-## Notes about licensing
+## Step-debugging in VS Code
 
-The code is currently licensed under the GPL-3, mainly due to one of its main dependencies, `eSpeak-NG`, being licensed with this license.
+Ensure the project is compiled (using the watch task above is highly recommended).
 
-In the future, I may want to re-license parts (or all) of the code to a more permissive license like MIT, if that is possible. If you make an external contribution, I would appreciate if you also agree to license it under the MIT license, so a future transition would be easier.
+Add a `.vscode/launch.json` file to launch the CLI in debug mode:
+
+```json
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"type": "node",
+			"request": "launch",
+			"name": "Launch Program",
+			"skipFiles": [
+				"<node_internals>/**"
+			],
+			"program": "${workspaceFolder}/dist/cli/CLIStarter.js",
+			"outputCapture": "std",
+			"console": "integratedTerminal",
+			"runtimeArgs": ["--no-warnings", "--no-experimental-fetch", "--experimental-wasi-unstable-preview1", "--trace-uncaught"],
+
+			"args": ["speak", "Hello World!", "--debug"]
+		}
+	]
+}
+```
+
+Press F5 to start debugging.
+
+You can change `"args": ["speak", "Hello World!", "--debug"]` to any command line arguments you want to test. Adding the `--debug` CLI option ensures that errors are shown with full stack traces.
+
+## Updating the options schema
+
+If you add, modify or remove options from the API, that are exposed to the CLI, you should run:
+
+```
+npm run generate-options-schema
+```
+
+To update the JSON schema used when parsing command line options in the CLI. Otherwise, the CLI may not recognize the modified option names or types.