Document QF's tracklists.

doc/faq.dox

@@ -5,6 +5,7 @@
 \li \ref gfx_wad
 \li \ref pak0_pak
 \li \ref git_compile_error
+\li \ref no_music
 
 \section gfx_wad What does "W_LoadWadFile: unable to load gfx.wad" mean?
 The most common cause of this error is QuakeForge is unable to find
@@ -32,4 +33,25 @@ configure is being created autotools sources m4 files... If the files do not
 exist, you get the errors you have seen. Try installing packages which contain
 the libraries that caused the syntax error, including the -dev versions, then
 recreate configure using bootstrap and try again.
+
+\section no_music Why doesn't \QF play the background music even though I have the CD in the drive?
+By default, \QF no longer uses the CD drive to play music. Instead, \QF now
+looks for a \ref tracklist to map Quake's cd tracks to sound files. If you
+wish to continue using the CD instead, you may set the \c cd_plugin cvar to
+the value appropriate for your system:
+<dl>
+	<dt><code>file</code></dt>	<dd>The default CD plugin. Uses sound files
+									for the BGM.</dd>
+	<dt><code>linux</code></dt>	<dd>Use this plugin on a Linux system.</dd>
+	<dt><code>sdl</code></dt>	<dd>This plugin can be used on most
+									systems.</dd>
+<!--	<dt><code>sgi</code></dt>	<dd>Use this plugin on SGI systems.</dd>-->
+	<dt><code>win</code></dt>	<dd>Use this plugin on Windows
+									systems.</dd>
+	<dt><code>xmms</code></dt>	<dd>The predecessor to the \c file plugin.
+									Not always available, and expects xmms
+									to be available (but not necessarily
+									running) on the system. Useful if you
+									absolutely must have MP3 support.</dd>
+</dl>
 */

doc/tracklist.cfg

@@ -1,14 +1,14 @@
 // sample track list
 { 
-  2 = "music/02.ogg";
-  3 = "music/03.ogg";
-  4 = "music/04.ogg";
-  5 = "music/05.ogg";
-  6 = "music/06.ogg";
-  7 = "music/07.ogg";
-  8 = "music/08.ogg";
-  9 = "music/09.ogg";
-  10 = "music/10.ogg";
-  11 = "music/11.ogg";
+  2 = "music/track02.cdda.ogg";
+  3 = "music/track03.cdda.ogg";
+  4 = "music/track04.cdda.ogg";
+  5 = "music/track05.cdda.ogg";
+  6 = "music/track06.cdda.ogg";
+  7 = "music/track07.cdda.ogg";
+  8 = "music/track08.cdda.ogg";
+  9 = "music/track09.cdda.ogg";
+  10 = "music/track10.cdda.ogg";
+  11 = "music/track11.cdda.ogg";
 }
  

doc/tracklist.dox

@@ -0,0 +1,46 @@
+//unfortunately, have to wrap the docs in a C comment for doxygen
+/**
+\page tracklist Tracklist config file
+
+As \QF supports playing arbitrarily sized audio files, it seemed rather
+obvious that \QF should be able to use them as BGM in place of the CD
+drive. However, requiring specific names and locations for the files seemed
+overly onerous. Thus \QF looks for \c traclist.cfg in the root of the game
+directory (eg. \c id1, same place as \c pak0.pak, \c config.cfg, etc).
+
+Using the following \c tracklist.cfg:
+\verbinclude tracklist.cfg
+
+and the following commands in the \c id1 directory:
+\verbatim
+mkdir music
+cd music
+cdparanoia -B 2-
+oggenc *.wav
+rm *.wav
+cd ..
+pak -vcf quake1-music.pak tracklist.cfg `find music -type f print`
+rm -rf music tracklist.cfg
+\endverbatim
+
+a convenient pak file can be made of the Quake CD audio. Of course, the
+last two commands are optional if you prefer to have the files loose in the
+filesystem.
+
+\section tl-format Tracklist format
+The tracklist config file is a \ref property-list consistinf of a
+dictionary mapping the track numbers to the file to be played when that
+track is requested. The keys of the dictionary are the track number (the
+Quake CD has only tracks 2 to 11 as audio tracks) as a property list
+string, and the values are the file to play, also as a property list
+string.
+
+However, if the value is an array of strings, that track will
+become a playlist, and each file specified in the array will be played in
+order, looping back to the first file in the list.
+
+The files may be <code>.wav</code>, <code>.ogg</code> (Ogg Vorbis),
+<code>.mid</code> or <code>.midi</code> (MIDI), or <code>.flac</code>
+files. MP3 is <em>not</em> supported, and is not likely to ever be
+supported.
+*/