source: lliurex-tts/trunk/fuentes/simple-google-tts/README.md @ 4721

Last change on this file since 4721 was 4721, checked in by joamuran, 3 years ago

included code

File size: 11.3 KB
Line 
1## Status update
2
3**This project is currently unmaintained and will remain so for the foreseeable future**.
4
5This script and many others like it rely on an unofficial API that has recently become increasingly difficult to support. As Google continues to lock down access to their TTS interface I see no choice other than to suspend maintaining this script for the time being. I sincerely hope that the future will see an official way to use Google TTS on desktop Linux. Until then, please feel free to fork this project if you want to try to fix it.
6
7As a last note: Make sure to also check out the [section on similar projects](https://github.com/Glutanimate/simple-google-tts#similar-projects) provided in this README.
8
9----------------------------
10
11# Simple Google™ TTS
12
13Ever wanted to use Google text-to-speech on Linux? Now you can.
14
15## Table of Contents
16
17<!-- MarkdownTOC -->
18
19- [Description](#description)
20- [Why use this script?](#why-use-this-script)
21- [Installation and dependencies](#installation-and-dependencies)
22    - [Dependencies](#dependencies)
23    - [Installation](#installation)
24- [Usage](#usage)
25    - [General usage](#general-usage)
26    - [Detailed explanation](#detailed-explanation)
27    - [Options](#options)
28    - [Supported languages](#supported-languages)
29    - [More examples](#more-examples)
30- [Known issues](#known-issues)
31- [Similar projects](#similar-projects)
32- [License](#license)
33
34<!-- /MarkdownTOC -->
35
36## Description
37
38The intent of this project is to provide an easy way to use text-to-speech output by Google on your Linux desktop. The script supports reading from standard input, plain text files, and highlighted text. A fall-back interface based on `pico2wave` takes care of the TTS output when you are offline.
39
40----
41
42`simple-google-tts` is based on [`speak.pl` by Michal Fapso](http://michalfapso.blogspot.de/2012/01/using-google-text-to-speech.html) which uses an [unofficial Google TTS API](http://weston.ruter.net/2009/12/12/google-tts/). This results in several limitations. `simple_google_tts` and `speak.pl` try to work around some of these issues, e.g. requests being limited to 100 characters, but are subject to other restrictions, e.g. obligatory CAPTCHA input for overly frequent requests. Please keep this in mind when using this project.
43
44## Why use this script?
45
46*Note: What follows is a technical explanation of the inner workings of `speak.pl` and `simple_google_tts`. You don't have to read this to understand how to use this program, but it can help shed some light on the issues you might experience.*
47
48Google imposes a 100-character limit on their speech synthesis service that makes it hard to use their TTS system for anything other than short sentences.
49
50`speak.pl` works around this limitation by breaking the text input down into appropriate chunks. These chunks are set intelligently based on punctuation and syntax of the text. Having processed all chunks `speak.pl` then concatenates the speech fragments into one audio file while truncating segments of silence at the start and end of each fragment.
51
52All of these processing steps ensure a relatively natural voice output and minimize the number of clunky pauses caused by the 100-character limitation. The one remaining problem with this approach is that the waiting time between user input and voice playback scales drastically with the length of the text.
53
54This is where `simple_google_tts` comes in: Instead of passing the text directly to `speak.pl`, `simple_google_tts` first breaks down the input into paragraphs. The paragraphs are then processed one by one with each paragraph being played back while the next one is synthesized. Any length of text can be parsed with reasonable speed in this manner.
55
56Additionally, `simple_google_tts` includes automatic playback, more input modes, an offline TTS back-end, and several adjustments that facilitate parsing of documents with fixed formatting (e.g. [selected text in PDF files](http://superuser.com/a/796341/170160)).
57
58All of this could have probably been accomplished a lot more elegantly within the original `speak.pl` script, but I am not familiar with perl.
59
60## Installation and dependencies
61
62The following instructions are provided for Debian/Ubuntu based systems.
63
64### Dependencies
65
66**Overview of all dependencies**
67
68You can install all dependencies with the following command:
69
70    sudo apt-get install xsel libnotify-bin libttspico0 libttspico-utils libttspico-data libwww-perl libwww-mechanize-perl libhtml-tree-perl sox libsox-fmt-mp3
71
72A breakdown of the dependencies by component and role:
73
74**simple_google_tts**
75
76`xsel` provides support for parsing the X selection contents
77
78
79`libnotify-bin` is used for GUI notifications
80
81
82`pico2wave` provides the offline speech synthesis back-end
83
84The actual audio playback is handled by `sox`, which is part of `speak.pl`'s dependencies.
85
86**speak.pl**
87
88Dependencies, as listed in `speak.pl`'s header:
89
90`libwww-perl libwww-mechanize-perl libhtml-tree-perl sox libsox-fmt-mp3`
91
92Perl should be part of your default Debian/Ubuntu installation.
93
94### Installation
95
961. Install all dependencies
97
982. Clone this repository:
99   
100        git clone https://github.com/Glutanimate/simple-google-tts.git
101
1023. Navigate to the download directory
103
104        cd simple-google-tts
105
106You should be able to run `./simple_google_tts` now. If you wish you can symlink `simple_google_tts` to your `PATH` (e.g. `~/bin` or `/usr/local/bin`) to make it easier to access.
107
108`speak.pl` must always reside in the same directory as `simple_google_tts`.
109
110## Usage
111
112### General usage
113
114    simple_google_tts <options> <languagecode> <input>
115
116E.g.:
117
118    $ simple_google_tts en "Hello World"
119    Reading from string.
120    Using Google for TTS synthesis.
121    Synthesizing virtual speech.
122    Processing 1 out of 1 paragraphs
123    Playing synthesized speech 1
124    All sections processed. Waiting for playback to finish.
125
126### Detailed explanation
127
128`simple_google_tts` can read text from standard input or a text file. The syntax is the same in each case. The script will automatically identify the type of input provided and perform the text to speech synthesis via `speak.pl`.
129
130If no arguments are provided `simple_google_tts` will try to read from the current X selection. This corresponds with the currently highlighted text. Using this functionality you can set up a keyboard shortcut that automatically reads out selected text.
131
132
133At all times you can access an overview of all supported options by invoking the help output:
134
135    $ simple_google_tts -h
136    simple_google_tts [-p|-g|-h] languagecode ['strings'|'file.txt']
137
138        -p:   use offline TTS (pico2wave) instead of Google's TTS system
139        -g:   activate gui notifications (via notify-send)
140        -h:   display this help section
141
142        Selection of valid language codes: en, es, de...
143        Check speak.pl for a list of all valid codes
144
145        Warning: offline TTS only supports en, de, es, fr, it
146
147        If an instance of the script is already running it will be terminated.
148
149        If you don't provide an input string or input file, simple_google_tts
150        will read from the X selection (current/last highlighted text)
151
152### Options
153
154- `-p`: By default `simple_google_tts` will use `speak.pl` to query Google's speech synthesis service and only fall back to `pico2wave` if no Internet connection is found. If you don't want to use Google's TTS service you can use this option to default to `pico2wave` speech synthesis.
155- `-g`: If you plan to assign `simple_google_tts` to a keyboard shortcut you can use this option to enable GUI notifications using `libnotify-bin` (the default notification daemon).
156- `-h`: Display help section
157
158### Supported languages
159
160**Google TTS**
161
162Google's TTS service currently supports the following language codes:
163
164    af  Afrikaans
165    sq  Albanian
166    am  Amharic
167    ar  Arabic
168    hy  Armenian
169    az  Azerbaijani
170    eu  Basque
171    be  Belarusian
172    bn  Bengali
173    bh  Bihari
174    bs  Bosnian
175    br  Breton
176    bg  Bulgarian
177    km  Cambodian
178    ca  Catalan
179    zh-CN Chinese (Simplified)
180    zh-TW Chinese (Traditional)
181    co  Corsican
182    hr  Croatian
183    cs  Czech
184    da  Danish
185    nl  Dutch
186    en  English
187    eo  Esperanto
188    et  Estonian
189    fo  Faroese
190    tl  Filipino
191    fi  Finnish
192    fr  French
193    fy  Frisian
194    gl  Galician
195    ka  Georgian
196    de  German
197    el  Greek
198    gn  Guarani
199    gu  Gujarati
200    ha  Hausa
201    iw  Hebrew
202    hi  Hindi
203    hu  Hungarian
204    is  Icelandic
205    id  Indonesian
206    ia  Interlingua
207    ga  Irish
208    it  Italian
209    ja  Japanese
210    jw  Javanese
211    kn  Kannada
212    kk  Kazakh
213    rw  Kinyarwanda
214    rn  Kirundi
215    ko  Korean
216    ku  Kurdish
217    ky  Kyrgyz
218    lo  Laothian
219    la  Latin
220    lv  Latvian
221    ln  Lingala
222    lt  Lithuanian
223    mk  Macedonian
224    mg  Malagasy
225    ms  Malay
226    ml  Malayalam
227    mt  Maltese
228    mi  Maori
229    mr  Marathi
230    mo  Moldavian
231    mn  Mongolian
232    sr-ME Montenegrin
233    ne  Nepali
234    no  Norwegian
235    nn  Norwegian (Nynorsk)
236    oc  Occitan
237    or  Oriya
238    om  Oromo
239    ps  Pashto
240    fa  Persian
241    pl  Polish
242    pt-BR Portuguese (Brazil)
243    pt-PT Portuguese (Portugal)
244    pa  Punjabi
245    qu  Quechua
246    ro  Romanian
247    rm  Romansh
248    ru  Russian
249    gd  Scots Gaelic
250    sr  Serbian
251    sh  Serbo-Croatian
252    st  Sesotho
253    sn  Shona
254    sd  Sindhi
255    si  Sinhalese
256    sk  Slovak
257    sl  Slovenian
258    so  Somali
259    es  Spanish
260    su  Sundanese
261    sw  Swahili
262    sv  Swedish
263    tg  Tajik
264    ta  Tamil
265    tt  Tatar
266    te  Telugu
267    th  Thai
268    ti  Tigrinya
269    to  Tonga
270    tr  Turkish
271    tk  Turkmen
272    tw  Twi
273    ug  Uighur
274    uk  Ukrainian
275    ur  Urdu
276    uz  Uzbek
277    vi  Vietnamese
278    cy  Welsh
279    xh  Xhosa
280    yi  Yiddish
281    yo  Yoruba
282    zu  Zulu
283
284Please note that, out of these, the `pico2wave` back-end only supports the following languages:
285
286    en  English
287    de  German
288    es  Spanish
289    fr  French
290    it  Italian
291
292### More examples
293
294**Read English text from file**
295
296    simple_google_tts en readme.md
297
298**Read from X selection, using pico2wave, and enable notifications**
299
300    simple_google_tts -gp en
301
302## Known issues
303
304- to prevent simultaneous output the script tries to force only one instance at a time. Unfortunately this fails sometimes, which can be a problem when using the script through a keyboard shortcut
305
306- there is no easy way to terminate the TTS output if the script is used via a keyboard shortcut.
307 
308    Highlighting an empty line or space and then executing the script should, in theory, terminate the last script instance and stop the playback. Because of the first issue this does not always work.
309
310    You could probably assign another hotkey to terminate any running instances of the script (e.g. `pkill -9 simple_google_tts`; warning: I have yet to try this out).
311
312- too many requests too quickly will cause Google to start requesting CAPTCHA input. I have yet to hit this limit in my regular use of the script.
313
314## Similar projects
315
316- [desbma/GoogleSpeech](https://github.com/desbma/GoogleSpeech)
317- [pndurette/gTTS](https://github.com/pndurette/gTTS)
318
319## License
320
321*`speak.pl` copyright 2012 Michal Fapso*
322
323*`simple_google_tts` copyright 2014 Glutanimate*
324
325`simple_google_tts` is licensed under the [GNU GPLv3](http://www.gnu.de/documents/gpl-3.0.en.html). For licensing information concerning `speak.pl` please contact [Michal Fapso](https://github.com/michalfapso).
326
327This project is not endorsed, certified or otherwise approved in any way by Google™.
Note: See TracBrowser for help on using the repository browser.