> How SPX is configured from config file? All [[Documentation/Server/Overview|SPX Server]] configurations can be found in `config.json` in the root SPX folder and most used settings are available on the Application Configuration page from the main menu. --- ## Authentication ### `general.users` (Added in v1.2.2) Defines the list of user accounts that can log in to SPX. Each entry has a `username` and a `password` (stored encrypted — never in plain text). ```json "users": [ { "username": "operator", "password": "" }, { "username": "admin", "password": "" } ] ``` **Behavior:** - When `users` is an empty array, authentication is disabled and anyone can access SPX. - When one or more users are present, a login screen is shown and only listed users can sign in. - Leave `password` as an empty string `""` for a new account — SPX will prompt that user to create a password on their first login. **Adding users:** Users are added by editing `config.json` directly. 1. Add an entry to the `general.users` array with the desired `username` and set `password` to `""`. 2. The user will be asked to set their own password the first time they log in. SPX does not need to be restarted for a newly added user to be able to log in. > [!note] There is no limit to the number of users you can add. > Give each operator their own account so sessions can be distinguished in logs. > [!warning] When authentication is enabled, [[#API Keys|API keys]] are also required for API access. ## Server Identification ### `general.hostname` Identifies the SPX instance for logging purposes. ```json "hostname": "My main machine" ``` **Use cases:** - Distinguishing multiple instances in logs - Identifying instances in multi-server setups - Mostly for future use and logging ## Localization ### `general.langfile` File reference in `locales`-folder for a JSON file containing UI strings in that language. ```json "langfile": "english.json" ``` The `locales` folder is scanned at server start and files are shown in the configuration as language options. **Available Languages:** - English (default) - Dutch (v1.0.12) - Chinese (v1.1.0) - Swedish (v1.1.2) - Portuguese (v1.1.2) - Japanese (v1.3.0) - German (v1.3.3) > If you're interested in translating SPX user interface to your local language, see [SPXLocaleEditor](https://github.com/TuomoKu/SPXLocaleEditor) repository for a browser-based utility. ## Logging ### `general.loglevel` Controls the verbosity of log messages. **Values:** - `error` - Least logging (errors only) - `warn` - Warnings and errors - `info` - Default value (informational messages) - `verbose` - Recommended for troubleshooting - `debug` - Most log data (for deep analysis) **Default:** `info` Log messages are shown in the SPX console window and stored in log files in the logfolder. The active file is named `access.log`. > **Tip:** Remember to set log level back to `info` after troubleshooting, as heavy logging will increase disk usage and may affect software performance. ### `general.logfolder` Path to the folder where log files are stored. ```json "logfolder": "X:/SPX/LOG/" ``` ## Network Settings ### `general.port` The port number on which SPX server listens. ```json "port": "5656" ``` **Default:** `5656` Change this if the port is already in use or you need multiple instances. ## HTTPS By default SPX runs over plain HTTP. Enabling HTTPS encrypts all traffic between the browser and the server, which is recommended when SPX is accessed over a network or from the internet. ### `tls.enable` Set to `true` to enable HTTPS. ```json "tls": { "enable": true, "keyPath": "/path/to/spx-key.pem", "certPath": "/path/to/spx.pem" } ``` **Fields:** | Field | Description | |-------|-------------| | `enable` | `true` to start the server over HTTPS, `false` to use plain HTTP (default) | | `keyPath` | Absolute path to the private key file (`.pem`) | | `certPath` | Absolute path to the certificate file (`.pem`) | **Behavior:** - When enabled, SPX reads the key and certificate files at startup and serves all traffic over HTTPS. - If the certificate files cannot be read, SPX logs a warning and falls back to HTTP automatically — the server will still start. - Once HTTPS is active, the web renderer URL and API base URL will use `https://` and `wss://` respectively. **Getting a certificate:** You can use any certificate trusted by your browser or operating system: - **Self-signed** — sufficient for a closed local network; browsers will show a security warning on first visit that you can accept. - **Let's Encrypt** — free, trusted certificates for publicly reachable servers. - A certificate issued by your organisation's internal CA. > [!note] A server restart is required after changing any TLS setting or replacing the certificate files. ## License Server By default SPX validates its license locally using a license file on the machine. When a License Server is present on the network, SPX can be configured to check out a license from it instead — this is common in multi-seat deployments where a single license server manages access for multiple SPX instances. ### `useLicenseService` ```json "useLicenseService": { "enable": true, "licenseType": "spx-broadcast", "server": "http://localhost:6660", "retry": { "enable": true, "duration": 2 }, "activationRetryDuration": 10 } ``` **Fields:** | Field | Description | |-------|-------------| | `enable` | `true` to use the License Server instead of a local license file | | `licenseType` | The product being activated (e.g. `spx-broadcast`) | | `server` | URL of the License Server, including port | | `retry.enable` | `true` to keep retrying activation if the License Server is temporarily unavailable at startup | | `retry.duration` | How long to keep retrying at startup, in minutes (default: `2`) | | `activationRetryDuration` | How long SPX will wait for an available license slot if all slots are occupied, in minutes (default: `10`) | **Behavior:** - At startup SPX contacts the License Server to check out a license slot. If the server is unreachable and `retry.enable` is `true`, SPX will keep retrying for up to `retry.duration` minutes before giving up and shutting down. - Once activated, SPX sends periodic keep-alive pings to the License Server to hold its slot. If two consecutive keep-alive pings fail, SPX restarts automatically to re-establish the connection. - When SPX shuts down gracefully it releases its slot back to the License Server, making it available for another instance. - If all license slots are occupied, SPX will wait up to `activationRetryDuration` minutes for a slot to become free before shutting down. > [!note] The License Server URL must be reachable from the machine running SPX. > A server restart is required after changing any `useLicenseService` setting. ## File Paths ### `general.dataroot` Path to the folder where [[Documentation/Graphics Controller/Project Settings|projects]] and [[Documentation/Graphics Controller/Rundown Settings|rundowns]] are stored. ```json "dataroot": "X:/SPX/DATAROOT/" ``` **Structure:** - Projects are subfolders in the dataroot folder - Rundowns are JSON files in project subfolders - Project settings are stored in `profile.json` within each project folder ## Template Source ### `general.templatesource` (Added in v1.0.9) For [[Documentation/Renderer/Workflows/CasparCG - AMCP|CasparCG]] playout, [[Documentation/Graphic Templates/Overview|templates]] can be loaded from the filesystem or via HTTP connection provided by SPX. **Supported values:** - `spx-ip-address` - Automatically use SPX's IP address and HTTP protocol for playing out templates from SPX's template folder (default) - `casparcg-template-path` - Playout templates from target CasparCG server's file system template-path (see `caspar.config` file) - `http://<ip-address>` - Manually entered address when automatically generated IP is not usable (e.g., Docker containers, VM hosted instances) > [!note] `templatesource` only affects CasparCG playout, not [[Documentation/Renderer/Web Render|web playout]]. Also, `file://` protocol is more restrictive in using external data sources and can yield JavaScript errors, such as CORS. ## Preview Settings ### `general.preview` (Version 1.1.0+) Controls which event on the [[Documentation/Graphics Controller/Rundown Settings|rundown]] triggers a preview in the [[Documentation/Renderer/Preview & Program|preview renderer]]. **Values:** - `selected` - Preview will play whenever a focus is changed on the rundown (default) - `none` - Preview will not be triggered - ~~`next`~~ - Preview will play the next item from the rundown when an item is played (coming later) Any output [[Documentation/Renderer/Overview|renderer]] is treated as a preview renderer if `preview=true` parameter is present in the renderer URL. ## Renderer Display ### `general.renderer` (Version 1.1.0+) Option to have the [[Documentation/Graphics Controller/Local Renderer|local renderer]] in traditional position at the top right corner of SPX UI or taken out to a floating window. **Values:** - `normal` - Inline renderer view (default) - `popup` - Renderer in a floating window "popup" > [!note] Popup blocker may prevent popup from working as expected. ### `general.resolution` (Version 1.3.0+) Affects output from SPX [[Documentation/Renderer/Resolutions|renderer viewport size]]. **Values:** - `HD` - 1920 x 1080 pixels (16:9) - Default - `4K` - 3840 x 2160 pixels (16:9) - `AUTO` - Full output height and width of the browser viewport rendering the template > [!note] Templates will also need to support the set size and aspect ratio. Most templates are implemented or optimized for 16:9 aspect ratio and 1920x1080 output size. ## Browser Launch ### `general.launchBrowser` Controls whether the browser is automatically opened when the server starts. ```json "launchBrowser": false ``` **Default:** `false` Set to `true` to automatically open the browser on every server start. ## Advanced Options ### `general.disableConfigUI` Disables the web-based configuration interface. ```json "disableConfigUI": true ``` When enabled, configuration must be done manually by editing the config file. ### API Keys API keys let you restrict who can send commands to SPX through the [[Documentation/Control Interfaces/REST/Overview of SPX API|REST API]]. This is useful when SPX is reachable over a network and you want to make sure only trusted devices — such as a Stream Deck, a control panel, or an automation system — can trigger playback. **When no API keys are configured**, the API is open and any request is accepted. **When at least one key exists**, every API request must include a valid key or it will be rejected. **Creating a key:** 1. Open the Application Configuration page from the main menu. 2. Scroll to the **API** section. 3. Enter an optional name for the key (e.g. "Stream Deck") and click **Generate New Key**. 4. Copy the key immediately — it is shown only once and cannot be retrieved later. **Using a key in requests:** Include the key in the request header: ``` Authorization: Bearer <your-key> ``` **Managing keys:** - Keys can be deleted at any time from the Application Configuration page. - Deleting a key immediately revokes access for any device using it. - There is no limit to the number of keys you can create, so you can give each device or integration its own key. > [!note] Keys are managed exclusively through the Application Configuration page. > Do not edit the `apikeys` entries in `config.json` directly. ### `general.disableLocalRenderer` Disables the [[Documentation/Graphics Controller/Local Renderer|local renderer]] preview. ```json "disableLocalRenderer": false ``` ### `general.disableSeveralControllersWarning` Disables warning when multiple controllers are detected. ```json "disableSeveralControllersWarning": false ``` ## Global Extras ### `globalExtras` Additional user interface controls, or [[Documentation/Graphics Controller/Plugins & Extensions|plugins]], shown below the preview window in all projects (as opposed to project-specific extras). ```json "globalExtras": { "customscript": "/ExtraFunctions/demoFunctions.js" } ``` > [!warning] Global extras will be replaced by [[Documentation/Graphics Controller/Plugins & Extensions|Plugins]] in future versions, since they are easier to install and maintain. ## Restart Required > [!warning] The SPX server process must be restarted whenever changes are made to the configuration file. --- ## Read Next - [[Documentation/Renderer/Workflows/CasparCG - AMCP|CasparCG Setup]] - Configure CasparCG servers - [[Documentation/Renderer/Overview|Renderer Overview]] - Understanding SPX renderers - [[Documentation/Graphics Controller/Application Configuration|Application Configuration]] - UI configuration options - [[FAQ/Troubleshooting|Troubleshooting]] - Common configuration issues