Congegni
/
sintonia
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: rework docs into the new website 

- multipass docs moved to local-dev.md
- add documentation to website
- rework fogotten files
- disable fogotten files

Co-authored-by: Zachary Klosko <zklosko@users.noreply.github.com>
This commit is contained in:
jo 2022-02-09 09:37:52 +01:00 committed by Jonas L
parent 2fa10793ec
commit 6d9e7a6765
39 changed files with 698 additions and 721 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/interface-customization.md → docs/_interface-customization.md
View File

@ -1,23 +1,24 @@
---
layout: article
title: Modifying the LibreTime interface
git: interface-customization.md
category: admin
---
The LibreTime administration interface, as a web application, is fully customizable using the same methods that you might use to modify a website. For instance, you may wish to increase certain font sizes or change the colours in the LibreTime interface to better suit staff users with impaired vision. To do so, open one of the CSS files in the _/public/css/_ directory under the LibreTime _DocumentRoot_ directory in an editor such as **nano**:
sudo nano /usr/share/airtime/public/css/styles.css
```bash
sudo nano /usr/share/airtime/public/css/styles.css
```
To change the background colour of the administration interface from dark gray to white, the _background:_ property of the body tag could be changed to _\#ffffff_ as follows:
body {
font-size: 62.5%;
font-family:Arial, Helvetica, sans-serif;
background: #ffffff;
margin: 0;
padding: 0;
}
```css
body {
font-size: 62.5%;
font-family: Arial, Helvetica, sans-serif;
background: #ffffff;
margin: 0;
padding: 0;
}
```
Save the file with **Ctrl+S**, then refresh your browser to see the change to the interface background colour.
@ -29,7 +30,9 @@ If you have installed Icecast, in the directory _/etc/icecast2/web/_ you will fi
For example, you could change the _status.xsl_ page:
sudo nano /etc/icecast2/web/status.xsl
```bash
sudo nano /etc/icecast2/web/status.xsl
```
Modifying the _status.xsl_ page is a good place to start, because this is the default page that site visitors see when they browse port 8000 on your Icecast server. The most obvious change to make in the XSLT pages is the content of the _&lt;title&gt;_ and _&lt;h2&gt;_ tags, to announce the name of your station. You can also modify the _style.css_ file in this directory to change colour and layout options.

50
docs/interface-localization.md → docs/_interface-localization.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Interface Localization
category: admin
---
The LibreTime administration interface can be localized using the standard GNU **gettext** method. Using GitHub for this task means you don't have to tackle the whole of a localization yourself; just as much as you can manage.
@ -12,9 +10,11 @@ First, you should check if a localization is already under way for your locale o
GNU **gettext** means using a .po file for each language or dialect, a specially formatted plain text file with groups of three or more lines, like this example from LibreTime's Korean localization:
#: legacy/application/configs/navigation.php:57
msgid "Media Folders"
msgstr "미디어 폴더"
```
#: legacy/application/configs/navigation.php:57
msgid "Media Folders"
msgstr "미디어 폴더"
```
The first of these three lines starts with the hash symbol, and references where this string of text is found in the source code by its file name and line number. If this string is found more than once in the source code, you will see other reference lines here. The second line contains the **msgid**, which is the original version of the string. The third line contains the **msgstr**, which is the translation of that string for the localization that this particular .po file relates to.
@ -28,33 +28,43 @@ In the locale code _de_CH_, for example, _de_ represents the German language and
After forking the LibreTime git repository, make sure you're in the **main** branch:
git branch
devel
* main
```bash
git branch
devel
* main
```
Create a new locale directory (e.g. _legacy/locale/de_CH/LC_MESSAGES/_ for German as spoken in Switzerland):
mkdir -p legacy/locale/de_CH/LC_MESSAGES/
```bash
mkdir -p legacy/locale/de_CH/LC_MESSAGES/
```
Copy the template _airtime.po_ file into the directory you just created:
cp legacy_locale/template/airtime.po legacy/locale/de_CH/LC_MESSAGES
```bash
cp legacy_locale/template/airtime.po legacy/locale/de_CH/LC_MESSAGES
```
and update the header information in the new copy of the _airtime.po_ file using the **nano** editor:
nano legacy/locale/de_CH/LC_MESSAGES/airtime.po
```bash
nano legacy/locale/de_CH/LC_MESSAGES/airtime.po
```
For the example of Swiss German, the header of the file should now look like this:
# SWISS GERMAN (de_CH) translation for LibreTime.
# Copyright (C) 2013 Sourcefabric
# This file is distributed under the same license as the LibreTime package.
# Sourcefabric <contact@sourcefabric.org>, 2013.
#
msgid ""
msgstr ""
"Project-Id-Version: LibreTime 3.0-Alpha\n"
"Report-Msgid-Bugs-To: https://discourse.libretime.org/\n"
```bash
# SWISS GERMAN (de_CH) translation for LibreTime.
# Copyright (C) 2013 Sourcefabric
# This file is distributed under the same license as the LibreTime package.
# Sourcefabric <contact@sourcefabric.org>, 2013.
#
msgid ""
msgstr ""
"Project-Id-Version: LibreTime 3.0-Alpha\n"
"Report-Msgid-Bugs-To: https://discourse.libretime.org/\n"
```
After using an online translation tool to begin a new localization, you can load the exported .po file into Poedit and complete your translation there. Enter the localization team's contact information and language into Poedit's **Edit -&gt; Preferences** and **Catalog -&gt; Settings** dialogs, which will be added to the .po file. When you save a .po file in Poedit, the corresponding binary .mo file will be compiled automatically.

18
docs/microsite.md → docs/_microsite.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Built-in Microsite
category: admin
---
![](/img/radio-page.png)
@ -12,16 +10,16 @@ podcast tabs, and a live feed of your station with information on the the curren
## Modifying the LibreTime Radio Page
The background of the mini-site that appears when you visit the server's domain in your web browser can be changed by modifying the page's CSS file, located at _/usr/share/airtime/php/legacy/public/css/radio-page/radio-page.css_.
The background of the mini-site that appears when you visit the server's domain in your web browser can be changed by modifying the page's CSS file, located at `/usr/share/airtime/php/legacy/public/css/radio-page/radio-page.css`.
```
```css
html {
background: url("img/background-testing-3.jpg") no-repeat center center fixed;
-webkit-background-size: cover;
-moz-background-size: cover;
-o-background-size: cover;
background-size: cover;
overflow-y: auto;
background: url("img/background-testing-3.jpg") no-repeat center center fixed;
-webkit-background-size: cover;
-moz-background-size: cover;
-o-background-size: cover;
background-size: cover;
overflow-y: auto;
}
```

4
docs/troubleshooting.md → docs/_troubleshooting.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Troubleshooting
category: admin
---
Is something not working for your Libretime installation? Here's a quick guide to help you
@ -27,7 +25,7 @@ If one of the services isn't working, text will display with a terminal command
or get status information for a particular service. For example (for Ubuntu 18.04), the following
commands would restart or check the status of Libretime's Liquidsoap instance, respectively.
```
```bash
sudo systemctl restart libretime-liquidsoap
sudo systemctl status libretime-liquidsoap
```

4
docs/appendix/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "Appendix",
"position": 7
}

8
docs/appendix/api.md
View File

@ -1,9 +1,13 @@
---
layout: article
title: LibreTime API Usage
category: dev
---
:::info
We're in the process of rewriting Libretime's API. This page contains the instructions for the current version, written in PHP.
:::
The LibreTime API enables many types of information about the broadcast schedule and configuration to be retrieved from the LibreTime server. Other than the live-info and week-info data fetched by website widgets (see the chapter _Exporting the schedule_), all API requests must be authenticated using the secret API key stored in the file _/etc/airtime/api_client.cfg_ on the LibreTime server. This key is autogenerated during LibreTime installation and should be unique for each server.
If you intend to use the LibreTime API across a public network, for security reasons it is highly recommended that all API requests are sent over encrypted https: and that the web server is configured to accept requests to the api/ directory from specific host names or IP addresses only.

5
docs/appendix/hd-audio-modules.md
View File

@ -1,11 +1,8 @@
---
layout: article
title: HD Audio Modules
git: hd-audio-modules.md
category: admin
---
This listing is provided to help ensure that the correct model parameter is passed to the ALSA kernel module for an Intel HDA soundcard, if one is fitted to your LibreTime server. See the chapter _Preparing the server_ in this book for more details.
This listing is provided to help ensure that the correct model parameter is passed to the ALSA kernel module for an Intel HDA soundcard, if one is fitted to your LibreTime server.
```
Model name Description

2
docs/appendix/rights-royalties.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Rights and Royalties
category: manager
---
If you're new to broadcasting, or have not streamed your station online before,

16
docs/appendix/widgets.md
View File

@ -1,7 +1,5 @@
---
title: Widgets
category: interface
layout: article
---
Bring your Libretime broadcast to your website with embeddable widgets! Libretime comes with two widgets: a streaming player and a schedule. Both widgets use iframes to display and can be placed wherever embeddable code can on a website.
@ -10,9 +8,13 @@ Bring your Libretime broadcast to your website with embeddable widgets! Libretim
Before using the widgets, make sure Libretime's Public API is enabled in **Settings** > **General**.
![](/img/widgets_settings.png)
![](./widgets-widgets_settings.png)
> **Note:** Your Libretime instance needs to be accessible to the public _without the use of a VPN or SSH tunneling_ in order for the widgets to work.
:::tip Note
Libretime widgets cannot function through VPNs or SSH tunneling. The instance must be accessible from the internet for the widgets to work.
:::
## Streaming Player Widget
@ -20,12 +22,12 @@ The streaming player widget inserts your Libretime stream into your website. One
<iframe frameborder="0" width="400" height="235" src="http://broadcast.wcrsfm.org/embed/player?stream=auto&title=Now Playing"></iframe>
![](/img/widgets_player.png)
![](./widgets-widgets_player.png)
From **Widgets** > **Player**, enter a title for your streaming widget and select what stream you'd like to use. All selectible streams must first be configured in **Settings** > **Streams** (see [Settings](/docs/settings)). **Auto detect** should be fine for most.
From **Widgets** > **Player**, enter a title for your streaming widget and select what stream you'd like to use. All selectible streams must first be configured in **Settings** > **Streams** (see [Settings](/docs/guides/settings)). **Auto detect** should be fine for most.
## Show Schedule Widget
![](/img/widgets_schedule.png)
![](./widgets-widgets_schedule.png)
The show schedule widget displays the upcoming shows for the next seven days. There are no customizable settings for this widget.

4
docs/getting-started/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "Getting Started",
"position": 2
}

29
docs/getting-started/default-passwords.md
View File

@ -1,10 +1,9 @@
---
title: How To Change Default Passwords
layout: article
category: admin
title: Change Default Passwords
sidebar_position: 3
---
### Libretime
## Libretime
To change the password of the current user:
@ -18,7 +17,7 @@ To change the password for a different user (requires _Administrator_ privileges
2. Go to **Settings** > **Manage Users**
3. Select the user, enter the new password twice, and click **Save**
### PostgreSQL
## PostgreSQL
Two of the most important passwords that should be changed _immediately_ after installation
are the passwords used by the PostgreSQL database.
@ -32,15 +31,13 @@ It is strongly recommended that you do this before exposing your server to the i
4. If all is successful, logout of PostgreSQL with `\q`, go back to _/etc/airtime/airtime.conf_ to edit the password
in the config file, and restart all services mentioned in the previous section.
### Icecast
## Icecast
Random passwords are generated for Icecast during the installation. To look up and change the passwords, look in the file below.
`/etc/icecast2/icecast.xml`
Random passwords are generated for Icecast during the installation. To look up and change the passwords, edit `/etc/icecast2/icecast.xml`.
Replace the admin and _changeme_ fields below.
```
```xml
<authentication>
<!-- Sources log in with username 'source' -->
<source-password>changeme</source-password>
@ -52,19 +49,15 @@ Replace the admin and _changeme_ fields below.
</authentication>
```
Then, restart your icecast2 service.
```
sudo systemctl restart icecast2
```
Then, restart your icecast2 service with `sudo systemctl restart icecast2`.
> Note: If you change the source password, you may need to manually configure Libretime to use the new password: go to **Settings** > **Streams**, set the streaming server to **Custom** and fill out the **Additional Options** below Stream 1.
### Rabbitmq
## RabbitMQ
To change the default password for Rabbitmq, run the following command
To change the default password for RabbitMQ, run the following command
```
```bash
sudo rabbitmqctl change_password airtime newpassword
```

48
docs/getting-started/install.md
View File

@ -1,8 +1,6 @@
---
title: Install
layout: article
category: install
permalink: /install
title: Installation
sidebar_position: 1
---
## Minimum System Requirements
@ -12,15 +10,11 @@ permalink: /install
- Debian [current stable](https://www.debian.org/releases/)
- 1 Ghz Processor
- 2 GB RAM recommended (1 GB required)
- Wired internet connection and static IP address for on-prem install
[DigitalOcean](https://www.digitalocean.com/pricing/#Compute) and [Linode](https://www.linode.com/pricing/#row--compute)
have similar plans that meet Cloud Install requirements. Both plans cost $10/month.
- A static IP address for your server
## Preparing the server
Configure the server to have a static IP address by modifying the Netplan configuration.
If you're using a cloud VM, you likely already have a static IP address. Check with your provider to confirm this.
```
cd /etc/netplan && ls # find the netplan filename
@ -29,10 +23,21 @@ sudo nano ##-network-manager-all.yaml
If the Netplan configuration is empty, fill in the file with the example below. Otherwise,
input the IP address reserved for the server in `xxx.xxx.xxx.xxx/yy` format, the gateway (the IP address
of your router), and the DNS nameserver. If you don't have a nameserver on your network,
feel free to use Cloudflare's: `1.1.1.1` and `1.0.0.1`. In this File is "Tab" not allowed.
of your router), and your DNS server's address.
```
:::tip
Don't have a DNS server of your own? You can use a public DNS server like Google (`8.8.8.8`) or Cloudflare (`1.1.1.1`), or input your router's address in most cases.
:::
:::caution
Do not use tabs in YAML files. Use two spaces to indent instead.
:::
```yaml title="Netplan configuration on Ubuntu"
network:
version: 2
renderer: networkd
@ -48,18 +53,20 @@ After the netplan file has been saved, run `sudo netplan apply` to apply changes
Next, configure Ubuntu's firewall by running:
```
```bash
sudo ufw enable
sudo ufw allow 22,80,8000/tcp
```
:::info
Unblock ports 8001 and 8002 if you plan to use LibreTime's Icecast server to broadcast livestreams without an external Icecast server acting as a repeater.
```
```bash
sudo ufw allow 8001,8002/tcp
```
> If needed, instructions for setting up a reverse proxy can be found [here](/docs/reverse-proxy).
:::
## Installing LibreTime
@ -67,9 +74,10 @@ sudo ufw allow 8001,8002/tcp
Installing LibreTime consists of running the following commands in the terminal:
```
```bash
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo bash install -fiap
```
@ -84,7 +92,7 @@ it is important that the server starts them during the boot process, to cut down
Ubuntu 18.04 uses the `systemctl` command to manage services, so run the following commands to enable all
LibreTime-needed services to run at boot:
```
```bash
sudo systemctl enable libretime-liquidsoap
sudo systemctl enable libretime-playout
sudo systemctl enable libretime-celery
@ -93,7 +101,11 @@ sudo systemctl enable apache2
sudo systemctl enable rabbitmq-server
```
> If an error is returned, try adding `.service` to the end of each command.
:::tip
If an error is returned, try adding `.service` to the end of each command.
:::
## User Permissions

24
docs/getting-started/reverse-proxy.md
View File

@ -1,7 +1,6 @@
---
title: Reverse Proxy
layout: article
category: install
sidebar_position: 5
---
In some deployments, the LibreTime server is deployed behind a reverse proxy,
@ -10,7 +9,7 @@ makes extensive use of its API for some site functionality, which causes
[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
to occur. By default, CORS requests are blocked by your browser and the origins
need to be added to the **Allowed CORS URLs** block in
[**General Settings**](/docs/settings). These origins should include any
[**General Settings**](/docs/guides/settings). These origins should include any
domains that will be used externally to connect to your reverse proxy that you
want handled by LibreTime. These URLS can also be set during the first run configuration
that is displayed when you first install LibreTime
@ -40,16 +39,7 @@ Nginx set up on `proxy` and LibreTime will be installed on `libretime`. You will
access on both. `libretime` also needs to be able to be accessed from `proxy`
(`ping libretime` on `proxy`).
On `libretime`, install LibreTime as described in the [install guide](/install). In short
this means run the following commands:
```
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo ./install -fiap
```
Once it has installed, replace `<hostname>localhost</hostname>` in
On `libretime`, install LibreTime as described in the [install guide](/docs/getting-started/install). Once it has installed, replace `<hostname>localhost</hostname>` in
`/etc/icecast2/icecast.xml` with the following:
```
@ -57,15 +47,11 @@ Once it has installed, replace `<hostname>localhost</hostname>` in
```
This is the hostname that people listening to your stream will connect to and what
LibreTime will use to stream out to them. You will then need to restart Icecast:
```
sudo systemctl restart icecast2
```
LibreTime will use to stream out to them. You will then need to restart Icecast using `sudo systemctl restart icecast2`.
On `proxy`, run the following:
```
```bash
cat << EOF | sudo tee /etc/nginx/sites-available/libretime.conf
server {
listen 80;

79
docs/getting-started/set-server-time.md
View File

@ -1,21 +1,20 @@
---
title: Setting the Server Time
layout: article
category: install
sidebar_position: 2
---
Accurate time keeping on your server is vital for LibreTime performance. You can confirm that the date and time of your server are set correctly with the `date` command.
The server should respond with the date, time, time zone and year in a format similar to the following example:
Tue Jul 2 15:08:57 BST 2013
```
Tue Jul 2 15:08:57 BST 2013
```
If the time on your server is wrong, it is strongly recommended that you take LibreTime off-air until the problem is fixed.
If the time on your server is wrong, we strongly recommend that you take LibreTime off-air until the problem is fixed.
### Configuring NTP
## Configuring NTP
Although it is possible to set the date and time of the server manually, this is not recommended because the server clock can drift over time, compromising the accuracy of your broadcast schedule. If your LibreTime server is permanently connected to the Internet, you can synchronize your server to a time server with the **ntp** program. If **ntp** is not yet installed, you can enter the following command on Debian or Ubuntu:
sudo apt-get install ntp
Although it is possible to set the date and time of the server manually, this is not recommended because the server clock can drift over time, compromising the accuracy of your broadcast schedule. If your LibreTime server is permanently connected to the Internet, you can synchronize your server to a time server with the **ntp** program. If **ntp** is not on your server, you can install it with `sudo apt-get install ntp`.
Optionally, open the **ntp** configuration file in the **nano** editor to add further time server names:
@ -23,51 +22,49 @@ Optionally, open the **ntp** configuration file in the **nano** editor to add fu
On Ubuntu GNU/Linux, the default time server is _ntp.ubuntu.com_, but there are many other time servers available on the public Internet, including the group of servers listed at <http://www.pool.ntp.org/> for each country. Using a variety of NTP servers located closely to your LibreTime server should produce the most accurate results. For example, for a server in the United Kingdom you could use the following list:
# You do need to talk to an NTP server or two (or three).
server ntp.ubuntu.com
server 0.uk.pool.ntp.org
server 1.uk.pool.ntp.org
server 2.uk.pool.ntp.org
server 3.uk.pool.ntp.org
```title="/etc/ntp.conf"
# You do need to talk to an NTP server or two (or three).
server ntp.ubuntu.com
server 0.uk.pool.ntp.org
server 1.uk.pool.ntp.org
server 2.uk.pool.ntp.org
server 3.uk.pool.ntp.org
```
Enter the server names you require, press **Ctrl+O** to write out the _/etc/ntp.conf_ file, then **Ctrl+X** to exit **nano**. Restart the **ntp** service with:
sudo invoke-rc.d ntp restart
Enter the server names you require, press **Ctrl+O** to write out the _/etc/ntp.conf_ file, then **Ctrl+X** to exit **nano**. Restart the **ntp** service with `sudo systemctl restart ntp`.
The server should respond:
* Stopping NTP server ntpd [ OK ]
* Starting NTP server ntpd [ OK ]
```
* Stopping NTP server ntpd [ OK ]
* Starting NTP server ntpd [ OK ]
```
Then use the **ntpq -p** command to confirm that **ntp** is working. This command should produce output similar to the following:
ntpq -p
remote refid st t when poll reach delay offset jitter
==================================================================
europium. 193.79.237.14 2 u 28 64 3 39.571 12.600 3.590
norb.v4.c 46.227.200.72 3 u 28 64 3 47.856 -6.908 10.028
82.113.15 193.62.22.82 2 u 29 64 3 11.458 -0.513 2.629
ntppub.le 158.43.192.66 2 u 91 64 2 122.781 44.864 0.001
dns0.rmpl 195.66.241.3 2 u 27 64 3 22.171 1.464 4.242
```
ntpq -p
remote refid st t when poll reach delay offset jitter
==================================================================
europium. 193.79.237.14 2 u 28 64 3 39.571 12.600 3.590
norb.v4.c 46.227.200.72 3 u 28 64 3 47.856 -6.908 10.028
82.113.15 193.62.22.82 2 u 29 64 3 11.458 -0.513 2.629
ntppub.le 158.43.192.66 2 u 91 64 2 122.781 44.864 0.001
dns0.rmpl 195.66.241.3 2 u 27 64 3 22.171 1.464 4.242
```
### Adjusting the server time zone
## Adjusting the server time zone
The data centre which hosts your LibreTime server could be located anywhere in the world. Some servers are set to _Coordinated Universal Time_ or UTC (similar to _Greenwich Mean Time_ or GMT), regardless of their location. LibreTime uses UTC time in its database for scheduling purposes, independent of the server time zone.
If the server time zone is not appropriate for integration with your station's other systems, on a Debian or Ubuntu server you can reconfigure the **tzdata** (time zone data) package with the command:
Find your timezone's shortcode with `timedatectl list-timezones`, then enter
sudo dpkg-reconfigure tzdata
```bash
sudo timedatectl set-timezone your_time_zone
```
This command opens a menu in which you can select the continent that you require, by pressing the Enter key.
:::tip
![](/img/Screenshot15-Configuring_tzdata.png)
You can check to see which time zone your server is set to by running `timedatectl` without any arguments.
The next step is to select your nearest city, again by pressing the Enter key. The appropriate time zone is selected according to the information that you have entered.
![](/img/Screenshot16-Configure_city.png)
The console output from the **dpkg-reconfigure tzdata** command will confirm the new setting:
Current default time zone: 'Europe/London'
Local time is now: Tue Jul 2 15:18:01 BST 2013.
Universal Time is now: Tue Jul 2 14:18:01 UTC 2013.
:::

132
docs/getting-started/ssl.md
View File

@ -1,54 +1,22 @@
---
title: SSL Configuration
layout: article
category: install
sidebar_position: 4
---
To increase the security of your server, you can enable encrypted access to the LibreTime administration interface, and direct your users towards this more secure login page. The main advantage of using this encryption is that your remote users' login names and passwords are not sent in plain text across the public Internet or untrusted local networks, such as shared Wi-Fi access points.
### Deploying a certificate with Certbot
## Deploying a certificate with Certbot (Recommended)
One of the fastest, easiest, and cheapest ways to get an SSL certificate is through [Certbot](https://certbot.eff.org/), as created by the
Electronic Frontier Foundation. There are some requirements for this process:
Electronic Frontier Foundation. To use Certbot, your Libretime installation must be open to the internet on port 80.
- you have an HTTP website (already installed and configured by default by the LibreTime installer) and
- this website is open to the public internet (likely via. port forwarding if your computer is behind a firewall) and
- the server is accessible to the public via. port 80
Follow [Certbot's documentation](https://certbot.eff.org/instructions) for your OS and webserver to install an SSL certificate. You'll need to renew the certificate every 90 days to keep your installation secure.
If you aren't able to verify all three requirements, you may want to try a self-signed certificate (see next section).
If you aren't able to use Certbot, you may want to try a self-signed certificate.
These instructions come from Certbot's website and assume that you are using an Apache web server
running on Ubuntu 18.04 LTS (the Apache web server is installed with LibreTime by default).
Instructions for other Debian-based OSes are similar, but check with Certbot for clarification.
## Deploying a self-signed certificate
Note: all instructions require you to have sudo privileges
First, add Certbot's PPA using:
```
sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
```
Next, install Certbot and install the SSL certificate using the below commands:
```
sudo apt-get install certbot python3-certbot-apache
sudo certbot --apache # get and install the certificate
sudo certbot certonly --apache # to only get the certificate, not install it using Certbot
```
You can test certificate renewal by running `sudo certbot renew --dry-run`.
Head to your server's IP address to check to see that the installation worked.
### Deploying a self-signed certificate
The Debian/Ubuntu package _ssl-cert_ creates a _snakeoil_ certificate and key based on your server's hostname. This gratis certificate and key pair created under the _/etc/ssl/certs_/ and _/etc/ssl/private/_ directories will not be recognised by users' browsers without manual intervention. You can install the _ssl-cert_ package with the command:
sudo apt-get install ssl-cert
The Debian/Ubuntu package _ssl-cert_ creates a _snakeoil_ certificate and key based on your server's hostname. This gratis certificate and key pair created under the _/etc/ssl/certs_/ and _/etc/ssl/private/_ directories will not be recognised by users' browsers without manual intervention. You can install the _ssl-cert_ package with `sudo apt-get install ssl-cert`.
If the hostname of your server does not match the domain name you intend to use with the LibreTime virtual host, the user's browser will present an additional security warning. You can set the domain name of the certificate by editing the file _/usr/share/ssl-cert/ssleay.cnf_ to replace the _@HostName@_ variable:
@ -58,84 +26,88 @@ with the domain name used by LibreTime:
commonName = airtime.example.com
Then save the file and regenerate the certificate with the command:
Then save the file and regenerate the certificate with
sudo make-ssl-cert generate-default-snakeoil --force-overwrite
```bash
sudo make-ssl-cert generate-default-snakeoil --force-overwrite
```
You should enable additional Apache modules for page redirections, custom headers and secure access:
sudo a2enmod alias headers ssl
```bash
sudo a2enmod alias headers ssl
```
Next, edit the virtual host configuration for your LibreTime server to include a stanza for the https:// interface on port 443 and a redirect for logins from port 80:
sudo nano /etc/apache2/sites-available/airtime-vhost.conf
```bash
sudo nano /etc/apache2/sites-available/airtime-vhost.conf
```
Using the following configuration for Apache 2.2 as a guide, replace _airtime.example.com_ with the name of your server and *admin@example.com* with your email address. The older SSLv2 and SSLv3 protocols and SSL compression should be disabled, as they are generally believed to be insecure. You may wish to create a _ServerAlias_ for users to access the administration interface over https:// if required.
Using the following configuration as a guide, replace _libretime.example.com_ with the name of your server and *admin@example.com* with your email address. The older SSLv2 and SSLv3 protocols and SSL compression should be disabled, as they are generally believed to be insecure. You may wish to create a _ServerAlias_ for users to access the administration interface over https:// if required.
On port 80, Apache's _alias_ module is used to set a _Redirect permanent_ for the login page. Optionally, access could be denied to all sites except _localhost_ and any other LibreTime servers on your network, so that unencrypted communication between LibreTime components can continue.
```
```apacheconf title="/etc/apache2/sites-available/airtime-vhost.conf"
<VirtualHost *:443>
SSLEngine on
SSLProtocol All -SSLv2 -SSLv3
SSLCompression off
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
Header always set Strict-Transport-Security "max-age=31536000"
SSLEngine on
SSLProtocol All -SSLv2 -SSLv3
SSLCompression off
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
Header always set Strict-Transport-Security "max-age=31536000"
ServerName airtime.example.com
#ServerAlias www.example.com
ServerName libretime.example.com
#ServerAlias www.example.com
ServerAdmin admin@example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/legacy/public
DirectoryIndex index.php
DocumentRoot /usr/share/airtime/php/legacy/public
DirectoryIndex index.php
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride all
Order allow,deny
Allow from all
</Directory>
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride all
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
<VirtualHost *:80>
ServerName airtime.example.com
ServerName libretime.example.com
ServerAdmin admin@example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/legacy/public
Redirect permanent /login https://airtime.example.com/login
DocumentRoot /usr/share/airtime/php/legacy/public
Redirect permanent /login https://airtime.example.com/login
SetEnv APPLICATION_ENV "production"
SetEnv APPLICATION_ENV "production"
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Directory>
<Directory /usr/share/airtime/php/legacy/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
```
Save the file with **Ctrl+O** and exit the **nano** editor with **Ctrl+X**. Then restart Apache with the command:
Save the file, then restart Apache with `sudo systemctl restart apache2`.
sudo service apache restart
When attempting to log into your server via http:// in future, you should be redirected to https:// automatically.
When attempting to log into your server via `http://` in future, you should be redirected to `https://` automatically.
### Importing a self-signed certificate into the browser
The first time you access an LibreTime server with a self-signed certificate over https:// your browser will block the login page and display a security warning. In **Mozilla Firefox**, you can click **Technical Details** to confirm that the warning is due to the certificate being self-signed before clicking the **Add Exception** button. In **Google Chrome**, the button to click on the security warning page is **Proceed Anyway**.
![](/img/Screenshot547-connection_untrusted.png)
![](./ssl-screenshot547-connection_untrusted.png)
On the next page in Firefox, click the **Get Certificate** button to inspect the details of the self-signed certificate. If all is well, click the **Confirm Security Exception** button. You should now be able to proceed to the https:// login page.
![](/img/Screenshot548-confirm_exception.png)
![](./ssl-screenshot548-confirm_exception.png)
If the users of your LibreTime server wish to avoid going through these steps, or they do not trust the remote LibreTime server to be what it claims to be, it is also possible to import a trusted local copy of a certificate file into the browser. For example, in Firefox version 30 preferences, you can go into the **Advanced** section, click the **Certificates** tab, then click the **View Certificates** button. On the **Servers** tab of the **Certificate Manager**, there is an **Import** button which enables you to load a certificate file from the local computer.
### Mixed encrypted and unencrypted content
## Mixed encrypted and unencrypted content
Whether your certificate is self-signed or not, you will see browser security warnings whenever a https:// page is delivering unencrypted content, such as the stream from an Icecast server. In Firefox, an exclamation mark icon is displayed in the address bar of the **Listen** pop-up.

4
docs/guides/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "Guides",
"position": 3
}

18
docs/guides/calendar.md
View File

@ -1,26 +1,24 @@
---
layout: article
title: Show Calendar
category: interface
---
The Calendar page of the LibreTime administration interface has three views: **day**, **week** and **month**, which can be switched using the grey buttons in the top right corner. By default, the **month** view is shown, with today's date highlighted by a pale grey background.
![](/img/Screenshot451-Calendar.png)
![](./calendar-screenshot451-calendar.png)
In the top left corner of the page, you can go back or forward through the **Calendar** by clicking on the buttons which have a small grey triangle in a white circle. Click the **today** button to jump to today's date in the current view. (The **today** button will be greyed out if you are already viewing that date). In the **day** or **week** views, there is also a drop-down menu which allows you to set the resolution displayed for the calendar, ranging from one minute per row to sixty minutes per row.
![](/img/Screenshot452-Calendar_resolution.png)
![](./calendar-screenshot452-calendar_resolution.png)
### Editing a show
Show configuration and metadata can be changed at any time, except for **Date/Time Start** and **Record from Line In?** options, which are fixed after broadcast of that show commences. Click the show in the Calendar, and select **Edit Show** from the pop-up context menu. This opens the **Update Show** box, which is almost exactly the same as the **Add this Show** box. Click the **+ Update show** button at the top or bottom of the box when you are done.
![](/img/Screenshot459-Update_show.png)
![](./calendar-screenshot459-update_show.png)
Episodes of repeating shows also have an **Instance Description** field in which you can add details for that particular episode. Click the episode in the Calendar, click **Edit** on the pop-up menu, then click **Edit this instance**. After entering an Instance Description, click the **+ Update show** button.
![](/img/Screenshot583-Show_instance_description_vC9ooiT.png)
![](./calendar-screenshot583-show_instance_description_vc9ooit.png)
Alternatively, individual shows can be clicked on and dragged to new days and times in the calendar. However, LibreTime will not allow you to drag a future show into the past, or drag and drop instances of a repeated show. In the **Day** and **Week** views, show length can be adjusted by clicking on the lower edge of the show box, and dragging the edge of the box upwards or downwards. The new show length is calculated automatically.
@ -28,17 +26,17 @@ Alternatively, individual shows can be clicked on and dragged to new days and ti
To add content to a show, click the show in any view on the Calendar, and select **Schedule Tracks** from the pop-up menu. Shows that do not yet contain any scheduled content are marked with a red exclamation mark icon, to the right of the show start and end times in the top bar. Shows partially filled with content have a yellow exclamation mark icon. During playout of the show, a green play icon will also be shown in the top bar.
![](/img/Screenshot488-Add_remove_content.png)
![](./calendar-screenshot488-add_remove_content.png)
The **Schedule Tracks** action opens a window with the name of the show. Like when using the **Now Playing** page, you can search for content items and add them to the show schedule on the right side of the page. Refer to the _Now Playing_ chapter for details.
When your show has all the required content, click the **OK** button in the bottom right corner to close the window. Back in the **Calendar**, click the show and select **View** from the pop-up menu to view a list of content now included in the show.
![](/img/Screenshot489-Show_Content.png)
![](./calendar-screenshot489-show_content.png)
The **Contents of Show** window is a read-only interface featuring an orange bar which indicates how much media has been added to the show. Click the **OK** button in the bottom right corner, or the white **x** icon in the top right corner, to close the window.
![](/img/Screenshot353-Contents_of_show.png)
![](./calendar-screenshot353-contents_of_show.png)
### Removing content from a show
@ -48,7 +46,7 @@ To remove an individual item from a show, click on the show in the **Calendar**,
To delete an upcoming instance of a repeating show, click on the show in the **Calendar**, and select **Delete**, then **Delete Instance** from the pop-up menu. If you wish to delete all future instances of a repeating show, select **Delete Instance and All Following** from the pop-up menu.
![](/img/Screenshot490-Delete_this_instance.png)
![](./calendar-screenshot490-delete_this_instance.png)
You cannot delete or remove content from shows that have already played out. These shows have only one option on the pop-up menu, which is **View**.

24
docs/guides/dashboard.md
View File

@ -1,10 +1,12 @@
---
layout: article
title: Dashboard
category: interface
---
> Want to listen to Libretime's output stream? Click **Listen** below the **On Air** light.
:::tip
Want to listen to Libretime's output stream? Click **Listen** below the **On Air** light.
:::
The Dashboard is divided into two sections a Library section divided between
Tracks, Playlists, Smart Blocks, Webstreams, and Podcasts, with the **Scheduled
@ -21,12 +23,12 @@ yet. Click the calendar and clock icons above the table to change the date and
time range, then click the **Find Shows** button (with the magnifying glass
icon) to the right.
![](/img/now-playing.png)
![](./dashboard-now-playing.png)
To display the content of a particular show, click **Filter by Show** and select
the name of the show from the drop-down menu which will appear.
![](/img/filter.png)
![](./dashboard-filter.png)
On the left side of the page, the **Start** and **End** times, **Duration**
and **Title** of each content item are shown. On the right, **Creator**,
@ -40,7 +42,7 @@ item at the same time of day.
Click the **Show/hide columns** button on the right to configure the metadata
displayed, by checking the boxes in the pop-up window.
![](/img/columns.png)
![](./dashboard-columns.png)
The row for the currently playing item is displayed with a bright green
background. Any underbooked shows (shows with insufficient content to fill the
@ -48,7 +50,7 @@ time allowed) are displayed with a row indicating the length of the underbooking
in minutes and seconds. These rows contain a red exclamation mark in the first
column, and have a pink background.
![](/img/end-gap.png)
![](./dashboard-end-gap.png)
### Removing content from a running show
@ -65,7 +67,7 @@ from the schedule. If you remove the currently playing item, playout will skip
to the next item in the show automatically, so you should make sure you have
enough items remaining in the show to avoid dead air.
![](/img/delete-extra.png)
![](./dashboard-delete-extra.png)
If you have a long schedule displayed, and you wish to skip to the currently
playing item, click the button with the end arrow icon, to the right of the
@ -94,7 +96,7 @@ other sources such as microphones or telephone hybrids on its way to a
transmitter, or a separate stream encoder. For instance, a live show's host may
not wish to cut off a studio discussion in order to play music at a fixed time.
![](/img/drag-and-drop.png)
![](./dashboard-drag-and-drop.png)
You can also select multiple items using the **Select** menu button, just
beneath the simple search field, which has the options to **Select this page**
@ -117,7 +119,3 @@ There is no need to select or drag the item first.
Right-clicking on a song in the schedule table will show a pop-up. This pop-up
menu also enables you to audition the entire show in advance of playout, or
remove the item that was clicked on from the show.
Multiple insertion points can be enabled, so that the same item is inserted into
the schedule at different times. For example, you may wish to play a news report
every hour, or a station ident after every five music files.

4
docs/guides/listener-stats.md
View File

@ -1,12 +1,10 @@
---
title: Listener Statistics
layout: article
category: manager
---
The Listener Stats page on the Analytics menu shows graphs of listener connections to the configured streaming servers for the selected date and time range. On the right side, a green **Status** indicator shows **OK** if the connection to the streaming server is active.
![](/img/portfolio/stream-stats.jpg)
![](./listener-stats-stream-stats.jpg)
If the status indicator is red, check that the **Admin User** and **Admin Password** settings are correct under **Additional Options** for the named mount point, such as _libretime_128_, on the **Streams** page of the **Settings** menu.

41
docs/guides/live-broadcast.md
View File

@ -1,11 +1,8 @@
---
layout: article
title: Broadcasting live with MIXXX or B.U.T.T.
git: live-broadcast.md
category: interface
title: Broadcasting live
---
## Live shows with MIXXX {#mixxx}
## MIXXX
[Mixxx](https://www.mixxx.org) is a cross-platform Open Source application for DJs.
@ -18,25 +15,22 @@ Mixxx supports a wide variety of popular hardware control surfaces, which can be
computer using a USB cable. A control surface might replace or augment an analogue mixer in your studio,
depending on your live mixing and playout requirements.
Mixxx 1.9.0 or later includes a live streaming client which, like LibreTime, is compatible with the **Icecast**
and **SHOUTcast** media servers. This feature can also be used to stream from Mixxx directly into LibreTime,
Mixxx 1.9.0 or later includes a live streaming client which, like LibreTime, is compatible with the Icecast
and SHOUTcast media servers. This feature can also be used to stream from Mixxx directly into LibreTime,
using either the **Show Source** or **Master Source**.
![](/img/Screenshot369-Mixxx_streaming_preferences.png)
To configure **Mixxx** for streaming into LibreTime, click **Options**, **Preferences**, then
To configure Mixxx for streaming into LibreTime, click **Options**, **Preferences**, then
**Live Broadcasting** on the main Mixxx menu. For server **Type**, select the default of **Icecast 2**.
For **Host**, **Mount**, **Port**, **Login** and **Password**, use the **Input Stream Settings**
configured in the LibreTime **Streams** page, on LibreTime's **System** menu. See [stream settings](stream-settings)
for remote input connection details.
configured in the LibreTime **Streams** page, on LibreTime's **System** menu.
## Live shows with B.U.T.T. (Broadcast Using This Tool)
## B.U.T.T. (Broadcast Using This Tool)
<html>
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/4GLsU9hPTtM" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</html>
**Setup**
### Setup
1. Download and install [BUTT](https://danielnoethen.de/) for your OS.
_Note: be sure you have butt version 0.1.17 or newer installed_
@ -51,18 +45,14 @@ for remote input connection details.
- Type **/show** under IceCast mountpoint:
- Type your dj login under **IceCast user:**
5. Click **ADD**
6. Still in settings click, **Audio** and select your external sound card under
**Audio Device** _Note: if you only have an internal sound card you maybe able
to use it but that is OS specific and outside of this tutorial. We are assuming
you have a mic and mixer or a USB mixer hooked up to or as an external soundcard_
6. Still in settings click, **Audio** and select your audio input device under
**Audio Device**
**Show Time**
### Show Time
1. When its almost your show time go to your LibreTime page and look at the time
in the top right when your show starts go to Butt.
1. When its almost your show time go to your LibreTime page and look at the time in the top right when your show starts go to Butt.
2. Click the white Play button (third button in the middle).
3. If it says connecting... and then stream time with a counter- congratulations,
your are connected!
3. If it says connecting... and then stream time with a counter- congratulations, your are connected!
4. Go to the LibreTime page and at the top right under Source Streams the
tab besides Show Source is to the left and Orange - if it is and Current
shows Live Show you are connected.
@ -81,8 +71,3 @@ slot. If you choose to stop streaming before it is over click the white square
**Stop** button to disconnect. Then go to the LibreTime page and if the Show
Source didn't automatically disconnect you can click it to the right and it
should turn gray.
You are now done streaming.
If you have issues connecting check with your system administrator to see if you
have the details right.

39
docs/guides/playlists.md
View File

@ -1,20 +1,12 @@
---
layout: article
title: Playlists and Smartblocks
category: interface
---
> **About Autoloading Playlists**
>
> Libretime will schedule tracks from a selected playlist an hour before a show is
> scheduled to air. This is a great way to automatically schedule weekly shows which are received
> via. podcasts.
### Creating a new playlist
## Creating a new playlist
You can create a new playlist on the toolbar of the **Playlists** page.
![](/img/Playlist-Editor.png)
![](./playlists-playlist-editor.png)
Enter a **Name** and **Description** for the playlist, then click the **Save** button. Setting good quality metadata here will help you find the playlist using the search box later, so you should be as descriptive as possible.
@ -32,9 +24,13 @@ When your playlist is complete, click the **New** button in the top left corner
If you want to edit the playlist content or metadata later, you can find it by **Title**, **Creator**, **Last Modified** date, **Length**, **Owner** or **Year** using one of the search tools on the Library page. Click the playlist in the search results list, and then click **Edit** from the pop-up menu. You can also **Preview** the entire playlist in a pop-up audition window, **Duplicate** or **Delete** one of your playlists from this menu.
### Creating a Smartblock
### Autoloading Playlists
![](/img/Smartblock-options.png)
Libretime will schedule tracks from a selected playlist an hour before a show is scheduled to air. This is a great way to automatically schedule weekly shows which are received via. podcasts.
## Creating a Smartblock
![](./playlists-smartblock-options.png)
Smart blocks are automatically filled with media files from the LibreTime library, according to the criteria that you specify. This feature is intended to save staff time, compared to selecting items for a playlist manually, and can be used to schedule shows that operate in a consistent format.
@ -44,20 +40,25 @@ Fill out the smart block's **Name**, **Search Criteria**, and **Limit to** secti
If you have a large number of files which meet the criteria that you specify, you may wish to limit the duration of the smart block using the **Limit to** field, so that it fits within the show you have in mind. Select **hours**, **minutes** or **items** from the drop-down menu, and click the **Generate** button again, if it is a static smart block. Then click the **Save** button.
> **Note:** Smart Blocks by default will not overflow the length of a scheduled show.
> This is to prevent tracks from being cut-off because they exceed the time limit of a show.
> If you want a smartblock to schedule tracks until it is longer than the Time Limit you can check **"Allow last track to exceed time limit"**
> (helpful for avoiding dead air on autoscheduled shows).
:::note
![](/img/Smartblock-advanced.png)
Smart Blocks by default will not overflow the length of a scheduled show. This is to prevent tracks from being cut-off because they exceed the time limit of a show. If you want a smartblock to schedule tracks until it is longer than the Time Limit you can check **"Allow last track to exceed time limit"** (helpful for avoiding dead air on autoscheduled shows).
:::
![](./playlists-smartblock-advanced.png)
You can also set the **smart block type**. A **Static** smart block will save the criteria and generate the block content immediately. This enables you to edit the contents of the block in the **Library** page before adding it to a show. A **Dynamic** smart block will only save the criteria, and the specific content will be generated at the time the block is added to a show. After that, the content of the show can be changed or re-ordered in the **Now Playing** page.
Click the **plus button** on the left to add OR criteria, such as **Creator** containing _beck_ OR _jimi_. To add AND criteria, such as **Creator** containing _jimi_ AND BPM in the range _120_ to _130_, click the **plus button** on the right. (The criteria are not case sensitive). Click **Preview** to see the results.
> If you see the message **0 files meet the criteria**, it might mean that the files in the Library have not been tagged with the correct metadata. See the chapter [Preparing media](/docs/preparing-media) for tips on tagging content.
:::tip
![](/img/Smartblock-content.png)
If you see the message **0 files meet the criteria**, it might mean that the files in the Library have not been tagged with the correct metadata. See the chapter [Preparing media](/docs/guides/preparing-media) for tips on tagging content.
:::
![](./playlists-smartblock-content.png)
If you don't like the ordering which is generated, click the **Shuffle** button, or drag and drop the smart block contents into the order that you prefer. You can also remove items or add new items manually from the Library. Changes to static smart block contents are saved automatically when you add items, remove or re-order them, or click the **Generate** button. Click the **Save** button in the upper right corner to save any changes to smart block criteria.

8
docs/guides/playout-history.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Playout History
category: manager
---
On the History menu, the **Playout History** page enables you to view a list of files played within a specific date and time range. This page is designed to help your station prepare reports for music royalty collection societies and regulatory agencies.
@ -10,7 +8,7 @@ Search results can be copied to the clipboard using the **Copy** button, exporte
This page has three tabs: **Log Sheet**, **File Summary** and **Show Summary**. On any of these tabs, you can select a date and time range by clicking the calendar and clock icons in the upper left corner of the page. Then click the search button, which has a magnifying glass icon, to the right. A list of files played during that date and time range will appear further down the page.
![](/img/log-sheet.png)
![](./playout-history-log-sheet.png)
In the **Log Sheet** tab, the playout history is sorted by **Start Time** and **End Time** by default.
@ -26,11 +24,11 @@ Log entries can also be manually deleted, using the button with the trashcan ico
## History Templates
![](/img/history-templates.png)
![](./playout-history-history-templates.png)
The **History Templates** page on the History menu enables you to prepare reports with the exact content required by regulatory agencies in the territories that you are broadcasting to. You can begin creating a custom template by clicking the button **New Log Sheet Template** or the button **New File Summary Template**.
![](/img/new-hist-temp.png)
![](./playout-history-new-hist-temp.png)
Either of these actions opens a page in which you can name the new template, and add or remove elements from the list on the left. To add a new element from the list on the right, click the plus icon for the item you require. If the element you require is not listed, you can use the **Add New Field** box at the lower end of the right side column. Select _string_, _boolean_, _integer_, or _float_, depending on the type of data that you wish to log, and then click the **+ Add** button.

16
docs/guides/podcasts.md
View File

@ -1,14 +1,18 @@
---
title: Podcasts
layout: article
category: interface
---
The Podcasts page allows you add subscriptions to podcasts which are often used to syndicated audio files using a URL called a RSS feed. This allows your LibreTime instance to automatically download new shows from the web.
In order to add a podcast you need to get the RSS feed. All podcasts available on iTunes have a RSS feed but it is sometimes hidden. See this issue on our github page [#510](https://github.com/LibreTime/libretime/issues/510) for more information. RSS feeds that do not end in _.xml_ may be accepted by LibreTime but might fail to download episodes; in that case, download the episode using a podcast client such as [gpodder](https://gpodder.github.io/) and then manually upload and schedule the episode. Podcast feeds coming from Anchor.fm have been known to have this issue.
:::info
The podcast interfaces provides you with the ability to generate [Smartblocks](/docs/playlists) that can be used in conjunction with autoloading playlists to schedule the newest episode of a podcast without human intervention.
All podcasts available on iTunes have a RSS feed but it is sometimes hidden. See issue [#510](https://github.com/LibreTime/libretime/issues/510) for more information. RSS feeds that do not end in _.xml_ may be accepted by LibreTime yet fail to download episodes. A work-around is to download the episode using a podcast client such as [gpodder](https://gpodder.github.io/) and then manually upload and schedule the episode.
Podcast feeds coming from Anchor.fm have been known to have a similar issue.
:::
The podcast interfaces provides you with the ability to generate [Smartblocks](/docs/guides/playlists) that can be used in conjunction with autoloading playlists to schedule the newest episode of a podcast without human intervention.
<html>
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/g-4UcD8qvR8" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
@ -16,7 +20,7 @@ The podcast interfaces provides you with the ability to generate [Smartblocks](/
### Podcasts Dashboard
![](/img/Podcasts_Dashboard.png)
![](./podcasts-podcasts_dashboard.png)
The podcasts dashboard is similar to the tracks view, allowing you to add, edit, and remove
podcasts by the toolbar, in addition to sorting by columns.
@ -26,7 +30,7 @@ Once the podcast's feed is recognized, the editor pane opens for the podcast.
### Editor
![](/img/Podcasts_Editor.png)
![](./podcasts-podcasts_editor.png)
In the podcasts editor, you can rename the podcast, update settings for the podcast, and manage episodes.
A search box is available to search for episodes within the feed.

22
docs/guides/preparing-media.md
View File

@ -1,14 +1,12 @@
---
layout: article
title: Preparing Media for Upload
category: interface
---
Before uploading media to an LibreTime server, there are a number of factors which should be considered. Getting your ingest workflow right will save you a lot of time later.
## Metadata quality
LibreTime automatically imports any metadata that is in the files' ID3 tags. If these tags are incorrect or are missing information, you will have to either edit the metadata manually, or suffer the consequences. For example, if the files have creator or genre metadata missing, it will be impossible to search for, create playlists or generate smart blocks according to these criteria until you add it.
LibreTime automatically imports any metadata that is in the files' ID3 tags. If these tags are incorrect or are missing information, you will have to either edit the metadata manually. Files with metadata such as track title and artist information may be difficult to locate in larger libraries, or add to shows, playlists, or smart blocks.
There are a number of programs available which can be used to correct mistakes or incomplete information in ID3 tags. You can use a music library manager (like Apple Music, Rhythmbox, or Windows Media Player) to edit ID3 tags as well, but you may be required to import the files into your library, which may not always be convenient.
@ -19,15 +17,13 @@ There are a number of programs available which can be used to correct mistakes o
The _Tags From Path_ feature of Ex Falso is a particularly useful time saver if you have a large archive of untagged files. Sometimes there is useful creator or title information in the file name or directory path structure, which can be converted into an ID3 tag automatically.
![](/img/Screenshot175-Ex_Falso.png)
![](./preparing-media-screenshot175-ex_falso.png)
## Metadata in legacy character sets
LibreTime expects file tag metadata to be stored in the international _UTF-8_ character set. Programs such as **Ex Falso** (described above) encode metadata in UTF-8 by default. If you have an archive of files encoded with metadata in a legacy character set, such as the Cyrillic encoding _Windows-1251_, you should convert these files before import.
The program **mid3iconv** (part of the **python-mutagen** package in Debian and Ubuntu) can be used to batch convert the metadata character set of files on the command line. You can install **python-mutagen** with the command:
sudo apt-get install python-mutagen
The program **mid3iconv** (part of the **python-mutagen** package in Debian and Ubuntu) can be used to batch convert the metadata character set of files on the command line. You can install **python-mutagen** with the `sudo apt-get install python-mutagen`.
<span id="Convert_MP3_Tags_using_mid3iconv" class="mw-headline"> For example, to preview the conversion of tags from Windows-1251 </span><span id="Convert_MP3_Tags_using_mid3iconv" class="mw-headline">(CP1251)</span><span id="Convert_MP3_Tags_using_mid3iconv" class="mw-headline"> character set to UTF-8 for a whole archive of MP3 files, you could use the command: </span>
@ -89,8 +85,14 @@ In the output from vorbisgain, _Peak_ is the maximum sample value of the file be
## Silence in media files
Before importing media, it is good practice to check for any silent sections in the media files. While LibreTime compensates for leading and trailing silence with the use of automatic cue-in and cue-out points, it may be preferable to trim these files to the intended length before upload. This is because media in the LibreTime library could potentially be re-used in many different systems. There are many cross-platform audio editors, including [Audacity](https://www.audacityteam.org/) and [ocenaudio](https://www.ocenaudio.com/), that are suitable for the task of trimming audio files
Before importing media, it is good practice to check for any silent sections in the media files. While LibreTime compensates for leading and trailing silence with the use of automatic cue-in and cue-out points, it is best to trim these files to the intended length before upload. Two notable audio file editors for removing silent sections are [Audacity](https://www.audacityteam.org/) and [Ocenaudio](https://www.ocenaudio.com/).
Quiet introductions or extended fades can also lead to apparent gaps in your broadcast playout. This is more common when playing back audio from ripped CDs or dubbed from tape or vinyl; this issue is not as common with digitally-purchased music. For best results, long periods of silence should be removed from files before uploading to Libretime.
:::danger
![](/img/Screenshot126-Debra_silence.png)
Gaps in playout or dead air can have legal repercussions for your station. Check with your station manager or local or state communications authority for more information.
:::
Quiet introductions or extended fades can also lead to apparent gaps in your broadcast playout. This is more common when playing back audio from ripped CDs or dubbed from tape or vinyl. Long periods of silence should be removed from files before uploading to Libretime.
![](./preparing-media-screenshot126-debra_silence.png)

60
docs/guides/scheduling-shows.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: Scheduling Shows
category: interface
---
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/TJtWUzAlP08" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
@ -13,7 +11,7 @@ The main workflow in LibreTime is **Upload** media -> create a show on the **Cal
Once you log in, click on the big blue button on the left navigation that says **Upload**.
![](/img/Select_files.png)
![](./scheduling-shows-select_files.png)
Select the type of media you are uploading (Music, Station IDs, etc.) by using the dropdown box
at the top of the pane. After that, either drag and drop media into the area below or click the
@ -22,17 +20,43 @@ dashed rectangle to open a file browser.
Once your files have uploaded and have been successfully imported (as shown in the pane on the right),
click on **Calendar** on the left navigation.
![](/img/Screenshot558-Add_Show.png)
![](./scheduling-shows-screenshot558-add_show.png)
Click on the blue **+ New Show** button to add a new show.
![](/img/Screenshot560-Show_when.png)
![](./scheduling-shows-screenshot560-show_when.png)
At the very minimum, fill out the show's name and when the show will take place. If the show will repeat regularly,
check the **Repeats?** box and fill out the repeat information. A description of all fields of the New Show box
are in the table below. Finially, click on the grey **+ Add this show** button at the top
are in the table below. Finally, click on the grey **+ Add this show** button at the top
of the pane to add your show to the calendar.
Once your show is created, click on it to open its context menu. Select **Schedule Tracks** to open the track scheduler.
![](./scheduling-shows-screenshot561-add_show_content.png)
The track scheduler behaves similarly to iTunes or Windows Media Player: media browser on the left, playlist on the right.
Find the tracks that you would like to schedule by using the search box or sorting columns and then dragging them
into the playlist.
![](./scheduling-shows-screenshot562-drag_show_content.png)
The bar at the end of the show's playlist will show the amount of time the show is underscheduled or overscheduled.
Shows that are underscheduled will have dead air at the end and shows that are overscheduled
will fade out exactly when the show is over (the orange colored entry), meaning tracks scheduled to start
after this point will not play (dark red colored entries). Click the **Ok** button in the bottom right to save.
Show playback will start and end as per each show's start and end times, allowing you to rely completely on
LibreTime for running your station or using LibreTime as a part of your live setup to cover when DJs are not present.
When media is playing, the **On Air** indicator at the top will turn red.
![](./scheduling-shows-on-air-status.png)
You can listen to your stream by going to `yourserverIP:8000` or by clicking the **Listen** button under the On Air
indicator.
### Show Properties Appendix
| Field | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| _What_ | |
@ -56,27 +80,3 @@ of the pane to add your show to the calendar.
| _Style_ | |
| Background/Text Color | Set the color of the background and text of entries on the calendar. If not set, LibreTime will select contrasting colors for easy readability. |
| Show Logo | If desired, you can upload a show logo here. The logo does not appear on the public page. |
Once your show is created, click on it to open its context menu. Select **Schedule Tracks** to open the track scheduler.
![](/img/Screenshot561-Add_show_content.png)
The track scheduler behaves similar to iTunes or Windows Media Player: media browser on the left, playlist on the right.
Find the tracks that you'd like to schedule by using the search box or sorting columns and then drag them
into the playlist.
![](/img/Screenshot562-Drag_show_content.png)
The bar at the end of the show's playlist will show the amount of time the show is underscheduled or overscheduled.
Shows that are underscheduled will have dead air at the end and shows that are overscheduled
will fade out exactly when the show is over (the orange colored entry), meaning tracks scheduled to start
after this point will not play (dark red colored entries). Click the **Ok** button in the bottom right to save.
Show playback will start and end as per each show's start and end times, allowing you to rely completely on
LibreTime for running your station or using LibreTime as a part of your live setup to cover when DJs are not present.
When media is playing, the **On Air** indicator at the top will turn red.
![](/img/on-air-status.png)
You can listen to your stream by going to `yourserverIP:8000` or by clicking the **Listen** button under the On Air
indicator.

28
docs/guides/settings.md
View File

@ -1,19 +1,17 @@
---
layout: article
title: Settings
category: admin
---
## General Settings
![](/img/station-info-settings.png)
![](./settings-station-info-settings.png)
On the **Settings** menu, click **General** to set your **Station Name**. This
text is shown in your web browser's title bar when your station staff are logged
into LibreTime, and optionally in stream metadata. You can also set a **Station
Description** and **Station Logo** here.
![](/img/general-playback-settings.png)
![](./settings-general-playback-settings.png)
The **Default Interface Language** drop-down menu sets the default localization
for your LibreTime instance, and the **Station Timezone** drop-down menu can be
@ -49,7 +47,7 @@ podcast to LibreTime. This can also be done manually by the generate smartblock
and playlist button under a podcasts settings which is why it is disabled by
default.
![](/img/api-settings.png)
![](./settings-api-settings.png)
You can opt-in to test new features with the **Feature Previews** option.
Features that we soft rollout this way may need more feedback or still have
@ -59,7 +57,7 @@ refactors. You can switch back at any time.
You can enable live, read-only access to the LibreTime schedule calendar for
your station's public website with the **Public LibreTime API** option, if you
wish. (There is more about this feature in the
[_Exporting the schedule_](/docs/playout-history) chapter, in the
[_Exporting the schedule_](/docs/guides/playout-history) chapter, in the
_Advanced Configuration_ section of this book).
The **Allowed CORS URLs** is intended to deal with situations where you want a
@ -68,22 +66,20 @@ there is a reverse proxy server in front of LibreTime. If you are using a
reverse proxy, the URLs that will be used to access it should be added here.
The **Display login button on your Radio Page?** will determine whether visitors
to your site see a link to login. If this is disabled DJs and admins will need
to your site see a link to login. If this is disabled, DJs and admins will need
to goto http://SITEURL/login to be able to login.
The **Tune-In Settings** section is intended for stations that have partnered
with TuneIn to automatically push their now playing metadata to TuneIn. This
hasn't been tested and also requires special credentials from TuneIn.
![](/img/dangerous-options.png)
The **Dangerous Options** section provides an administrator the ability to erase LibreTime's track library.
The **Dangerous Options** section provides an administrator the ability to erase
the entire LibreTime library.
:::danger
When you are done remember click the **Save** button at the top or bottom of the
form.
Erasing Libretime's track library cannot be undone.
![](/img/save-button.png)
:::
Individual LibreTime users can choose another interface localization when they
log in, or set personal preferences for localization and time zone by clicking
@ -91,7 +87,7 @@ their username on the right side of the menu bar.
---
## Track Types {#types}
## Track Types
### Create track types
@ -148,11 +144,11 @@ If your Airtime server is behind a firewall, and you wish remote broadcasters to
In the Master Panel, available input source streams are shown with an orange line connecting the source to the switch, which you could think of like a patch cable connecting a source to a broadcast mixer. When that switch is active, another orange line connects the switch to the On Air indicator, like a patch cable connecting a mixer to a transmitter.
![](/img/libretime-master-source-stream.png)
![](./settings-libretime-master-source-stream.png)
If you have checked the **Auto Switch On** box in the Stream Settings page, the **Master Source** switch will move automatically to the active position, on the left, when an authenticated master source connects to Airtime. Otherwise, you can activate the switches manually by clicking the left side of each switch, or deactivate them by clicking the right side. The switches do not have to be dragged with the mouse, in the way that a switch on a hardware mixer would be pushed sideways. **Show Source** live input streams can also be manually activated or deactivated in the same way. If neither the show source or master source is active then LibreTime will default to what is scheduled to play in the Calendar.
![](/img/libretime-show-source-stream.png)
![](./settings-libretime-show-source-stream.png)
If you have the **Auto Switch Off** box checked LibreTime will resume scheduled playback whenever a stream disconnects. Otherwise you will need to slide to disable a source after a DJ stops streaming.

8
docs/guides/status.md
View File

@ -1,17 +1,15 @@
---
layout: article
title: System Status
category: admin
---
On the **Settings** menu, the **Status** page provides an overview of the health and resource usage of the various
services that make up a LibreTime system. If all is well, you will only see green check mark icons in the
**Status** column. This page also shows how much **Disk Space** you have used on the disk partition containing the media storage folder.
Status column. This page also shows how much **Disk Space** you have used on the disk partition containing the media storage folder.
![](/img/Screenshot521-System_status_240.png)
![](./status-screenshot521-system_status_240.png)
If any of the check mark icons in the **Status** column have changed to a red warning sign, contact your system
administrator for assistance. (The chapter [Troubleshooting](/docs/troubleshooting) contains some tips). LibreTime will
administrator for assistance. LibreTime will
do its best to restart any failing services, but sometimes manual intervention may be required; for example, in the case of hardware failure.
If you have run out of storage space, a LibreTime user with _admin_ privileges could log in and delete media files

31
docs/guides/users.md
View File

@ -1,23 +1,23 @@
---
layout: article
title: Managing Users
category: interface
---
> Note: if your Libretime server is accessible from the public Internet (ex. being hosted in a cloud VM)
> it is strongly recommended to create a second administrator account with a secure password and then
> delete the `admin` account.
:::danger
It is strongly recommended not to use the default `admin` account in production, especially if your LibreTime server is accessible from the internet.
:::
## User Account Types
To add further user accounts to the system, one for each of your station staff that need access to Airtime, click the **New User** button with the plus icon. Enter a user name, password and contact details, and then select the **User Type** from the drop down menu, which can be _Admin_, _Program Manager_, _DJ_, or _Guest_. The difference between these user types is:
To add further user accounts to the system, one for each of your station staff that need access to Airtime, click the **New User** button with the plus icon. Enter a user name, password and contact details, and then select the **User Type** from the drop down menu, which can be _Admin_, _Program Manager_, _DJ_, or _Guest_.
**Guests**
### Guests
- Can view shows and the playout log on the Calendar and Dashboard, respectively
- Listen to the output stream without leaving the interface
**DJs**
### DJs
- Everything Guests can do, plus
- Upload media (music, PSAs, underwriting, shows, etc.) to their own library (DJs cannot view other libraries)
@ -25,7 +25,7 @@ To add further user accounts to the system, one for each of your station staff t
- Preview uploaded media _without_ affecting the live playout
- Create Playlists, Smart Blocks, and connect Podcasts and Webstreams to LibreTime
**Program Managers**
### Program Managers
- Everything DJs can do, plus
- Manage other users' libraries in addition to their own
@ -34,7 +34,7 @@ To add further user accounts to the system, one for each of your station staff t
- View listener statistics
- Export playout logs for analysis or reporting for music royalties
**Administrators**
### Administrators
- Everything Program Managers can do, plus
- Manage all user accounts, including the ability to reset passwords
@ -43,18 +43,11 @@ To add further user accounts to the system, one for each of your station staff t
## Editing or deleting user accounts
![](/img/user-list.png)
New user accounts that you add will be shown in the table on the left side of the **Users** page. If you have a
large number of users on the system, you can use the search tool above the table (which has a magnifying glass icon)
to identify specific user accounts. Click the white chevrons in the table headings to sort the search results
by **Username**, **First Name**, **Last Name** or **User Type**.
![](/img/user-edit.png)
To edit a user account, click on that user's row in the table, change the user's details in the box on the
right side, and then click the **Save** button. To remove a user account, click the small **x** icon to the right
side of its row in the table. You cannot delete your own user account, and usernames cannot be changed once created.
![](./users-user-edit.png)
Users can update their own password, and their contact, language and time zone details, by clicking their username on the
right side of the main menu bar, next to the **Logout** link.

12
docs/guides/webstreams.md
View File

@ -1,21 +1,23 @@
---
title: Webstreams
layout: article
category: interface
---
<html>
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Ha3X6aYdY04" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</html>
### Adding a webstream
## Adding a webstream
A web stream URL and metadata can be added to the LibreTime library, so that a remote stream can be searched for and scheduled to be _pulled_ into a show. For example, at the top of the hour your station may pull a news report from journalists working in another studio. This is a different concept from **Master Source** and **Show Source** remote streams which are _pushed_ into the LibreTime playout schedule.
To add a web stream, click the **+ New** button on the left side of the Webstreams page. Like a playlist, web streams in the Library can have a title and **Description**, which may help you find them in searches later.
![](/img/webstream.jpg)
![](./webstreams-webstream.jpg)
The **Stream URL** setting must include the _port number_ (such as 8000) and _mount point_ (such as remote_stream) of the remote stream, in addition to the streaming server name. A **Default Length** for the remote stream can also be set. If the stream is added at the end of a show which becomes overbooked as a result, it will be faded out when the show ends.
Note: LibreTime checks the remote webstream's status upon editing stream settings, so an offline stream will result in an error. There are many tools such as [BUTT](https://danielnoethen.de/butt/) and [MIXXX](https://www.mixxx.org) that can be used to send a test stream to LibreTime can save it; read more [here](/docs/live-broadcast).
:::note
LibreTime checks the remote webstream's status upon editing stream settings, so an offline stream will result in an error. There are many tools such as [BUTT](https://danielnoethen.de/butt/) and [MIXXX](https://www.mixxx.org) that can be used to send a test stream to LibreTime can save it; read more [here](/docs/guides/live-broadcast).
:::

57
docs/intro.md Normal file
View File

@ -0,0 +1,57 @@
---
sidebar_position: 1
---
# Introduction
Libretime is an open-source radio automation system. It can be used for music and show playout in a radio studio or start an internet radio station on its own. Libretime runs on Ubuntu and Debian Linux; [we're also working on making Docker images](https://github.com/LibreTime/libretime/issues/949).
## Getting Started
Get started by installing Libretime on your server. Open up your terminal and enter
```bash
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo ./install -fiap
```
After the installer is done, head to your server's IP address in a web browser and complete the setup wizard.
### Upload some music
Login using the default username and password and click on the blue **Upload** button in the left pane. Drag and drop files onto the upload area or click to browse for files on your computer.
![](./guides/scheduling-shows-select_files.png)
Once the files have uploaded and finished being analyzed, you can schedule your first show.
### Schedule your first show
Navigate to the Calendar and click the **+ New Show** button on the toolbar.
![](./guides/scheduling-shows-screenshot560-show_when.png)
Fill out the **What** (name, description of your show) and **When** (start time, end time) blocks, then click the grey **+ Add This Show** button at the top.
Click on the new show in the Calendar to open its context menu and select **Schedule Tracks**.
![](./guides/scheduling-shows-screenshot561-add_show_content.png)
Your uploaded tracks, playlists, smartblocks, and webstreams appear in the left pane; drag them to the right pane in the order you want them to play back for your show. The bar at the bottom of the right playlist tells you how much time you have left in your show.
![](./guides/scheduling-shows-screenshot562-drag_show_content.png)
When you're done, click **Ok** at the bottom of the window.
### That's it!
You just scheduled your first show! It will automatically begin playing back at the time your show is set to start. You can listen to what is playing live by clicking the **Listen** button under the On Air indicator in the top right corner.
## Next Steps
- Make sure you [set the time on your server](/docs/getting-started/set-server-time)
- Learn how to [work with podcasts](/docs/guides/podcasts)
- [Create user accounts](/docs/guides/users) for your DJs, Program Managers, and Administrators
- Learn how to [broadcast live](/docs/guides/live-broadcast) from your studio

77
docs/local-dev.md
View File

@ -1,26 +1,12 @@
---
layout: article
title: Using Vagrant for local development
category: dev
title: Local Development
---
> Prerequisites: git, [Vagrant](https://vagrantup.com), libvirt or VirtualBox
## Vagrant
## VirtualBox
To use Vagrant, you need to install a virtualization engine: [VirtualBox](https://www.virtualbox.org) or Libvirt. The [vagrant-vbguest] package on Github can help maintain guest extensions on host systems using VirtualBox.
You will need to install [VirtualBox](https://www.virtualbox.org) and may want to consider
installing [vagrant-vbguest](https://github.com/dotless-de/vagrant-vbguest) to update the
guest extensions to match your host system on vagrant up.
```bash
vagrant plugin install vagrant-vbguest
```
## Libvirt
Setting the libvirt provider up on Ubuntu and Debian is straight-forward,
using the distribution provided packages. While on
other distributions it can be built from within vagrant.
:::tip
If you try run a libvirt provided box after using a VirtualBox one, you will receive an
error:
@ -32,28 +18,34 @@ Call to virNetworkCreate failed: internal error: Network is already in use by in
This is fixed by stopping virtualbox and re-creating the vagrant box:
```
```bash
sudo systemctl stop virtualbox
vagrant destroy ubuntu-bionic
vagrant up ubuntu-bionic --provider=libvirt
```
### Debian and Ubuntu
:::
### Installing Libvirt
On Debian and Ubuntu:
1. Install Vagrant
```bash
sudo apt install vagrant vagrant-libvirt libvirt-daemon-system vagrant-mutate libvirt-dev
sudo usermod -aG libvirt $USER
```
# Reboot
2. Reboot your computer, and then run
```bash
vagrant box add bento/ubuntu-18.04 --provider=virtualbox
vagrant mutate bento/ubuntu-18.04 libvirt
vagrant up ubuntu-bionic --provider=libvirt
```
### Other Distributions
You will need to install [libvirt](https://libvirt.org/) and `vagrant-mutate` and then run
On other distributions, you will need to install [libvirt](https://libvirt.org/) and `vagrant-mutate` and then run
```bash
vagrant plugin install vagrant-libvirt
@ -67,7 +59,7 @@ vagrant mutate bento/ubuntu-18.04 libvirt
vagrant up ubuntu-bionic --provider=libvirt
```
## Starting LibreTime Vagrant
### Starting LibreTime Vagrant
To get started you clone the repo and run `vagrant up`. The command accepts a parameter to
change the default provider if you have multiple installed. This can be done by appending
@ -86,7 +78,7 @@ Once you reach the web setup GUI you can click through it using the default valu
connect to the vagrant machine you can run `vagrant ssh ubuntu-bionic` in the libretime
directory.
## Alternative OS installations
### Alternative OS installations
With the above instructions LibreTime is installed on Ubuntu Bionic. The Vagrant setup
offers the option to choose a different operation system according to you needs.
@ -99,10 +91,41 @@ offers the option to choose a different operation system according to you needs.
| Ubuntu 20.04 | `vagrant up ubuntu-focal` | Install on Ubuntu Focal Fossa. |
| CentOS | `vagrant up centos` | CentOS 8 with native systemd support and activated SELinux. |
## Troubleshooting
### Troubleshooting
If anything fails during the initial provisioning step you can try running `vagrant provision`
to re-run the installer.
If you only want to re-run parts of the installer, use `--provision-with $step`. The
supported steps are `prepare` and `install`.
## Multipass
[Multipass](https://multipass.run) is a tool for easily setting up Ubuntu VMs on Windows, Mac, and Linux.
Similar to Docker, Multipass works through a CLI. To use, clone this repo and then create a new Multipass VM.
```
git clone https://github.com/libretime/libretime.git
cd libretime
multipass launch bionic -n ltTEST --cloud-init cloud-init.yaml
multipass shell ltTEST
```
Multipass isn't currently able to do an automated install from the cloud-init script.
After you enter the shell for the first time, you will still need to [run the Libretime installer](/docs/getting-started/install).
The IP address of your new VM can be found by running `multipass list`. Copy and paste it into your web browser to access the LibreTime interface and complete the setup wizard.
You can stop the VM with `multipass stop ltTEST` and restart with `multipass start ltTEST`.
If you want to delete the image and start again, run `multipass delete ltTEST && multipass purge`.
### Cloud-init options in cloud-init.yaml
You may wish to change the below fields as per your location.
```yaml
timezone: America/New York # change as needed
ntp:
pools: ["north-america.pool.ntp.org"]
servers: ["0.north-america.pool.ntp.org", "0.pool.ntp.org"]
```

46
docs/multipass.md
View File

@ -1,46 +0,0 @@
---
title: Multipass
layout: article
category: dev
---
[Multipass](https://multipass.run) is a tool for easily setting up Ubuntu VMs on Windows, Mac, and Linux.
Similar to Docker, Multipass works through a CLI. To use, clone this repo and then create a new Multipass VM.
```
git clone https://github.com/libretime/libretime.git
cd libretime
multipass launch bionic -n ltTEST --cloud-init cloud-init.yaml
multipass shell ltTEST
```
Multipass isn't currently able to do an automated install from the cloud-init script.
After you enter the shell for the first time, you will still need to run the install script for LibreTime.
```
cd /libretime
sudo bash install -fiap
```
The IP address of your new VM can be found by running `multipass list`. Copy and paste it into your web browser to access the LibreTime interface and complete the setup wizard.
You can stop the VM with `multipass stop ltTEST` and restart with `multipass start ltTEST`.
If you want to delete the image and start again, run `multipass delete ltTEST && multipass purge`.
### Cloud-init options in cloud-init.yaml
You may wish to change the below fields as per your location.
```
timezone: America/New York # change as needed
ntp:
pools: ['north-america.pool.ntp.org']
servers: ['0.north-america.pool.ntp.org', '0.pool.ntp.org']
```
If you are running your forked repo of LibreTime for testing purposes,
modify the URL on this line:
```
- cd / && git clone https://github.com/LibreTime/libretime.git
```

4
docs/server-config/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "Server Configuration",
"position": 5
}

17
docs/server-config/backing-up-the-server.md
View File

@ -1,13 +1,12 @@
---
layout: article
title: Backing Up Libretime
category: admin
---
> At the moment, there is not a way to automatically restore a Libretime backup.
> To restore a failed Libretime instance, install a fresh copy, go through the
> standard setup process, and reupload the backed-up media files. A _Watched Folders_
> feature is [currently in development](https://github.com/LibreTime/libretime/issues/70).
:::info
At the moment, there is no script to cleanly restore a Libretime backup. To restore a Libretime backup, install a fresh copy, go through the standard setup process, and reupload the backed-up media files.
:::
A backup script is supplied for your convenience in the _utils/_ folder of the Libretime repo.
Run it using:
@ -62,4 +61,8 @@ Two notible backup tools are [rsync](http://rsync.samba.org/) (without version c
[rdiff-backup](http://www.nongnu.org/rdiff-backup/) (with version control). _rsync_ comes
preinstalled with Ubuntu Server.
> **Note:** Standard _rsync_ backups, which are used by the backup script, cannot restore files deleted in the backup itself
:::note
Standard rsync backups, which are used by the backup script, cannot restore files deleted in the backup itself
:::

2
docs/server-config/freeipa.md
View File

@ -1,7 +1,5 @@
---
layout: article
title: FreeIPA Configuration
category: install
---
You can configure LibreTime to delegate all authentication to a FreeIPA server.

255
docs/server-config/host-configuration.md
View File

@ -1,77 +1,78 @@
---
title: Host Configuration
layout: article
category: install
---
The streaming host configuration for LibreTime is shown in the file _/etc/airtime/liquidsoap.cfg_ which is automatically generated by the **Streams** page, found on the **System** menu of the LibreTime administration interface. For this reason, you would not normally edit the streaming configuration manually, as any changes are likely to be overwritten by the administration interface.
## Database and RabbitMQ hosts {#database}
## Database and RabbitMQ hosts
Optionally, you may wish to edit the file _/etc/airtime/airtime.conf_ to set the PostgreSQL database host, and the username and password to connect to the database with:
sudo nano /etc/airtime/airtime.conf
Optionally, you may wish to edit the file _/etc/airtime/airtime.conf_ to set the PostgreSQL database host, and the username and password to connect to the database with.
You can also set options for RabbitMQ messaging and the LibreTime server in this file, although you should not normally need to adjust the defaults unless you are running a large LibreTime system distributed across multiple servers. To run the LibreTime server in demo mode, which changes the greeting on the login page and prevents user accounts from being created or modified, set the value of _demo_ to 1.
[database]
host = localhost
port = 5432
name = libretime
user = libretime
password = libretime
```ini title="/etc/airtime/airtime.conf"
[database]
host = localhost
port = 5432
name = libretime
user = libretime
password = libretime
[rabbitmq]
host = 127.0.0.1
port = 5672
user = airtime
password = XXXXXXXXXXXXXXXXXXXX
vhost = /airtime
[rabbitmq]
host = 127.0.0.1
port = 5672
user = airtime
password = XXXXXXXXXXXXXXXXXXXX
vhost = /airtime
[general]
api_key = XXXXXXXXXXXXXXXXXXXXX
web_server_user = www-data
airtime_dir = /usr/share/airtime
base_url = libretime.example.com
base_port = 80
base_dir = /
cache_ahead_hours = 1
[general]
api_key = XXXXXXXXXXXXXXXXXXXXX
web_server_user = www-data
airtime_dir = /usr/share/airtime
base_url = libretime.example.com
base_port = 80
base_dir = /
cache_ahead_hours = 1
[monit]
monit_user = guest
monit_password = airtime
[monit]
monit_user = guest
monit_password = airtime
[demo]
demo = 0
[demo]
demo = 0
```
Save and close the file with **Ctrl+O** and **Ctrl+X**. In order to update the configuration
used by the various components of LibreTime, run the following commands
Save and close the file then, run the following commands to restart Libretime's services:
sudo systemctl restart libretime-liquidsoap
sudo systemctl restart libretime-playout
sudo systemctl restart libretime-celery
sudo systemctl restart libretime-analyzer
```bash
sudo systemctl restart libretime-liquidsoap
sudo systemctl restart libretime-playout
sudo systemctl restart libretime-celery
sudo systemctl restart libretime-analyzer
```
## API client configuration {#api}
## API client configuration
The LibreTime API enables many types of information about the broadcast schedule and configuration to be retrieved from the LibreTime server. Other than the live-info and week-info data fetched by website widgets (see the chapter _Exporting the schedule_), all API requests must be authenticated using the secret API key stored in the file _/etc/airtime/api_client.cfg_ on the LibreTime server. This key is autogenerated during LibreTime installation and should be unique for each server.
If you intend to use the LibreTime API across a public network, for security reasons it is highly recommended that all API requests are sent over encrypted https: and that the web server is configured to accept requests to the api/ directory from specific host names or IP addresses only.
If you have changed the _base_url_, _base_port_ or _base_dir_ setting in _/etc/airtime/airtime.conf_ from the defaults, you will probably also have to update the _Hostname_ settings in the file _/etc/airtime/api_client.cfg_ accordingly.\*\*
If you have changed the _base_url_, _base_port_ or _base_dir_ setting in _/etc/airtime/airtime.conf_ from the defaults, you will probably also have to update the _Hostname_ settings in the file _/etc/airtime/api_client.cfg_ accordingly.
bin_dir = /usr/lib/airtime/api_clients
api_key = 'XXXXXXXXXXXXXXXXXXXX'
api_base = api
host = libretime.example.com
base_port = 80
base_dir = /
```ini
bin_dir = /usr/lib/airtime/api_clients
api_key = 'XXXXXXXXXXXXXXXXXXXX'
api_base = api
host = libretime.example.com
base_port = 80
base_dir = /
```
## Apache max file size configuration {#apache}
## Apache max file size configuration
By default, the maximum upload file size is 40 MB, which may not be large enough for some stations, especially if they are uploading prerecorded shows. The setting for this is located in _/etc/apache2/sites-available/airtime.config_. Search for and update the following in megabytes:
```
```ini
; Maximum allowed size for uploaded files.
upload_max_filesize = 40M
@ -79,88 +80,82 @@ upload_max_filesize = 40M
post_max_size = 40M
```
For quick reference, 1024 MB = 1 GB and 2048 MB = 2 GB, but most will be okay with rounding to the nearest thousand. After updating the config file, restart Apache.
For quick reference, 1024 MB = 1 GB and 2048 MB = 2 GB, but most will be okay with rounding to the nearest thousand. After updating the config file, restart Apache with `sudo systemctl restart apache2`.
## Playout settings
Settings for pypo, the playout engine used by LibreTime, are found in the file _/etc/airtime/airtime.conf_. After making changes to this file, run `sudo systemctl restart libretime-playout`.
```ini
############################################
# pypo - configuration #
############################################
# Set the type of client you are using.
# Currently supported types:
# 1) "obp" = Open Broadcast Platform
# 2) "airtime"
#
api_client = airtime
############################################
# Cache Directories #
# *include* trailing slash !! #
############################################
cache_dir = /var/tmp/airtime/pypo/cache/
file_dir = /var/tmp/airtime/pypo/files/
tmp_dir = /var/tmp/airtime/pypo/tmp/
############################################
# Setup Directories #
# Do *not* include trailing slash !! #
############################################
cache_base_dir = /var/tmp/airtime/pypo
bin_dir = /usr/lib/airtime/pypo
log_base_dir = /var/log/airtime
pypo_log_dir = /var/log/airtime/pypo
liquidsoap_log_dir = /var/log/airtime/pypo-liquidsoap
############################################
# Liquidsoap settings #
############################################
ls_host = 127.0.0.1
ls_port = 1234
############################################
# RabbitMQ settings #
############################################
rabbitmq_host = localhost
rabbitmq_user = airtime
rabbitmq_password = XXXXXXXXXXXXXXXXXXXX
rabbitmq_vhost = /airtime
############################################
# pypo preferences #
############################################
# Poll interval in seconds.
#
# This will rarely need to be changed because any schedule changes are
# automatically sent to pypo immediately.
#
# This is how often the poll script downloads new schedules and files from the
# server in the event that no changes are made to the schedule.
#
poll_interval = 3600# in seconds.
# Push interval in seconds.
#
# This is how often the push script checks whether it has something new to
# push to liquidsoap.
#
# It's hard to imagine a situation where this should be more than 1 second.
#
push_interval = 1# in seconds
# 'pre' or 'otf'. 'pre' cues while playlist preparation
# while 'otf' (on the fly) cues while loading into ls
# (needs the post_processor patch)
cue_style = pre
```
sudo systemctl restart apache2
```
## Playout settings {#playout}
Settings for pypo, the playout engine used by LibreTime, are found in the file _/etc/airtime/airtime.conf_. After making changes to this file, you will have to issue the command:
sudo systemctl restart libretime-playout
for the changes to take effect.
############################################
# pypo - configuration #
############################################
# Set the type of client you are using.
# Currently supported types:
# 1) "obp" = Open Broadcast Platform
# 2) "airtime"
#
api_client = airtime
############################################
# Cache Directories #
# *include* trailing slash !! #
############################################
cache_dir = /var/tmp/airtime/pypo/cache/
file_dir = /var/tmp/airtime/pypo/files/
tmp_dir = /var/tmp/airtime/pypo/tmp/
############################################
# Setup Directories #
# Do *not* include trailing slash !! #
############################################
cache_base_dir = /var/tmp/airtime/pypo
bin_dir = /usr/lib/airtime/pypo
log_base_dir = /var/log/airtime
pypo_log_dir = /var/log/airtime/pypo
liquidsoap_log_dir = /var/log/airtime/pypo-liquidsoap
############################################
# Liquidsoap settings #
############################################
ls_host = 127.0.0.1
ls_port = 1234
############################################
# RabbitMQ settings #
############################################
rabbitmq_host = localhost
rabbitmq_user = airtime
rabbitmq_password = XXXXXXXXXXXXXXXXXXXX
rabbitmq_vhost = /airtime
############################################
# pypo preferences #
############################################
# Poll interval in seconds.
#
# This will rarely need to be changed because any schedule changes are
# automatically sent to pypo immediately.
#
# This is how often the poll script downloads new schedules and files from the
# server in the event that no changes are made to the schedule.
#
poll_interval = 3600# in seconds.
# Push interval in seconds.
#
# This is how often the push script checks whether it has something new to
# push to liquidsoap.
#
# It's hard to imagine a situation where this should be more than 1 second.
#
push_interval = 1# in seconds
# 'pre' or 'otf'. 'pre' cues while playlist preparation
# while 'otf' (on the fly) cues while loading into ls
# (needs the post_processor patch)
cue_style = pre
## RabbitMQ hostname changes
@ -177,19 +172,19 @@ but the RabbitMQ server is running normally, this error might be due to a change
1. Delete the files in _/var/lib/rabbitmq/mnesia/_
```
```bash
sudo rm -r /var/lib/rabbitmq/mnesia/*
```
2. Restart RabbitMQ:
```
```bash
sudo systemctl restart rabbitmq-server
```
3. Enter the following commands to set up authentication and grant permissions. The _rabbitmqctl add_user_ command requires the RabbitMQ password from the /etc/airtime/airtime.conf file as an argument. The _rabbitmqctl set_permissions_ command should be entered on one line, with the list of Airtime services repeated three times:
```
```bash
rabbitmqctl add_vhost /airtime
rabbitmqctl add_user airtime XXXXXXXXXXXXXXXXXXXX
rabbitmqctl set_permissions -p /airtime airtime

132
docs/server-config/icecast.md
View File

@ -1,122 +1,116 @@
---
layout: article
title: Icecast Configuration
category: admin
---
## Background
LibreTime supports direct connection to two popular streaming media servers, the open source **Icecast** (<http://www.icecast.org>) and the proprietary **SHOUTcast** (<http://www.shoutcast.com>). Apart from the software license, the main difference between these two servers is that Icecast supports simultaneous MP3, AAC, Ogg Vorbis or Ogg Opus streaming from LibreTime, whereas SHOUTcast supports MP3 and AAC streams but not Ogg Vorbis or Opus. The royalty-free Ogg Vorbis format has the advantage of better sound quality than MP3 at lower bitrates, which has a direct impact on the amount of bandwidth that your station will require to serve the same number of listeners. Ogg Opus also benefits from good sound quality at low bitrates, with the added advantage of lower latency than other streaming formats. Opus is now an IETF standard (<http://tools.ietf.org/html/rfc6716>) and requires Icecast 2.4 or later to be installed on the streaming server.
LibreTime supports direct connection to two popular streaming media servers, the open source Icecast (<http://www.icecast.org>) and the proprietary SHOUTcast (<http://www.shoutcast.com>). Apart from the software license, the main difference between these two servers is that Icecast supports simultaneous MP3, AAC, Ogg Vorbis or Ogg Opus streaming from LibreTime, whereas SHOUTcast only supports MP3 and AAC streams. The royalty-free Ogg Vorbis format has the advantage of better sound quality than MP3 at lower bitrates, which has a direct impact on the amount of bandwidth that your station will require to serve the same number of listeners. Ogg Opus also benefits from good sound quality at low bitrates, with the added advantage of lower latency than other streaming formats. Opus is now an [IETF standard](http://tools.ietf.org/html/rfc6716) and requires Icecast 2.4 or later to be installed on the streaming server.
Ogg Vorbis playback is supported in **Mozilla Firefox**, **Google Chrome** and **Opera** browsers, via **jPlayer** (<http://jplayer.org/>), and is also supported in several popular media players, including VideoLAN Client, also known as VLC (<http://www.videolan.org/vlc/>). (See the chapter _Stream player for your website_ on how to deliver **jPlayer** to your audience). Ogg Opus is relatively new and is supported natively in the very latest browsers, such as Mozilla Firefox 25.0, and media players including VLC 2.0.4 or later.
Ogg Vorbis playback is supported in most modern web browsers (see [this MDN article](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_codecs#opus) for more information) and desktop players like [VLC](http://www.videolan.org/vlc/).
Streaming MP3 below a bitrate of 128kbps is not recommended for music, because of a perceptible loss of high audio frequencies in the broadcast playout. A 96kbps or 64kbps MP3 stream may be acceptable for voice broadcasts if there is a requirement for compatibility with legacy hardware playback devices which do not support Ogg Vorbis or Opus streams.
Because LibreTime supports simultaneous streaming in multiple formats, it is possible to offer one or more streams via your website, and another independent stream for direct connection from hardware players. You can test whether Ogg streams sound better at low bitrates for yourself, by using the **LISTEN** button in LibreTime's **Master Panel** to switch between streaming formats.
Conversely, you may have a music station which wants to stream at 160kbps or 192kbps to offer a quality advantage over stations streaming at 128kbps or less. Since Ogg, AAC and MP3 formats use lossy compression, listeners will only hear the benefit of higher streaming bitrates if the media files in the LibreTime storage server are encoded at an equivalent bitrate, or higher.
:::tip
Setting a higher bitrate for your output stream will only benefit your listeners if you have high bitrate source material to play. Libretime can convert bitrates down for lower-quality streams but _cannot_ convert up for higher-quality streams.
:::
## UTF-8 metadata in Icecast MP3 streams
When sending metadata about your stream to an Icecast server in non-Latin alphabets, you may find that Icecast does not display the characters correctly for an MP3 stream, even though they are displayed correctly for an Ogg Vorbis stream. In the following screenshot, Russian characters are being displayed incorrectly in the _Current Song_ field for the MP3 stream:
![](/img/Screenshot223-Icecast_UTF-8_metadata.png)
![](./icecast-screenshot223-icecast_utf-8_metadata.png)
The solution is to specify that the metadata for the MP3 mount point you are using should be interpreted using UTF-8 encoding. You can do this by adding the following stanza to the _/etc/icecast2/icecast.xml_ file, where _libretime.mp3_ is the name of your mount point:
<mount>
<mount-name>/libretime.mp3</mount-name>
<charset>UTF-8</charset>
</mount>
```xml
<mount>
<mount-name>/libretime.mp3</mount-name>
<charset>UTF-8</charset>
</mount>
```
After saving the _/etc/icecast2/icecast.xml_ file, you should restart the Icecast server:
sudo invoke-rc.d icecast2 restart
Restarting icecast2: Starting icecast2
Detaching from the console
icecast2.
After saving the _/etc/icecast2/icecast.xml_ file, restart the Icecast server with `sudo systemctl restart icecast2`.
## Icecast handover configuration
In a typical radio station configuration, the live output from the broadcast studio and the scheduled output from LibreTime are mixed together before being sent further along the broadcast chain, to a transmitter or streaming media server on the Internet. (This may not be the case if your LibreTime server is remote from the studio, and you are using the **Show Source Mount Point** or **Master Source Mount Point** to mix live and scheduled content. See the _Stream Settings_ chapter for details).
If your **Icecast** server is hosted in a remote data centre, you may not have the option to handover the streaming media source manually, because you have no physical access to connect a broadcast mixer to the server. Disconnecting the stream and beginning another is less than ideal, because the audience's media players will also be disconnected when that happens.
If your Icecast server is hosted in a remote data centre, you may not have the option to handover the streaming media source manually, because you have no physical access to connect a broadcast mixer to the server. Disconnecting the stream and beginning another is less than ideal, because the audience's media players will also be disconnected when that happens.
The **Icecast** server has a _fallback-mount_ feature which can be used to move clients (media players used by listeners or viewers) from one source to another, as new sources become available. This makes it possible to handover from LibreTime output to a show from another source, and handover to LibreTime again once the other show has ended.
The Icecast server has a _fallback-mount_ feature which can be used to move clients (media players used by listeners or viewers) from one source to another, as new sources become available. This makes it possible to handover from LibreTime output to a show from another source, and handover to LibreTime again once the other show has ended.
To enable fallback mounts, edit the main Icecast configuration file to define the mount points you will use, and the relationship between them.
To enable fallback mounts, edit the main Icecast configuration file (`/etc/icecast2/icecast.xml`) to define the mount points you will use, and the relationship between them.
sudo nano /etc/icecast2/icecast.xml
The example mount section provided in the _icecast.xml_ file is commented out by default. Before or after the commented section, add three mount point definitions. The default mount point used by LibreTime is _/airtime_128_ which is shown in the _/etc/airtime/liquidsoap.cfg_ file. You must also define a mount point for the live source (ex. _/live.ogg_) and a mount point for the public to connect to (ex. _/stream.ogg_).
The example _<mount>_ section provided in the _icecast.xml_ file is commented out by default. Before or after the commented section, add three mount point definitions. The default mount point used by LibreTime is _/airtime_128_ which is shown in the _/etc/airtime/liquidsoap.cfg_ file. You must also define a mount point for the live source (called _/live.ogg_ in this example) and a mount point for the public to connect to (called _/stream.ogg_ in this example).
```xml title="/etc/icecast2/icecast.xml"
<mount>
<mount-name>/airtime_128</mount-name>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/airtime_128</mount-name>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/live.ogg</mount-name>
<fallback-mount>/airtime_128</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/live.ogg</mount-name>
<fallback-mount>/airtime_128</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/stream.ogg</mount-name>
<fallback-mount>/live.ogg</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
<mount>
<mount-name>/stream.ogg</mount-name>
<fallback-mount>/live.ogg</fallback-mount>
<fallback-override>1</fallback-override>
<hidden>0</hidden>
</mount>
```
These mount point definitions mean that a client connecting to a URL such as *http://icecast.example.com:8000/stream.ogg* will first fall back to the _/live.ogg_ mount point if it is available. If not, the client will fall back in turn to the _/airtime_128_ mount point for LibreTime playout.
Setting the value of _<fallback-override>_ to 1 (enabled) means that when the _/live.ogg_ mount point becomes available again, the client will be re-connected to it. If you wish to hide the _/airtime_128_ and _/live.ogg_ mount points from the public Icecast web interface, set the value of _<hidden>_ in each of these definitions to 1.
Setting the value of _fallback-override_ to 1 (enabled) means that when the _/live.ogg_ mount point becomes available again, the client will be re-connected to it. If you wish to hide the _/airtime_128_ and _/live.ogg_ mount points from the public Icecast web interface, set the value of _hidden_ in each of these definitions to 1.
## Source configuration
Connect the other source to the Icecast server with the same parameters defined in the _/etc/airtime/liquidsoap.cfg_ file, except for the mount point. This should one of the mount points you have defined in the _/etc/icecast2/icecast.xml_ file, such as _/live.ogg_ in the example above.
To configure **Mixxx** for streaming to Icecast, click _Options_, _Preferences_, then _Live Broadcasting_. For server _Type_, select the default of _Icecast 2_ when streaming to Debian or Ubuntu servers, as this is the current version of Icecast supplied with those GNU/Linux distributions.
:::tip Streaming with Mixxx
![](/img/Screenshot123-Mixxx_Preferences.png)
To configure Mixxx for streaming to Icecast, click _Options_, _Preferences_, then _Live Broadcasting_. For server _Type_, select the default of _Icecast 2_ when streaming to Debian or Ubuntu servers.
:::
By default, Icecast streams are buffered to guard against network problems, which causes latency for remote listeners. When monitoring the stream from a remote location, you may have to begin the live stream a few seconds before the previous stream ends to enable a smooth transition.
## Promoting your station through Icecast
## Promoting your station
If you have an Icecast server, you can put a link to the Icecast status page (by default at port 8000) on your station's homepage,
to provide an overview of available streams. See the chapter _Interface customization_ for tips on theming the
Icecast status page. You can also use Now Playing widgets (see the chapter _Exporting the schedule_) or HTML5 stream players (see the chapter _Stream player for your website_) to help grow your audience.
:::note
On an Icecast server, you can uncomment the `<directory>` section in the _/etc/icecast2/icecast.xml_ file to have
your station automatically listed on the Icecast directory website <http://dir.xiph.org> which could help you pick
up more listeners.
This section covers how to edit Icecast's configuration to broadcast your station's information to online radio station directories. If you aren't using Icecast (or don't want to edit the configuration file), many online directories will allow you to manually add your station to their listings.
<!-- Uncomment this if you want directory listings -->
:::
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
There are many online radio station directories you can add your station to for additional exposure.
The Indymedia stream directory at <http://radio.indymedia.org/en/yp> links to grassroots independent radio projects around the world. You can add your station to their list with an additional _<directory>_ section, as follows:
On an Icecast server, you can uncomment the `directory` section in the _/etc/icecast2/icecast.xml_ file to have
your station automatically listed on the [Icecast directory website](http://dir.xiph.org).
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://radio.indymedia.org/cgi-bin/yp-cgi</yp-url>
</directory>
```xml
<!-- Uncomment this if you want directory listings -->
Another stream directory service is provided by the Liquidsoap Flows! site <http://flows.liquidsoap.fm/>. The following section can be added to the file _/usr/lib/airtime/pypo/bin/liquidsoap_scripts/ls_script.liq_ after _add_skip_command(s)_ on line 174, for a stream named '_ourstation_':
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
</directory>
```
ourstation = register_flow(
radio="Rock 'n Roll Radio",
website="http://radio.example.com/",
description="Canada's most rockin' radio!",
genre="Rock",
user="",
password="",
streams=[("ogg/128k","http://streaming.example.com/libretime_128")],
ourstation)
The Indymedia stream directory at <http://radio.indymedia.org/en/yp> links to grassroots independent radio projects around the world. You can add your station to their list with an additional _directory_ section, as follows:
> **Note:** For the time being, a stream can be registered on the Liquidsoap Flows! site with any username and password. Authenticated services may be offered in future.
```xml
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://radio.indymedia.org/cgi-bin/yp-cgi</yp-url>
</directory>
```

49
docs/upgrading.md
View File

@ -1,38 +1,15 @@
---
layout: article
title: Upgrading Libretime
category: admin
---
## LibreTime versioning
:::caution
In a nutshell, given a version number MAJOR.MINOR.PATCH we increment the:
While upgrading your installation may not cause any station downtime or data loss, always plan for the worst. Only upgrade your installation when Libretime isn't playing out shows, notify your DJs and essential personnel, and back up your database, configuration files, and media library before you make any changes.
1. MAJOR version when we make incompatible API changes,
2. MINOR version when we add functionality in a backwards-compatible manner, and
3. PATCH version when we make backwards-compatible bug fixes.
:::
Any pre-release versions of LibreTime are denoted by appending a hyphen and a
series of dot separated identifiers immediately following the patch version.
This pre-release indicates that the version is unstable in a sense that it might
contain incomplete features or not satisfy the intended compatibility
requirements as per semver.
## Upgrading
> After your LibreTime server has been deployed for a few years, you may need to
> upgrade the GNU/Linux distribution that it runs in order to maintain security
> update support. If the upgrade does not go smoothly, it may cause significant
> downtime, so you should always have a fallback system available during the
> upgrade to ensure broadcast continuity.
1. Take a [backup of the server](/docs/backing-up-the-server). This is
especially important if you have not already set up a regular back up routine.
This extra back up is a safety measure in case of accidental data loss during
the upgrade, for example due to the wrong command being entered when moving
files. It is also recommended to backup all the configuration files under
`/etc/airtime/`.
2. Run `./install -fiap` as described in the [install documentation](/install).
1. [Back up the server](/docs/server-config/backing-up-the-server) and make a copy of all the configuration files under `/etc/airtime/`.
2. Run `./install -fiap` as described in the [installation guide](/docs/getting-started/install).
This will detect an existing LibreTime deployment and backup any
configuration files that if finds. The install script also tries to restart
the needed services during an upgrade. In any case you should monitor if this
@ -48,23 +25,25 @@ requirements as per semver.
### Migrating from Airtime
> **Note:** Airtime's _linked files_ and _watched folders_ features currently do
> not work in Libretime.
:::note
Airtime's _linked files_ and _watched folders_ features currently do not work in Libretime.
:::
LibreTime has dropped support for Ubuntu 16.04, which is the last supported
version of Ubuntu that Airtime supports. The following instructions describe how
to migrate from Airtime to LibreTime. If there are issues encountered while
upgrading, please [file a bug](https://github.com/libretime/libretime/issues/new?labels=bug&template=bug_report.md)
1. Take a [backup of the server](/docs/backing-up-the-server)
2. Create a new system for LibreTime and run the install script, as described in
[install](/install).
1. Take a [backup of the server](/docs/server-config/backing-up-the-server)
2. Create a new system for LibreTime and run the install script, as described in the [install guide](/docs/getting-started/install).
3. Before running the web-configuration, restore the Airtime database to the new
PostgreSQL server, media database and configuration file
4. Update the configuration file to match the new configuration schema and update any
changed values. See the [host configuration](/docs/host-configuration) documentation
changed values. See the [host configuration](/docs/server-config/host-configuration) documentation
for more details.
5. Edit the Icecast password in `/etc/icecast2/icecast.xml` to reflect the
password used in Airtime
6. Restart the LibreTime services
7. Navigate to the LibreTime web-page
7. Open LibreTime's dashboard and verify all services are running

15
website/docusaurus.config.js
View File

@ -60,6 +60,12 @@ const config = {
src: "img/logo.svg",
},
items: [
{
type: "doc",
docId: "intro",
position: "left",
label: "Docs",
},
{ to: "/contribute", label: "Contribute", position: "left" },
{ type: "localeDropdown", position: "right" },
{
@ -72,6 +78,15 @@ const config = {
footer: {
style: "dark",
links: [
{
title: "Docs",
items: [
{
label: "Install",
to: "/docs/intro",
},
],
},
{
title: "Community",
items: [