From e8e21f949ccfa749f0b52fc8aebe2d87e94689dd Mon Sep 17 00:00:00 2001 From: erew123 <35898566+erew123@users.noreply.github.com> Date: Sun, 24 Dec 2023 10:00:08 +0000 Subject: [PATCH] Update README.md Detail API Suite --- README.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74f3dff..415fbe0 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ AllTalk is an updated version of the Coqui_tts extension for Text Generation web - **Finetuning** Train the model specifically on a voice of your choosing for better reproduction. - **Documentation:** Fully documented with a built in webpage. [Screenshot](https://github.com/erew123/alltalk_tts#screenshots) - **Console output** Clear command line output for any warnings or issues. -- **Standalone/3rd Party support via JSON calls** Can be used with 3rd party applications via JSON calls. +- **API Suite and 3rd Party support via JSON calls** Can be used with 3rd party applications via JSON calls. ## Index @@ -20,6 +20,7 @@ AllTalk is an updated version of the Coqui_tts extension for Text Generation web - 🟨 [Help with problems](https://github.com/erew123/alltalk_tts?#-help-with-problems) - ⚫ [Finetuning a model](https://github.com/erew123/alltalk_tts?#-finetuning-a-model) - πŸ”΅πŸŸ’πŸŸ‘ [DeepSpeed Installation (Windows & Linux)](https://github.com/erew123/alltalk_tts?#-deepspeed-installation-options) +- 🟠 [API Suite and JSON-CURL](https://github.com/erew123/alltalk_tts?#-api-suite-and-json-curl) - πŸ”΄ [Future to-do list & Upcoming updates](https://github.com/erew123/alltalk_tts?#-future-to-do-list) #### Updates @@ -286,7 +287,6 @@ As mentioned you must have a small portion of the Nvidia CUDA Toolkit **11.8** i 9) Follow the on-screen instructions when the web interface starts up. 10) When you have finished finetuning, the final tab will tell you what to do with your files and how to move your newly trained model to the correct location on disk. - ## πŸ”΅πŸŸ’πŸŸ‘ DeepSpeed Installation Options #### πŸ”΅ Linux Installation
@@ -438,6 +438,140 @@ def get_shm_size(): **Removal** - If it became necessary to uninstall DeepSpeed, you can do so with `cmd_windows.bat` and then `pip uninstall deepspeed`

+## 🟠 API Suite and JSON-CURL +### 🟠Overview +The Text-to-Speech (TTS) Generation API allows you to generate speech from text input using various configuration options. This API supports both character and narrator voices, providing flexibility for creating dynamic and engaging audio content. + +- URL: `http://127.0.0.1:7851/api/tts-generate`
+- Method: `POST`
+- Content-Type: `application/x-www-form-urlencoded`
+ +### 🟠 Example command lines +Standard TTS speech Example (standard text) generating a time-stamped file
+ +`curl -X POST "http://127.0.0.1:7851/api/tts-generate" -d "text_input=All of this is text spoken by the character. This is text not inside quotes, though that doesnt matter in the slightest" -d "text_filtering=standard" -d "character_voice_gen=female_01.wav" -d "narrator_enabled=false" -d "narrator_voice_gen=male_01.wav" -d "text_not_inside=character" -d "language=en" -d "output_file_name=myoutputfile" -d "output_file_timestamp=true" -d "autoplay=true" -d "autoplay_volume=0.8"`
+ +Narrator Example (standard text) generating a time-stamped file + +`curl -X POST "http://127.0.0.1:7851/api/tts-generate" -d "text_input=*This is text spoken by the narrator* \"This is text spoken by the character\". This is text not inside quotes." -d "text_filtering=standard" -d "character_voice_gen=female_01.wav" -d "narrator_enabled=true" -d "narrator_voice_gen=male_01.wav" -d "text_not_inside=character" -d "language=en" -d "output_file_name=myoutputfile" -d "output_file_timestamp=true" -d "autoplay=true" -d "autoplay_volume=0.8"`
+ +Note that if your text that needs to be generated contains double quotes you will need to escape them with `\"` (Please see the narrator example). + +### 🟠 Request Parameters +🟠 **text_input**: The text you want the TTS engine to produce. Use escaped double quotes for character speech and asterisks for narrator speech if using the narrator function. Example: + +`-d "text_input=*This is text spoken by the narrator* \"This is text spoken by the character\". This is text not inside quotes."` + +🟠 **text_filtering**: Filter for text. Options: + +- **none** No filtering. Whatever is sent will go over to the TTS engine as raw text, which may result in some odd sounds with some special characters.
+- **standard** Human-readable text and a basic level of filtering, just to clean up some special characters.
+- **html** HTML content. Where you are using HTML entity's like "
+ +`-d "text_filtering=none"`
+`-d "text_filtering=standard"`
+`-d "text_filtering=html"`
+ +Example: + +- **Standard Example**: `*This is text spoken by the narrator* "This is text spoken by the character" This is text not inside quotes.`
+- **HTML Example**: `*This is text spoken by the narrator* "This is text spoken by the character" This is text not inside quotes.`
+- **None**: `Will just pass whatever characters/text you send at it.`
+ +🟠 **character_voice_gen**: The WAV file name for the character's voice.
+ +`-d "character_voice_gen=female_01.wav"` + +🟠 **narrator_enabled**: Enable or disable the narrator function. If true, minimum text filtering is set to standard. Anything between double quotes is considered the character's speech, and anything between asterisks is considered the narrator's speech. + +`-d "narrator_enabled=true"`
+`-d "narrator_enabled=false"` + +🟠 **narrator_voice_gen**: The WAV file name for the narrator's voice. + +`-d "narrator_voice_gen=male_01.wav"` + +🟠 **text_not_inside**: Specify the handling of lines not inside double quotes or asterisks, for the narrator feature. Options: + +- **character**: Treat as character speech.
+- **narrator**: Treat as narrator speech.
+ +`-d "text_not_inside=character"`
+`-d "text_not_inside=narrator"` + +🟠 **language**: Choose the language for TTS. Options: + +`ar Arabic`
+`zh-cn Chinese (Simplified)`
+`cs Czech`
+`nl Dutch`
+`en English`
+`fr French`
+`de German`
+`hu Hungarian`
+`it Italian`
+`ja Japanese`
+`ko Korean`
+`pl Polish`
+`pt Portuguese`
+`ru Russian`
+`es Spanish`
+`tr Turkish`
+ +`-d "language=en"`
+ +🟠 **output_file_name**: The name of the output file (excluding the .wav extension). + +`-d "output_file_name=myoutputfile"`
+ +🟠 **output_file_timestamp**: Add a timestamp to the output file name. If true, each file will have a unique timestamp; otherwise, the same file name will be overwritten each time you generate TTS. + +`-d "output_file_timestamp=true"`
+`-d "output_file_timestamp=false"` + +🟠 **autoplay**: Feature not yet available. Enable or disable autoplay. Still needs to be specified in the JSON request. + +`-d "autoplay=true"`
+`-d "autoplay=false"` + +🟠 **autoplay_volume**: Feature not yet available. Set the autoplay volume. Should be between 0.1 and 1.0. Still needs to be specified in the JSON request. + +`-d "autoplay_volume=0.8"` + +### 🟠 TTS Generation Response +The API returns a JSON object with the following properties: + +- **status** Indicates whether the generation was successful (generate-success) or failed (generate-failure).
+- **output_file_path** The on-disk location of the generated WAV file.
+- **output_file_url** The HTTP location for accessing the generated WAV file.
+ +Example JSON TTS Generation Response: + +`{"status": "generate-success", "output_file_path": "C:\text-generation-webui\extensions\alltalk_tts\outputs\myoutputfile_1703149973.wav", "output_file_url": "http://127.0.0.1:7851/audio/myoutputfile_1703149973.wav"}` + +🟠 **Switching Model**

+`curl -X POST "http://127.0.0.1:7851/api/reload?tts_method=API%20Local"`
+`curl -X POST "http://127.0.0.1:7851/api/reload?tts_method=API%20TTS"`
+`curl -X POST "http://127.0.0.1:7851/api/reload?tts_method=XTTSv2%20Local"`
+ +Switch between the 3 models respectively. + +JSON return `{"status": "model-success"}` + +🟠 **Switch DeepSpeed**

+`curl -X POST "http://127.0.0.1:7851/api/deepspeed?new_deepspeed_value=True"` + +Replace True with False to disable DeepSpeed mode. + +JSON return `{"status": "deepspeed-success"}` + +🟠 **Switching Low VRAM**

+`curl -X POST "http://127.0.0.1:7851/api/lowvramsetting?new_low_vram_value=True"` + +Replace True with False to disable Low VRAM mode. + +JSON return `{"status": "lowvram-success"}` + ### πŸ”΄ Future to-do list - Voice output within the command prompt/terminal (TBD). - Correct a few spelling mistakes in the documentation.