X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/5aff007d8fcfb4c6cc3c3627ae15f45562db7a0d..HEAD:/doc/disorder.3 diff --git a/doc/disorder.3 b/doc/disorder.3 index f3bbe91..cbb3ea0 100644 --- 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 -.\" 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 . .\" .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. -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 @@ -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. -.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. @@ -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. -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 @@ -329,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: @@ -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 -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); @@ -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. +.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.