This updates only Documentation and log messages.
Features
========
-configurable audio streaming software
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+configurable audio streaming software:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
para_server streams binary audio data (mp3/ogg files) over
local or remote networks. It contains two built-in streamers:
the http streamer and the ortp streamer.
configurable audio file selectors:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- There are three audio file selectors (aka "database tools")
- available:
+ There are three audio file selectors available:
- random
- plm (playlist manager)
to retrieve the list of available commands and some server info.
-Choose your database tool (dbtool)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You have two options:
+Choose an audio file selector
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+paraslash has three different audio file selectors: random (default),
+plm (the playlist manager) and mysql.
- 1. Use the mysql dbtool which comes with paraslash and requires
- mysql.
+ The random selector chooses files randomly from the given
+ directory.
- 2. If you can not use the mysql dbtool and you just want
- to quickly make paraslash working, use the random dbtool.
- The directory which is searched for audio files can be given
- via the server option --random_dbtool_dir.
+ The playlist selector allows to send a playlist to para_server
+ via the lpl (load playlist) command. para_server will choose
+ files from the loaded playlist in sequential order.
- Note, however, that this database tool is really dopey. It
- scans the given directory on every audio file change and
- chooses one randomly. There is no further functionality.
+ The mysql selector stores information about your audio
+ files in a mysql database. It is much more involved than
+ the other two selectors and lets you chose files in many
+ interesting ways. If you like to use the mysql selector,
+ read README.mysql and follow the instructions given there.
+ Return to this document when ready.
-The current database tool can be changed at runtime via
+The current audio file selector can be changed at runtime via
- para_client cdt new_dbtool
+ para_client cdt new_selector
-If you have choosen 1. above, read README.mysql and follow the
-instructions given there. Return to this document when ready.
Start streaming manually
o the new ipc subsystem
- o new database tool: plm, the playlist manager
+ o new audio file selector: plm, the playlist manager
- o para_server: the dopey file selector is now called "random",
- and it is selected by default. Use the --selector option to
- choose another selector at startup, or the cdt command to switch
- between the supported selectors.
+ o para_server: the dopey selector is now called "random",
+ and is the default selector. Use the --selector option to
+ choose another selector at startup, or the cdt command to
+ switch between the supported selectors.
o X86_64 fixes (thanks to Steffen Klassert)
All senders have the same set of commands that allow to
control the access permissions of the stream.
- para_server needs a "database tool" to work, mainly to
- determine which song to stream next. There are three such
- tools available: random, plm and mysql. The former chooses
- audio files randomly and plm, the playlist manager, can handle
+ para_server needs an "audio file selector" to work, mainly to
+ determine which song to stream next. There are three selectors
+ available: random, plm and mysql. The former chooses audio
+ files randomly and plm, the playlist manager, can handle
playlists. Both are always supported.
- The (optional) mysql database tool connects to a mysql server
+ The (optional) mysql selector connects to a mysql server
which holds information on your audio files. It has several
unusual features, see README.mysql for details.
LIMITATIONS:
~~~~~~~~~~~~
-The mysql database tool assumes that the basenames of your audio files
-are unique. If this is not the case, don't use this database tool,
-rename your files, or create your own database tool.
+The mysql selector assumes that the basenames of your audio files are
+unique. If this is not the case, don't use this selector, rename your
+files, or create your own one.
THE AUTHOR:
~~~~~~~~~~~
README.mysql
============
-This file describes how to use the mysql database tool which comes
-with the paraslash package.
+This file describes how to use the mysql audio file selector which
+comes with the paraslash package.
It assumes you have already installed mysql and paraslash as described
in INSTALL, so read README and INSTALL before proceeding.
Or, restart the server.
-Switch to the mysql dbtool
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Switch to the mysql audio file selector
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Actually, the mysql database tool should already be selected (just
-ignore the warning about the missing database). To verify that it is
-indeed activated, type
+The command
para_client cdt
-which prints the name of the current database tool. If the mysql
-dbtool is not selected, try
+prints the name of the current selector. Try
para_client cdt mysql
-If this doesn't work either, it means that some required config options
-were not specified (check the log for more info) or that para_server
-was built without mysql support. Type
+to switch to the mysql selector. If this doesn't work, it means that
+some required config options were not specified (check the log for
+more info) or that para_server was built without mysql support. Type
para_client si
-to find out. If mysql is not mentioned as a supported database tool,
+to find out. If mysql is not mentioned as a supported selector,
you'll have to recompile.
Create a new database
~~~~~~~~~~~~~~~~~~~~~
-Once the mysql database tool is selected, create the database:
+Once the mysql selector is activated, create the database:
para_client cdb
para_client cdt mysql
-The second command forces para_server to re-init the mysql dbtool.
+The second command forces para_server to re-init the mysql selector.
Check the log. There should not be any warnings or errors.
para_client ls
-prints the list of all files known by the mysql dbtool. If the list
+prints the list of all files known by the mysql selector. If the list
is empty, double check the mysql_audio_file_dir option.
Attribute usage
~~~~~~~~~~~~~~~
-An attribute is simply a bit which can be set for each sound file
+An attribute is simply a bit which can be set for each audio file
individually. You may have as many attributes as you like. A new
attribute "test" is created by
para_client laa
lists all available attributes. You can set the "test" attribute for
-the current song by executing
+the current audio file by executing
para_client sa test+
-or for any particular song by
+or for any particular audio file by
para_client sa test+ filename
-You can unset the attribute "test" for the current song with
+Unset the attribute "test" for the current audio file with
- para_client sa test-
+ para_client sa test-
-and you can drop the test attribute entirely from the database with
+and drop the test attribute entirely from the database with
para_client da test
Stream usage
~~~~~~~~~~~~
-A stream is a pair of expressions in terms of attributes and other
-meta data contained in the database. The first, boolian, expression
-determines the set of songs which are permitted in this stream. The
-second, integer, expression determines the order in which permitted
-songs are going to be fed to the audio file sender(s).
+A stream is a pair of expressions in terms of attributes and other data
+contained in the database. The first, boolian, expression determines
+the set of audio files which are admissible in this stream. The second,
+integer, expression determines the order in which admissible files
+are going to be fed to the audio file sender(s).
To create a new stream called "my_stream", put arbitrary many (including
none) accept or deny lines and one or zero score lines into some
para_client stradd my_stream < tmpfile
-adds the stream "my_stream" to dbtool's stream database.
+adds the stream "my_stream" to the table of streams.
If the stream definition is really short, you may also just pipe it to
the client rather than using temporary files. Like this:
Example:
- Assume you already have an attribute "test" and you'd like to
- to restrict the set of songs being played to those having the
- "test" attribute set. Define a new stream "only_test" by
+ Assume you already have an attribute "test" and you'd like to
+ to restrict the set of songs being played to those having the
+ "test" attribute set. Define a new stream "only_test" by
echo 'accept: IS_SET(test)' | para_client stradd only_test
only the desired songs are going to be played.
There is no need to keep the temporary files containing the stream
-definition since you can always query the database to get it back:
+definition since you can always use the strq command to get it back:
para_client strq only_test
LASTPLAYED()/1440
-This means that each song's score is just the number of days that went
-by since this song has been played (one day is 1440 minutes). This
-is fine in many cases since the dbtool then always chooses that
-admissible song, which wasn't played for the longest time.
+This means that the score of an audio file is just the number of days
+that went by since it has been played the last time (one day is 1440
+minutes). In other words, the mysql selector choses that admissible
+file which wasn't played for the longest time.
-However, one disadvantage of this scoring sheme is that new songs,
+However, one disadvantage of this scoring sheme is that new files,
once played, are going to be deferred for a possibly very long period
-depending on the size of your collection of (admissible) songs. Hence
+depending on the size of your collection of (admissible) files. Hence
the following scoring rule comes into mind:
- score: -NUMPLAYED()
+ score: -NUMPLAYED()
-since this gives newer songs, i.e. songs to which you haven't listen to
+since this gives newer files, i.e. files to which you haven't listen to
that often, a higher score than older songs you already know by heart.
You can also use a combination of these two methods:
- score: LASTPLAYED()/1440 - 10 * NUMPLAYED()
+ score: LASTPLAYED()/1440 - 10 * NUMPLAYED()
which subtracts 10 score points for each time paraslash has played
-this song.
+this file.
-Another useful feature for scoring is due to the fact that "true"
-expands to one and "false" to zero. So you can also use the
-IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give
-your favorite band "bar" some extra points:
+Another useful feature for scoring is due to the fact that
+"true" expands to one and "false" to zero. So you can also use the
+IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give your favorite
+band "bar" some extra points:
score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
Pictures
~~~~~~~~
-dbtool can also magage images that, when associated with certain songs,
-can be displayed by para_sdl_gui and para_krell when one of these songs
-is playing. It is also possible to just retrieve the current image via
+The mysql selector can also magage images that, when associated
+with one or more audio files, can be displayed by para_sdl_gui and
+para_krell. It is also possible to just retrieve the current image via
para_client pic > filename
.name = "cdt",
.handler = com_cdt,
.perms = DB_READ | DB_WRITE,
-.description = "change database tool",
-.synopsis = "cdt [name_of_new_dbtool]",
+.description = "change the current audio file selector",
+.synopsis = "cdt [new_selector]",
.help =
-"Deactivate current dbtool and activate name_of_new_dbtool. If no\n"
-"argument was given, print the current database tool.\n"
+"Shutdown the current selector and activate new_selector. If no\n"
+"argument was given, print the name of the current selector.\n"
},
{
*handler = para_strdup("para_server"); /* server commands */
return cmd;
}
- /* not found, look for dbtool commands */
+ /* not found, look for commands supported by the current selector */
mmd_lock();
if (handler)
*handler = make_message("the %s database tool", dblist[mmd->dbt_num].name);
/** shut down non-authorized connections after that many seconds */
#define ALARM_TIMEOUT 10
-/* these are exported to afs/command/dbtool */
+/* these are exported to afs.c. command.c and to all selectors */
struct misc_meta_data *mmd;
/** the configuration of para_server
*
- * It also contains the options for all database tools and all supported
+ * It also contains the options for all audio file selectors and all supported
* senders.
*/
struct gengetopt_args_info conf;
extern void ortp_send_init(struct sender *);
extern struct audio_format afl[];
-/** the list of supported database tools */
+/** the list of supported audio file selectors */
struct dbtool dblist[] = {
{
.name = "random",
for (i = 0; dblist[i].name; i++) {
if (strcmp(dblist[i].name, conf.selector_arg))
continue;
- PARA_NOTICE_LOG("initializing %s database tool\n",
+ PARA_NOTICE_LOG("initializing %s audio file selector\n",
dblist[i].name);
ret = dblist[i].init(&dblist[i]);
if (ret < 0) {
mmd->dbt_num = i;
return;
}
- PARA_WARNING_LOG("%s", "falling back to the random dbtool\n");
+ PARA_WARNING_LOG("%s", "falling back to the random selector\n");
random:
mmd->dbt_num = 0;
dblist[0].init(&dblist[0]); /* always successful */
return;
}
/* init failed */
- PARA_ERROR_LOG("%s -- switching to the random dbtool\n", PARA_STRERROR(-ret));
+ PARA_ERROR_LOG("%s -- switching to the random selector\n", PARA_STRERROR(-ret));
dblist[0].init(&dblist[0]);
mmd->dbt_num = 0;
}
close_log(logfile); /* gets reopened if necessary by parse_config */
logfile = NULL;
parse_config(1); /* reopens log */
- mmd->dbt_change = mmd->dbt_num; /* do not change dbtool */
- handle_dbt_change(); /* force reloading dbtool */
+ mmd->dbt_change = mmd->dbt_num; /* do not change selector */
+ handle_dbt_change(); /* reload selector */
}
static void status_refresh(void)
projects / paraslash.git / commitdiff