mAirList Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Text Playlist Import Format Specification ======

This document contains the specification of the "Text Playlist Import" (TPI) format introduced in mAirList 5.0.3.

The purpose of this format is to import playlists from 3rd party music scheduling systems.

TPI is a text/CSV based format that contains the IDs or filenames of the items to import, plus optional control information.
===== General =====

==== File Format ====

  * TPI file files are plain text, with either <CR><LF> or <LF> line endings.
  * Columns can be delimited by comma or tab. If a line contains a tab character, tab-delimited is assumed, else comma-delimited.
  * Text encoding is always UTF-8.
==== File Name Conventions ====

  * File extension should be ''.txt''.
  * In situations where it is important to tell the files apart from other text files, the file extension ''.tpi'' can be used instead.
  * For automatic import in the Mini Scheduler, either **hourly** playlists (one file per hour) or **daily** playlists (one file per day) can be used.
  * For hourly playlists, the file name must be one of the following:
    * ''yyyy-mm-dd-hh.txt'' 
    * ''yyyymmddhh.txt''
    * ''yy-mm-dd-hh.txt''
    * ''yymmddhh.txt''
  * For daily playlists, the file name must be one of the following:
    * ''yyyy-mm-dd.txt''
    * ''yyyymmdd.txt''
    * ''yy-mm-dd.txt''
    * ''yymmdd.txt''

===== Column Layout =====

Each line contains four or more tab-separated columns:

^ Column # ^ Field ^
| 1 | Start Time |
| 2 | Timing |
| 3 | Line Type |
| 4 | Line Data | 
| 5..x | Optional columns, depending on line type |
==== Start Time ====

  * Start time is given in ''hh:mm:ss'' or ''hh:mm'' format.
  * Start time can be left empty if unknown or irrelevant for that particular line.
  * When using hourly playlists, the Mini Scheduler uses the hour part of the start time in order to identify the hour boundaries, so it is mandatory to specify a start time for at least the first item of each hour.
  * The minute/second part is generally ignored, except when fixed times are used (see below).
  * The minute/second part can exceed 60 minutes in this case. (Some schedulers give start times for overflow music as e.g. ''12:67:23''.)

==== Timing ====

The Timing column can contain one of the following values which correspond to the respective Timing settings in mAirList:

^ Value ^ Description ^
| N | Normal |
| H | Hard fixed time |
| S | Soft fixed time | 
| B | Backtimed | 
| E | Excluded from backtiming |

The Timing column can be left empty, in which case Normal timing is assumed, or the default value from the item metadata is used.

For Hard and Soft timing, a valid Start Time must be given in column 1. 

==== Line Type ====

The third column specified the type of the respective line. Currently, the folllowing types are defined:

^ Type ^ Name ^ Description ^
| B | Block | Indicates the start of the next music block | 
| D | Dummy | A dummy/note item | 
| E | External ID | An item from the database library, identified by its External ID | 
| F | File | An audio file, identified by its filename |
| I | ID | An item from the database library, identified by its ID | 
| O | Options | Options for file import |
| R | Remark | Silently ignored during import |

===== Line Definitions =====

Below it the description of all supported Line Types (column 3) and the corresponding Line Data (column 4).

==== B: Block ====

Used to indicate the boundary of a (music or advertising) block. In column 4, the number of the block starting here is given. Column 4 can be left empty, in which case the number of the previous block + 1 is assumed. Timing is ignored and can be left empty. If the file contains no B lines at all, block 1 is assumed for all content.

Example:

  12:00:00                B       2
  
Indicates the start of music/advertising block #2.


==== D: Dummy ====

Adds a new Dummy item to the output playlist. In column 4, specify the title of the new item.

Example:

  12:00:00        H       D       Start of Hour
  
Adds a new dummy with title '''Start of Hour''' and a Hard fixed time of 12:00:00.
  
==== E: External ID ====

Adds the item with the specified **External** ID from the database. 
Example:

  12:00:00        N       E       100810-01
  
Adds the item with the External ID 100810-01, with Normal timing.
  
==== F: File ====

Adds an audio file to the playlist. In column 4, specify the file name of the audio file; if no full path is give, the file name is assumed to be relative to the playlist file. Metadata will be fetched from the database, MMD files, or file tags automatically, whatever is available.

Example:

  12:00:00        N       F       C:\news.mp3
  
Adds the file ''C:\news.mp3'', with Normal timing.
 
Additional columns can be used to set fields on the imported file:

^ Column ^ Field ^
| 5 | Title |
| 6 | Artist |
| 7 | Item Type |
==== I: ID ====

Adds the item with the specified (internal) ID from the database.

Example:

  12:00:00        N       I       120577
  
Adds the item with the ID 120577, with Normal timing.
  
  
==== O: Options ====

Specifies the options for the processing of all subsequent F lines. Start time and timing is ignored. Column 4 and 5 contain the name and value of the option. Currently the following options are available:

^ Name ^ Description ^
| ItemType | Override playlist item type, e.g. ''News'' or ''Advertising''. Default is ''Unknown'' which means no overriding. |
| ImportTasks | Tasks to perform during file import. Comma separated list of one or more of the following values: ''MDD, Tags, NativeTags, Duration, Tilde, AutoCue, Normalize, DatabaseLookup, UnpackPlaylists''. Use ''*'' for all tasks, which is also the default. |
==== R: Remark ====

Lines of type R are silently ignored during import. R lines can be used to add comments to TPI file, to make it more readable by humans.