.\"
-.\" 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
-.\" 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.
-.\"
-.\" 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
-.\" 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
.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
.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
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:
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);
.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.