Nullsoft SHOUTcast Transcoder Version 2 (sc_trans) Calendar Event XML File Specification (Last Updated 07 July 2011) 1.0 Introduction 2.0 File Layout 2.1 Calendar Tag 2.1.1 Time Periodic Events 3.0 Supported Events 3.1 DJ Events 3.2 Playlist Events 3.3 Relay Events 1.0 Introduction ------------------ The purpose of the calendar.xml file is to allow for the scheduling of events in your sc_trans instance such as for specifying a time when a DJ is able to join or when a specific playlist will be used. An important thing to note is that sc_trans will only read the settings from your calendar xml file when it is loaded. So if you do change anything in the file externally whilst sc_trans is running then you will need to restart your sc_trans instance for the new values to be read in. If you use the AJAX api (see sc_trans_ajax_api.txt and Sections 2.14 to 2.16) then you can make changes to the calendar file whilst sc_trans is running but you will need to make sure to have 'calendarrewrite=1' in your sc_trans configuration file so that any live changes made will be saved back into your calender file. 2.0 File Layout ----------------- The following xml file shows the general layout of a calendar.xml file and the options which are available for it for a single entry. The file does allow you to specify more than one event by adding in more ... blocks. playlistname djname 2.1 Calendar Tag ------------------ The tag contains date information about scheduled events and it can contain the following attributes allowing for finer control over the event: startdate (specified as yyyy/mm/dd) enddate (specified as yyyy/mm/dd) starttime (specified as hh:mm:ss - 24 hour format) duration (specified as hh:mm:ss - 24 hour format) timeoffset (specified as hh:mm:ss - 24 hour format) repeat (numeric value) The 'startdate' and 'enddate' attributes indicate the date range the event is valid for otherwise the event will be ignored. Either value can be left out and if so then the event will be unbounded in that direction i.e. specifying no 'startdate' is the way to indicate the event takes effect when sc_trans starts. The 'starttime' and 'endtime' attributes work in a similar manner to the date ones for the event but are used when the associated 'startdate' is met. So if no 'starttime' is indicated then the event starts immediately on 'startdate'. So as you can see this could be left out along with 'startdate' to make events start always when sc_trans is started. The 'duration' attribute is the length of the scheduled event and if this is not specified then the event will end when 'enddate' (if specified) is reached. The 'repeat' attribute is a numeric code for an event which gives control over how an event will be repeated. The repeat attribute can be one of the following as listed below or a combination to create more complicated repeat patterns e.g. '62' will make an event repeat every day of the week (i.e. 2 + 4 + 8 + 16 + 32) 1 - Every Sunday 2 - Every Monday 4 - Every Tuesday 8 - Every Wednesday 16 - Every Thursday 32 - Every Friday 64 - Every Saturday 128 - Time periodic 2.1.1 Time Periodic Events ---------------------------- Time periodic events are those which occur at regular intervals and are defined by the 'starttime', 'timeoffset' and 'repeat' attributes allowing for control over the time interval between the event and the next instance of the event. The 'starttime' attribute is used to indicate the interval between this type of event and the next time it will occur. So with a number of these events you can have a jingle play at a specific time during the day at a consistent time. The 'timeoffset' atribute is used to indicate an offset from midnight at which the periodic event will be applied relative to the 'starttime' value. This will allow you to specify a specific time during the interval so if you wanted to have an event which is activated every hour but on the half hour you could do: timeoffset="00:30:00" starttime="01:00:00" If no other repeat field values are specified i.e. repeat isn't 128 then the event will be valid for every day of the week. If other values are specified then the event will be restricted to those days specified e.g. repeat=190 repeats the event only during weekdays Important Note: If you use this on a playlist event then the event will be activated at the specified time period after the last event successfully occurred but the required file(s) will not be played until the currently playing file has completed playing as playlist events add to the main playback queue and do not act as an instant event as the relay and DJ events do. 3.0 Supported Events ---------------------- As shown in the previous section, there are 3 types of events supported by the file format which are: DJ Playlist Relay The following sections will detail the options available with each event type. 3.1 DJ Events --------------- The purpose of a DJ event is to control the access a DJ has to the instance of sc_trans for the duration of the specified event. This makes it simple to setup scheduling of access of different DJs at different times of the day or week. This is enabled in combination with the settings in the sc_trans configuration file for controlling DJ access. So for this to work you will also need to make sure you enable 'djport / djport2' (depending on you using SHOUTcast 1 or SHOUTcast 2 features) and to set any passwords and names in the sc_trans config file to match the event. See sc_trans.txt - section 3.0.3 for more information setting up DJ support. The parameters supported for this event type are: archive : Specify if the DJ show will be archived (sc_trans does this normally) 1 - Yes 0 - No inherit - Use value set for 'djcapture' in the configuration file. e.g. This would enable archiving of the show made by the DJ identified as 'Bob' Bob 3.2 Playlist Events --------------------- This allows you to schedule playlists to be used at the specified time or date thus making it easier to change to a weekend or an evening playlist if needed. The playlists are those defined by the playlistfilename and playlistfilepath entries in you sc_trans configuration file which allows for multiple playlists to be accessed by this event type. The event uses the symbolic name of the playlist (set with playlistfilename_X i.e. the name you've given to the playlist, not the actual playlist filename). So if you had 3 playlists and wanted to use the second one then you would set things up as follows (playlistfilepath also needs to be set but is not shown): In the sc_trans configuration file: playlistfilename_1=morning playlistfilename_2=daytime playlistfilename_3=evening In the calendar xml file: daytime The parameters supported for this event type are: loopatend : Specify if the playlist will restart if the end of the playlist is reached before the duration of the event is completely fulfilled. 1 - Yes 0 - No (Default) shuffle : Specify if the playlist should be shuffled when being played. 1 - Yes 0 - No inherit - Use value set for 'shuffle' in the configuration file. priority : Specify the priority of the playlist when a playlist event overlaps with that of another playlist event. The result in this case is that the playlist event with the highest priority will become active. Note: Supported priority values are 1 (default) and higher. e.g. This would specify the playlist known as 'evening' to loop if needed and to not be shuffled when played evening Important Note: Playlist events are queued up instead of being activated immediately so if you have a 'jingle' playlist then this would not be played until the currently playing file has completed playing and has not been pushed down the queue by a higher priority playlist event. This is something you need to take into account if you want to have a jingle play every 10 minutes but none of the files have a roughly standard duration. 3.3 Relay Events ------------------ This allows you to make use of the relaying support within sc_trans and so when used in the event system will allow you to control when a relay is allowed to connect to you sc_trans instance (much like the DJ support mentioned earlier). The parameters supported for this event type are: url : Specify the url of the source to be relayed. priority : Specify the priority of the source when a relay event overlaps with that of another relay event. The result in this case is that the relay event with the highest priority will become active. Note: Supported priority values are 1 (default) and higher. e.g. This would enable the relaying of the stream on 'my_site' on port 9000 Note: It may be necessary to append /; onto the end of the url as in some cases the wrong mime type will be returned from the server and so causes the relay url fail to be recognised by sc_trans. This depends on the server.