Merge branch 'master' of git.distorted.org.uk:~mdw/publish/public-git/disorder

[disorder] / doc / disorder.3

diff --git a/doc/disorder.3 b/doc/disorder.3
index 5bd10b3483139a4ed0f9e07afa187747de2837dd..cbb3ea0ba0d7c78efccfa86a81022819ff238ab7 100644 (file)
--- a/doc/disorder.3
+++ b/doc/disorder.3
@@ -1,5 +1,5 @@
 .\"
-.\" 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
 .\" it under the terms of the GNU General Public License as published by
@@ -146,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.
-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
@@ -292,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.
-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
@@ -318,8 +318,10 @@ A standalone player that writes directly to some suitable audio
 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:
@@ -392,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
-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
-On error, should return -1.
+On error, should return \-1.
 .PP
 .nf
 \fBvoid disorder_play_resume(void *data);
@@ -403,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.
+.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.