Understand SPE directory structure

Good understanding of SPE directory structure helps to better understand the inner workings of SPE and simplifies troubleshooting.
It’s also useful for expert-level tuning of parameters of individual technologies and optimizing SPE configuration e.g. for deployments with shared resources, or deployments in virtualized environments, etc.

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

bsapi directory contains the BSAPI core subsystem, i.e. all files and data of the speech technologies itself. This directory contains 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 limited subset.

Location of 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 contains typically three main subdirectories:

There is one exception – LID – which 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 5^th generation English language and 6^th 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

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

The phxspe.properties.default file is used by phxadmin tool – when phxadmin is run, it checks for phxspe.properties file in {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 systemd service unit file for running SPE as service under Linux.
SPE administrator should make a copy of 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 default audio file for built-in benchmark functionality – see more details in Understanding SPE benchmark article and .../benchmark REST API endpoint of each technology in SPE REST API documentation.

The database directory contains SQL scripts for setup, maintenance and updates of supported databases. See more details in Understanding SPE database scripts.

doc

doc directory contains various documentation

EULA

EULA directory contains Phonexia EULA in PDF format

external

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 Understanding SPE connectors for external TTS article.

home

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

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

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

The storage directory holds audio files uploaded to SPE via REST API by that 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 for the API after file registration via POST /audiofile/registration.

The data directory holds additional data files for entities created by that 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 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

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

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 SPE installation directory root.

log

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 be also a phxspe.browser.log file present. This is a log file produced by SPE when it’s started by Phonexia Browser in so-called “embedded” mode. Refer to Phonexia Browser manual for more information about the “embedded SPE” mode.

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

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

settings

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

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

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

shared

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 are registered for particular SPE user only (e.g. when registering LID language pack using phxadmin --add-language-pack). Putting the customized technology model in shared directory makes it available for all users.

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

Location of shared directory can be modified using server.shared.path option in SPE configuration file. This might be useful in complex network infrastructure, 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