From be14fb8096e84d42b54b565e5b130b9e7d48bb5a Mon Sep 17 00:00:00 2001 From: jo <ljonas@riseup.net> Date: Wed, 24 Aug 2022 18:43:09 +0200 Subject: [PATCH] docs: file based stream configuration --- docs/admin-manual/setup/configuration.md | 234 +++++++++++++++++++++++ docs/releases/unreleased.md | 38 ++++ 2 files changed, 272 insertions(+) diff --git a/docs/admin-manual/setup/configuration.md b/docs/admin-manual/setup/configuration.md index b7293bc1d..748ccc25f 100644 --- a/docs/admin-manual/setup/configuration.md +++ b/docs/admin-manual/setup/configuration.md @@ -221,6 +221,240 @@ In order to apply the changes made in this section, please restart the following libretime-liquidsoap ``` +## Stream + +The `stream` section configures anything related to the input and output streams. + +```yml +stream: + inputs: # See the [stream.inputs] section. + outputs: # See the [stream.outputs] section. +``` + +:::info + +To help you simplify your stream configuration, you can use yaml anchors to define a common properties and reuse them in your output definitions: + +```yml +stream: + outputs: + # This can be reused to define multiple outputs without duplicating data + .default_icecast_output: &default_icecast_output + source_password: "hackme" + admin_password: "hackme" + name: "LibreTime!" + description: "LibreTime Radio!" + website: "https://libretime.org" + genre: "various" + + icecast: + - <<: *default_icecast_output + enabled: true + mount: "main.ogg" + audio: + format: "ogg" + bitrate: 256 + + - <<: *default_icecast_output + enabled: true + mount: "main.mp3" + audio: + format: "mp3" + bitrate: 256 +``` + +::: + +In order to apply the changes made in this section, please restart the following services: + +``` +libretime-liquidsoap +libretime-playout +``` + +### Inputs + +The `stream.inputs` section configures anything related to the input streams. + +```yml +stream: + # Inputs sources. + inputs: + # Main harbor input. + main: + # Harbor input public url. If not defined, the value will be generated from + # the [general.public_url] hostname, the input port and mount. + public_url: + # Mount point for the main harbor input. + # > default is main + mount: "main" + # Listen port for the main harbor input. + # > default is 8001 + port: 8001 + + # Show harbor input. + show: + # Harbor input public url. If not defined, the value will be generated from + # the [general.public_url] hostname, the input port and mount. + public_url: + # Mount point for the show harbor input. + # > default is show + mount: "show" + # Listen port for the show harbor input. + # > default is 8002 + port: 8002 +``` + +### Outputs + +The `stream.outputs` section configures anything related to the output streams. + +```yml +stream: + # Output streams. + outputs: + icecast: # See the [stream.outputs.icecast] section. + shoutcast: # See the [stream.outputs.shoutcast] section. + system: # See the [stream.outputs.system] section. +``` + +#### Icecast + +The `stream.outputs.icecast` section configures the icecast output streams. + +```yml +stream: + outputs: + # Icecast output streams. + # > max items is 3 + icecast: + - # Whether the output is enabled. + # > default is false + enabled: false + # Output public url, If not defined, the value will be generated from + # the [general.public_url] hostname, the output port and mount. + public_url: + # Icecast server host. + # > default is localhost + host: "localhost" + # Icecast server port. + # > default is 8000 + port: 8000 + # Icecast server mount point. + # > this field is REQUIRED + mount: "main" + # Icecast source user. + # > default is source + source_user: "source" + # Icecast source password. + # > this field is REQUIRED + source_password: "hackme" + # Icecast admin user. + # > default is admin + admin_user: "admin" + # Icecast admin password. If not defined, statistics will not be collected. + admin_password: "hackme" + + # Icecast output audio. + audio: + # Icecast output audio format. + # > must be one of (aac, mp3, ogg, opus) + # > this field is REQUIRED + format: "ogg" + # Icecast output audio bitrate. + # > must be one of (32, 48, 64, 96, 128, 160, 192, 224, 256, 320) + # > this field is REQUIRED + bitrate: 256 + + # format=ogg only field: Embed metadata (track title, artist, and show name) + # in the output stream. Some bugged players will disconnect from the stream + # after every songs when playing ogg streams that have metadata information + # enabled. + # > default is false + enable_metadata: false + + # Icecast stream name. + name: "LibreTime!" + # Icecast stream description. + description: "LibreTime Radio!" + # Icecast stream website. + website: "https://libretime.org" + # Icecast stream genre. + genre: "various" +``` + +#### Shoutcast + +The `stream.outputs.shoutcast` section configures the shoutcast output streams. + +```yml +stream: + outputs: + # Shoutcast output streams. + # > max items is 1 + shoutcast: + - # Whether the output is enabled. + # > default is false + enabled: false + # Output public url. If not defined, the value will be generated from + # the [general.public_url] hostname and the output port. + public_url: + # Shoutcast server host. + # > default is localhost + host: "localhost" + # Shoutcast server port. + # > default is 8000 + port: 8000 + # Shoutcast source user. + # > default is source + source_user: "source" + # Shoutcast source password. + # > this field is REQUIRED + source_password: "hackme" + # Shoutcast admin user. + # > default is admin + admin_user: "admin" + # Shoutcast admin password. If not defined, statistics will not be collected. + admin_password: "hackme" + + # Shoutcast output audio. + audio: + # Shoutcast output audio format. + # > must be one of (aac, mp3) + # > this field is REQUIRED + format: "mp3" + # Shoutcast output audio bitrate. + # > must be one of (32, 48, 64, 96, 128, 160, 192, 224, 256, 320) + # > this field is REQUIRED + bitrate: 256 + + # Shoutcast stream name. + name: "LibreTime!" + # Shoutcast stream website. + website: "https://libretime.org" + # Shoutcast stream genre. + genre: "various" +``` + +#### System + +The `stream.outputs.system` section configures the system outputs. + +```yml +stream: + outputs: + # System outputs. + # > max items is 1 + system: + - # Whether the output is enabled. + # > default is false + enabled: false + # System output kind. + # > must be one of (alsa, ao, oss, portaudio, pulseaudio) + # > default is alsa + kind: "alsa" +``` + ## LDAP The `ldap` section provide additional configuration for the authentication mechanism defined in `general.auth`, please see the [custom authentication documentation](../custom-authentication.md) for more details. diff --git a/docs/releases/unreleased.md b/docs/releases/unreleased.md index 4c88386a8..0699a92b2 100644 --- a/docs/releases/unreleased.md +++ b/docs/releases/unreleased.md @@ -36,6 +36,44 @@ Along with the Debian Buster deprecation, the following dependencies versions ar - [php7.3](https://packages.debian.org/buster/php7.3) - [python3.7](https://packages.debian.org/buster/python3) +## :arrow_up: Before upgrading + +:::caution + +Please follow this **before the upgrade procedure**! + +::: + +### File based stream configuration + +The stream configuration moved from the database to the [configuration](../admin-manual/setup/configuration.md#stream) file. A configuration sample can be found in the project folder under `installer/config.yml`. Make sure to save your existing stream config to the configuration file. + +:::info + +To prevent accidental data loss during upgrade, the stream configuration data will only be removed from the database in future releases. You can view the data using the following commands: + +```bash +sudo -u libretime libretime-api dbshell --command=" + SELECT * + FROM cc_stream_setting + ORDER BY keyname;" + +sudo -u libretime libretime-api dbshell --command=" + SELECT * + FROM cc_pref + WHERE keystr IN ( + 'default_icecast_password', + 'default_stream_mount_point', + 'live_dj_connection_url_override', + 'live_dj_source_connection_url', + 'master_dj_connection_url_override', + 'master_dj_source_connection_url' + ) + ORDER BY keystr;" +``` + +::: + ## :arrow_up: Upgrading ### Worker python package and service