phonexia/spe repository overview

⁠Quick reference

• Developed by: Phonexia⁠
• Where to get help: SPE API reference⁠, Phonexia Partner Portal⁠
• Where to file issues: Issues can be filed on Phonexia Service Desk⁠ under the "Speech Platform: Speech Engine" product.
• Where to get license: contact Phonexia support at [email protected]⁠

⁠What is Phonexia Speech Engine

Phonexia Speech Engine (SPE) is HTTP server provides REST API designed for developers who want to integrate Phonexia speech technologies.

⁠How to use this image

Note: Pulling an images requires using a specific tag. The latest tag is not supported. See Tag naming⁠ chapter for more info.

Starting a Phonexia Speech Engine version 3.61 with VAD technology:

$ docker run --detach --name some-spe --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat phonexia/spe:3.61-vad

or:

$ docker network create some-network
$ docker run --detach --name some-spe --network some-network --volume /license.dat:/opt/spe/license.dat phonexia/spe:3.61-vad

... where:

• some-network is a newly created network
• some-spe is the name you want to assign to your container
• /license.dat is path to Phonexia license file. Contact our support at [email protected]⁠ to get the license.

SPE is automatically configured, by entry point script, during the start to initialize 1 instance of technology (also 1 instance of stream variant of technology is initialized if available → it will consume another slot from license). See Technologies configuration⁠ chapter for more info.

⁠Connect to Speech Engine server

You can visit API documentation from your web browser: http://localhost:8600/doc⁠ (you need to run SPE with --publish 8600:8600)

or user curl to get SPE status (you need to run SPE with --publish 8600:8600):

$ curl localhost:8600/status

or use phxclient in the image (SPE has to be connected to a some-network network):

$ docker run --rm --network some-network phonexia/spe:3.61-vad phxclient -m GET -u some-spe:8600/status

⁠Technologies configuration

SPE is automatically configured, by entry point script, to start 1 instance of each technology upon container start (also 1 instance of stream variant of technology is initialized if available → it will consume another slot from license). To initialize multiple instances of technology you can use environment variable SPE_N_INSTANCES. You can also set number of workers by variables SPE_N_WORKERS and SPE_N_REALTIME_WORKERS (since SPE 3.55 workers are configured automatically (value -1) according to number of CPUs and number of configured technologies). To use 4 instances run:

$ docker run --detach --name some-spe -e SPE_N_INSTANCES=4 --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat phonexia/spe:3.61-vad

... or you can use environment variable SPE_ENABLE_TECHNOLOGIES. This variable is passed as phxadmin2 technology enable ${SPE_ENABLE_TECHNOLOGIES} command in the entry point script. To configure 3 instances of VAD technology and 1 instance of VAD_STREAM technology run:

$ docker run --detach --name some-spe -e SPE_ENABLE_TECHNOLOGIES="vad:*=3 vad_stream:*=1" --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat phonexia/spe:3.61-vad

... or you can bind your own configuration file to /opt/spe/settings/technologies.xml in the container. Entry point script doesn't configure SPE if the /opt/spe/settings/technologies.xml file already exists. See Data persistence⁠ chapter for more info.

⁠Environment variables

Entry-point script variables:

SPE configuration varaibles:

Column Variable is the name of the environment variable, SPE property is the name of property in settings/phxspe.properties file to which is the variable mapped to.

See data/phxspe.properties.default file for more info:

$ docker run --rm phonexia/spe:3.61-vad cat data/phxspe.properties.default

⁠Additional explanation of semantics

SPE_OUTPUT_STREAM_RTP_TIMEOUT If output stream doesn't send any data for more than given timeout, it is closed. Prevents stuck stream in case client forgets to close stream.

SPE_TECHNOLOGIES_TTS_CONNECTORS Enables external technology Text To Speech. Comma separated list of connector's folder names. By default stored in external/technologies/tts folder. Each connector has to be configured by it's own configuration file, located in it's folder. Template for creating such configuration file can be found in connectors.properties.template file in the connector's folder.

⁠Default values

You can inspect default values of environment variables by run:

$ docker inspect phonexia/spe:3.61-vad

⁠Data persistence

⁠Configuration

SPE configuration is stored in /opt/spe/settings folder. Files phxspe.properties and technologies.xml in this folder are generated automatically upon container start (if don't exist). You can bind your own configuration files by bind the settings folder:

docker run --detach --name some-spe --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat --volume /spe/my_settings:/opt/spe/settings phonexia/spe:3.61-vad

You can edit those files manually. You can also edit technologies.xml file by phxadmin or phxadmin2 utilities. Restart of SPE is required after editing configuration files.

You can list currently configured technologies:

$ docker run --rm --volume /spe/my_settings:/opt/spe/settings phonexia/spe:3.61-vad phxadmin2 technology

You can enable or disable VAD technology:

$ docker run --rm --volume /spe/my_settings:/opt/spe/settings phonexia/spe:3.61-vad phxadmin2 technology enable vad
$ docker run --rm --volume /spe/my_settings:/opt/spe/settings phonexia/spe:3.61-vad phxadmin2 technology disable vad

See help for more info:

$ docker run --rm phonexia/spe:3.61-vad phxadmin2 --help

⁠SPE data

SPE stores data in folders home and shared. SQLite database file is stored in home folder by default. You can make data persistent by bind those folders:

$ docker run --detach --name some-spe --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat --volume /spe/my_home:/opt/spe/home --volume /spe/my_shared:/opt/spe/shared phonexia/spe:3.61-vad

⁠Using Phonexia RLS server

Use environment variable SPE_REPORTING_URLS to confiugure RLS addresses:

$ docker run --detach --name some-spe --publish 8600:8600 --volume /license.dat:/opt/spe/license.dat -e SPE_REPORTING_URLS="server1.com:8777, 192.168.0.10:8777" phonexia/spe:3.61-vad

⁠Using MariaDB database

Start MariaDB database with persistent storage in /mariadb-data folder:

$ docker run -d --network some-network --name mariadb --volume /mariadb-data:/var/lib/mysql -e MARIADB_ROOT_PASSWORD=secret -e MARIADB_DATABASE=phxspe mariadb:latest

Where secret is a password for root user in MariaDB and phxspe is a name of SPE's database.

Run SPE using MariaDB database:

docker run --detach --name some-spe --network some-network --volume /license.dat:/opt/spe/license.dat -e SPE_DB_ENGINE=MariaDB -e SPE_DB_MARIADB_HOST=mariadb -e SPE_DB_MARIADB_USER=root -e SPE_DB_MARIADB_PASSWORD=secret -e SPE_DB_MARIADB_DB=phxspe phonexia/spe:3.61-vad

⁠Use docker-compose

Example docker-compose.yml file for SPE:

version: '3'
services:
  mariadb:
    image: mariadb:latest
    container_name: mariadb
    environment:
      MARIADB_ROOT_USER: root
      MARIADB_ROOT_PASSWORD: secret
      MARIADB_USER: phonexia
      MARIADB_DATABASE: phxspe
    volumes:
      - dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  spe:
    image: phonexia/spe:3.61-vad
    container_name: spe
    links:
      - mariadb
    environment:
      SPE_DB_ENGINE: MariaDB
      SPE_DB_MARIADB_HOST: mariadb
      SPE_DB_MARIADB_USER: root
      SPE_DB_MARIADB_PASSWORD: secret
      SPE_DB_MARIADB_DB: phxspe
    ports:
      - 8600:8600
    volumes:
      - home:/opt/spe/home
      - shared:/opt/spe/shared
      - settings:/opt/spe/settings
      - /spe/license.dat:/opt/spe/license.dat
    depends_on:
      mariadb:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl" ,"-f", "http://localhost:8600/status"]
      timeout: 30s
      retries: 10

volumes:
  dbdata:
  home:
  shared:
  settings:

Where /spe/license.dat is path to license file.

Run docker-compose up -d in the folder with the docker-compose.yml file.

⁠Combining multiple technologies

Example spe-vad-sqe-sid4.Dockerfile file combining VAD, SQE and SID4 technologies:

FROM phonexia/spe:3.61-vad as VAD
FROM phonexia/spe:3.61-sqe as SQE
FROM phonexia/spe:3.61-sid4 as SID4
FROM phonexia/spe:3.61

COPY --from=VAD /opt/spe/bsapi ./bsapi
COPY --from=SQE /opt/spe/bsapi ./bsapi
COPY --from=SID4 /opt/spe/bsapi ./bsapi

Run docker build -t spe-vad-sqe-sid4:3.61 -f spe-vad-sqe-sid4.Dockerfile . in the folder with spe-vad-sqe-sid4.Dockerfile file to build an image.

⁠Tag naming

There are few version naming styles, to make it easy to stay with newest or your preferred version of SPE.

For example we have tag named 3.61.0-vad-generic_3. Where:

• 3.61.0 is version of SPE. If you want to keep track of a new bug-fix releases, you can specify version as 3.61, which will always point to the latest bug-fix version
• vad is name of technology. Supported technologies are: age, denoise, diar, gid, kws, lid, sid, sid4, sqe, stt, tanalysis and vad.
• generic_3 is name of a technology model. Model name can be omitted for some technologies to get default model. For example VAD technology's default model is generic_3 sou you can use tag 3.61.0-vad instead.

We also provide an image without any technology. The tag name contains only the version 3.61.0 or 3.61. Note that the SPE doesn't start with this image due to missing technology. This image is useful as a base image for combining multiple technologies (see the Combining multiple technologies⁠ section for more information)