server/gstdecode.c: Add `-s' option to omit DisOrder's usual framing.

[disorder] / doc / disorder.3

diff --git a/doc/disorder.3 b/doc/disorder.3
index f3bbe9175d35767fa42c2317450dcdb928df33b3..cbb3ea0ba0d7c78efccfa86a81022819ff238ab7 100644 (file)
--- a/doc/disorder.3
+++ b/doc/disorder.3
@@ -1,20 +1,18 @@
 .\"
 .\"

-.\" Copyright (C) 2004-2008 Richard Kettlewell
+.\" Copyright (C) 2004-2008, 2013 Richard Kettlewell

 .\"
 .\"

-.\" This program is free software; you can redistribute it and/or modify
+.\" This program is free software: you can redistribute it and/or modify

 .\" it under the terms of the GNU General Public License as published by
 .\" it under the terms of the GNU General Public License as published by

-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or

 .\" (at your option) any later version.
 .\" (at your option) any later version.

-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
+.\" 
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\" 

 .\" You should have received a copy of the GNU General Public License
 .\" You should have received a copy of the GNU General Public License

-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.

 .\"
 .TH disorder 3
 .SH NAME
 .\"
 .TH disorder 3
 .SH NAME


@@ -148,7 +146,7 @@ If the track or key are not found a null pointer is returned.
 .IP
 This function sets the value of \fBkey\fR for \fBtrack\fR to
 \fBvalue\fR.
 .IP
 This function sets the value of \fBkey\fR for \fBtrack\fR to
 \fBvalue\fR.

-On success, 0 is returned; on error, -1 is returned.
+On success, 0 is returned; on error, \-1 is returned.

 .IP
 If \fBvalue\fR is a null pointer then the preference is deleted.
 .IP
 .IP
 If \fBvalue\fR is a null pointer then the preference is deleted.
 .IP


@@ -157,15 +155,6 @@ and are lost if the track is deleted; they should only ever have
 values that can be regenerated on demand.
 Other values are stored in the prefs database and never get
 automatically deleted.
 values that can be regenerated on demand.
 Other values are stored in the prefs database and never get
 automatically deleted.

-.PP
-.nf
-\fBconst char *disorder_track_random(void)
-.fi
-.IP
-Returns a pointer to a copy of the name of a randomly chosen track.
-Each non-alias track has an equal probability of being chosen.
-Aliases are never returned.
-Only available in server plugins.

 .SH "PLUGIN FUNCTIONS"
 This section describes the functions that you must implement to write various
 plugins.
 .SH "PLUGIN FUNCTIONS"
 This section describes the functions that you must implement to write various
 plugins.


@@ -303,7 +292,7 @@ match them back up to the right collection to call
 .fi
 .IP
 Check whether file \fBpath\fR under \fBroot\fR still exists.
 .fi
 .IP
 Check whether file \fBpath\fR under \fBroot\fR still exists.

-Should return 1 if it exists, 0 if it does not and -1 on error.
+Should return 1 if it exists, 0 if it does not and \-1 on error.

 This is run in the main server process.
 .PP
 Both scan and recheck are executed inside a subprocess, so it will not
 This is run in the main server process.
 .PP
 Both scan and recheck are executed inside a subprocess, so it will not


@@ -329,8 +318,10 @@ A standalone player that writes directly to some suitable audio
 device.
 .TP
 .B DISORDER_PLAYER_RAW
 device.
 .TP
 .B DISORDER_PLAYER_RAW

-A player that writes raw samples to \fB$DISORDER_RAW_FD\fR, for
-instance by using the \fBdisorder\fR libao driver.
+A player that writes blocks of raw samples to \fB$DISORDER_RAW_FD\fR.
+See
+.B "RAW FORMAT PLAYERS"
+below.

 .RE
 .IP
 Known capabilities are:
 .RE
 .IP
 Known capabilities are:


@@ -403,10 +394,10 @@ This function must never block, as it runs inside the main loop of the
 server.
 .IP
 On success, should return 0 and set \fB*playedp\fR to the number of
 server.
 .IP
 On success, should return 0 and set \fB*playedp\fR to the number of

-seconds played so far of this track, or to -1 if this cannot be
+seconds played so far of this track, or to \-1 if this cannot be

 determined.
 .IP
 determined.
 .IP

-On error, should return -1.
+On error, should return \-1.

 .PP
 .nf
 \fBvoid disorder_play_resume(void *data);
 .PP
 .nf
 \fBvoid disorder_play_resume(void *data);


@@ -414,6 +405,53 @@ On error, should return -1.
 .IP
 Resume playing the current track after a pause.
 This function must never block, as it runs inside the main loop of the server.
 .IP
 Resume playing the current track after a pause.
 This function must never block, as it runs inside the main loop of the server.

+.SH "RAW FORMAT PLAYERS"
+Raw format players should write data to the file descriptor given by
+the environment variable \fBDISORDER_RAW_FD\fR.
+.PP
+The output format is a series of chunks.  Each chunk has a header with
+the following format:
+.PP
+.nf
+struct stream_header {
+  uint32_t nbytes;
+  uint32_t rate;
+  uint8_t channels;
+  uint8_t bits;
+  uint8_t endian;
+} attribute((packed));
+.fi
+.PP
+The meanings of the fields are as follows:
+.TP
+.B nbytes
+The total number of bytes of sample data that follow the header.
+.TP
+.B rate
+The sample rate in samples per second.
+e.g. 44100.
+.TP
+.B channels
+The number of channels per frame.
+e.g. 2.
+.TP
+.B bits
+The number of bits per sample.
+e.g. 16.
+.TP
+.B endian
+The sample byte order.
+1 for big-endian samples and 2 for little-endian samples.
+.PP
+Any number of chunks are allowed.
+.PP
+Raw format players may be started before the track is to be played,
+and (if the track is then removed from the queue before it reaches the
+head) terminated before the track ever reaches a physical speaker.
+The point of this is to allow audio data to be ready to play the
+moment the previous track end, without having to wait for the player
+to start up.
+There is no way for a player to tell that this is going on.

 .SH NOTES
 There is no special DisOrder library to link against; the symbols are
 exported by the executables themselves.
 .SH NOTES
 There is no special DisOrder library to link against; the symbols are
 exported by the executables themselves.