echogarden 0.9.2 → 0.10.0

package/docs/Server.md

@@ -0,0 +1,110 @@
+# Starting and interfacing with the WebSocket server
+
+## Starting the server
+
+```bash
+echogarden serve [options]
+```
+
+**Options** (all optional):
+* `port`: Port number. Defaults to `45054`
+* `secure`: Start a secure server? Defaults to `false`
+* `certPath`: Path to a certificate file, required when `secure = true`
+* `keyPath`: Path to a private key file, required when `secure = true`
+* `deflate`: Use per-message deflate. Defaults to `true`
+* `maxPayload`: Maximum raw message payload size (in bytes). Defaults to `1000 * 1000000` (1GB)
+* `useWorkerThread`: Run worker in a separate thread. Defaults to `true` (recommended to leave as is)
+
+## The protocol
+
+The protocol is based on binary WebSocket messages, for both request and response objects. Messages are encoded using the [MessagePack](https://msgpack.org/index.html) encoding scheme.
+
+All messages are objects and have the basic structure:
+
+```ts
+{
+	messageType: string
+	requestId: string
+
+	// ... other data specific for the target message type
+}
+```
+
+The `messageType` property is a string representing the operation to perform. These operations are parallel to the methods provided by the Node.js API. They can be one of:
+
+* `SynthesisRequest`
+* `VoiceListRequest`
+* `RecognitionRequest`
+* `AlignmentRequest`
+* `SpeechTranslationRequest`
+* `SpeechLanguageDetectionRequest`
+* `TextLanguageDetectionRequest`
+
+When sending a message, `requestId` should contain a long random string that uniquely identifies your request, like `cb7e0f3ec835a213b005c4424c8d5775`.
+
+For example, this message requests synthesis:
+```ts
+{
+	messageType: 'SynthesisRequest',
+	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',
+
+	input: 'Hello World!',
+
+	options: {
+		engine: 'espeak',
+		voice: 'en-GB'
+	}
+}
+```
+
+After a message is sent, the server may send one or more response messages. Each response message includes the `requestId` identifier that was given on the request it replies to. The response message `messageType` can be:
+
+* `SynthesisResponse`, `SynthesisSegmentEvent`, `SynthesisSentenceEvent`
+* `VoiceListResponse`
+* `RecognitionResponse`
+* `AlignmentResponse`
+* `SpeechTranslationResponse`
+* `SpeechLanguageDetectionResponse`
+* `TextLanguageDetectionResponse`
+
+The properties included in the response objects, are similar to the ones returned by the API.
+
+Example response, for the above synthesis request:
+
+```ts
+{
+	messageType: 'SynthesisResponse',
+	requestId: 'cb7e0f3ec835a213b005c4424c8d5775',
+
+	rawAudio: {
+		sampleRate: 22050,
+		channels: [ ... ] // An array of `float32` sample data
+	}
+
+	// ... other result object properties
+}
+```
+
+## Client package (future)
+
+For Node.js clients, there is a simpler client class, that allows to wrap communications with with the server in a more convenient interface.
+
+Currently, the client is is embedded in the original codebase. This means you have to import the entire package to use it.
+
+In the future, this module would be separated to an independent lightweight package.
+
+## Web-based user interface (future)
+
+When an HTTP web-based user interface is developed, it would be integrated with the WebSocket server and share the same port.
+
+Currently, if you start a non-secure server and try to open `http://localhost:45054` (or another port you specified), you should see a placeholder message saying:
+
+```
+This is the Echogarden HTTP server!
+```
+
+If you can't see this message, there may be a configuration issue, or some other problem.
+
+## TODO
+
+Expose more operations to the server.

package/docs/Tasklist.md

@@ -42,9 +42,7 @@
 
 ### Worker
 * Add cancelation checks in more operations
-* Optionally omit unnecessary data from the response (decoded input, segment data, etc.)
 * Support more operations
-* Support compressed audio in response
 
 ### CLI
 * Show names of files written do disk. This is useful for cases where a file is auto-renamed to allow overwrite.
@@ -53,7 +51,6 @@
 * Consider what to do with non-supported templates like `[hello]`
 * Show a message when a new version is available
 * Figure out which terminal outputs should go to stdout, or if that's a good idea at all
-* Option to set audio output codec options
 * Option to set audio output device for playback
 * Print available synthesis voices when no voice matches (or suggest near matches)
 * `transcribe` may also accept `http://` and `https://` URLs and pull the remote media file
@@ -83,9 +80,9 @@
 
 ### CLI / New commands
 * `speak-youtube`: To speak the subtitles of a YouTube video
-* `play-with-captions`: Preview captions in terminal
+* `play-with-subtitles`: Preview subtitles in terminal
 * `play-with-timeline`: Preview timeline in terminal
-* `captions-to-text`, `captions-to-timeline`, `srt-to-vtt`, `vtt-to-srt`
+* `subtitles-to-text`, `subtitles-to-timeline`, `srt-to-vtt`, `vtt-to-srt`
 * `crop-to-timeline`, `split-by-timeline`
 * `text-to-ipa`, `arpabet-to-ipa`, `ipa-to-arpabet`
 * `phonemize-text`
@@ -110,7 +107,6 @@
 ### Segmentation
 * Split long words
 * See if it's possible to reliably use eSpeak as a segmentation engine
-* Path to `kuromoji` dictionaries can be found more reliably than current
 
 ### Subtitles
 * If a subtitle is too short and at the end of the audio, try to extend it back if possible (for example, if the previous subtitle is already extended, take back from it)
@@ -139,10 +135,10 @@
 
 ### Synthesis / preprocessing
 * Extend the heteronyms JSON document with additional words like "conducts", "survey", "protest", "transport", "abuse", "combat", "combats", "affect", "contest", "detail", "marked", "contrast", "construct", "constructs", "console", "recall", "permit", "permits", "prospect", "prospects", "proceed", "proceeds", "invite", "reject", "deserts", "transcript", "transcripts", "compact", "impact", "impacts"
-* Full date normalization (e.g. `21 August 2023`, `21 Aug 2023`)
+* Full date normalization (e.g. `21 August 2023`, `21 Aug 2023`, `August 21, 2023`)
 * Add support for capitalized-only rules, and possibly also all uppercase / all lowercase rules.
-* Support normalizing to graphemes, not only phonemes
 * Add support for multiple words in `precededBy` and `succeededBy`
+* Support substituting to graphemes in lexicons, not only phonemes
 * Cache lexicons to avoid parsing the JSON each time it is loaded (this may not be needed for if the file is relatively small)
 * Is it possible to pre-phonemize common words like "the" or is it a bad idea / not necessary?
 * Add support for text preprocessing for all engines that can benefit from it (possibly including cloud engines).

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "echogarden",
-	"version": "0.9.2",
+	"version": "0.10.0",
 	"description": "An integrated speech system, providing a set of synthesis, recognition, alignment, and other processing tools, designed to be directly accessible to end-users.",
 	"author": "Rotem Dan",
-	"license": "GPL-3.0-only",
+	"license": "GPL-3.0",
 	"keywords": [
 		"speech",
 		"text-to-speech",
@@ -53,8 +53,8 @@
 		"echogarden": "./dist/cli/CLILauncher.js"
 	},
 	"dependencies": {
-		"@aws-sdk/client-polly": "^3.379.1",
-		"@aws-sdk/client-transcribe-streaming": "^3.379.1",
+		"@aws-sdk/client-polly": "^3.382.0",
+		"@aws-sdk/client-transcribe-streaming": "^3.382.0",
 		"@echogarden/espeak-ng-emscripten": "^0.1.2",
 		"@echogarden/fasttext-wasm": "^0.1.0",
 		"@echogarden/flite-wasi": "^0.1.1",
@@ -66,7 +66,6 @@
 		"@echogarden/speex-resampler-wasm": "^0.1.1",
 		"@echogarden/svoxpico-wasm": "^0.1.0",
 		"@mozilla/readability": "^0.4.4",
-		"@types/graceful-fs": "^4.1.6",
 		"alawmulaw": "^6.0.0",
 		"buffer-split": "^1.0.0",
 		"chalk": "^5.3.0",
@@ -124,8 +123,9 @@
 		"@types/recursive-readdir": "^2.2.1",
 		"@types/tar": "^6.1.5",
 		"@types/ws": "^8.5.5",
-		"@typescript-eslint/eslint-plugin": "^6.2.0",
-		"@typescript-eslint/parser": "^6.2.0",
+		"@typescript-eslint/eslint-plugin": "^6.2.1",
+		"@typescript-eslint/parser": "^6.2.1",
+		"@types/graceful-fs": "^4.1.6",
 		"eslint": "^8.46.0",
 		"ts-json-schema-generator": "^1.2.0",
 		"typescript": "^5.1.6"