109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# What is it?
|
|
TTS Server is an Android-only application that provides a REST-based interface for on-board
|
|
TTS engine of your device. The application is aimed on home automation and allows you to give
|
|
a second life to your old smartphone, which can now act as a standalone, all-inclusive web TTS
|
|
provider for your speech-based home notification system.
|
|
|
|
# For what?
|
|
Android is provided with a great *offline* TTS engine for almost every language on the
|
|
world.
|
|
If you care about high availability of the web TTS provider or you don't want your notifications
|
|
go through the Internet to the cloud providers, you can utilise your smartphone to done the job.
|
|
|
|
|
|
# How does it work?
|
|
TTS Server runs a service with HTTP server that exposes endpoints allowing you
|
|
to perform TTS task. As the Android implements its own process-killer, the application needs
|
|
to run the service *on the foreground* (so the notification is always shown)
|
|
keeping it alive and preventing it from being killed. Because of that, keep in mind that
|
|
the application might drain your battery, so it is recommended to use it *only*
|
|
on the devices being always connected to the power source.
|
|
|
|
|
|
# Consuming REST interface
|
|
So far, the application provides two endpoints: `/say`, `/wave`, `/sonos` and `/sonos/{fileName}`.
|
|
Each data-accepting endpoint works with JSON-based body, so each request carrying the data
|
|
requires a proper `Content-Type` header.
|
|
|
|
## The `/say` endpoint
|
|
```
|
|
POST /say
|
|
{
|
|
"text": "The text to be spoken",
|
|
"language": "en_US"
|
|
}
|
|
```
|
|
*Returns:* `200 OK` with empty body
|
|
|
|
The `/say` endpoint allows you to perform TTS task using device's speakers or the
|
|
external ones connected to it via jack, Bluetooth etc. For example if you have some
|
|
old PC-speakers you are able to connect your device to them via line port and
|
|
get a complete speech-based notification system.
|
|
|
|
|
|
## The `/{wave,acc,mp3,m4a,wma,flac}` endpoint
|
|
```
|
|
POST /{wave,acc,mp3,m4a,wma,flac}
|
|
{
|
|
"text": "The text to be spoken",
|
|
"language": "en_US"
|
|
}
|
|
```
|
|
*Returns:* `200 OK` with proper audio file
|
|
|
|
This endpoint enables you to download an audio file file containing speech of the
|
|
provided text. The goal of this endpoint is to provide interface allowing you establishment
|
|
of the connection between the TTS Server and some other kind of already running TTS system,
|
|
which can invoke the HTTP request to your Android device and do something with returned
|
|
audio file. Note that all files but wav originates right from the wav file through FFmpeg
|
|
converter.
|
|
|
|
## The `/sonos` endpoint
|
|
```
|
|
POST /sonos
|
|
{
|
|
"text": "The text to be spoken",
|
|
"language": "en_US",
|
|
"zone": "Living room",
|
|
"volume": 60
|
|
}
|
|
```
|
|
*Returns:* `202 Accepted` meaning that the request has been queued and waits
|
|
to be completed.
|
|
|
|
The `/sonos` endpoint enables you to use your Sonos devices as a TTS speakers.
|
|
You need just to provide a text to be spoken and a desired zone name, where message is
|
|
supposed to be spoken. In the contrast to other endpoints, the `/sonos` endpoint
|
|
is non-blocking, which means your request is *accepted* and pushed at the end of
|
|
queue, where you are immediately given with response. The message waits in the queue to be
|
|
spoken protecting the Sonos device from messages race condition problem.
|
|
|
|
|
|
## The `/sonos/{fileName}` endpoint
|
|
```
|
|
GET /sonos/{fileName}
|
|
```
|
|
*Returns:* `200 OK` with wave file (`Content-Type: audio/x-wav`)
|
|
|
|
This endpoint is designed for serving synthesized wave files by `/sonos` endpoint
|
|
to Sonos devices and is not intended to be used directly by you. After hitting
|
|
the `/sonos` endpoint, requested message is synthesized to wave file which is being
|
|
served through the `/sonos/{fileName}` endpoint and Sonos device is requested to
|
|
change its source stream URL to this file. The already generated files are stored in cache
|
|
directory so there is no need to resynthesize frequently-used message which reduces
|
|
the overall time needed to complete the request. You are still able to invalidate
|
|
this cache via application settings.
|
|
|
|
|
|
## The `/gong.wav` endpoint
|
|
```
|
|
GET /gong.wav
|
|
```
|
|
*Returns:* `200 OK` with gong wave file (`Content-Type: audio/x-wav`)
|
|
|
|
This endpoint is designed for serving gong wave to Sonos devices
|
|
and – similar to `/sonos/{fileName}` – is not intended
|
|
to be used directly by you. If gong is enabled in the settings,
|
|
Sonos is requested to change its source stream URL to a gong
|
|
file prior to the actual announcement being served by `/sonos/{fileName}` endpoint.
|