Skip to content

Commit

Permalink
Update README (#322)
Browse files Browse the repository at this point in the history 
Signed-off-by: rany <[email protected]>
  • Loading branch information
@rany2
rany2 authored Nov 22, 2024
1 parent 3f2b635 commit 5a2674c
Showing 1 changed file with 29 additions and 40 deletions.
69 changes: 29 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ To install it, run the following command:

$ pip install edge-tts

If you only want to use the `edge-tts` and `edge-playback` commands, it would be better to use pipx:
If you only want to use the `edge-tts` and `edge-playback` commands, it would be better to use `pipx`:

$ pipx install edge-tts

Expand All @@ -24,64 +24,53 @@ If you wish to play it back immediately with subtitles, you could use the `edge-

$ edge-playback --text "Hello, world!"

Note the above requires the installation of the `mpv` command line player.
Note that `edge-playback` requires the installation of the [`mpv` command line player](https://mpv.io/).

All `edge-tts` commands work in `edge-playback` as well.
All `edge-tts` commands work with `edge-playback` with the exception of the `--write-media`, `--write-subtitles` and `--list-voices` options.

### Changing the voice

If you want to change the language of the speech or more generally, the voice.

You must first check the available voices with the `--list-voices` option:
You can change the voice used by the text-to-speech service by using the `--voice` option. The `--list-voices` option can be used to list all available voices.

$ edge-tts --list-voices
Name: Microsoft Server Speech Text to Speech Voice (af-ZA, AdriNeural)
ShortName: af-ZA-AdriNeural
Gender: Female
Locale: af-ZA

Name: Microsoft Server Speech Text to Speech Voice (am-ET, MekdesNeural)
ShortName: am-ET-MekdesNeural
Gender: Female
Locale: am-ET

Name: Microsoft Server Speech Text to Speech Voice (ar-EG, SalmaNeural)
ShortName: ar-EG-SalmaNeural
Gender: Female
Locale: ar-EG

Name: Microsoft Server Speech Text to Speech Voice (ar-SA, ZariyahNeural)
ShortName: ar-SA-ZariyahNeural
Gender: Female
Locale: ar-SA

Name Gender ContentCategories VoicePersonalities
--------------------------------- -------- --------------------- --------------------------------------
af-ZA-AdriNeural Female General Friendly, Positive
af-ZA-WillemNeural Male General Friendly, Positive
am-ET-AmehaNeural Male General Friendly, Positive
am-ET-MekdesNeural Female General Friendly, Positive
ar-AE-FatimaNeural Female General Friendly, Positive
ar-AE-HamdanNeural Male General Friendly, Positive
ar-BH-AliNeural Male General Friendly, Positive
ar-BH-LailaNeural Female General Friendly, Positive
ar-DZ-AminaNeural Female General Friendly, Positive
ar-DZ-IsmaelNeural Male General Friendly, Positive
ar-EG-SalmaNeural Female General Friendly, Positive
...

$ edge-tts --voice ar-EG-SalmaNeural --text "مرحبا كيف حالك؟" --write-media hello_in_arabic.mp3 --write-subtitles hello_in_arabic.vtt

### Custom SSML

Support for custom SSML has been removed since 5.0.0 because Microsoft has taken the initiative to prevent it from working. You cannot use custom SSML anymore.
Support for custom SSML was removed because Microsoft prevents the use of any SSML that could not be generated by Microsoft Edge itself. This means that all the cases where custom SSML would be useful cannot be supported as the service only permits a single `<voice>` tag with a single `<prosody>` tag inside it. Any available customization options that could be used in the `<prosody>` tag are already available from the library or the command line itself.

### Changing rate, volume and pitch

It is possible to make minor changes to the generated speech.
You can change the rate, volume and pitch of the generated speech by using the `--rate`, `--volume` and `--pitch` options. When using a negative value, you will need to use `--[option]=-50%` instead of `--[option] -50%` to avoid the option being interpreted as a command line option.

$ edge-tts --rate=-50% --text "Hello, world!" --write-media hello_with_rate_halved.mp3 --write-subtitles hello_with_rate_halved.vtt
$ edge-tts --volume=-50% --text "Hello, world!" --write-media hello_with_volume_halved.mp3 --write-subtitles hello_with_volume_halved.vtt
$ edge-tts --pitch=-50Hz --text "Hello, world!" --write-media hello_with_pitch_halved.mp3 --write-subtitles hello_with_pitch_halved.vtt
$ edge-tts --rate=-50% --text "Hello, world!" --write-media hello_with_rate_lowered.mp3 --write-subtitles hello_with_rate_lowered.vtt
$ edge-tts --volume=-50% --text "Hello, world!" --write-media hello_with_volume_lowered.mp3 --write-subtitles hello_with_volume_lowered.vtt
$ edge-tts --pitch=-50Hz --text "Hello, world!" --write-media hello_with_pitch_lowered.mp3 --write-subtitles hello_with_pitch_lowered.vtt

In addition, it is required to use `--rate=-50%` instead of `--rate -50%` (note the lack of an equal sign) otherwise the `-50%` would be interpreted as just another argument.
## Python module

### Note on the `edge-playback` command
It is possible to use the `edge-tts` module directly from Python. Examples from the project itself include:

`edge-playback` is just a wrapper around `edge-tts` that plays back the generated speech. It takes the same arguments as the `edge-tts` option.
* [/examples/](/examples/)
* [/src/edge_tts/util.py](/src/edge_tts/util.py)

## Python module
Other projects that use the `edge-tts` module include:

It is possible to use the `edge-tts` module directly from Python. For a list of example applications:
* [hass-edge-tts](https://github.com/hasscc/hass-edge-tts/blob/main/custom_components/edge_tts/tts.py)
* [Podcastfy](https://github.com/souzatharsis/podcastfy/blob/main/podcastfy/tts/providers/edge.py)

* https://github.com/souzatharsis/podcastfy/blob/main/podcastfy/tts/providers/edge.py
* https://github.com/rany2/edge-tts/tree/master/examples
* https://github.com/rany2/edge-tts/blob/master/src/edge_tts/util.py
* https://github.com/hasscc/hass-edge-tts/blob/main/custom_components/edge_tts/tts.py

0 comments on commit 5a2674c

Please sign in to comment.