Directory Structure

A good understanding of the SPE directory structure helps in understanding the inner workings of SPE and simplifies troubleshooting. It is also useful for expert-level tuning of individual technology parameters and optimizing SPE configuration, such as for deployments with shared resources or in virtualized environments.

The SPE directory structure looks like this (the tree depth is limited for better readability):

{SPE_installation_directory}
├── bsapi
│   ├── age
│   │   ├── data
│   │   ├── example
.   .   └── settings
.   .
.   .
│   └── vad
│       ├── data
│       ├── example
│       └── settings
├── data
│   ├── benchmark
│   └── database
│       ├── MariaDB
│       ├── SQLite
│       └── MySQL - obsolete
├── doc
├── EULA
├── external
│   └── technologies
│       └── tts
├── home
│   └── admin
│       ├── data
│       └── storage
├── lib
├── log
├── settings
└── shared

bsapi

The bsapi directory contains the BSAPI core subsystem, i.e. all files and data of the speech technologies themselves. This directory contains a separate subdirectory for each technology included in the distribution package. The number of subdirectories depends on which technologies are included in the particular SPE installation. For testing and first-time evaluation, we usually include the full set of technologies, other installations may contain only a limited subset.

The location of the bsapi directory can be modified using bsapi.path option in SPE configuration file. This might be useful in complex network infrastructure, for sharing technologies between multiple SPEs, and similar advanced configurations.

bsapi
  ├── age
  ├── denoiser
  ├── diar
  ├── gid
  ├── kws
  ├── lid
  ├── sid4
  ├── sqe
  ├──stt
  ├── tae
  └── vad

Each individual technology directory typically contains three main subdirectories:

Directory	Description
`data`	Technology data, stored in separate directories for individual technological or language-specific models.
`example`	Audio files for quick testing, sometimes also stored in separate directories for individual models.
`settings`	BSAPI configuration files (`.bs`) and optionally manually created user configuration files (`.bs.usr`).

caution

There is one exception: LID (Language Identification) has additional two directories containing pre-built languageprint archives (*.lpa) and language packs: lprints and models.

Schemes below show examples of directories for GID (Gender Identification), STT (Speech to Text) and LID (Language Identification):

GID and LID with data for XL3 and L4 models.
STT with data for the 5th generation English language and the 6th generation Czech language.

gid                 stt                          lid
├── data            ├── data                     ├── data
│   ├── l4          │   ├── models_cs_cz_6       │   ├── l4
│   └── xl3         │   └── models_en_us_5       │   └── xl3
├── example         ├── example                  ├── example
│   ├── l4          │   ├── cs_cz_6              │   ├── l4
│   └── xl3         │   └── en_us_5              │   └── xl3
└── settings        └── settings                 ├── lprints
                                                 │   ├── l4
                                                 │   └── xl3
                                                 ├── models
                                                 │   ├── l4
                                                 │   └── xl3
                                                 └── settings

data

The data directory contains various SPE operational data: default SPE configuration file, example init.d script, example systemd service unit file, built-in benchmark audio files and database SQL scripts.

data
├── phxspe.properties.default
├── init.d-phxspe.template
├── phxspe.service.template
│
├── benchmark
└── database

File Name	Description
`phxspe.properties.default`	Default `phxspe.properties` SPE configuration file.
`init.d-phxspe.template`	Example SPE init.d script.
`phxspe.service.template`	Example SPE systemd service unit file.
`benchmark`	Default audio files for built-in benchmark functionality.
`database`	Database SQL scripts for supported databases: SQLite, MariaDB, and MySQL.

The file phxspe.properties.default is used by the phxadmin tool. When phxadmin is run, it checks for the phxspe.properties file in the {SPE}/settings directory and if the file does not exist, it's created as a copy of this phxspe.properties.default file. This typically happens when phxadmin is run for the first time after SPE installation.

The init.d-phxspe.template or phxspe.service.template file can be used by SPE administrator to create init.d script or a systemd service unit file for running SPE as service under Linux. The SPE administrator should make a copy of the corresponding template and modify it to fit the local installation (mainly paths). (To run SPE as service under Windows, use the /registerService or /unregisterService parameters of SPE for Windows. See phxspe /help for details.)

The benchmark directory contains a default audio file for built-in benchmark functionality. For more details refer to Speech engine benchmark article and .../benchmark REST API endpoint of each technology in the article SPE REST API documentation.

The database directory contains SQL scripts for setup, maintenance, and updates of supported databases. See more details in the article Speech engine database scripts.

doc

The doc directory contains various documentation.

File Name	Description
`api_reference.html`	Default REST API documentation, also available online at https://download.phonexia.com/docs/spe/
`INSTALL.html, INSTALL.txt`	Quick installation guide in HTML and TXT formats
`UPDATE.txt`	Quick update instructions and SPE configuration file changes between SPE versions
`result_versions.txt`	List of REST API result versions
`Phonemes_for_STT_and_KWS.pdf`	List of STT/KWS phonemes, useful for keyword pronunciation definitions
`Technology_LID_L4_Language_tags.pdf`	List of LID L4 language tags and more details about the languages they refer to

EULA

EULA directory contains Phonexia EULA in PDF format.

The directory structure is technologies/{technology_name}. Currently, tts is the only supported technology.

For TTS (Text to Speech) technology, the directory structure is tts/{TTS_provider_name}. Inside the TTS provider directory SPE expects an executable named connector. For details about the TTS connectors, see Connectors for external TTS article.

external

The external directory is intended to hold connectors for external components. This directory currently exists only in SPE for Linux since the only connector supported out-of-the-box exists for Linux only.

external
└── technologies
    └── tts
        └── acapela
            ├── connector
            ├── connector.properties.template
            .
            .
            .

The directory structure is technologies/{technology_name}. Currently, tts is the only supported technology.

For TTS (Text-To-Speech) technology, the directory structure is tts/{TTS_provider_name}. Inside the TTS provider directory SPE expects an executable named connector. For details about the TTS connectors, see Connectors for external TTS article.

home

The home directory holds subdirectories for individual users configured in SPE, and these directories contain data belonging to each user. SPE comes with an admin user preconfigured by default, so directories for admin user are present by default.

The location of the home directory can be modified using server.user.home option in SPE configuration file. This might be useful in complex network infrastructures, multi-SPE deployments, and similar advanced configurations.

home
└── admin
    ├── storage
    └── data

The storage directory holds audio files uploaded to SPE via REST API by the user. This directory maps to the root of the SPE storage for that user, i.e. files and directories uploaded/created in the SPE storage via API are stored here. Similarly, files and directories created directly on the filesystem (i.e., "outside" of the REST API) in this directory, are accessible to the API after file registration via POST /audiofile/registration.

The data directory holds additional data files for entities created by the user: e.g., SID Speaker models, or LID language packs. If there no such entities exist for that user, this directory is empty. Here is an example of admin's data directory containing a custom LID language pack for model L4 and SID speaker models named "David" and "Paul" (the tree depths are limited for better readability):

home
└── admin
    └── data
        ├── lid
        │   └── languagepack
        │       └── L4
        └── sid
            └── model
                ├── David
                └── Paul

The home directory can also optionally contain a phxserver.sqlite file. This is a main SPE database file when SPE is started by Phonexia Browser in so-called "embedded" mode. Refer to Phonexia Browser manual for more information about the "embedded SPE" mode.

lib

The lib directory contains shared runtime .so libraries. This directory currently exists only in SPE for Linux. On Windows, shared .dll libraries are placed directly in the root of the SPE installation directory.

log

The log directory contains SPE log files. The default log base name is phxspe.log and can be changed in the SPE configuration file. Optionally, there might also be a phxspe.browser.log file present. This is a log file produced by SPE when it is started by Phonexia Browser in the so-called "embedded" mode. Refer to the Phonexia Browser manual for more information about the "embedded SPE" mode.

The location and name of SPE log files can be modified using the server.logging.file option in the SPE configuration file. This might be useful in complex network infrastructures, multi-SPE deployments, and similar advanced configurations.

log
├── phxspe.log
└── phxspe.browser.log

settings

The settings directory contains the SPE configuration file phxspe.properties and the technologies configuration file technologies.xml. Optionally, there might also be phxspe.browser.properties and technologies.json files present. These are configuration files created by SPE when it is started by Phonexia Browser in the so-called "embedded" mode. Refer to the Phonexia Browser manual for more information about the "embedded SPE" mode.

The location and name of the technologies configuration file can be modified using the technologies.configuration option in the SPE configuration file. This might be useful in complex network infrastructures, multi-SPE deployments, and similar advanced configurations.

settings
├── phxspe.properties
└── technologies.xml

shared

The shared directory exists only in SPE 3.41 or newer and is intended to hold (customized) technology models shared by all SPE users. Historically, customizations were registered for a particular SPE user only (e.g., when registering a LID language pack using phxadmin --add-language-pack). Placing the customized technology model in the shared directory makes it available to all users.

The shared directory should contain a bsapi subdirectory with the same structure as the main directory in the root of the SPE installation (see above). The example below shows a shared customized STT CS_CZ_6 model.

The location of the shared directory can be modified using the server.shared.path option in the SPE configuration file. This might be useful in complex network infrastructures, multi-SPE deployments, and similar advanced configurations.

shared
└── bsapi
    └── stt
        ├── data
        │   └── models_cs_cz_6_customized
        └── settings
            ├── stt_cs_cz_6_customized.bs
            └── stt_cs_cz_6_customized_online.bs

bsapi​

data​

doc​

EULA​

external​

home​

lib​

log​

settings​

shared​