From 0bc403b073086306c979dd70383db1f5b7fa2452 Mon Sep 17 00:00:00 2001 From: Zachary Klosko Date: Mon, 25 May 2020 12:48:55 -0400 Subject: [PATCH] More merging, adjustments for new site --- docs/_data/nav.yml | 54 +++---- docs/api.md | 54 ------- docs/calendar.md | 145 ------------------ docs/dashboard.md | 66 ++++++++- docs/exporting-the-schedule.md | 257 -------------------------------- docs/history.md | 264 ++++++++++++++++++++++++++++++++- docs/host-configuration.md | 79 ++++++++-- docs/live-broadcast.md | 11 +- docs/track-types.md | 5 +- docs/troubleshooting.md | 10 +- 10 files changed, 434 insertions(+), 511 deletions(-) delete mode 100644 docs/api.md delete mode 100644 docs/calendar.md delete mode 100644 docs/exporting-the-schedule.md diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml index 29fd7cfaf..a29fb2390 100644 --- a/docs/_data/nav.yml +++ b/docs/_data/nav.yml @@ -4,7 +4,7 @@ topnav: - page: Features url: features - page: Docs - url: advanced-configuration + url: preparing-the-server - page: Contribute url: contribute - page: Sponsor @@ -13,47 +13,49 @@ topnav: docsnav: - section: Install contents: - - page: Preparing the Server + - page: 0. Preparing the Server url: preparing-the-server - - page: Quick Install + - page: 1. Quick Install url: quickstart - - page: Host Configuration + - page: 2. Host Configuration url: host-configuration - - page: Setting the Server Time + - page: 3. Setting the Server Time url: setting-the-server-time - - page: Configuring Track Types + - page: 4. Configuring Track Types url: track-types - - page: Setting up SSL + - page: 5. Setting up SSL url: ssl-config - page: - section: Using LibreTime contents: - - page: Preparing Media - url: preparing-media - - page: Scheduling Shows - url: scheduling-shows + - page: Broadcasting Live + url: live-broadcast + - page: Dashboard and Calendar + url: dashboard + - page: Help! + url: troubleshooting + - page: Listen To Your Stream + url: listen + - page: Managing Users + url: users - page: Playlists and Smartblocks url: playlists-smartblocks - page: Podcasts and Webstreams url: podcasts-webstreams - - page: Broadcasting Live - url: live-broadcast - - page: LibreTime Settings + - page: Preparing Media + url: preparing-media + - page: Scheduling Shows + url: scheduling-shows + - page: Settings url: settings - - page: Managing Users - url: users - - page: Listen To Your Stream - url: listen - - page: Help! - url: troubleshooting - section: Advanced Configuration contents: + - page: Backing up LibreTime + url: backing-up-the-server + - page: Configuring Streaming Services + url: icecast-shoutcast - page: Interface Customization url: interface-customization - - page: Configuring Streaming Services - url: icecast-shoutcast - - page: Backing up LibreTime - url: backing-up-the-server - page: Upgrading LibreTime url: upgrading - section: Radio Broadcasting 101 @@ -65,9 +67,9 @@ docsnav: contents: - page: HD Audio Modules url: hd-audio-modules + - page: Media Folders used by LibreTime + url: folders - page: Rights and Royalties url: rights-royalties - - page: Media Folders used by LibreTime - url: folders - page: Uninstalling LibreTime url: uninstall \ No newline at end of file diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index c26c76a53..000000000 --- a/docs/api.md +++ /dev/null @@ -1,54 +0,0 @@ -LibreTime API Usage --------------------- - -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", - "]} diff --git a/docs/calendar.md b/docs/calendar.md deleted file mode 100644 index 0461e41e4..000000000 --- a/docs/calendar.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -sidebar: mainmenus ---- - -# 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) - -Adding a show -------------- - -Only *Admins* and *Program Managers* can use this feature. To add a new show to the Calendar, click the **+ New Show** button in the top left corner of the page, or click on any future row or box in the Calendar which is empty. Either of these actions opens the **Add this show** box, which has seven sections, arranged vertically: **What**, **Autoloading Playlist**, **When**, **Live Stream Input**, **Record & Rebroadcast**, **Who**, and **Style**. Click the small orange triangle to the left of the section name if you wish to minimize or maximize it. - -What ----- - -In the **What** box, enter the **Name**, public website **URL**, **Genre** and **Description** for the show that you are creating. - -![](img/Screenshot453-Show_what.png) - -Autoloading Playlist ------------------- - -In this section, you can select a playlist that will be used for this show. The playlist must already be defined in your library. **Auto Schedule Playlist** needs to be checked for **Select Playlist** and **Repeat AutoPlaylist Until Show is Full** to be visible. - -![](img/Screenshot454-Show_playlist.png) - -When ----- - -Next, in the **When** section, if you clicked on a date in the **Calendar** this should already be entered in the **Date/Time Start** field. To set another date for the show, click on the date in the **Date/Time Start** field and select the date that you require from the small pop-up calendar which will appear. Click on the adjacent time field to set the start time for the show, with the pop-up **Hour** and **Minute** box. The Minute values in the pop-up time boxes are rounded to the nearest five minutes. You can also adjust the times manually by clicking into the fields and typing. Repeat the process to set the **Date/Time End** fields. The **Start Time** can be **Now** or **In the Future**. A show that starts now, will start at the time save is pressed, while a future show will start at the time set. The **Duration** of the show will be displayed automatically, based on the start and end times you have set. - -By default, the **Timezone** of the show start and end times will be the timezone of the station, as set on the Preferences page on the System menu. You can specify an alternative time zone using the drop-down menu, if you wish. The time zone displayed in the Calendar when you log in depends on your personal settings. See 'Updating your own account' in the chapter *Users* for more details. - -![](img/Screenshot526-Add_show_when_250.png) - -LibreTime will only allow you to enter valid times for shows. If you attempt to schedule show times which would be impossible, by ending the show before it begins, LibreTime will highlight the error with a pink background. - -![](img/Screenshot527-negative_time250.png) - -To schedule a regular show, check the **Repeats?** box, which will make a new section of the dialog appear. Optionally, click the **Link:** box to automatically schedule the same content in the repeated shows as in the original show. - -![](img/Screenshot528-Link_shows_250.png) - -Then select either **weekly**, **every 2 weeks**, **every 3 weeks**, **every 4 weeks** or **monthly** from the **Repeat Type** drop-down menu. If you have selected a weekly option, check the boxes for the days of the week that you want to schedule the regular show on. If you have selected **monthly**, you have the option to **Repeat By: day of the month** (for example the 9th of each month) or **day of the week** (for example the second Wednesday of each month). - -![](img/Screenshot529-repeat_type_monthly_250.png) - -Uncheck the **No End?** box and set the **Date End** for the regular show to finish, or leave the **No End?** box checked to schedule the show indefinitely. - -![](img/Screenshot530-show_end_date_250.png) - -Live Stream Input ------------------ - -The **Live Stream Input** section can be used to enable live input streams during the show, and also to configure authentication for them. If you check the **Use LibreTime Authentication** box, the DJs (presenters) of the show will be able to connect a live stream to LibreTime's **Show Source Mount Point** using their login name and password. See the chapter *Stream Settings* for details. - -If you check the **Use Custom Authentication** box instead, you can set a one-time username and password pair for live stream input to the show. For example, you may wish to create an authenticated live stream input for a particular remote news reporter, without providing any further access to your LibreTime server for that person. - -![](img/Screenshot457-Live_stream_input.png) - -A reminder of the connection **Host**, **Port** and **Mount** for the live input stream to use is shown at the end of the **Live Stream Input** section. - -Record & Rebroadcast --------------------- - -The **Record & Rebroadcast** section is currently not working, and so has been removed from the web interface. If this feature is important to you, please search for relevant issues in the [LibreTime github repository](https://github.com/LibreTime/libretime/search?q=record&type=Issues) and help us make it happen! - -Who ---- - -In the **Who** section, type the first few letters of the name of the show's DJ (presenter) in the **Search Users** field to select a name from the LibreTime database, or check one of the **DJs** boxes in the vertical list below. This association of a DJ name with a particular show enables that presenter to add playout media to the show, and also to connect a live Show Source input stream (if that has been enabled), so it is important to get the DJ's name right. - -![](img/Screenshot161-Show_users.png) - -Style ------ - -Show colours in the Calendar are set automatically, based on the **Name** of the show, so that individual shows can be easily identified in the **Calendar**. If you wish, you can select a **Background Colour** and **Text Colour** manually by clicking the boxes in the **Style** section. Click the coloured circle icon in the lower right corner to close this pop-up window. - -![](img/Screenshot162-Show_colours.png)  - -Optionally, you can upload a Show Logo by clicking the **Browse** button. - -![](img/Screenshot584-Show_logo.png) - -Finally, click the **Add this show** button at the top or bottom of the box. The new show will now be displayed in the **Calendar**, with a regular slot if you have chosen to schedule one.  - -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. LibreTime will ask you if you are sure about this action, as it cannot be undone. - -![](img/Screenshot357-Cancel_current_show.png) - diff --git a/docs/dashboard.md b/docs/dashboard.md index 6a9576220..a227dff9c 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -1,4 +1,14 @@ -# Dashboard +--- +layout: docs +title: Dashboard and Calendar +--- + +> Quick Links: +- [Dashboard](#dashboard) +- [Calendar](#calendar) + +# Dashboard {#dashboard} + The Dashboard is divided into two sections a Library section divided between [Tracks](../tracks), [Playlists](../playlists), [Smart Blocks](../smartblocks), [Webstreams](../webstreams), and [Podcasts](../podcasts), with the **Scheduled @@ -119,3 +129,57 @@ 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. + +# Calendar {#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. diff --git a/docs/exporting-the-schedule.md b/docs/exporting-the-schedule.md deleted file mode 100644 index 83d5fb110..000000000 --- a/docs/exporting-the-schedule.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -layout: docs ---- - -Exporting the schedule ----------------------- - -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. This information can then be displayed on your broadcast station or affiliate websites by a content management system, such as Sourcefabric's **Newscoop** (). It can be presented using Javascript widgets and styled with CSS, in any format that you require. The **Broadcaster** theme for Newscoop () integrates these widgets with ready-to-use styles. - -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. - -![](img/Screenshot497-System_preferences_240.png) - -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: - - - ServerName schedule.example.com - DocumentRoot /var/www/schedule/ - - -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: - - - -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: - - - -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. \ No newline at end of file diff --git a/docs/history.md b/docs/history.md index d877c9652..690df3fd4 100644 --- a/docs/history.md +++ b/docs/history.md @@ -1,4 +1,13 @@ -# History +--- +layout: docs +title: Playout History +--- + +> Quick Links: +- [Playout History](#history) +- [Exporting the Playout History](#exporting) + +# 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. @@ -38,3 +47,256 @@ Either of these actions opens a page in which you can name the new template, and 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. This information can then be displayed on your broadcast station or affiliate websites by a content management system, such as Sourcefabric's **Newscoop** (). It can be presented using Javascript widgets and styled with CSS, in any format that you require. The **Broadcaster** theme for Newscoop () integrates these widgets with ready-to-use styles. + +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. + +![](img/Screenshot497-System_preferences_240.png) + +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: + + + ServerName schedule.example.com + DocumentRoot /var/www/schedule/ + + +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: + + + +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: + + + +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. diff --git a/docs/host-configuration.md b/docs/host-configuration.md index 083b86482..7390ed3d6 100644 --- a/docs/host-configuration.md +++ b/docs/host-configuration.md @@ -1,14 +1,19 @@ --- layout: docs +title: Host configuration +blurb: After installation, follow these instructions to set up your LibreTime server or VM --- -Host configuration ------------------- +> Quick Links: +- [Database and RabbitMQ Hosts](#database) +- [Changing the default PostgreSQL passwords](#postgre) +- [API Client Configuration](#api) +- [Apache max file size configuration](#apache) +- [Playout and recorder settings](#playout) 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 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: @@ -57,8 +62,7 @@ used by the various components of LibreTime, run the following commands sudo systemctl restart libretime-celery sudo systemctl restart libretime-analyzer -Changing the default PostgreSQL passwords ----------------------------------------- +# 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. @@ -72,8 +76,61 @@ 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. -API client configuration ------------------------- +# 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. + +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", + "]} +``` 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.** @@ -84,8 +141,7 @@ If you have changed the *base\_url*, *base\_port* or *base\_dir* setting in */et base_port = 80 base_dir = / -Apache max file size configuration ----------------------------------- +# 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: @@ -100,8 +156,7 @@ 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 and recorder settings ------------------------------ +# Playout and recorder settings {#playout} Settings for pypo, the playout and recording 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: diff --git a/docs/live-broadcast.md b/docs/live-broadcast.md index 4e98026df..388bb2f62 100644 --- a/docs/live-broadcast.md +++ b/docs/live-broadcast.md @@ -1,16 +1,18 @@ --- layout: docs +title: Broadcasting live with MIXXX or B.U.T.T. --- -# Broadcasting live with MIXXX or B.U.T.T. +> Quick Links: +- [MIXXX](#mixxx) +- [BUTT](#butt) [![How to Livestream Your Show](http://img.youtube.com/vi/4GLsU9hPTtM/0.jpg)](https://www.youtube-nocookie.com/embed/4GLsU9hPTtM "How to Livestream Your Show") This how to is intended for DJs using BUTT or MIXXX to stream to their LibreTime server with an external USB audio card setup to route a mixer and sound. -Live shows with MIXXX ---------------------- +# Live shows with MIXXX {#mixxx} Mixxx is a cross-platform Open Source application for DJs, available [here](https://www.mixxx.org). @@ -35,8 +37,7 @@ For **Host**, **Mount**, **Port**, **Login** and **Password**, use the **Input S 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) ------------------------------------------------------- +# Live shows with B.U.T.T. (Broadcast Using This Tool) {#butt} ## Set Up diff --git a/docs/track-types.md b/docs/track-types.md index ff63aa850..921ec19b5 100644 --- a/docs/track-types.md +++ b/docs/track-types.md @@ -1,11 +1,8 @@ --- layout: docs +title: Working with Track Types --- -Working with track types ------------------------- - -**Audience**: Adminstrators ## Using track types when uploading tracks diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6f9a799d9..9eb390dee 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,12 +1,10 @@ --- -sidebar: main +layout: docs +title: Troubleshooting +blurb: Having trouble with your LibreTime installation? We've got you covered! --- -# Troubleshooting - -Having trouble with your LibreTime installation? We've got you covered! - -Since LibreTime is effectively a web site running on a LAPP stack, individual components of the system can be started, stopped, restarted or checked in the server console using the **systemctl** command: +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