Skip to contentSkip to main navigation Skip to footer

SPE configuration file explained

In this article we explain details of the Speech Engine configuration file, located in settings subdirectory in SPE installation location.
Settings in this configuration file affect the Speech Engine behavior and performance.

The configuration file is usually created after SPE installation – on first use of phxadmin, default configuration file is created in the settings directory.
The file is loaded during SPE startup, i.e. you need to restart SPE to apply any changes made in the file.
(If for any reason you don’t run phxadmin after SPE installation, you can create the default configuration manually by copying data/ file to settings/ file.)

If Speech Engine is used together with Phonexia Browser in so-called “embedded” mode (see details about “embedded SPE” mode in Browser manual), the configuration file is named This is to keep the “embedded SPE” mode specific configuration separated from the normal configuration.
Changing the file manually won’t have much effect as the file will be overwritten by Browser the next time Browser is run in “embedded SPE” mode.

Below you can find detailed description of all SPE configuration settings, together with some usage tips:

Table of Contents

Generic settings


# IP address and port for server listening
server.bind_ip =
server.port = 8600

IP address and port where SPE listens for REST queries.
The default address means that SPE listens on all local IPv4 addresses. On machines with multiple IPv4 addresses assigned, if SPE should be accessible only on one of them, set the IP address here.
Default port is 8600 and can be changed to any other number suitable for your network.


# Name of server used as ID for RLS and in database log (if 'server.logging.database.identifier' is not specified)
# server.identifier = spe

Optional server name to be used in RLS* reports to identify the server. If it’s not specified, the machine hostname is used.
If it’s not overridden by server.logging.database.identifier value, it is also used to identify the server in logs written into database (writing logs into database can be configured in  server.logging.destination).
By default it’s commented out, i.e. disabled.

* RLS = Reporting and Licensing Server


# Set umask value for server (Linux only)
# server.umask = 0022

Allows to set the umask file permissions value (valid only on Linux).
This setting is by default commented out, i.e. disabled.

Paths, locations


# Home directory path. To this folder are stored all the data of all users.
server.user.home = ${application.dir}home

Path to the home directory where data of all SPE users are stored in individual per-user subdirectories.
Default is a home subdirectory of SPE application directory.

For multi-instance SPE deployments, this can be set to a shared location, so that individual SPE instances can access the common data storage.
Note that the disk subsystem performance (or network throughput, in case of networked storage) can be a limiting factor in such setup – multiple SPE instances would read and write files from/to this location. This should be taken in account when designing the deployment architecture.


# Set path to bsapi directory
# bsapi.path = ${application.dir}bsapi

Path to a directory where data of individual Phonexia speech technologies are stored in per-technology subdirectories.
Defaults to bsapi* subdirectory of SPE application directory

For multi-instance SPE deployments, this can be set to a shared location to save the disk space occupied by individual SPE instances (depending on the number of deployed technologies and their technological models, this directory can take several gigabytes). Centralized common BSAPI location can be also useful for easier maintenance.
Note that the disk subsystem performance (or network throughput, in case of networked storage) can be a limiting factor in such setup – multiple SPE instances would read data from this location during SPE initialization.

* BSAPI = Brno Speech API, the core of Speech Engine, created by Phonexia


# Path to technologies configuration
technologies.configuration = ${application.dir}settings/technologies.xml

Location of technologies configuration XML file.
Defaults to technologies.xml file in settings subdirectory of SPE application directory.

The technologies.xml file contains configuration of  SPE technologies – which technologies should be initialized, their technological models and number of their instances.
The file can be created and maintained using phxadmin application… or even programmatically, since the XML structure is very simple.

For multi-instance SPE deployments, it can be useful to use a shared configuration file to simplify the maintenance.


# Sets path to license file
# server.license = ${application.dir}license.dat

Location of license file.
Defaults to license.dat file in SPE application directory.

For multi-instance SPE deployments, it can be useful to use a shared license file to simplify the maintenance.



# Server logging
# Level (trace, debug, information, warning, error, fatal)
server.logging.level = debug

Controls the logging verbosity. Follows the Apache Commons Logging levels – trace is the most verbose log output, fatal is the least verbose.
Default value is debug.

For troubleshooting or first steps with SPE, we recommend using trace level, to have the most detailed information at hand.
For production servers we recommend to change to information level at most, to prevent unnecessarily oversized logs.


# Destination (console, file, database) - can be comma separated list specifying 
# multiple simultaneous options, e.g. "console,file"
# Logging to database is supported only for MySQL
server.logging.destination = file

Sets one or more logging target(s), where server log is written.
Default value is file.

Logging to database is useful when running multiple SPE instances/machines – logs from all SPEs can be centralized in a database in a structured form for futher processing (analysis, etc.).
Logging to database is supported only with external MySQL, the built-in SQLite is not supported.

When running SPE in console, i.e. not as service, it’s useful to set console,file to see the processing details live in the console, while still having access to the processing history in the log file.
Logging to console is useful in conjuction with trace logging level, e.g. during first steps when you are learning how SPE works… or when watching immediate SPE reactions to REST queries.


# Path to file where log is stored
server.logging.file = ${application.dir}log/phxspe.log

Path and filename to write the log to, if the server.logging.destination setting contains file value.
Default value is ${application.dir}log/phxspe.log, i.e. a phxspe.log file in a log subdirectory of the SPE application directory.


# Log file rotation based on log file size or time intervals
server.logging.file.rotation = daily

Sets the log file rotation strategy. It can be time-based (log file rotated after some period), or size-based (log file rotated after reaching some size).
Default value is daily, i.e. log file is rotated every day.

Further settings details are described directly in the configuration file.


# The value specifies the maximum number of archived log files. If the number is exceeded,
# archived log files are deleted, starting with the oldest.
server.logging.file.purge_count = 5

Sets the log files housekeeping strategy – how many most recent log files to keep.
Default value is 5 days.


# Use separate thread for logging. It may increase speed of logging but in case of server crash or if server is killed,
# some logs may be lost. Default is false.
server.logging.enable_async = false

Sets the log writing strategy – whether logging is done in separate thread, or not.
Logging using separate thread may increase performace, but in case of SPE crash or when SPE is forcefully killed for some reason, information not yet written to log may be lost.
Default value is false, i.e. log writes are performed synchronously, ensuring that all information is written into log.


# Name of server used in log. If it is not specified 'server.identifier' is used instead. If 'server.identifier' is not specified hostname is used instead.
# server.logging.database.identifier = spe

Optional server name to identify database log records written by this SPE instance. Valid only if the server.logging.destination setting contains database value.
If this value is not set, the server.identifier value is used instead. If server.identifier is not set either, the hostname is used to identify the database log records.
By default it’s commented out, i.e. not set.



# Whether server can be started if initialization of some technology fails
# initialization of some technology may fail due to invalid license or insufficient processing capacity left
server.require_all_configured_technologies = false

This setting controls whether all technologies and instances (configured in technologies.xml) must be successfully started during SPE initialization.
The default value is false, which allows SPE to be initialized even if some of the technologies instances fail during startup (e.g. due to insufficient memory, incorrect technology model name, etc.).
If set to true, any failed instance initialization causes the entire SPE initialization to fail and server is terminated.

This feature is useful for all-or-nothing “guaranteed service” implementation – using the true setting ensures that SPE either doesn’t start at all, or starts exactly as configured, i.e. with guaranteed configuration.


# Set multi-thread technology initialization
# When enabled server use multiple thread to speed up initialization of technologies
server.technology_multithread_initialization = false

This setting controls whether technologies initialization during SPE startup should run in multiple parallel threads, or not.
Default value is false, i.e. the initialization runs in single thread.

In single-threaded configuration, technologies and their instances are initialized one-by-one. Depending on the number of configured technologies and instances, it may take longer time to fully initialize the whole system. On the other hand, it’s easier to track down any eventual issues in the log file, since only single initialization happens at a time.

In multi-threaded configuration, technologies and their instances are initialized in multiple parallel threads. This, in general, results in faster initialization of the whole system. A little downside of this configuration is a little messy log file ;-), as the messages are written to the log as they come (still, marked by a thread number), making an eventual troubleshooting a bit harder.
Therefore this configuration is more suitable rather for stable environments, e.g. production deployments.


# Number of threads for initialization of technologies
# Use 0 for automatic detection
server.technology_multithread_initialization.n_threads = 0

Sets the number of parallel threads to be used for technologies initialization. It is a complementary setting to server.technology_multithread_initialization.
Default value is 0, which means that the number of threads will be set automatically to number of CPU cores.

The system needs to read various files of various sizes from the BSAPI location during initialization. Using too many parallel threads may cause the disk- or network subsystem (depending on the bsapi.path location) to become a bottleneck due to its throughput. Therefore it’s recommended to do some experiments and measurements with various threads numbers to find the optimal setting.



# Store results of technologies in database
server.db.save_results = true

Controls whether processing results are cached in the SPE database.
Results caching is enabled by default.

If results caching is enabled, result of processing by each technology is saved to database for each file. Repeated request for processing the same file using the same technology, model, etc. then simply returns the cached result, instead of re-processing the file (this behavior can be overridden using cache_disable=true REST query parameter).


# Type of database
# Suported are SQLite and MySql
server.db.engine = SQLite

Sets the database to be used for storing some internal data (files information, speaker models, keyword lists, etc.) and optionally for caching processing results (see server.db.save_results).
Default value is SQLite, other supported database is MySql. No other databases are suported.


# Set SQLite database file
server.db.sqlite.data_source = ${application.dir}phxspe.sqlite

Path and filename of SQLite database file.
Defaults to phxspe.sqlite file in the SPE application directory.

For multi-instance SPE deployments, it can be useful to use a shared database file, so that all SPE instances can access the same internal data (files information, speaker models, …).
On the other hand, shared SQLite database may create a performance bottleneck, i.e. it’s recommended to do some testing of particular setup.

# Database address
# =

# Database port
# server.db.mysql.port = 3306

MySQL database server address and port.


# Name of database
# server.db.mysql.db = phxspe

# Database user name
# server.db.mysql.user = phonexia

# Database password
# server.db.mysql.password = phonexia

MySQL database name, and username and password for the database.


# Database options
# server.db.mysql.options = compress=true;auto-reconnect=true

# Maximum of MySQL database connections at the time. Default is 32
# server.db.mysql.max_connections = 32

MySQL connection options – see for details.  Note: host, port, db, user and password are set separately, see above.
Maximum number of simultaneous connections to MySQL database to be used by SPE.

Audio Source Profile


# Number of recently used Audio Source Profiles hold in cache, if set to 0, cache is disabled
server.audio_source_profiles_cache_size = 64

See Audio Source Profiles cache for more detials.


# Number of recently used score shifts for false acceptance calibration hold in cache, if set to 0, cache is disabled. Default is 100 000.
# Hold per pair of Audio Source Profile with enabled false acceptance calibration and compared voiceprint.
server.bsapi_comparator_fa_cache_size = 100000

See False Acceptance cache for mor details.



# Authentication mode
# Set true for authentication with sessions
# Set false for basic authentication
server.enable_authentication_token = true

Controls which user authentication mode should SPE accept – whether X-SessionID authentication token, or HTTP Basic authentication.
Default value true enables the X-SessionID authentication, i.e. the HTTP Basic authentication is not available.

Using the authentication token mode (default) means that you need to call the /login endpoint (using HTTP Basic authentication) to get the X-SessionID token and then use this token in HTTP request header for any subsequent REST queries which require authentication.

Using the HTTP Basic authentication (when this setting is set to false) means that you need to use the HTTP Basic authentication – i.e. send the username and password – for each REST query which requires authentication.


# Resource locker
# If enabled every resources (file, speaker model, keyword list etc.) are exclusively locked for modifications during processing. 
# This ensures that resource cannot be modified when it is used for processing
server.enable_resource_locker = true

Controls whether the Resource Locker feature should be turned on or not.
By default it’s enabled, i.e. resources (audio files, speaker models, speaker groups, calibration sets, keyword lists, etc.) used by an asynchronous request are locked by SPE from being modified while they are in use by the request. Trying to modify such locked resource results in a “Resource is locked” error. Locked resources are available for reading and can be used by other requests. The lock is released after finishing the request.

If you disable the Resource Locker, you should make sure that your application fully takes care about such conflicts. Otherwise, modifying a resource while being in use by asynchronous request may create unpredictable results.


# File size Limit for upload and registration
# server.upload_max_filesize = 10MB

Allows to set a file size limit for audio files uploaded to SPE storage, e.g. to prevent oversized files to be uploaded.
By default there is no limit.


# Limit for maximum upload file metadata size
# server.max_metadata_size = 1KB

Allows to set a file size limit for metadata files uploaded to SPE storage, e.g. to prevent oversized files to be uploaded.
By default there is no limit.

Metadata files (AKA metainfo, metafiles) can be attached to audio files, speaker models, calibration sets, or audio source profiles. Metadata files can contain custom additional information related to their attached object.


# Set maximum length of TCP connection queue. 
# if the queue is full, new requests are rejected
# Default is 64
server.tcp.queue = 64

Sets the size of internal queue for incoming TCP connections. Connections waiting in the queue are picked up by a pool of TCP threads (see server.tcp.threads) and processed. If the TCP queue is full, new connections are rejected.
Default value is 64 and normally you should not need to change it.

Changing this value can be useful e.g. if there are some occasional peaks in number of requests to SPE – bigger queue can absorb the peak without rejecting the requests.


# Set maximum threads for TCP connections. 
# The threads fetch TCP connections from TCP queue and process them
# Default is 16
server.tcp.threads = 16

Sets the size of internal pool of TCP processing threads. These processing threads take TCP connections waiting in queue (see server.tcp.queue) and process them.
Default value is 16 and normally you should not need to change it.

Changing the value can be useful in applications bombarding the server by high number of requests – higher number of processing threads makes SPE to handle the requests faster.


# Enable CORS (Cross-origin resource sharing).
# Disabled by default
# server.cors_enable = true

Enables or disables the CORS* support in SPE.
By default is CORS support disabled.

Enabling CORS can be useful when talking to SPE directly from simple web applications based purely on client-side code, without any server middleware (for example web application running from local HTML file – requests are sent from a local file, but responses are coming from SPE… which is something a web browser won’t allow without CORS).

* CORS = Cross-Origin Resource Sharing, see e.g. MDN, W3C or Wikipedia article



# Multithread settings
server.n_workers = 8
server.n_realtime_workers = 8

Sets the number of task workers for processing audio files (server.n_workers) and realtime streams (server.n_realtime_workers).
This is extremely important setting, which may heavily affect the SPE performance.

Basically, if  SPE is used to process only audio files, the server.n_workers should be set to number of physical CPU cores  of the machine.
It is highly recommended to read more details in How to configure SPE workers article.
Additional info about SPE workers is avaialble in Speech Engine and technologies, instances, workers… explained article.


# Sets limit for number of pending operations.
server.n_task_limit = 1000

Sets the maximum number of “pending” tasks (see the asynchronous requests statuses in REST API documentation).

This value basically sets the size of processing queue and therefore indirectly defines how quickly would the server be able to react to changes.
E.g. if the server is busy processing a 1000 tasks and you would want to quickly process some additional files, you would either need to cancel the 1000 pending tasks, or use the task priorities feature… If the queue would be smaller, it would be processed in a reasonable time, i.e. it would not be necessary to cancel the pending tasks (or use priorities) because the new processing requests would get processed quickly enough.

Additional info about SPE processing queue is available in Understanding SPE processing queue article.


# If enabled, server will respects priority of a task configured by HTTP header.
# Only users with role 'prioritize' can create task with non-default priority.
# Default is true
server.task_priorities_enable = true

Controls whether SPE will support setting task priorities using X-Priority request HTTP header.
Task priorities are by default enabled.

Using task priorities can be useful in mass-processing applications – if there is a long queue of files waiting to be processed, and one needs to urgently process another bunch of files, these files can be sent for processing using higher priority. These files are then injected to the queue front and processed as soon as possible.
You can get more information about task priorities in Task prioritization section of REST API documentation and in Understanding SPE processing priority article.


# Task default priority. Priority must be number from 0 to 99. This priority will be set 
# to each task if request doesn't contains any priority or if user doesn't have permission to set it.
# 0 is the highest and 99 is the lowest priority. Default value is 50
server.task_default_priority = 50

Sets the default task priority value. If task priorities are enabled, and task priority is not explicitly specified when creating the task, this priority value will be used.
Default value is 50.


# Timeout auto remove finished task
server.finished_task_timeout = 60

Sets the timeout in seconds, after which finished tasks are automatically removed.
Default is 60 seconds.

This is related to using polling to get results of asynchronous tasks, see Asynchronous request – Polling section of REST API documentation.
When polling for asynchronous task result using either GET /pending/{id} or GET /done/{id}, the result of finished task is available for picking up only for a limited time (60 seconds by default). After this time, the result expires and the GET returns HTTP status 404.
In such case, the only way to get the result is to request re-processing of the file – if results caching is enabled, the result is returned from cache (i.e. file is not physically re-processed again).



# Enable HTTP stream subsystem
stream.http.enable = true

Controls whether HTTP streams support is enabled or disabled.
By default, HTTP stream support is enabled.


# Set timeout for input HTTP stream in seconds.
# If the input stream doesn't recieve any data for given time, then input stream is closed.
# ! Note that 'stream.http.timeout' is deprecated since SPE 3.23.x
input_stream.http.timeout = 30

Sets the timeout limit for HTTP stream incoming data – when no audio data come from the stream for the defined time, the stream is automatically closed.
Default value is 30 seconds.


# Enable RTP stream subsystem
stream.rtp.enable = true

Controls whether RTP streams support is enabled or disabled.
By default, RTP stream support is enabled.


# IP address for creating input RTP sessions 
# ! Note that 'stream.rtp.bind_ip' is deprecated since SPE 3.23.x
input_stream.rtp.bind_ip =

Sets the IP address on which the incoming RTP listeners should listen.
Default value is, i.e. all local IPv4 addresses. On machines with multiple IPv4 addresses assigned, if RTP listeners should listen only on one of them, set the IP address here.


# Sets starting port for creating input RTP sessions
# ! Note that 'stream.rtp.min_port' is deprecated since SPE 3.23.x
# ! Note that 'stream.rtp.max_port' is deprecated since SPE 3.23.x
input_stream.rtp.min_port = 10000
input_stream.rtp.max_port = 11000

Sets the port number range for creating incoming RTP listeners.
Default is from 10000 to 11000.


# Number of max opened input RTP sessions in one moment
# ! Note that 'stream.rtp.stream_limit' is deprecated since SPE 3.23.x
input_stream.rtp.stream_limit = 10

Sets the maximum number of simultaneous RTP sessions.
Default value is 10.

This value should play well together with server.n_realtime_workers value and also with number of initialized instances of stream technologies.
Additional info can be found in How to configure SPE workers article and also in Speech Engine and technologies, instances, workers… explained article.


# Set timeout for input RTP socket in seconds.
# If the input RTP socket don't receive any data for a given time, then the input RTP socket is closed.
# ! Note that 'stream.rtp.timeout' is deprecated since SPE 3.23.x
input_stream.rtp.timeout = 10.0

Sets the timeout limit for RTP stream incoming data – when no audio data come from the stream for the defined time, the stream is automatically closed.
Default value is 10 seconds.


# Set timeout for output stream RTP socket in seconds.
# If output stream doesn't send any data for more than given time it is closed.
# Prevents stuck streams in case client forgets to close stream.
# (this may occur when client dies or loses output stream ID in some other way)
output_stream.rtp.timeout = 60.0

Sets the timeout limit for RTP stream outgoing data – when no audio data is sent to the stream for the defined time, the stream is automatically closed.
Default value is 60 seconds.

Output RTP streams are used e.g. for text-to-speech output, or for audio files playback.

Audio formats


# Enable or disable native support for OPUS audio format (Default: true)
# When disbled, audio file will be converted to WAV
server.audio_formats.opus.enabled = true

Controls whether the OPUS audio format support is enabled or disabled.
By default it’s enabled.


# Enable or disable native support for FLAC audio format (Default: true)
server.audio_formats.flac.enabled = true

Controls whether the FLAC audio format support is enabled or disabled.
By default it’s enabled.


# Enable or disable audio converter
audio_converter.enabled = false

Controls whether support for automatic audio format conversion is enabled or disabled.
By default, audio converter is disabled. This is because it requires external 3rd party converter which needs to be set up separately.

Audio converter allows transparent processing of audio formats not natively supported by SPE.
When audio converter is enabled and correctly configured, audio files in formats not natively supported by SPE are internally automatically converted to WAV PCM 16-bit, 8 kHz. See audio_converter.command for more details.


# Set converter command
# %1 is for input file
# %2 is for output file
# ffmpeg example:
# audio_converter.command = ffmpeg -loglevel warning -y -i %1 %2
# sox example:
# audio_converter.command = sox %1 %2
audio_converter.command = ffmpeg -loglevel warning -y -i %1 %2

Sets the command to be used when audio_converter.enabled is set to true.
We provide simple examples for ffmpeg (default) and sox, but any other command line conversion utility, which allows specifying input and ouput file names (using %1 and %2 placeholder, respectively) can be used.

Note that due to licensing restrictions we do not distribute neither ffmpeg, nor sox or other converter with SPE. These need to be downloaded and installed separately.
Tip: On Windows, simply put the ffmpeg.exe or sox.exe file to SPE installation directory.



# Reporting server addresses
# Comma separated list of URLs
# reporting.urls =,

Allows to set address(es) and port(s) of RLS* to which SPE should connect to a) get information about allowed processing capacities, b) report consumed processing capacities.
By default it’s not enabled as connection to RLS has to be specifically enabled by a flag in SPE license.

Multiple RLS addresses can be specified, so that if SPE cannot contact first RLS (e.g. due to connection issues, RLS being down, etc.), it can try to contact other RLS(s).

* RLS = Reporting and Licensing Server


# Enable/disable SSL connection for sending reports to reporting server
reporting.ssl.enabled = false

Controls whether SSL should be used for connection between SPE and RLS, or not.
By default, SSL is disabled.


# Set path to Root CA certificate
# reporting.ssl.ca_file = ./root_ca.crt

Sets path to root certificate authority certificate file, for SSL support.
By default it’s commented out, as SSL support is disabled by default.


# Path to certificate file
# reporting.ssl.certificate_file = ./spe_certificate.crt

Sets path to certificate file, for SSL support.
By default it’s commented out, as SSL support is disabled by default.


# Path to private key file
# reporting.ssl.private_key_file = ./spe_private.key

Sets path to private key file, for SSL support.
By default it’s commented out, as SSL support is disabled by default.


# Private key password. Leave empty or commented out, when password is not used
# reporting.ssl.private_key_password =

Sets password for private key, if used. If private key is not password-protected, leave this settign blank or commented out.
By default it’s commented out, as SSL support is disabled by default.


# Set SSL cipher list (default: ALL:!COMPLEMENTOFDEFAULT:!eNULL)
# For more details, see
# reporting.ssl.cipher_list = ALL:!COMPLEMENTOFDEFAULT:!eNULL

# Set SSL cipher list (default: ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH)
# For more details, see
# reporting.ssl.cipher_list = ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH

Sets list of ciphers to use when SSL is enabled for reporting. The list should use OpenSSL cipherlist format,
see (SPE <= 3.38)
or (SPE >= 3.40) for more information.
By default it’s commented out, as SSL support is disabled by default.



# Enable external TTS (Text To Speech) connectors.
# A comma separated list of connector's folder names.
# Connectors can be found in 'external/technologies/tts' folder.
# Each connector needs configuration file '' in its folder. 
# Please create configuration according to '' file before you enable it.
# external.technologies.tts_connectors = acapela

Sets external TTS (Text To Speech) connectors to be initialized during SPE startup.
It should be a list of directory names located in external/technologies/tts directory, separated by comma.

Phonexia provides TTS connector (currently available for Linux only) for Acapela TTS Server.
Note: You need to have your own Acapela TTS Server installation and licese in order to use the Acapela TTS connector.