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

Starting work on new design for docs pages

Browse source
This commit is contained in:
Zachary Klosko 2020-10-31 23:23:29 -04:00
parent f62ed7d2e3
commit 630c789e4f
35 changed files with 1055 additions and 320 deletions
Download patch file Download diff file Expand all files Collapse all files

304
docs/_docs/analytics.md Normal file
View file

@ -0,0 +1,304 @@
---
layout: article
title: Analytics
git: analytics.md
category: manager
---
## History {#history}
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.
Search results can be copied to the clipboard using the **Copy** button, exported as data in **CSV** format (comma separated values), exported as a document in **PDF** format, or displayed in a printer-friendly format using the **Print** button. (Your web browser must have an Adobe Flash plugin installed for these buttons to appear). Press the **Esc** key to return to the LibreTime interface once the print job is complete.
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)
In the **Log Sheet** tab, the playout history is sorted by **Start Time** and **End Time** by default.
The number of times each file was played and the length of the files are shown in the **File Summary** tab. To make optimal use of this feature for royalty reporting purposes, music files must be tagged with **Composer** and **Copyright** metadata. The artist performing a piece of music may not be the original composer of the work, or the copyright holder of the sound recording.
On the **Show Summary** tab, click the name of a show within the search range to expand its row and see its playout details.
### Manual logging
If your station features playout from analogue sources such as turntables or microphones, there is no automatic metadata for LibreTime to collect from these inputs. To ensure that the playout history is complete, you can add log entries manually by clicking the **+ Create Entry** button. This action opens a pop-up window with default fields of Start Time, End Time, Title and Creator. Click the **Find** button to automatically fill the **Choose Show Instance** menu with the names of shows that took place within the specified time range. Then click the **Save** button to enter the new item into the playout history.
Log entries can also be manually deleted, using the button with the trashcan icon, to the right of the **+ Create Entry** button. Pages of entries can be selected for deletion using the **Select** drop-down menu.
## History Templates
![](img/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)
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.
When the template is in the format you require, click the **Save** button, and **Set Default Template** if you wish. The new template will now be listed on the History Templates page. If you have set a new default template, any changes will be visible on the tabs of the Playout History page.
## Exporting the schedule {#exporting}
LibreTime has a feature which enables your station's show and schedule information to be displayed on remote websites. This feature is included in LibreTime because you would not usually invite the general public to access your LibreTime server directly. If you had very large numbers of people requesting data from the LibreTime server at once, the burst of network traffic might overload the server, potentially disrupting your broadcasts. If carried out maliciously, this network overload is known as a *denial of service attack*.
Instead, your public-facing web server can retrieve the schedule information from the LibreTime API. It can be presented using Javascript widgets and styled with CSS, in any format that you require.
There are two kinds of information that can be retrieved remotely from the LibreTime API without authentication; the metadata for the current show plus the following show (live-info), or the schedule for the current week and the week ahead (week-info). The week-info metadata includes show names, times, and individual show URLs on your public website. That way, the audience for your station can click through from the schedule information to find out more about a particular show, or download a previous show recording that you might have made available.
If your LibreTime server was accessible at https://libretime.example.com the live show information could be retrieved by your web server using this URL:
https://libretime.example.com/api/live-info/?callback
The comma-separated text metadata returned to your web server might be something like this:
({"env":"production",
"schedulerTime":"2013-07-03 14:07:31",
"previous":{"name":"Earth, Wind & Fire - Boogie Wonderland",
"starts":"2013-07-01 22:53:00",
"ends":"2013-07-01 22:55:00",
"type":"track"},
"current":{"name":"Deodato - Also Sprach Zarathustra",
"starts":"2013-07-03 13:07:06",
"ends":"2013-07-03 13:16:05",
"media_item_played":true,
"record":0,
"type":"track"},
"next":{"id":8,
"instance_id":10,
"name":"Rock Show",
"url":"https:\/\/rock.example.com\/",
"start_timestamp":"2013-07-03 14:00:00",
"end_timestamp":"2013-07-03 15:00:00",
"starts":"2013-07-03 14:00:00",
"ends":"2013-07-03 15:00:00",
"record":0,
"type":"show"},
"currentShow":[{"start_timestamp":"2013-07-03 14:07:00",
"0":"2013-07-03 13:07:00",
"end_timestamp":"2013-07-03 15:00:00",
"1":"2013-07-03 14:00:00",
"name":"Funk Show",
"2":"Funk Show",
"id":7,
"3":7,
"instance_id":9,"4":9,
"record":0,
"5":0,
"url":"https:\/\/funk.example.com\/",
"6":"",
"starts":"2013-07-03 14:07:00",
"7":"2013-07-03 13:07:00",
"ends":"2013-07-03 15:00:00",
"8":"2013-07-03 14:00:00"}],
"nextShow":[{"id":8,
"instance_id":10,
"name":"Rock Show",
"url":"https:\/\/rock.example.com\/",
"start_timestamp":"2013-07-03 15:00:00",
"end_timestamp":"2013-07-03 16:00:00",
"starts":"2013-07-03 15:00:00",
"ends":"2013-07-03 16:00:00",
"record":0,
"type":"show"}],
"timezone":"BST",
"timezoneOffset":"3600",
"AIRTIME_API_VERSION":"1.1"})
The information for the current week's schedule could be retrieved using the URL:
https://libretime.example.com/api/week-info/?callback
In this case, the metadata returned would be in a different format from the above example, something like the following. To keep the example short, this particular schedule export only contains four shows on a Monday. A full weekly schedule export would contain a great deal more text.
({"monday":[
{"start_timestamp":"2013-07-01 12:05:00",
"end_timestamp":"2013-07-01 13:00:00",
"name":"Elvis Show",
"id":2,
"instance_id":2,
"record":0,
"url":"https:\/\/elvis.example.com\/",
"starts":"2013-07-01 12:05:00",
"ends":"2013-07-01 13:00:00"},
{"start_timestamp":"2013-07-01 13:00:00",
"end_timestamp":"2013-07-01 14:00:00",
"name":"News",
"id":3,
"instance_id":4,
"record":0,
"url":"https:\/\/news.example.com\/",
"starts":"2013-07-01 13:00:00",
"ends":"2013-07-01 14:00:00"},
{"start_timestamp":"2013-07-01 14:00:00",
"end_timestamp":"2013-07-01 15:00:00",
"name":"Funk Show",
"id":4,
"instance_id":6,
"record":0,
"url":"https:\/\/funk.example.com\/",
"starts":"2013-07-01 14:00:00",
"ends":"2013-07-01 15:00:00"},
{"start_timestamp":"2013-07-01 15:00:00",
"end_timestamp":"2013-07-01 17:30:00",
"name":"Rock Show",
"id":5,
"instance_id":7,
"record":0,
"url":"https:\/\/rock.example.com\/",
"starts":"2013-07-01 15:00:00",
"ends":"2013-07-01 17:30:00"},
],
"tuesday":[],
"wednesday":[],
"thursday":[],
"friday":[],
"saturday":[],
"sunday":[],
"AIRTIME_API_VERSION":"1.1"})
If you see the message *You are not allowed to access this resource* when attempting to display schedule information in your web browser, log in to the LibreTime administration interface, click *System* in the main menu, then *Preferences*. Set **Allow Remote Websites To Access "Schedule" Info?** to **Enabled**, click the **Save** button, then refresh the browser window opened on the schedule export URL. If you do not wish to make schedule information available to the public, set this option to **Disabled** instead.
### Caching schedule information
If the LibreTime server is behind a firewall, or you want to protect the LibreTime server from large numbers of schedule requests, you may wish to cache the schedule information on a public-facing or intermediate server. You can then create a firewall rule that only allows the schedule server to connect to the LibreTime server, in addition to any remote users of the LibreTime web interface.
Your system administrator can set up schedule caching on a standard Apache and PHP enabled web server with the *curl* program installed, using the following steps:
1. Create a shell script on the schedule server (schedule.example.com) that polls the remote LibreTime server (libretime.example.com), and writes the metadata returned into a pair of local temporary files:
sudo nano /usr/local/bin/libretime-schedule.sh
The content of this file should be like the following script, replacing libretime.example.com with the name of your LibreTime server:
#!/bin/sh
curl -s "https://libretime.example.com/api/live-info/?callback=***" > /tmp/live-info
curl -s "https://libretime.example.com/api/week-info/?callback=***" > /tmp/week-info
2. Make the script executable:
sudo chmod +x /usr/local/bin/libretime-schedule.sh
3. Create an Apache VirtualHost configuration for the schedule server:
sudo nano /etc/apache2/sites-available/schedule
containing a definition like the following, replacing *schedule.example.com* with the name of your schedule server:
<VirtualHost *:80>
ServerName schedule.example.com
DocumentRoot /var/www/schedule/
</VirtualHost>
4. In the schedule server's DocumentRoot folder, create the folders *api/live-info/* and *api/week-info/*
sudo mkdir -p /var/www/schedule/api/live-info/
sudo mkdir -p /var/www/schedule/api/week-info/
5. Create an index.php file in the *api/live-info/* folder:
sudo nano /var/www/schedule/api/live-info/index.php
containing the following code:
<?php
$filename = '/tmp/live-info'; // define here the path and name of uploaded live-info file
header('Content-Type: text/javascript');
header("Expires: Thu, 01 Jan 1970 00:00:00 GMT");
header("Cache-Control: no-store, no-cache, must-revalidate");
$callback = empty($_GET['callback']) ? null : $_GET['callback'];
$content = file_get_contents($filename);
$content = str_replace('***', $callback, $content);
echo $content;
?>
6. Create an index.php file in the *api/week-info/* folder:
sudo nano /var/www/schedule/api/week-info/index.php
containing the following code:
<?php
$filename = '/tmp/week-info'; // define here the path and name of uploaded week-info file
header('Content-Type: text/javascript');
header("Expires: Thu, 01 Jan 1970 00:00:00 GMT");
header("Cache-Control: no-store, no-cache, must-revalidate");
$callback = empty($_GET['callback']) ? null : $_GET['callback'];
$content = file_get_contents($filename);
$content = str_replace('***', $callback, $content);
echo $content;
?>
7. Enable the new configuration and reload the Apache web server:
sudo a2ensite schedule
sudo /etc/init.d/apache2 reload
8. Create a cron job to run the shell script each minute:
sudo nano /etc/cron.d/libretime-schedule
containing the line:
* * * * * www-data /usr/local/bin/libretime-schedule.sh
The schedule server will now be serving the same show information as the LibreTime server, with a cache lifetime of one minute. You can adjust the cache lifetime by altering the frequency of the cron job that polls the LibreTime server.
### Pushing schedule information via FTP or SSH
If there is no inbound access to the LibreTime server at all, an FTP script can be used to push cached schedule data from LibreTime to an external web server. The standard ftp command should be available on the LibreTime server and the external web server should have a suitably restricted FTP account set up. After following steps 1 and 2 above to export schedule data to a pair of temporary files on the LibreTime server, create a new script on the LibreTime server to automatically make the upload:
sudo nano /usr/local/bin/upload-schedule-data.sh
Replace host, user and password values with appropriate values for your external web server:
#!/bin/sh
HOST='website.example.com'
USER='ftp_user'
PASSWD='ftp_password'
ftp -n -v $HOST << EOT
user $USER $PASSWD
ascii
prompt
put /tmp/airtime-week-info
put /tmp/airtime-live-info
bye
EOT
Then make the new script executable and create a cron job to launch it every minute, as in step 8 above. Steps 3 to 7 above should be carried out on the external web server so that it can convert the two temporary files uploaded via FTP into public schedule data.
If you have secure shell access (SSH) to the remote web server, you could write a script to use the secure copy command (scp) instead of ftp.
---
## Streaming Listener Statistics
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)
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.
By default, statistics for the last 24 hours of streaming are shown. To change this date and time range, click the calendar and clock icons in the lower left corner of the page, then click the magnifying glass icon.
> To choose which particular streams should have statistics displayed, click the check boxes for the individual colour-coded mount points, just below the graph.

57
docs/_docs/api.md Normal file
View file

@ -0,0 +1,57 @@
---
layout: article
title: LibreTime API Usage
git: api.md
---
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.
The format of API requests is:
https://libretime.example.com/api/api-action/format/json/api_key/XXXXXX
where api-action is the type of request and XXXXXX is the secret API key. Available actions include:
- on-air-light - return true if the station is on air
- status - get the status of LibreTime components and resource usage
- version - returns the version of LibreTime installed
- get-files-without-silan-value - list files for which silence detection has not yet been performed
- get-stream-setting - gets the settings of LibreTime output streams
- get-stream-parameters - gets the parameters of LibreTime output streams
For example, using the action *get-stream-setting* returns the following output for the first configured stream:
{"keyname":"s1_type","value":"ogg","type":"string"},
{"keyname":"s1_host","value":"streaming.example.com","type":"string"},
{"keyname":"s1_port","value":"8000","type":"integer"},
{"keyname":"s1_mount","value":"airtime_128","type":"string"},
{"keyname":"s1_url","value":"http:\/\/airtime.sourcefabric.org","type":"string"},
{"keyname":"s1_description","value":"Airtime Radio! Stream
#1","type":"string"},
{"keyname":"s1_genre","value":"Screamo","type":"string"},
which is enough information to construct a player widget dynamically. (s1\_url is the station's homepage, not the stream URL). The same information is provided with an s2\_ prefix for the second stream, and s3\_ prefix for the third stream.
Some API requests require the directory ID number to be specified as *dir\_id* including:
- list-all-files - list files in the specified directory
- get-files-without-replay-gain - list files in the specified directory for which ReplayGain has not been calculated yet
For example, using a request such as:
http://libretime.example.com/api/list-all-files/format/json/api_key/XXXXXX/dir_id/1/
returns the full path to each media file in the LibreTime storage directory:
{"files":[
"imported\/1\/Mark Ronson feat. Saigon\/Here Comes the Fuzz\/7-Diduntdidunt-unknown.flac",
"imported\/1\/Jimi Tenor & Tony Allen\/Inspiration Information\/3-Selfish Gene-128kbps.mp3",
"]}

77
docs/_docs/backing-up-the-server.md Normal file
View file

@ -0,0 +1,77 @@
---
layout: article
title: Backing Up The Server
category: admin
git: backing-up-the-server.md
---
## Database Backup
The following shell commands can be used for database backup and restore on a
running *PostgreSQL* server in an LibreTime system.
You can dump the entire database to a zipped file with the combination of the
**pg\_dumpall** command and **gzip**. The **pg\_dumpall** command is executed
as the user *postgres*, by using the **sudo** command and the **-u** switch. It
is separated from the **gzip** command with the pipe symbol.
```bash
sudo -u postgres pg_dumpall | gzip -c > libretime-backup.gz
```
This command can be automated to run on a regular basis using the standard
**cron** tool on your server.
When restoring a production database on a cleanly installed LibreTime system, it
may be necessary to drop the empty database that was created during the new
installation, by using the **dropdb** command. Again, this command is executed
with **sudo** as the user *postgres*: 
```bash
sudo -u postgres dropdb airtime
```
This **dropdb** command above is necessary to avoid 'already exists' errors on
table creation when overwriting an empty LibreTime database in the next step.
These errors might prevent some data from being restored, such as user account
data.
To restore, first unzip the backup file with **gunzip**, then use the **psql**
command as the *postgres* user:
```bash
gunzip libretime-backup.gz
sudo -u postgres psql -f libretime-backup
```
You should now be able to log in to the LibreTime web interface in the usual way.
For safety reasons, your regular database backups should be kept in a directory
which is backed up by your storage backup tool of choice; for example, the
*/srv/airtime/database\_backups* directory. This should ensure that a storage
restore can be made along with a matching and complete version of the LibreTime
database from the day that the storage backup was made. 
## Storage backup
Backing up the LibreTime database with **pg\_dumpall** will not back up the
LibreTime media storage server, which is likely to need a great deal more backup
space. Creating a compressed file from hundreds of gigabytes of storage server
contents is likely to take a very long time, and may have little benefit for the
amount of CPU power used, if the media files are already stored in a highly
compressed format. It is also impractical to copy very large backup files across
the network on a daily basis.
Instead, it is preferable to use an incremental backup technique to synchronize
the production LibreTime server storage with a backup server each day or night. If
the backup server also contains an LibreTime installation, it should be possible
to switch playout to this second machine relatively quickly, in case of a
hardware failure or other emergency on the production server.
A standard incremental backup tool on GNU/Linux servers is [rsync](http://rsync.samba.org/) which can be installed
using the package manager of your GNU/Linux distribution. However, incremental
backup alone cannot help in the scenario where a file which later proves to be
important has been deleted by an administrator. For backups that can be rolled
back to restore from an earlier date than the current backup, the tool
[rdiff-backup](http://www.nongnu.org/rdiff-backup/) can
be deployed.  

64
docs/_docs/contribute.md Normal file
View file

@ -0,0 +1,64 @@
---
layout: article
title: Contributing to LibreTime
git: contribute.md
---
> LibreTime is a fork of AirTime due to stalled development of the FLOSS version. For background on this,
see this [open letter to the Airtime community](https://gist.github.com/hairmare/8c03b69c9accc90cfe31fd7e77c3b07d).
## Bug reporting
If you think you've found a bug, please report it on our [Github issues page](https://github.com/LibreTime/libretime/issues/new/choose).
Create a bug report by selecting **Get Started** next to **Bug Report**. That way, the LibreTime team can keep track of
your problem and notify you when it has been fixed. You can also suggest
improvements and new features for LibreTime on that site.
## Feature requests
Have an idea that would make LibreTime even better than it is right now? Start a **Feature request** on our
[Github issues page](https://github.com/LibreTime/libretime/issues/new/choose).
## Help translate LibreTime
LibreTime can run in over 15 different languages due to the gracious help of our volunteers. Is your language not
supported? Follow [this guide](interface-localization) to add your language to LibreTime!
## Help write documentation for LibreTime
Our site is now run by Jekyll. After cloning our repo locally, enter the `/docs` directory and run
```
bundle install
jekyll serve
```
## Help write code for LibreTime
Are you familar with coding in PHP? Have you made projects in Liquidsoap and some of the other services we use?
Take a look at the bugs and feature requests [here](https://github.com/LibreTime/libretime/issues), and then
fork our repo and have a go! Just use the **Fork** button at the top of our **Code** page, clone the forked repo to
your desktop, open up a favorite editor and make some changes, and then commit, push, and open a pull request.
Knowledge on how to use [Github](https://guides.github.com/activities/hello-world/) and [Git](https://git-scm.com/docs/gittutorial)
will suit you well, use the links for a quick 101.
### Testing LibreTime in Vagrant
Before submitting code to the project, it's a good idea to test it first. To do this, it's easiest to install
LibreTime in a virtural machine on your local system or in a cloud VM. Instructions on how to set up a virtural
instance of LibreTime with Vagrant are located [here](vagrant).
If you would like to try LibreTime in a Docker image,
Odclive has instructions [here](https://github.com/kessibi/libretime-docker) for setting up a test image
and a more persistant install.
### Modifying the Database
LibreTime is designed to work with a [PostgreSQL](https://www.postgresql.org/) database server running locally.
LibreTime uses [PropelORM](http://propelorm.org) to interact with the ZendPHP components and create the database.
If you are a developer seeking to add new columns to the database here are the steps.
1. Modify `airtime_mvc/build/schema.xml` with any changes.
2. Run `dev_tools/propel_generate.sh`
3. Update the upgrade.sql under `airtime_mvc/application/controllers/upgrade_sql/VERSION` for example
`ALTER TABLE imported_podcast ADD COLUMN album_override boolean default 'f' NOT NULL;`

108
docs/_docs/freeipa.md Normal file
View file

@ -0,0 +1,108 @@
---
layout: article
title: FreeIPA Configuration
category: admin
---
You can configure LibreTime to delegate all authentication to a FreeIPA server.
This allows you users to use their existing FreeIPA credentials. For this to
work you need to configure Apache to use `mod_authnz_pam` and `mod_intercept_form_submit`.
## Apache configuration {#apache}
After installing the needed modules you can set up Apache to intercept form logins and
check them against pam.
```apache
<Location /login>
InterceptFormPAMService http-libretime
InterceptFormLogin username
InterceptFormPassword password
InterceptFormLoginSkip admin
InterceptFormPasswordRedact on
InterceptFormLoginRealms INT.RABE.CH
Require pam-account http-libretime
</Location>
<Location />
<RequireAny>
<RequireAny>
Require pam-account http-libretime
Require all granted
</RequireAny>
<RequireAll>
Require expr %{REQUEST_URI} =~ /(index.php|login|favicon.ico|js|css|locale)/
Require all granted
</RequireAll>
</RequireAny>
</Location>
```
## PAM configuration {#pam}
The above configuration expects a PAM configuration for the `http-libretime` service.
To confiure this you need to create the file `/etc/pam.d/http-libretime` with the following contents.
```
auth required pam_sss.so
account required pam_sss.so
```
## LDAP configuration {#ldap}
LibreTime needs direct access to LDAP so it can fetch additional information. It does so with
a [system account](https://www.freeipa.org/page/HowTo/LDAP#System_Accounts) that you need to
set up beforehand.
You can configure everything pertaining to how LibreTime accesses LDAP in
`/etc/airtime/airtime.conf`. The default file has the following values you need to change.
```ini
#
# ----------------------------------------------------------------------
# L D A P
# ----------------------------------------------------------------------
#
# hostname: Hostname of LDAP server
#
# binddn: Complete DN of user used to bind to LDAP
#
# password: Password for binddn user
#
# account_domain: Domain part of username
#
# basedn: base search DN
#
# filter_field: Name of the uid field for searching
# Usually uid, may be cn
#
# groupmap_*: Map LibreTime user types to LDAP groups
# Lets LibreTime assign user types based on the
# group a given user is in.
#
[ldap]
hostname = ldap.example.org
binddn = 'uid=libretime,cn=sysaccounts,cn=etc,dc=int,dc=example,dc=org'
password = hackme
account_domain = INT.EXAMPLE.ORG
basedn = 'cn=users,cn=accounts,dc=int,dc=example,dc=org'
filter_field = uid
groupmap_guest = 'cn=guest,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_host = 'cn=host,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_program_manager = 'cn=program_manager,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_admin = 'cn=admins,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
groupmap_superadmin = 'cn=superadmin,cn=groups,cn=accounts,dc=int,dc=example,dc=org'
```
## Enable FreeIPA Authentication {#freeipa}
After everything is set up properly you can enable FreeIPA auth in `airtime.conf`:
```
[general]
auth = LibreTime_Auth_Adaptor_FreeIpa
```
You should now be able to use your FreeIPA credentials to log in to LibreTime.

319
docs/_docs/hd-audio-modules.md Normal file
View file

@ -0,0 +1,319 @@
---
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.
```
Model name Description
---------- -----------
ALC880
======
3stack 3-jack in back and a headphone out
3stack-digout 3-jack in back, a HP out and a SPDIF out
5stack 5-jack in back, 2-jack in front
5stack-digout 5-jack in back, 2-jack in front, a SPDIF out
6stack 6-jack in back, 2-jack in front
6stack-digout 6-jack with a SPDIF out
ALC260
======
N/A
ALC262
======
inv-dmic Inverted internal mic workaround
ALC267/268
==========
inv-dmic Inverted internal mic workaround
ALC269/270/275/276/28x/29x
======
laptop-amic Laptops with analog-mic input
laptop-dmic Laptops with digital-mic input
alc269-dmic Enable ALC269(VA) digital mic workaround
alc271-dmic Enable ALC271X digital mic workaround
inv-dmic Inverted internal mic workaround
headset-mic Indicates a combined headset (headphone+mic) jack
lenovo-dock Enables docking station I/O for some Lenovos
dell-headset-multi Headset jack, which can also be used as mic-in
dell-headset-dock Headset jack (without mic-in), and also dock I/O
ALC66x/67x/892
==============
mario Chromebook mario model fixup
asus-mode1 ASUS
asus-mode2 ASUS
asus-mode3 ASUS
asus-mode4 ASUS
asus-mode5 ASUS
asus-mode6 ASUS
asus-mode7 ASUS
asus-mode8 ASUS
inv-dmic Inverted internal mic workaround
dell-headset-multi Headset jack, which can also be used as mic-in
ALC680
======
N/A
ALC88x/898/1150
======================
acer-aspire-4930g Acer Aspire 4930G/5930G/6530G/6930G/7730G
acer-aspire-8930g Acer Aspire 8330G/6935G
acer-aspire Acer Aspire others
inv-dmic Inverted internal mic workaround
no-primary-hp VAIO Z/VGC-LN51JGB workaround (for fixed speaker DAC)
ALC861/660
==========
N/A
ALC861VD/660VD
==============
N/A
CMI9880
=======
minimal 3-jack in back
min_fp 3-jack in back, 2-jack in front
full 6-jack in back, 2-jack in front
full_dig 6-jack in back, 2-jack in front, SPDIF I/O
allout 5-jack in back, 2-jack in front, SPDIF out
auto auto-config reading BIOS (default)
AD1882 / AD1882A
================
3stack 3-stack mode
3stack-automute 3-stack with automute front HP (default)
6stack 6-stack mode
AD1884A / AD1883 / AD1984A / AD1984B
====================================
desktop 3-stack desktop (default)
laptop laptop with HP jack sensing
mobile mobile devices with HP jack sensing
thinkpad Lenovo Thinkpad X300
touchsmart HP Touchsmart
AD1884
======
N/A
AD1981
======
basic 3-jack (default)
hp HP nx6320
thinkpad Lenovo Thinkpad T60/X60/Z60
toshiba Toshiba U205
AD1983
======
N/A
AD1984
======
basic default configuration
thinkpad Lenovo Thinkpad T61/X61
dell_desktop Dell T3400
AD1986A
=======
6stack 6-jack, separate surrounds (default)
3stack 3-stack, shared surrounds
laptop 2-channel only (FSC V2060, Samsung M50)
laptop-eapd 2-channel with EAPD (ASUS A6J)
laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100)
ultra 2-channel with EAPD (Samsung Ultra tablet PC)
samsung 2-channel with EAPD (Samsung R65)
samsung-p50 2-channel with HP-automute (Samsung P50)
AD1988/AD1988B/AD1989A/AD1989B
==============================
6stack 6-jack
6stack-dig ditto with SPDIF
3stack 3-jack
3stack-dig ditto with SPDIF
laptop 3-jack with hp-jack automute
laptop-dig ditto with SPDIF
auto auto-config reading BIOS (default)
Conexant 5045
=============
laptop-hpsense Laptop with HP sense (old model laptop)
laptop-micsense Laptop with Mic sense (old model fujitsu)
laptop-hpmicsense Laptop with HP and Mic senses
benq Benq R55E
laptop-hp530 HP 530 laptop
test for testing/debugging purpose, almost all controls
can be adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
Conexant 5047
=============
laptop Basic Laptop config
laptop-hp Laptop config for some HP models (subdevice 30A5)
laptop-eapd Laptop config with EAPD support
test for testing/debugging purpose, almost all controls
can be adjusted. Appearing only when compiled with
$CONFIG_SND_DEBUG=y
Conexant 5051
=============
laptop Basic Laptop config (default)
hp HP Spartan laptop
hp-dv6736 HP dv6736
hp-f700 HP Compaq Presario F700
ideapad Lenovo IdeaPad laptop
toshiba Toshiba Satellite M300
Conexant 5066
=============
laptop Basic Laptop config (default)
hp-laptop HP laptops, e g G60
asus Asus K52JU, Lenovo G560
dell-laptop Dell laptops
dell-vostro Dell Vostro
olpc-xo-1_5 OLPC XO 1.5
ideapad Lenovo IdeaPad U150
thinkpad Lenovo Thinkpad
STAC9200
========
ref Reference board
oqo OQO Model 2
dell-d21 Dell (unknown)
dell-d22 Dell (unknown)
dell-d23 Dell (unknown)
dell-m21 Dell Inspiron 630m, Dell Inspiron 640m
dell-m22 Dell Latitude D620, Dell Latitude D820
dell-m23 Dell XPS M1710, Dell Precision M90
dell-m24 Dell Latitude 120L
dell-m25 Dell Inspiron E1505n
dell-m26 Dell Inspiron 1501
dell-m27 Dell Inspiron E1705/9400
gateway-m4 Gateway laptops with EAPD control
gateway-m4-2 Gateway laptops with EAPD control
panasonic Panasonic CF-74
auto BIOS setup (default)
STAC9205/9254
=============
ref Reference board
dell-m42 Dell (unknown)
dell-m43 Dell Precision
dell-m44 Dell Inspiron
eapd Keep EAPD on (e.g. Gateway T1616)
auto BIOS setup (default)
STAC9220/9221
=============
ref Reference board
3stack D945 3stack
5stack D945 5stack + SPDIF
intel-mac-v1 Intel Mac Type 1
intel-mac-v2 Intel Mac Type 2
intel-mac-v3 Intel Mac Type 3
intel-mac-v4 Intel Mac Type 4
intel-mac-v5 Intel Mac Type 5
intel-mac-auto Intel Mac (detect type according to subsystem id)
macmini Intel Mac Mini (equivalent with type 3)
macbook Intel Mac Book (eq. type 5)
macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3)
macbook-pro Intel Mac Book Pro 2nd generation (eq. type 3)
imac-intel Intel iMac (eq. type 2)
imac-intel-20 Intel iMac (newer version) (eq. type 3)
ecs202 ECS/PC chips
dell-d81 Dell (unknown)
dell-d82 Dell (unknown)
dell-m81 Dell (unknown)
dell-m82 Dell XPS M1210
auto BIOS setup (default)
STAC9202/9250/9251
==================
ref Reference board, base config
m1 Some Gateway MX series laptops (NX560XL)
m1-2 Some Gateway MX series laptops (MX6453)
m2 Some Gateway MX series laptops (M255)
m2-2 Some Gateway MX series laptops
m3 Some Gateway MX series laptops
m5 Some Gateway MX series laptops (MP6954)
m6 Some Gateway NX series laptops
auto BIOS setup (default)
STAC9227/9228/9229/927x
=======================
ref Reference board
ref-no-jd Reference board without HP/Mic jack detection
3stack D965 3stack
5stack D965 5stack + SPDIF
5stack-no-fp D965 5stack without front panel
dell-3stack Dell Dimension E520
dell-bios Fixes with Dell BIOS setup
dell-bios-amic Fixes with Dell BIOS setup including analog mic
volknob Fixes with volume-knob widget 0x24
auto BIOS setup (default)
STAC92HD71B*
============
ref Reference board
dell-m4-1 Dell desktops
dell-m4-2 Dell desktops
dell-m4-3 Dell desktops
hp-m4 HP mini 1000
hp-dv5 HP dv series
hp-hdx HP HDX series
hp-dv4-1222nr HP dv4-1222nr (with LED support)
auto BIOS setup (default)
STAC92HD73*
===========
ref Reference board
no-jd BIOS setup but without jack-detection
intel Intel DG45* mobos
dell-m6-amic Dell desktops/laptops with analog mics
dell-m6-dmic Dell desktops/laptops with digital mics
dell-m6 Dell desktops/laptops with both type of mics
dell-eq Dell desktops/laptops
alienware Alienware M17x
auto BIOS setup (default)
STAC92HD83*
===========
ref Reference board
mic-ref Reference board with power management for ports
dell-s14 Dell laptop
dell-vostro-3500 Dell Vostro 3500 laptop
hp-dv7-4000 HP dv-7 4000
hp_cNB11_intquad HP CNB models with 4 speakers
hp-zephyr HP Zephyr
hp-led HP with broken BIOS for mute LED
hp-inv-led HP with broken BIOS for inverted mute LED
auto BIOS setup (default)
STAC9872
========
vaio VAIO laptop without SPDIF
auto BIOS setup (default)
Cirrus Logic CS4206/4207
========================
mbp55 MacBook Pro 5,5
imac27 IMac 27 Inch
auto BIOS setup (default)
Cirrus Logic CS4208
===================
mba6 MacBook Air 6,1 and 6,2
gpio0 Enable GPIO 0 amp
auto BIOS setup (default)
VIA VT17xx/VT18xx/VT20xx
========================
auto BIOS setup (default)
```

123
docs/_docs/icecast-shoutcast.md Normal file
View file

@ -0,0 +1,123 @@
---
layout: article
title: Icecast and Shoutcast Stream Configuration
git: icecast-shoutcast.md
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.
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.
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.
## 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)
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>
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.
## 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.
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.
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 (called */live.ogg* in this example) and a mount point for the public to connect to (called */stream.ogg* in this example).
<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>/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.
## 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.
![](img/Screenshot123-Mixxx_Preferences.png) 
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
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.
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.
<!-- 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>
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:
<directory>
<yp-url-timeout>15</yp-url-timeout>
<yp-url>http://radio.indymedia.org/cgi-bin/yp-cgi</yp-url>
</directory>
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*':
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)
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.

656
docs/_docs/install.md Normal file
View file

@ -0,0 +1,656 @@
---
title: Install
layout: article
git: install.md
---
> Note: this guide is assuming you are using Ubuntu 18.04 LTS for installation, which comes with `ufw` and `netplan`,
and that you have already installed `git` and configured `ntp`. NTP configuration instructions can be found [here](#configuring-ntp).
While it is possible to install LibreTime on other OSes, such as CentOS 7, Debian 9 and 10, and Raspbian 9 and 10,
these are less tested. Firewall and static IP address configuration will need to be done according to your OSes instructions.
## Minimum System Requirements
| On-Premises Install | Cloud Install |
|---------------------|---------------|
| (FM + Internet Radio) | (Internet Radio Only) |
| 1 Ghz Processor| 1vCPU |
| 2 GB RAM | 2 GB RAM |
| Wired ethernet connection, static IP address | 2 TB of data transfer/month |
[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.
## 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
sudo nano ##-netcfg.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`.
```
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses: [192.168.88.8/24]
gateway4: 192.168.88.1
nameservers:
addresses: 192.168.88.1
```
After the netplan file has been saved, run `sudo netplan apply` to apply changes.
Next, configure Ubuntu's firewall by running:
```
sudo ufw enable
sudo ufw allow 80/tcp
sudo ufw allow 8000/tcp
```
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.
```
sudo ufw enable 8001/tcp
sudo ufw enable 8002/tcp
```
> If needed, instuctions for setting up a reverse proxy can be found [here](quickstart#reverse-proxy).
### Installing LibreTime
Installing LibreTime consists of running the following commands in the terminal:
```
git clone https://github.com/LibreTime/libretime.git
cd libretime
sudo ./install -fiap
```
After the install is completed, head to the IP address of the server LibreTime was just installed on
to complete the welcome wizard. While not strictly necessary, it is recommended that you change the passwords prompted in the welcome wizard if you intend on accessing the server from the Internet. The welcome wizard will
walk you through the rest of the installation process.
### Services
Once all of the services needed to run LibreTime are installed and configured,
it is important that the server starts them during the boot process, to cut down on downtime, especially in live enviornments.
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:
```
sudo systemctl enable libretime-liquidsoap
sudo systemctl enable libretime-playout
sudo systemctl enable libretime-celery
sudo systemctl enable libretime-analyzer
sudo systemctl enable apache2
sudo systemctl enable rabbitmq-server
```
If an error is returned, try adding `.service` to the end of each command. For example:
```
sudo systemctl enable apache2.service
```
### User Permissions
If you plan to have LibreTime output analog audio directly from its server to a mixing console or transmitter,
the `www-data` user needs to be added to the `audio` user group using the command below.
```
sudo adduser www-data audio
```
---
## Reverse Proxy {#reverse-proxy}
In some deployments, the LibreTime server is deployed behind a reverse proxy,
for example in containerization use-cases such as Docker and LXC. LibreTime
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**](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
### Reverse Proxy Basics
A reverse proxy allows the LibreTime server to not be connected to the open internet. In
this configuration, it is rather behind another server that proxies traffic to it from
users. This provides some advantages in the containerization space, as this means that
the containers can be on their own internal network, protected from outside access.
A reverse proxy also allows SSL to be terminated in a single location for multiple sites.
This means that all your traffic to the proxy from clients is encrypted, but the reverse
proxy's traffic to the containers on the internal network is not. All the SSL certificates
live on the reverse proxy and can be renewed there instead of on the individual
containers.
### Setup
There are known bugs when using LibreTime behind a reverse proxy ([#957](https://github.com/LibreTime/libretime/issues/957)
tracks the issue and contains a temporary workaround). For SSL redirection to work, you
need two domains: one for LibreTime and one for Icecast. Here, these will be
`libretime.example.com` and `icecast.example.com`.
You will also require two VMs, servers or containers. Alternatively the reverse proxy can
be located on the server, proxying connections to containers also on the host. Setting up
a containerization environment is beyond the scope of this guide. It assumes that you have
Nginx set up on `proxy` and LibreTime will be installed on `libretime`. You will need root
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](quickstart). 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
`/etc/icecast2/icecast.xml` with the following:
```
<hostname>icecast.example.com</hostname>
```
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
```
On `proxy`, run the following:
```
cat << EOF | sudo tee /etc/nginx/sites-available/libretime.conf
server {
listen 80;
server_name libretime.example.com;
location / {
rewrite ^ https://$server_name$request_uri? permanent;
}
}
server {
listen 443 ssl;
server_name libretime.example.com;
ssl_certificate /etc/letsencrypt/live/libretime.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/libretime.example.com/privkey.pem;
add_header Strict-Transport-Security "max-age=15552000;";
add_header X-Frame-Options "SAMEORIGIN";
client_max_body_size 512M;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://libretime/;
}
}
EOF
```
This Nginx configuration ensures that all traffic uses SSL to the reverse proxy, and
traffic is proxied to `libretime`.
Next, the SSL certificate needs to be generated and the site activated.
```
sudo apt install certbot
sudo systemctl stop nginx
sudo certbot certonly -d libretime.example.com -a standalone
sudo systemctl start nginx
```
You can now go to [https://libretime.example.com](https://libretime.example.com) and go
through the installer. On `General Settings`, you need to change the Webserver Port to
`443` and add the following CORS URLs:
```
https://libretime.example.com
http://libretime.example.com
https://localhost
http://localhost
```
Finally, the configuration file needs updating. Under `[general]`, `force_ssl`
needs to be set to true:
```
[general]
...
force_ssl = true
```
---
## Host Configuration
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}
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
You can also set options for RabbitMQ messaging, the LibreTime server and SoundCloud uploads 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
dbname = airtime
dbuser = airtime
dbpass = 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
[monit]
monit_user = guest
monit_password = airtime
[soundcloud]
connection_retries = 3
time_between_retries = 60
[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
sudo systemctl restart libretime-liquidsoap
sudo systemctl restart libretime-playout
sudo systemctl restart libretime-celery
sudo systemctl restart libretime-analyzer
### Changing the default PostgreSQL passwords {#postgre}
Two of the most important passwords that should be changed *immediately* after installation
are the passwords used by the PostgreSQL database.
It is strongly recommended that you do this before exposing your server to the internet beyond your internal network.
1. Login to PostgreSQL with `sudo -u postgres psql`. The PostgreSQL shell - `postgres=#` - means that you have logged in successfully.
2. Change the admin password with `ALTER USER postgres PASSWORD 'myPassword';`, where `myPassword` is the new password.
Make sure to include the semicolon at the end! A response of `ALTER ROLE` means that the command ran successfully.
3. Change the password for the *airtime* user with `ALTER USER airtime WITH PASSWORD 'new_password';`
A response of `ALTER ROLE` means that the command ran successfully.
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.
### Changing the default Icecast passwords {#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`
Replace the admin and `changeme` field below with your own username and password.
```
<authentication>
<!-- Sources log in with username 'source' -->
<source-password>changeme</source-password>
<!-- Relays log in with username 'relay' -->
<relay-password>changeme</relay-password>
<!-- Admin logs in with the username given below -->
<admin-user>admin</admin-user>
<admin-password>changeme</admin-password>
</authentication>
```
Then, restart your icecast2 service.
```
service icecast2 restart
```
> 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.
### API client configuration {#api}
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.**
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}
By default, the maximum upload file size is 500 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:
```
; Maximum allowed size for uploaded files.
upload_max_filesize = 40M
; Must be greater than or equal to upload_max_filesize
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 by `sudo systemctl apache restart`.
### 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
---
## Setting the server time
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:
date
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
If the time on your server is wrong, it is recommended that you take LibreTime off-air until the problem is fixed.
### 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
Optionally, open the **ntp** configuration file in the **nano** editor to add further time server names:
sudo nano /etc/ntp.conf
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
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
The server should respond:
* 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
### 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:
sudo dpkg-reconfigure tzdata
This command opens a menu in which you can select the continent that you require, by pressing the Enter key.
![](img/Screenshot15-Configuring_tzdata.png)
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.
---
## SSL Configuration
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
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](https://www.eff.org/). There are some requirements for this process:
- 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
If you aren't able to verify all three requirements, you may want to try a self-signed certificate (see next section).
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.
Note: all instructions require you to have sudo priveledges
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
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:
commonName = @HostName@
with the domain name used by LibreTime:
commonName = airtime.example.com
Then save the file and regenerate the certificate with the command:
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
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
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.
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.
```
<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"
ServerName airtime.example.com
#ServerAlias www.example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/airtime_mvc/public
DirectoryIndex index.php
<Directory /usr/share/airtime/php/airtime_mvc/public>
Options -Indexes FollowSymLinks MultiViews
AllowOverride all
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
<VirtualHost *:80>
ServerName airtime.example.com
ServerAdmin admin@example.com
DocumentRoot /usr/share/airtime/php/airtime_mvc/public
Redirect permanent /login https://airtime.example.com/login
SetEnv APPLICATION_ENV "production"
<Directory /usr/share/airtime/php/airtime_mvc/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:
sudo service apache restart
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)
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)
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
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.

39
docs/_docs/interface-customization.md Normal file
View file

@ -0,0 +1,39 @@
---
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 this, 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
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;
}
Save the file with **Ctrl+O**, then refresh your browser to see the change to the interface background colour.
Any custom changes that you make to the administration interface should be backed up before upgrading LibreTime to a newer version, otherwise they could be overwritten. If you have made improvements that you think might be useful to other LibreTime users, please contact LibreTime and tell us about them.
# Modifying the Icecast interface
If you have installed Icecast, in the directory */etc/icecast2/web/* you will find several XSLT and other files which are used to generate the Icecast web interface. If you are familiar with HTML you should be able to modify these pages, as they are well commented. You do have to be careful with syntax, because something as simple as a missing bracket can cause the Icecast web interface to break down.
For example, you could change the *status.xsl* page:
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.
After saving the file with Ctrl+O, refresh your web browser, and the new look should now be visible.
![](img/Screenshot177-Icecast_rocks.png)

63
docs/_docs/interface-localization.md Normal file
View file

@ -0,0 +1,63 @@
---
layout: article
title: Interface Localization
git: interface-localization.md
---
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.
![](img/Screenshot464-Korean_stream_setting.png)
First, you should check if a localization is already under way for your locale of choice. The best way to do this is to take a look at the 'master' branch in the GitHub repository for LibreTime at <https://github.com/LibreTime/libretime>. You can also ask in the LibreTime development forum at <https://discourse.libretime.org/>, where you might find community members who can help you with the translation.
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:
#: airtime_mvc/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.
If you use the cross-platform program **Poedit** (<http://www.poedit.net/>) to edit the .po file, this formatting of the text is hidden by an easy-to-use GUI. The *poedit* package can be installed on most GNU/Linux distributions using the standard software installer. Versions of Poedit for Mac and Windows are available for free download from the project's homepage.
Before manually translating strings in Poedit from scratch, you should take a look at the online translation services available, such as Lingohub (<https://lingohub.com>) or Google's Translator Toolkit (<http://translate.google.com/toolkit/>), which both support gettext .po files. If using automatic translation, you can then use Poedit to fine-tune the localization and fix any formatting errors.
If you don't already have a GitHub account, you can sign up at <https://github.com/signup/free>. Once you have a GitHub account, you can fork a copy (<https://help.github.com/articles/fork-a-repo>) of the LibreTime project. Work for the next major version of the software is done in the **master** branch of each project, so that's the branch to **checkout** after you have made the initial **git clone**.
In the locale code *de\_CH*, for example, *de* represents the German language and the suffix *\_CH* indicates the dialect spoken in Switzerland. Some languages have a wide variety of dialect localizations, which can be differentiated with a suffix in this way. You should update the header information in the .po file, which includes the language code and a country code, using one of the existing .po files as a guide.
After forking the LibreTime git repository, make sure you're in the **master** branch:
git branch
devel
* master
Create a new locale directory (e.g. *airtime\_mvc/locale/de\_CH/LC\_MESSAGES/* for German as spoken in Switzerland):
mkdir -p airtime_mvc/locale/de_CH/LC_MESSAGES/
Copy the template *airtime.po* file into the directory you just created:
cp airtime_mvc_locale/template/airtime.po airtime_mvc/locale/de_CH/LC_MESSAGES
and update the header information in the new copy of the *airtime.po* file using the **nano** editor:
nano airtime_mvc/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"
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.
Finally, **git add**, **git commit** and **git push** these new .mo and .po files to your GitHub fork of the project, and send a git pull request (<https://help.github.com/articles/using-pull-requests>) to the LibreTime developers. The localization can then be added to a forthcoming LibreTime release.
If you don't want to work with git, that's no problem - download a copy of the .po template file, edit the header, run it through an automatic translator and check it with Poedit. Then email your contribution to the LibreTime team as an attachment - it will be very welcome! However, learning to use git is a good idea, because it means you can work directly on the current source code, share the localization work with the LibreTime community, and avoid duplicated effort.

239
docs/_docs/library.md Normal file
View file

@ -0,0 +1,239 @@
---
layout: article
title: Library
git: library.md
category: dj
---
## Dashboard {#dashboard}
The Dashboard is divided into two sections a Library section divided between
Tracks, Playlists, Smart Blocks, Webstreams, and Podcasts, with the **Scheduled
Shows** dialog on the right. This page provides an overview of the right-hand
interface. Check the links to see information about the other sections which
provide the content that can be scheduled.
The **Scheduled Shows** page provides a view of the content your station is will
playout, or has already played out, which defaults to showing the 3 hours
ahead. This page also enables you to make last-minute changes to running shows.
If you've only just installed LibreTime, there might not be any content shown
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)
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)
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**,
**Album**, **Cue** or **Fade** times and **Mime** type (file format) can also be
shown. This information can help you to prepare voice tracks for insertion into
the show, including time checks if you wish. Putting current time information i
to voice tracks describing specific content can, of course, limit the
re-usability of those voice tracks, unless you always broadcast a particular
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)
The row for the currently playing item is displayed with a bright green
background. Any underbooked shows (shows with insufficient content to fill the
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)
### Removing content from a running show
If a show is overbooked, which means the total playout duration is longer than
the time allowed for the show, a brown row indicates that the item will be faded
out when the show ends. A red row indicates that the item will not be played at
all. The length of the overbooking is shown in minutes and seconds in the last
row of the show. To remove the extra items from the end of an overbooked show,
click the **Scissors** button at the top left of the table.
Alternatively, check the boxes for items which have not yet completed playout,
and click the **Trashcan** button, to the right of the Scissors, to remove them
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)
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
**Trashcan**.
To cancel the current show completely, click the red button to the right again.
A pop-up window will ask you to confirm the cancellation, as this action cannot
be undone.
Items which are no longer available have an exclamation mark icon in the second
column. This may happen for media files which were part of previous shows, and
were removed from LibreTime's library (main storage or watched folders)
subsequently. Items which are included in forthcoming shows cannot be removed
from the Library via the LibreTime interface.
### Adding content to a running show
After you have found the items that you want using the search tools, you can
then drag and drop them from the library table on the left side of the page into
the shows on the right side, including the current playing show.
If the current show has nothing playing out at the time, the new item will begin
playing immediately. This manual triggering of playout can be used as a live
assist technique, in which the LibreTime server's soundcard output is mixed with
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)
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**
of search results, **Deselect this page** and **Deselect all**. Alternatively,
use the checkboxes on the left side of the library table to select specific
items. Then drag one of the items into the show to add all of the selected
items, or click the **Add to selected show** button, which has a plus icon. If
you wish, you can also use the **Trashcan** button to permanently remove items
from LibreTime's library. Only *admin* users have permission to delete all
items.
To insert checkbox selected items at a specific time in the show schedule, click
one of the songs in the schedule table. Then click the **Add to selected show**
button in the library table. This will insert the library songs after the
selected scheduled song.
To add a single item at the insertion point, double-click on it in the library.
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.
---
## Playlists {#playlists}
### Creating a new playlist
You can create a new playlist on the toolbar of the **Playlists** page.
![](img/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.
### Adding content to a playlist
With a playlist open, drag and drop items from the search results on the left into the playlist on the right. Jingles and voice tracks can be added before, after or between music items.
After adding files to the playlist, the total playlist time is displayed in the top right corner. The duration of an individual file is shown in each row of the playlist in a white font, and beneath this figure the time since the beginning of the playlist is displayed in a smaller light grey font. This elapsed time figure can be used as a time check for voice tracks, although this option may limit the re-usability of the voice track.
To audition a playlist file in your web browser, click the white triangle button on the left side of its row. (If the format of the file is not supported by your browser, the triangle in this button will be greyed out). If audition of the file format is supported, a pop-up window will open, with the playlist starting at the file you clicked.
Click the small white **x** icon on the right hand side of each row to remove a file from the playlist. You can also drag and drop files to re-order them, or click the **Shuffle** button to re-order files automatically.
When your playlist is complete, click the **New** button in the top left corner to create another playlist, click the close icon (a white cross in a black circle) in the top right corner, or browse to another page of the LibreTime interface.
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.
## Smartblocks {#smartblocks}
### Creating a Smartblock
![](img/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.
To create a smart block, click the **Smartblocks** button on the left sidebar, and select **New** from the toolbar. Like a playlist, smart blocks can have a title and description, which you can edit. This helps you find relevant smart blocks in searches.
Fill out the smart block's **Name**, **Search Criteria**, and **Limit to** sections. The search criteria can be any one of LibreTime's metadata categories, such as **Title**, **Creator** or **Genre**. The modifier depends on whether the metadata in question contains letters or numbers. For example, **Title** has modifiers including *contains* and *starts with*, whereas the modifiers for **BPM** include *is greater than* and *is in the range*.
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 never overflow the Time Limit. For instance if you set a time limit of 1 hour. It will add tracks to the schedule until it can't add any more tracks without exceeding the hour. 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". This will make LibreTime add tracks that meet the criteria until it equals or is longer than the time limit. This is helpful for avoiding dead air on shows that are being autoscheduled.
![](img/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](preparing-media) for tips on tagging content.
![](img/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.
By default, a smart block will not contain repeated items, which will limit the duration of the block if you do not have sufficient items meeting the specified criteria in your **Library**. To override the default behaviour, check the **Allow Repeat Tracks** box. The **Sort tracks by** menu offers the options of **random**, **newest** or **oldest** items first.
Smart blocks can be added to shows in the same way as a manually created playlist is added. Smart blocks can also be added to one or more playlists. In the case of a playlist containing a static smart block, click **Expand Static Block** to view the contents. For a dynamic smart block, you can review the criteria and duration limit by clicking **Expand Dynamic Block**.
Once created, smart blocks can be found under the Smartblocks tab and refined at any time. They can be re-opened by right-clicking on the smart block and selecting **Edit** from the pop-up menu.
---
## Podcasts {#podcasts}
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.
The podcast interfaces provides you with the ability to generate [Smartblocks](library#smartblocks) 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>
</html>
<br>
### Podcasts Dashboard
![](img/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.
To add a podcast, click on the **+ Add** button on the toolbar and provide the podcast's RSS feed, which usually ends in *.xml*.
Once the podcast's feed is recognized, the editor pane opens for the podcast.
### Editor
![](img/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.
- To import an episode directly into LibreTime, double-click on an episode or select it and click **+ Import**. The podcast will appear under tracks with the Podcast Name as the Album.
- To delete an episode from LibreTime, select the episode and click on the red trash can on the toolbar.
- If you would like LibreTime to automatically download the latest episodes of a podcast, make sure *Download latest episodes* is checked. This can be used in conjunction with Smartblocks and Playlists to automate downloading and scheduling shows that are received via podcast feed.
## Webstreams {#webstreams}
<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
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)
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](../live-shows-with-mixxx/index.md).

88
docs/_docs/live-broadcast.md Normal file
View file

@ -0,0 +1,88 @@
---
layout: article
title: Broadcasting live with MIXXX or B.U.T.T.
git: live-broadcast.md
category: dj
---
## Live shows with MIXXX {#mixxx}
[Mixxx](https://www.mixxx.org) is a cross-platform Open Source application for DJs.
Installed on a desktop or laptop computer, Mixxx complements your LibreTime server to provide a complete system
for both live and scheduled broadcasting. Although Mixxx has many features designed for dance music DJs
that require beat matching and pitch independent time stretching, the program can be used for any kind of
manually triggered broadcast playout, including live speech shows such as news or current affairs.
Mixxx supports a wide variety of popular hardware control surfaces, which can be connected to your
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,
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
**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.
## Live shows with B.U.T.T. (Broadcast Using This Tool) {#butt}
<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>
### Set Up
1. Download and install butt from <https://danielnoethen.de/> for your OS.
*Note: be sure you have butt version 0.1.17 or newer installed*
2. Open up butt
3. Click **settings**
4. Under **Main** under **Server **click **ADD**
* Type LibreTime (or your station) under Name
* Click the radio button next to **IceCast** under Type
* Type your stations URL (webpage address) under **Address**:
* Type **8002** under **Port**:
* Type your DJ login password under **Password**
* 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*
### 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.
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!
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.
5. If it is gray, click on the **Show Source** switch to the right of it and it
will toggle your show on and you will be broadcasting. *Note: whether auto
connect is turned on is a station specific setting so it could work either way*
### Recording your show
You can record your show under butt by clicking the red circle record button on
the left. It will save a mp3 based upon the date and time in your home/user
directory by default.
Everything should now be working and you can broadcast for your entire time
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.

32
docs/_docs/microsite.md Normal file
View file

@ -0,0 +1,32 @@
---
layout: article
title: Built-in Microsite
git: microsite.md
category: admin
---
## Overview
![](img/radio-page.png)
LibreTime includes a mini-site, which can be accessed at _serverIP_ (for local installations), or
_libretime.yourdomain.com_ or _cloudvmIP_ (for installations to a server on a domain). The site includes your
logo and station description (set under Settings > General), the login button to the LibreTime interface, the schedule for the next seven days,
podcast tabs, and a live feed of your station with the currently playing artist and track displayed.
## 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/airtime_mvc/public/css/radio-page/radio-page.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;
}
```
Place the new background image in the */usr/share/airtime/public/css/radio-page/img/* folder and change the `background:` entry's URL to point to the new image. The new image should be at least 1280 x 720 in pixel size to avoid being blurry.

97
docs/_docs/preparing-media.md Normal file
View file

@ -0,0 +1,97 @@
---
layout: article
title: Preparing Media for LibreTime
git: preparing-media.md
category: dj
---
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.
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.
| Windows | macOS | Linux |
|---------|-------|-------|
| [Mp3tag](https://www.mp3tag.de/en/index.html) | [MusicBrainz Picard](https://picard.musicbrainz.org/) | [Ex Falso](http://code.google.com/p/quodlibet/) |
| [TagScanner](https://www.xdlab.ru/en/) | | |
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)
## 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
<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>
find . -name "*.mp3" -print0 | xargs -0 mid3iconv -e CP1251 -d -p
in the base directory of the archive. The **-d** option specifies that the new tag should be printed to the server console (debug mode), and the **-p** option specifies a preview run. This preview will enable you to confirm that the metadata is being read and converted correctly before writing the new tags.
To actually convert all of the tags and strip any legacy ID3v1 tag present from each file at the same time, you could use the command:
find . -name "*.mp3" -print0 | xargs -0 mid3iconv -e CP1251 --remove-v1
The name of the original character set follows the **-e** option. Other legacy character sets that mid3iconv can convert to UTF-8 include:
KOI8-R: Russian
KOI8-U: Ukrainian
GBK: Traditional Chinese
GB2312: Simplified Chinese
EUC-KR: Korean
EUC-JP: Japanese
CP1253: Greek
CP1254: Turkish
CP1255: Hebrew
CP1256: Arabic
## Audio loudness
On file ingest, LibreTime analyzes each Ogg Vorbis, MP3, AAC or FLAC file's loudness, and stores a *ReplayGain* value for that file in its database. At playout time, the ReplayGain value is provided to Liquidsoap so that gain can be automatically adjusted to provide an average output of -14 dBFS loudness (14 decibels below full scale). See <http://www.replaygain.org/> for more details of ReplayGain.
Because of this automatic gain adjustment, any files with average loudness higher than -14 dBFS will not sound louder than quieter files at playout time, but the lower crest factor in the louder files (their relatively low peak-to-average ratio) may be apparent in the output, making those files sound less dynamic. This may be an issue for contemporary popular music, which can average at -9 dBFS or louder before ReplayGain adjustment. (See <http://www.soundonsound.com/sos/sep11/articles/loudness.htm> for a detailed analysis of the problem).
Your station's producers should therefore aim for 14dB between peak and average loudness to maintain the crest factor of their prepared material (also known as *DR14* on some dynamic range meters, such as the command-line DR14 T.meter available from <http://sourceforge.net/projects/dr14tmeter/>). If the producers are working to a different loudness standard, the ReplayGain modifier in LibreTime's Stream Settings page can be adjusted to suit their material.
Large transient peaks in otherwise quiet files should be avoided, to guard against the need for peak limiting when ReplayGain is applied to those quieter files.
The **vorbisgain** command-line tool, available in the **vorbisgain** package in Debian/Ubuntu, can be used to indicate the ReplayGain of an individual Ogg Vorbis file before ingest into LibreTime. (A similar tool for MP3 files is available in the **mp3gain** package in Debian/Ubuntu).
Here is an example of a very quiet file where the use of ReplayGain would make the output more than 17dB louder:
$ vorbisgain -d Peter_Lawson-Three_Gymn.ogg
Analyzing files...
   Gain | Peak | Scale | New Peak | Track
----------+------+-------+----------+------
+17.39 dB | 4536 | 7.40 | 33585 | Peter_Lawson-Three_Gymn.ogg
And here is an example of a very loud file, with lower crest factor, where the output will be more than 7dB quieter with ReplayGain applied:
$ vorbisgain -d Snoop_Dogg-Doggfather.ogg
Analyzing files...
   Gain   | Peak  | Scale | New Peak | Track
----------+-------+-------+----------+------
 -7.86 dB | 36592 |  0.40 |    14804 | Snoop_Dogg-Doggfather.ogg
In the output from vorbisgain, *Peak* is the maximum sample value of the file before any ReplayGain has been applied, where a value of 32,767 represents full scale when decoding to signed 16 bit samples. Note that lossy compressed files can have peaks greater than full scale, due to encoding artifacts. The *New Peak* value for the Snoop Dogg file may be relatively low due to the hard limiting used in the mastering of that piece of music.
## 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
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.
![](img/Screenshot126-Debra_silence.png)

86
docs/_docs/rights-royalties.md Normal file
View file

@ -0,0 +1,86 @@
---
layout: article
title: Rights and Royalties
git: rights-royalties.md
---
If you're new to broadcasting, or have not streamed your station online before,
reading the following brief explanation of compensation rules for songwriters,
musicians and other copyright holders may save you a great deal of trouble
later.
Independent music radio on the Internet has faced royalty demands from
SoundExchange in the USA, and similar organizations in other territories. These
organizations are usually membership societies or government-sanctioned national
authorities which are intended to collect money from broadcasters to compensate
copyright holders. The royalty collection societies require payment before you
can stream just about any music released commercially to the general public —
whether you make any money out of streaming, or not. It's not so much the
percentage of revenue demanded, but that there are usually annual minimum fees
to pay, which can hurt small stations disproportionately.
For example, in the UK, the MCPS-PRS Limited Online Music Licence covers
non-commercial music streaming by groups and individuals, as long as their gross
revenue is less then £12,500 per year. The cost is on a sliding scale, up to
£1,120 plus 20% tax per year for delivering up to 450,000 individual streams or
serving 25,000 files; after that, you have to apply for a full MCPS-PRS Online
Music Licence. That doesn't sound too bad at first, but 25,000 files per year
works out at less than four downloads per hour for a round-the-clock website.
This particular licence only covers publishing (songwriter) rights, not
recording (record label and musician's performance) rights, so you have to
negotiate an additional licence from Phonographic Performance Limited (PPL) to
play music online, including digital recordings converted from commercially
released CDs, vinyl or tape.
Typically, you have to provide full statistical details to the royalty society
of all music streamed or downloaded from your site, which can be onerous. Even
if your radio station is mostly speech, there are many limitations in the small
print of these music licences. For instance, you can't use music for
promotional purposes, and you can't stream a whole opera, without negotiating
separate licences. Weirdly, you are not allowed to play a piece of music in a
'derogatory context' to the writer or performers; no drummer jokes allowed,
then.
However, the biggest pitfall is that these MCPS-PRS licences for publishing
rights only cover listeners in the UK. For recording rights, PPL is a member of
the IFPI reciprocal scheme for webcasters, which means its licenses cover
listeners in some European countries, Australia, New Zealand and a few other
countries, but not listeners in the USA or Canada. So if your Internet station
picked up a significant number of listeners in countries not covered by the
MCPS-PRS licences or the IFPI reciprocal scheme, you would have to pay for
similar music licences in those countries as well. It's no wonder that many
not-for-profit radio stations have disappeared from the virtual airwaves over
the last few years, since not having the right licences could leave the operator
liable to legal action.
If you want to go down the commercial music route, check out the
<http://www.prsformusic.com> and <http://www.ppluk.com> websites for UK licence
details. In the USA, the <http://www.soundexchange.com> website currently quotes
a 500 dollar minimum annual fee for non-commercial webcasters, plus a usage fee
above a certain number of listener hours, for the right to stream music
recordings to listeners. See the websites of [ASCAP](http://www.ascap.com),
[BMI](http://www.bmi.com) and [SESAC](http://www.sesac.com) for details of music
publishing royalties payable by webcasters streaming to the USA.
Free content streaming offers an alternative for DIY Internet radio. Since
royalty collection societies like MCPS-PRS and SoundExchange can only represent
the interests of their own members, it follows that if you are not a member, you
can stream your own self-produced content without paying for their licences. If
you state somewhere on your website that the stream is of your own copyrighted
material, and is made available to the public under a specific licence, then
no-one should misunderstand your intentions.
You might be able to persuade other people to allow you to stream their content
too, as long as they do not have a conflicting legal obligation, such as having
previously joined one of the many royalty collection societies around the world.
You can ask for permission to stream when website visitors upload their own
music files to you via a HTML form, much as the likes of SoundCloud do. Or you
can collect files licensed under an appropriate Creative Commons licence
(<http://www.creativecommons.org>) or other free content licence.
Explicit permission to stream on your particular server is always going to be
the ideal, so think about your own terms and conditions before you accept files
from third parties for streaming. How, for example, would you know if someone
uploaded a file to your online radio station that unknown to you, had been
ripped from a commercially released CD? That's the kind of thing that could get
you in trouble with the licensing authorities and copyright holders.

143
docs/_docs/scheduling-shows.md Normal file
View file

@ -0,0 +1,143 @@
---
layout: article
title: Scheduling Shows
git: scheduling-shows.md
---
## Scheduling Shows
<html>
<br>
<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>
</html>
Log in using your username and password using the link in the upper right corner. (If you just installed
LibreTime, your username/password is admin/admin.)
The main workflow in LibreTime is **Upload** media -> create a show on the **Calendar** -> **Schedule Tracks**.
Once you log in, click on the big blue button on the left navigation that says **Upload**.
![](img/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
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)
Click on the blue **+ New Show** button to add a new show.
![](img/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
of the pane to add your show to the calendar.
| Field | Description |
|-------|-------|
| _What_ | |
| Name (Required) | The name of your show |
| URL | The URL of your show. Not used on the public page. |
| Genre | The genre of your show. Not used on the public page. |
| Description | Description of your show. Not used on the public page. |
| _When_ | |
| Start Time (Required) | The time and date the show starts. Note that the time element is in 24 hour time. If the **Now** option is selected, the show will be created to immediately start. |
| End Time (Required) | The time and date the show ends. Defaults to a time one hour after the start time, which can be seen in the **Duration** field, which is uneditable. |
| Repeats? | If checked, allows for options to schedule a repeated show. Shows can repeat weekly up to monthly in increments of one week and can be scheduled on multiple days of the same week. An end date can be set, otherwise the show can be deleted by clicking on its entry in the calendar and clicking Delete > Future Occurances. If **Linked ?** is checked, the playlist scheduled for the next show will also play for all future shows. |
| _Autoloading Playlist_ | |
| Add Autoloading Playlist? | If checked, allows for the following options |
| Select Playlist | Select the playlist the show will autofill from (shows autofill exactly one hour before air). If you wish to use a smartblock you must add it to a playlist and then select that playlist. This can be used to auto-schedule new podcast episodes to air. |
| Repeat Playlist Until Show Is Full | If checked, the playlist will be added to the show multiple times until the slot is full. Useful for applying a one-hour music playlist made up of smartblocks to a two-hour show. |
| _Live Stream Input_ | |
| Use LibreTime/Custom Authentication | |
| Show Source | |
| _Who_ | |
| Search Users, DJs | Program Managers and Admins may assign DJs to a show, giving DJs access to schedule tracks for said show. DJs cannot create shows on their own. |
| _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.
---
## Calendar Functions {#calendar}
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)
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)
### 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)
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)
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.
### Adding content to a show
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)
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)
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)
### Removing content from a show
To remove an individual item from a show, click on the show in the **Calendar**, and select **Schedule Tracks** from the pop-up menu. In the window which opens, click any item you wish to remove from the show, then click **Delete** on the pop-up menu, or check the box in the item's row then click the **Remove** icon at the top of the table. To remove all files and playlists from a show, click on the show in the **Calendar**, and select **Clear Show** from the pop-up menu. 
### Deleting an upcoming show
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)
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**.
### Cancelling playout
If you wish to cancel playout of a show while it is running, click on the show in the **Calendar** and select **Cancel Show** from the pop-up menu. This action cannot be undone.

206
docs/_docs/settings.md Normal file
View file

@ -0,0 +1,206 @@
---
layout: article
title: Settings
git: settings.md
---
## General Settings
![](img/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)
The **Default Interface Language** drop-down menu sets the default localization
for your LibreTime instance, and the **Station Timezone** drop-down menu can be
used to display local time at your station. LibreTime stores show times
internally in UTC format (similar to *Greenwich Mean Time*), but displays local
time for the convenience of your station staff. You can also set the day of the
week that you wish to start your station's weekly schedule on, which defaults
to Sunday.
The **Track Type Default** enables you to select a track type default for uploads.
Initially, the **Default Fade In** and **Default Fade Out** times for automated
fades are set to half a second, and the **Default Crossfade Duration** is set to
zero seconds. Custom fade and crossfade times can be set for adjacent items in a
playlist or static smart block. See the chapter *Library* for details.
The **Intro Autoloading Playlist** enables you to select a playlist that will be
scheduled at the beginning of every show that has enabled an autoloading
playlist. This can be used for instance to insert a station ID or other
announcements a the top of every show.
The **Outro Autoloading Playlist** enables you to select a playlist that will be
scheduled after the content of every show with an autoloading playlist.
The **Overwrite Podcast Episode Metatags** option which is enabled by default
causes LibreTime to override the Artist, Title & Album fields on any tracks
downloaded from a podcast with information from the RSS feed.
The **Generate a smartblock and a playlist upon creation of a new podcast**
option when enabled will create a smartblock matching the newest episode of a
podcast and a playlist containing that smartblock automatically upon adding a
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)
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*](exporting-the-schedule) chapter, in the
*Advanced Configuration* section of this book).
The **Allowed CORS URLs** is intended to deal with situations where you want a
remote site with a different domain to access the API. This is relevant when
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 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
the entire LibreTime library.
When you are done remember click the **Save** button at the top or bottom of the
form.
![](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
their username on the right side of the menu bar.
![](img/Screenshot475-Edit_own_user_account.png)
----
## Track Types {#types}
### Create track types
1. Click **Settings**
1. Click **Track Types**
1. Click **New Track Type**
1. On the "Code" field, type a unique code that can be easily identifiable. Example, for Music use "MUS" or for Sound Effects use something like "FX".
1. On the "Type Name" field, type a the name of the type of tracks. Example, "Station IDs".
1. On the "Description" field, enter the description of the type given.
1. On the "Visibility" drop down menu, choose to enable or disable the track type. By default, it is enabled. If disabled, it won't be shown across Libretime or in the API for developers.
1. Click **Save**.
----
## Stream Settings {#stream}
<html>
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/QPNo52Fc0ck" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</html>
### Global settings
You can configure direct Icecast and SHOUTcast streams and sound card output by clicking **Streams** on the **System** menu.
At the top left of the **Stream Settings** page are global settings including **Hardware Audio Output**, which enables playout from the default sound card on the server, if one is fitted. The default **Output Type** of *ALSA* on the drop-down menu will be suitable for most servers with a sound card. If not, you have the option to choose from other Liquidsoap interfaces available, such as *OSS* or *PortAudio*.
The second checkbox under Global Settings enables the sending of **Icecast Vorbis Metadata** with direct streams. This setting is optional, because some media players have a bug which makes them disconnect from Ogg Vorbis streams when an Icecast server notifies the player that a new track is starting.
The **Stream Label** radio button allows you to set the metadata that will be sent with direct streams; *Artist* and *Title*, *Show*, *Artist* and *Title*, or *Station name* and *Show name*.
![](img/Screenshot481-Global_stream_settings.png)
The **Off Air Metadata** field configures the text that will be sent to any configured streaming servers, and from there on to media players, when Airtime is not streaming any output.
Below this is the **Enable Replay Gain** checkbox which, if checked, automatically adjusts Airtime's output level to an average of -14dBFS, based on prior analysis of the level of individual files in the **Library**. This feature helps guard against unwanted changes in Airtime's output level caused by the typical variation in average level of recordings made in different studios at different times. The correction value for each file can be viewed by enabling the ReplayGain column in the **Library**.
If Replay Gain is enabled, output level can be adjusted up to 10dB louder or quieter from the reference level of -14dBFS by clicking and dragging the **Replay Gain Modifier** control. Increasing level too far is likely to result in clipping (distortion) since the output level is adjusted to be greater than that of the original files. This scenario is indicated by amplitude correction factors greater than 1.0 in the Liquidsoap log file.
Click the **Save** button on the right side of the page to save any changes that you have made to global settings. If you are only using the hardware audio output, and will not be streaming to or from Airtime, you can leave the **Stream Settings** page after clicking the **Save** button.
### Input stream settings
On the lower left side of the Stream Settings page you can configure remote live input streams from DJ programs such as **Mixxx** or **IDJC**, or smartphone applications used by broadcast journalists. A bug with **Butt** versions 1.14 to 1.16 causes streams not to connect to LibreTime. A fix has been introduced with **Butt** version 1.17 that allows it to be used by LibreTime.
Airtime supports two types of live input stream; the **Show Source**, which enables a specific person to stream in during their own show, and the **Master Source**, which can override the Show Source if necessary. If neither type of live input is available, Airtime will fall back to **Scheduled Play** (playlists, smart blocks, remote streams and files scheduled in Airtime, in advance of or during a show).
The **Auto Switch Off** and **Auto Switch On** checkboxes enable playout to be switched automatically to the highest priority source whenever an authenticated input source disconnects from or connects to Airtime, respectively. The field **Switch Transition Fade** sets the length of the audio fade as scheduled playout is switched to a remote input source, and back.
Each type of input stream requires a username and password before the remote broadcaster can connect to Airtime. The **Master Username** and **Master Password** can be set in the Input Stream Settings box, while the authentication for individual Show Sources is set up in Airtime's schedule calendar. See the *Calendar* chapter for details.
Input streams must have a **Port** for the remote broadcaster to connect to, which should be a number in the range from 1024 to 49151. If you have the Icecast or SHOUTcast streaming server running on the same machine as Airtime, you should avoid using port 8000 or 8001 for either type of Airtime input stream. This is because both Icecast and SHOUTcast use port 8000, and SHOUTcast also uses port 8001. If the usernames and passwords were similar, remote broadcasters might accidentally connect to the streaming server directly, bypassing Airtime.
To avoid further confusion, it is also recommended that you set a different **Mount Point** (the specific filename for broadcasters and listeners to connect to) from that used on your public Icecast or SHOUTcast server.
![](img/Screenshot401-Input_stream_settings.png)
If your Airtime server is behind a firewall, and you wish remote broadcasters to connect input streams to it across the public Internet, you may need to click the **Override** link to set a **Connection URL** which is available from outside your local area network. This URL might be based on the domain name assigned to the router which forwards the appropriate port to your Airtime server. Then click **OK** to save the new connection URL.
### Switching input streams
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)
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)
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.
You can also force disconnection of a live remote source, for example when the remote input source has crashed and is no longer sending audio data, click the **X** icon to the left of the source name.
### Output stream settings
The Default Streaming radio button that is configured by default currently relies upon an insecure icecast password. You will want to change the Icecast2 password and select Custom Streaming. See the notice above for a tutorial on how to fix this.
On the right side of the page, you can configure up to three independent output streams with different bit rates or formats, and send these streams to different Icecast or SHOUTcast servers. By default, only Stream 1 is enabled, with this stream being sent the Icecast server configured at installation time.
To configure another stream, click the bar with the stream number to expand its box, and make sure **Enabled** is checked. Enter at least the streaming **Server** IP address or domain name, and **Port** details. The default port for Icecast and SHOUTcast servers is 8000.
![](img/Screenshot402-Output_stream_settings.png)
Click **Additional Options** to expand a box in which you can enter the usernames, passwords and metadata to send to the streaming server. The default **Username** for Icecast servers is *source*, and if this the name in use on your streaming server, you can leave this field empty. The **Admin User** and **Admin Password** settings are optional, and are used to query the streaming server for audience numbers by the **Listener Stats** page on the **System** menu.
You can also set the specific **Mount Point** that listeners will connect to here. Then click one of the **Save** buttons in the upper or lower right corner of the page to update the Airtime server's settings.
![](img/Screenshot482-Additional_options.png)
Airtime supports output to Icecast in Ogg Vorbis, Ogg Opus, MP3 and AAC formats. When selecting a SHOUTcast server from the **Service Type** drop-down menu, you are restricted to using MP3 or AAC formats only, so the choice of Ogg Vorbis and Opus formats is greyed out in the **Stream Type** drop-down menu. The SHOUTcast username for stream sources is fixed, so you do not need to enter this value under **Additional Options**, but you will usually have to enter a password.
![](img/Screenshot404-Shoutcast_output_stream.png)
Any connection problems between Liquidsoap and Icecast or SHOUTcast are shown on the Stream Settings page. For example, if you enter the wrong password, you will see an *Authentication Required* error message. To fix this, enter the correct password in the **Additional Options** box, and click the **Save** button. If the streaming server is down for any reason, or you have entered an incorrect **Server** name or **Port** number, you will see the message *Can not connect to the streaming server*.
![](img/Screenshot405-Connection_timeout.png)
------
## The Status page {#status}
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.
![](img/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](troubleshooting) contains some tips). 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
that are no longer required from the **Library**. Alternatively, you could ask your system administrator to install additional storage capacity.

110
docs/_docs/troubleshooting.md Normal file
View file

@ -0,0 +1,110 @@
---
layout: article
title: Troubleshooting
git: troubleshooting.md
---
## Restarting services
LibreTime is effectively a web site running on a LAPP stack, so individual components of the system can be started, stopped, restarted or checked in the server console using the **systemctl** command:
```
sudo systemctl start|stop|restart|status libretime-liquidsoap
sudo systemctl start|stop|restart|status libretime-playout
sudo systemctl start|stop|restart|status libretime-celery
sudo systemctl start|stop|restart|status libretime-analyzer
sudo systemctl start|stop|restart|status apache2
sudo systemctl start|stop|restart|status rabbitmq-server
```
For example, to restart the Airtime playout engine, you could enter the command:
```
sudo systemctl restart libretime-playout
```
## Log files {#logs}
Airtime stores log files under the directory path */var/log/airtime/* which can be useful for diagnosing the cause of any problems. Copies of these log files may be requested by LibreTime developers while they are providing technical support for your Airtime deployment.
## Test tones {#tones}
If you need to test your computer's soundcard, you can use `speaker-test`, a tone generator for ALSA.
This does not come installed with LibreTime but can be installed with `sudo apt install speaker-test`.
```
speaker-test [-D] [-f]
Where:
-D device name
-f frequency of test tone
```
The **airtime-test-stream** command enables you to send a test tone to a local or remote streaming media server. Press **Ctrl+C** on your keyboard to stop the tone being streamed.
```
airtime-test-stream [-v]
[-o icecast | shoutcast ] [-H hostname] [-P port]
[-u username] [-p password] [-m mount]
[-h]
Where:
-v verbose mode
-o stream server type (default: icecast)
-H hostname (default: localhost)
-P port (default: 8000)
-u user (default: source)
-p password (default: hackme)
-m mount (default: test)
-h show help menu
```
## RabbitMQ hostname changes
If the Airtime logs indicate failures to connect to the RabbitMQ server, such as:
```
2013-10-31 08:21:11,255 ERROR - [pypomessagehandler.py : main() : line
99] - Error connecting to RabbitMQ Server. Trying again in few seconds
2013-10-31 08:21:11,255 ERROR - \[pypomessagehandler.py : main() : line 99\] - Error connecting to RabbitMQ Server. Trying again in few seconds - See more at: http://forum.sourcefabric.org/discussion/16050/\#sthash.W8OJrNFm.dpuf
```
but the RabbitMQ server is running normally, this error might be due to a change in the server's hostname since Libretime installation. Directory names under */var/lib/rabbitmq/mnesia/* indicate that RabbitMQ's database files are organised according to the hostname of the server (ex. `rabbit@airtime`) where the hostname is *airtime.example.com*. If the hostname has changed, it may be necessary to reconfigure RabbitMQ manually, as follows:
1. Delete the files in */var/lib/rabbitmq/mnesia/*
```
sudo rm -r /var/lib/rabbitmq/mnesia/*
```
2. Restart RabbitMQ:
```
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:
```
rabbitmqctl add_vhost /airtime
rabbitmqctl add_user airtime XXXXXXXXXXXXXXXXXXXX
rabbitmqctl set_permissions -p /airtime airtime
"airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
  "airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
 "airtime-pypo|pypo-fetch|airtime-analyzer|media-monitor"
```
## Uninstall LibreTime {#uninstall}
Hopefully it wasn't something that we did, but if you need to uninstall LibreTime for
any reason, cd to the directory of the installer and run
```
sudo ./uninstall
```
If allowed, the installer will **permanently** delete all databases and media uploaded to
LibreTime.
If it was something we did, please open an issue request on our Github page, located
[here](https://github.com/LibreTime/libretime/issues).
Until we meet again, best of luck.
<3 The LibreTime team

51
docs/_docs/upgrading.md Normal file
View file

@ -0,0 +1,51 @@
---
layout: article
title: Upgrading LibreTime
git: upgrading.md
---
## LibreTime versioning
LibreTime 3.x versions support upgrading from Airtime 2.5.x versions. LibreTime follows the [Semantic Versioning (semver)](http://semver.org/spec/v2.0.0.html) standards.
In a nutshell, given a version number MAJOR.MINOR.PATCH we increment the:
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.
Before upgrading a production LibreTime server, you should back up both the PostgreSQL
database and the storage server used by LibreTime. 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. See
[Backing up the server](backing-up-the-server) in this manual for details of how to perform these back ups.
The LibreTime [installation script](install) will detect an existing LibreTime or Airtime deployment and back up any configuration files that it finds. We recommend taking your own manual backups of the configuration yourself nevertheless. The install script also tries to restart the needed services during an upgrade. In any case you should monitor if this happened and also take a quick look at the logs files to be sure everything is still fine. Now might be the time to reboot the system or virtual machine LibreTime is running on since regular reboots are part of a healthy system anyway.
After the upgrade has completed, you may need to clear your web browser's cache before logging into the new version of the LibreTime administration interface. If the playout engine starts up and detects that a show should be playing at the current time, it will skip to the correct point in the current item and start playing.
There will be tested ways to switch from a LibreTime pre-release to a packaged version of LibreTime.
Airtime 2.5.x versions support upgrading from version 2.3.0 and above. If you are
running a production server with a version of Airtime prior to 2.3.0, you should
upgrade it to version 2.3.0 before continuing. 
In Airtime 1.9.0 onwards, the concept of *linked files* was replaced with the
concept of *watched folders*. If you are upgrading from a version of Airtime
earlier than 1.9.0 and you have previously linked files, the folders they are
in will not be watched until you add them to your watched folder list. See
[Media Folders](folders) for more details.

56
docs/_docs/users.md Normal file
View file

@ -0,0 +1,56 @@
---
layout: article
title: Managing Users
git: users.md
category: manager
---
> Note: if your Airtime server is accessible from the public Internet (ex. being hosted in a cloud VM)
it is recommended that you create a second administrator account with a secure password and then
delete the `admin` account, for best security practice.
## 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:
* Guests
- Can view shows and the playout log on the Calendar and Dashboard, respectively
- Listen to the output stream without leaving the interface
* DJs
- Everything Guests can do, plus
- Upload media (music, PSAs, underwriting, shows, etc.) to their own library (DJs cannot view other libraries)
- Edit metadata, delete, and schedule media in their own library to shows they are assigned to
- Preview uploaded media _without_ affecting the live playout
- Create Playlists, Smart Blocks, and connect Podcasts and Webstreams to LibreTime
- Publish media items to LibreTime's built-in My Podcast function or 3rd party sources such as Soundcloud
* Program Managers
- Everything DJs can do, plus
- Manage other users' libraries in addition to their own
- Create, edit, and delete color-coded shows on the Calender and assign them to DJs (if needed)
- Shows can be scheduled to repeat, with the option of linking content between the shows (helpful if a DJ livestreams in each week)
- View listener statistics
- Export playout logs for analysis or reporting for music royalties
* Administrators
- Everything Program Managers can do, plus
- Manage all user accounts, including the ability to reset passwords
- Configure Track Types for easy sorting of uploaded content
- Change system settings
## 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 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.

109
docs/_docs/vagrant.md Normal file
View file

@ -0,0 +1,109 @@
---
layout: article
title: Using Vagrant and Virtualbox for developing LibreTime
git: vagrant.md
---
> Prerequisites: git, [Vagrant](https://vagrantup.com), libvirt or VirtualBox
## 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.
If you try run a libvirt provided box after using a VirtualBox one, you will receive an
error:
```
Error while activating network:
Call to virNetworkCreate failed: internal error: Network is already in use by interface vboxnet0.
```
This is fixed by stopping virtualbox and re-creating the vagrant box:
```
sudo systemctl stop virtualbox
vagrant destroy ubuntu-xenial
vagrant up ubuntu-xenial --provider=libvirt
```
### Debian and Ubuntu
```bash
sudo apt install vagrant vagrant-libvirt libvirt-daemon-system vagrant-mutate libvirt-dev
sudo usermod -a -G libvirt $USER
# Reboot
vagrant box add bento/ubuntu-16.04 --provider=virtualbox
vagrant mutate bento/ubuntu-16.04 libvirt
vagrant up ubuntu-xenial --provider=libvirt
```
### Other Distributions
You will need to install [libvirt](https://libvirt.org/) and `vagrant-mutate` and then run
```bash
vagrant plugin install vagrant-libvirt
sudo usermod -a -G libvirt $USER
# Reboot
vagrant plugin install vagrant-mutate
vagrant box fetch bento/ubuntu-16.04
vagrant mutate bento/ubuntu-16.04 libvirt
vagrant up ubuntu-xenial --provider=libvirt
```
## 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
`--provider=virtualbox` or `--provider=libvirt` as applicable.
```bash
git clone https://github.com/libretime/libretime.git
cd libretime
vagrant up ubuntu-xenial
```
If everything works out, you will find LibreTime on [port 8080](http://localhost:8080),
icecast on [port 8000](http://localhost:8000) and the docs on
[port 8888](http://localhost:8888).
Once you reach the web setup GUI you can click through it using the default values. To
connect to the vagrant machine you can run `vagrant ssh ubuntu-xenial` in the libretime
directory.
## Alternative OS installations
With the above instructions LibreTime is installed on Ubuntu Xenial Xerus. The Vagrant setup
offers the option to choose a different operation system according to you needs.
| OS | Command | Comment |
| ------ | ------------------- | ------- |
| Debian 10 | `vagrant up debian-buster` | Install on Debian Buster. |
| Debian 9 | `vagrant up debian-stretch` | Install on current Debian Stretch. Needs manual intervention due to Liquidsoap 1.3.3. |
| Ubuntu 18.04 | `vagrant up ubuntu-bionic` | Install on current Ubuntu Bionic Beaver. |
| Ubuntu 16.04 | `vagrant up ubuntu-xenial` | Install on Ubuntu Xenial Xerus. |
| CentOS | `vagrant up centos` | Extremely experimental install on 7.3 with native systemd support and activated SELinux. Needs manual intervention due to Liquidsoap 1.3.3. |
## 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`.