.\"
-.\" 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
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.
.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.
~mdw / disorder / blobdiff