doc: correct & move description of raw format players

diff --git a/Makefile.am b/Makefile.am
index 4f98902a588c5e9a7eca3d54684db4ba2500907a..b9629ab2303562f2a10648cd98180eef0ba7441e 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 #
 # This file is part of DisOrder.
-# Copyright (C) 2004-2008 Richard Kettlewell
+# Copyright (C) 2004-2008, 2010, 2011, 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
@@ -17,7 +17,7 @@
 #
 
 EXTRA_DIST=CHANGES.html README.streams BUGS \
-README.upgrades.html README.client README.raw README.vhost README.developers \
+README.upgrades.html README.client README.vhost README.developers \
 docs.css
 SUBDIRS=@subdirs@
 

diff --git a/README b/README
index eba453a4c24c8ac8594b8097f08d32b456017987..59ebf9673fb9556dcc36c5b44a2cc35d42cf8ecc 100644 (file)
--- a/README
+++ b/README
@@ -134,7 +134,7 @@ platform, please get in touch.
 
    See README.streams for how to set up network play.
 
-   If adding new 'player' commands, see README.raw for details on setting up
+   If adding new 'player' commands, see disorder(3) for details on setting up
    "raw format" players.  Non-raw players are still supported but not in all
    configurations and they cannot support pausing and gapless play.  If you
    want additional formats to be supported natively please point the author at

diff --git a/README.raw b/README.raw
deleted file mode 100644 (file)
index a107964..0000000
--- a/README.raw
+++ /dev/null
@@ -1,41 +0,0 @@
-* DisOrder Raw Format Players
-
-** Purpose
-
-The purpose of raw format players is:
-
-   * Support pausing of playing tracks, with the audio device closed when not
-     in active use.
-
-   * Eliminate the inter-track gap.
-
-   * Perhaps in the future support network play.
-
-** Usage
-
-By default, built-in raw-format players are used for several encodings, so you
-do not need to do anything.
-
-** Low-Level Details
-
-Raw format players are started slightly differently to normal ones.  Before
-they are executed a pipe is created and one end passed to a special speaker
-process, which is spawned by the main server at startup.  The file descriptor
-of the player's end is identified by $DISORDER_RAW_FD.
-
-The expected data format is a ao_sample_format structure followed by the raw
-sample data.  However, this may be changed without notice in future versions of
-DisOrder.  If you need a stable interface here for some reason then get in
-touch.
-
-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.
-
-Local Variables:
-mode:outline
-fill-column:79
-End:

diff --git a/doc/disorder.3 b/doc/disorder.3
index cbd227802f00cb658ca3452c24d3e054fc059663..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
@@ -318,7 +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.
+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:
@@ -402,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.