ardj(1)

NAME
ardj - an internet radio playlist manager

SYNOPSIS
ardj
[command] [arguments...]

DESCRIPTION
ardj is a collection of tools that can be used to run a full featured fully automated internet radio station. It is designed to stay alive even when there's nobody looking for it from the administrative point of view: bad music will go away, fresh music will be found, as long as listeners care.

ardj uses an SQLite database to store the runtime data, a tiny web server to access it, an XMPP (Jabber) bot for runtime management and to interact with the audience, and a plugin which feeds ezstream. The web server which is used as the database interface is built on web.py and requires zero configuration; it's main purpose is to prevent deadlocking the SQLite database by synchronizing multiple processes accessing it.

Buzzword bingo: streaming, MP3, SQLite, Jabber, robotics, Last.fm, Libre.fm, scrobbling, jingles, prerolls.

This document is a work in progress. The complete documentation is available on the website.

SETTING UP A STATION
To run a streaming radio station you will need the following components: icecast2, ices and ardj.

Icecast2 is the multiplexor, it has little brain. Its main job is to receive a stream from a source (ices) and retransmits it to as many listening clients as there are. It's like a proxy for multimedia streams. It is a separate product and has nothing to do with ardj.

Ices is the stream source. It reads file names from a playlist, loads and decodes the files, cross-fades them nicely, encodes the result to the configured format (typically MP3) and sends the result to icecast. This is also an independent component that has little to do with ardj. It only uses the playlist plugin which ardj provides to read file names from the database instead of flat files.

ardj is the virtual brain of your radio station. It maintains playlists, picks the music and jingles, collects feedback from the audience, adjusts track priorities and so on.

MAIN CONCEPTS
This is a sort of glossary.

Jingles
    TODO

Rotation priority
    There are two track weights: the real one and the running one.

User karma
    TODO

Failure mode
    TODO

COMMAND LINE OPTIONS
The first parameter to ardj is the command. Some commands require additional arguments, they are described below.

\FCadd-incoming-tracks\F[]
    Looks for audio files in the \FCincoming_path\F[] folder. What's found is moved to the database, source files are deleted. If the source can't be deleted, it's ignored (to prevent adding it multiple times). Only files with extensions \FC.mp3\F[] and \FC.ogg\F[] are added, other files are ignored. When the files are imported, artist names and track titles are read from the metadata, other common tags are ignored. One uncommon tag which is used is \FCardj\F[]: with it you can preset track labels. Example format: "ardj=1;labels=music,rock" (this is the value, including the "ardj=1" prefix, which designates metadata format). This is similar to the jabber command upload.

\FCconfig\F[]
    Opens the configuration file for editing with your default editor. The editor name is read from the \FCEDITOR\F[] environment variable. If there's nothing, the editor command is used.

\FCconsole\F[] [jid]
    Opens a console which emulates a jabber connection. You can send jabber commands to the bot, except that you're not using Jabber or a network connection at all. This is useful for debugging, e.g. when a user says that some command he sends doesn't work as expected.

\FCdb-console\F[]
    Opens the database console. This is useful if you need to perform some low-level operations and don't want to type the full database path. This command only works if you have sqlite3 installed.

\FCdb-init\F[]
    Initializes the database structure by creating tables and indexes which are missing. This command is normally used by the installation script only. You might only need to use it if you deleted the database file and want to create a new one from scratch.

\FCdb-purge\F[]
    Removes dead data from the database. Dead data is labels that are no longer used and files which correspond to deleted tracks.

\FCdb-stats\F[]
    Shows brief database statistics, e.g.: "2883 tracks, 192.0 hours".

\FCdownload-artist\F[] artist_name
    Schedules retrieving more tracks by the specified artist. This only adds a request to the database, without immediately downloading anything. This is similar to the jabber command download.

\FCfind-new-tracks\F[]
    Starts searching for new music. It first selects artists that have tracks rated above average, then looks for their music on Last.fm and Jamendo. Tracks which can be downloaded and which aren't in the database are downloaded and added to it.

\FCfix-artist-names\F[]
    Looks up all artists in the Last.fm database and corrects their names when necessary. This usually implies case correction, but can sometime change the name completely (which is still correct unless Last.fm fails drasticly). You typically run this command on a nightly basis.

\FChelp\F[]
    Shows a help screen similar to this manual.

\FCmark-hitlist\F[]
    Marks approximately 10 best tracks which have the "music" label with the "hitlist" label. The number of tracks can be higher than 10 if there are many tracks with weight equal to track number 10 (i.e. they all share 10th place)..

\FCmark-liked-by\F[] label jid1 jid2 ...
    Applies label "label" to tracks that are liked by all specified users. One typical use is when you have an upcoming live show with multiple hosts and you want to play music that they all like, to adjust the mood of the audience.

\FCmark-long\F[]
    Marks tracks longer than average with the "long" label. You can use it to remove those tracks from daily rotation or something like that.

\FCmark-orphans\F[]
    Marks tracks that don't belong to a playlist with the "orphan" label. This can help you find blind spots in your playlists. If you want to prevent some special tracks (with special labels) from being marked as orphans, just create a playlist for them (the one below the default playlist, which will actually never be used).

\FCmerge-votes\F[]
    Merge votes from aliases defined in the \FCjabber_aliases\F[] config parameter. This command should be used after you edit the list of aliases.

\FCqueue-flush\F[]
    Delete everything from the manual playlist (see the queue jabber command).

\FCscan-replaygain\F[] [files...]
    Calculates ReplayGain for files that don't have it. If \FCfiles\F[] not specified, checks all tracks.

\FCserve\F[]
    Starts the Web API server, which typically listens to localhost:8080. This server is used by the ices plugin to get names of files to play and by the jabber bot to perform some actions. Normally you don't start the server manually, unless you want to debug it; normally it's started by the ardj-server upstart job, e.g.: sudo start ardj-server.

\FCtags\F[] files...
    Reads and displays tags from the specified files. This is primarily needed for testing whether ardj sees tags from certain files or not (OGG/Vorbis should cause no problems, but MP3 might). Tag reading only works if you have a recent version of python-mutagen installed.

\FCtwit\F[] message
    Send the specified message to Twitter. Only works if you have the \FCtwitter\F[] config file parameter set up properly, otherwise it'll tell you how to do that.

\FCtwit-replies\F[]
    Shows recent messages which mention your Twitter account. Not really useful.

\FCupdate-schedule\F[]
    Looks up Last.fm for upcoming concerts by artists which have tracks rated above average. Saves the data to a JavaScript file named in the \FCevent_schedule_path\F[], which can be used to display a Google map on your web site. Also, all tracks by artists which have upcoming concerts are marked with the "upcoming-concert" label, so that you could add some prerolls or change the rotation priority. Only works if you configured the Last.fm integration properly.

\FCupdate-track-lengths\F[]
    Updates track lengths stored in the database with real values from the files. This is useful if you change files in the \FCmusicdir\F[] folder manually, or if you had a failure and resorted to backups.

\FCupdate-track-weights\F[]
    Updates real track weights according to user votes.

\FCxmpp-send\F[] message_text [jid]
    Sends the specified message to the specified recipient. If the recipient jid was not specified, the message is sent to the chat room (named in the \FCjabber_chat_room\F[] configuration parameter).

JABBER COMMANDS FOR REGULAR USERS
These commands must be sent to the jabber bot directly. If sent as private messages in the chat room, the bot will complain and tell the user how to communicate properly.

To disable any of these command for regular users, use the \FCpublic_jabber_commands\F[] config file parameter.

bm  Adds the currently played track to your bookmarks. The bookmarks are searchable using the find -b command.

download artist_name
    Looks for tracks by the specified artist on Last.fm and Jamendo. This command is for discovering new artists; if there are tracks by this artist already, nothing will be downloaded.

dump track_id
    Displays raw information about the specified track (JSON encoded). This command can be used for debugging purposes or if you write an application which interacts with the station using the XMPP protocol.

echo text
    Sends the specified text back to you. This command can be used for debugging your connection with the bot.

find [flags] [pattern] [labels]
    Displays tracks that have the substring \FCpattern\F[] in their title or in the artist name. You can restrict the results by adding labels which the tracks must have, e.g.: find gorky @heavy. The tracks are sorted by weight: best come first. The flag parameter is a combination of command-line-like switches. The \FC-l\F[] flag changes the order to the upload date, i.e. fresh tracks come first. The \FC-f\F[] flag changes the order to the upload date reversed, i.e. oldest come first. The \FC-r\F[] flag sorts tracks in random order. With the \FC-b\F[] flag only bookmarked tracks will be listed.

hitlist
    Lists 10 best tracks.

last
    Displays basic information about 10 most recently played tracks.

news
    Lists10 most recently added tracks.

rocks [track_id]
    This is how you vote for the specified track (the current one if \FCtrack_id\F[] not given). When you vote, the track's running weight is increased by 0.25, but the real weight is only changed the first time you vote.

shitlist
    Lists 10 worst tracks.

show [track_id]
    Displays information about a track (the current one if \FCtrack_id\F[] wasn't given). This is a human readable version of the dump command.

speak text
    Renders the specified text using festival and schedules it for playing after the current track finishes. The speech will only be played once, however, you can queue it again later.

status
    Displays basic information about the currently played track. This is exactly the same text that the bot has in its status line.

sucks [track_id]
    This is how you vote against the specified track (the current one if \FCtrack_id\F[] not given). When you vote, the track's running weight is decreased by 0.25, but the real weight is only changed the first time you vote.

tags [modification [for track_id]]
    If sent without arguments, shows a tag cloud. If the \FCmodification\F[] argument was given, it is treated as a list of labels to add or remove to the specified track, e.g.: tags rock -pop. The \FCmodification\F[] argument is only available to privileged users (i.e. admins).

queue
    Adds a track to the manual playlist, which have the highest priority.

JABBER COMMANDS FOR ADMINS
These commands require special privileges, see the \FCjabber_admins\F[] config parameter.

ban artist_name
    Deletes all tracks by the specified artist (sets their weight to zero).

delete track_id
    Deletes the specified track (sts it weight to zero).

merge dst_id src_id
    Merges two tracks together. The second track is deleted, it's labels and votes are added to the first track. This is the way you deal with duplicates.

play labels...
    Creates a virtual ad-hoc playlist for next hour. The playlist has lower priority than the queue jabber command, but higher than all configured playlists. You can use multiple labels, e.g.: play rock +instrumental -loud.

purge
    Cleans up the database and file system. Does exactly what the ardj db-purge command-line command does.

reload
    Tells the ices plugin to reload the configuration. This does not really work because ices can't really reload Python modules, which ardj uses, and because the real work is done by the web service, which reloads the configuration automatically.

restart
    Terminates the jabber bot. It will be restarted immediately by the upstart job. The rough command-line equivalent is sudo restart ardj-jabber. You should only need to do this after you modify the jabber bot source code manually or by upgrading the installed package.

say message
    Sends the specified message to the chat room (named in the \FCjabber_chat_room\F[] config parameter) from the bot's name. Typically used for fun.

set property to value [for track_id]
    This is how you modify track properties (which can be either "artist" or "title").

skip
    Tells ices to skip the current track. This is done by sending it the USR1 signal.

sql query
    Lets you perform low-level database queries. Use with caution.

twit message
    Sends the specified message to Twitter. Works exactly like the twit command-line action. Only works if you have properly configured the \FCtwitter\F[] config file parameter.

voters
    Shows voting statistics, which includes jids of active users and their karma.

votes
    Shows you who and how voted for the currently played track.

CONFIGURATION
There is one configuration wile which contains all settings. This file is named \FC/etc/ardj.yaml\F[], if you're installing system wide, or \FC$HOME/.config/ardj/ardj.yaml\F[] if you're testing locally.

\FCdatabase_path\F[]
    This names the SQLite database file. This option has no default, but the installer sets it to \FC/var/lib/ardj/database.sqlite\F[].

\FCdupes\F[]
    This parameter defines how many recently played artists will be ignored when picking the next track. This is good for ensuring that the same artist isn't played too often even if he has amazingly well rated tracks. Set this to a value higher than 0 only after you upload a significant amount of music, because if there's not enough artists, your stream will go into the failure mode. Defaults to 5.

\FCevent_schedule_label_filter\F[]
    Here you can specify the label which tracks must have to feed the schedule updater. The logic is simple: first tracks with this label are picked, from those only tracks with weight above 1.0 are picked (i.e., well rated), and that's the source of artist names. Defaults to nothing, all tracks are used.

\FCevent_schedule_path\F[]
    Here you name a file where the information on upcoming concerts will be saved (see the ardj update-schedule command). If not set, the function won't work.

\FCevent_schedule_weight\F[]
    Here you can set a custom weight requirement for tracks that feed the schedule updater. If you set this to a value that roughly equals to your 10th top track weight, then the schedule will only feature artists from your station's hitlist. Defaults to 1.0, e.g. tracks that don't suck.

\FCincoming_path\F[]
    This parameter defines the folder where you should put music that you want to add to the database. This folder is typicalliy made available over ftp or sftp. After copying files to this folder, send the upload command to the jabber bot. When files are added to the database, only two common tags are read and used: "artist" and "title". One uncommon tag is "ardj", with which you can preset internal metadata, such as labels. Syntax example: "ardj=1;labels=music,rock" (normally you only set the labels this way, other options are currently ignored). Default location is \FC/var/lib/ardj/incoming\F[].

\FCincoming_labels\F[]
    With this parameter you can set default labels for new files. This typically has labels which will later help you find unsorted music and label it properly. If you have a playlist for incoming unsorted music, you can also specify it here.

\FCjabber_id\F[]
    This option defines the bot's JID and password in the "user:password@server" form. If you don't define this parameter, the jabber bot won't start. Look in the log file for authentication error messages.

\FCjabber_admins\F[]
    This parameter names privileged users. This is a list of jids, i.e. it must be either one line of comma-separated values in square brackets (e.g., "[one, two]"), or one item per line, prefixed with a dash sign. Look in the \FCshare/doc/ardj/examples\F[] folder for an example.

\FClog\F[]
    This names the log file. Defaults to \FC/var/log/ardj.log\F[].

\FCmusicdir\F[]
    This option defines the folder where the music will be stored. Files in this folder have scrambled names, related to the file contents' MD5 checksum, e.g. \FC2/4/24a141bfaaae48969901a9ab1206dc76.mp3\F[]. This is not a publicly accessible folder, you should not try to do anything with the files in it. To add new music, add it to the folder specified with the \FCincoming_path\F[] parameter. This is also where the \FCplaylists.yaml\F[] file is looked for. Default location is \FC/var/lib/ardj/music\F[].

\FCtwitter\F[]
    Having this block enables integration with Twitter. The block must contain values with keys \FCconsumer_key\F[], \FCconsumer_secret\F[], \FCaccess_token_key\F[] and \FCaccess_token_secret\F[]. To get these values, go to the dev.twitter.com/apps website and register yourself an application.

\FCuse_jabber_status\F[]
    Set this to "yes" to add track info to the bot's status line.

\FCuse_jabber_tunes\F[]
    This enables sending track info using the XMPP Tunes extension (doesn't work with Gmail servers).

\FCwebapi_socket\F[]
    This names the socket at which the Web API server is expected to be. Defaults to "127.0.0.1:8080".

FILES

\FC/etc/ardj.yaml\F[]
    This is the default location of the configuration file.

\FC$HOME/.config/ardj/ardj.yaml\F[]
    This is the location of the user's local configuration file. If it exists, the system wide configuration file is ignored. Having a local configuration file is good for testing purposes, but on a production system you should stick to the global one.

\FC/var/lib/ardj/database.sqlite\F[]
    This is the default location of the database. It can be changed using the \FCdatabase\F[] configuration file parameter.

\FC/var/lib/ardj/music\F[]
    This is the default location of the music library. It can be changed using the \FCmusicdir\F[] configuration file parameter.

\FC/var/lig/ardj/music/playlists.yaml\F[]
    The default playlist description. Is always bound to the \FCmusicdir\F[] folder.

\FC/var/lib/ardj/incoming\F[]
    This is the default location of the folder where you should put files to add them to the media database (using the ardj add-incoming-files command). You can change it using the \FCincoming_path\F[] configuration file parameter.

\FC/var/log/ardj.log\F[]
    This is the default location of the log files. It can be changed using the \FClog\F[] configuration file parameter. The file is rotated after it grows over 1MB; 10 files are kept.

\FC/etc/init/ardj-*.conf\F[]
    These are the upstart jobs that start the jabber bot (\FCardj-jabber.conf\F[]), the Web API server (\FCardj-server.conf\F[]) and the source client (\FCardj-ices.conf\F[])

\FC/usr/share/ardj/failure/\F[]
    This folder contains OGG/Vorbis files which should be played when the Web API server fails. The files are picked in random order. This is typically something with neutral mood and with a short voice message for the admins to go look in the log file.

AUTHOR
Justin Forest <\FChex@umonkey.net\F[]>