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