chiark / gitweb /
doc: correct & move description of raw format players
authorRichard Kettlewell <rjk@terraraq.org.uk>
Mon, 28 Oct 2013 20:10:00 +0000 (20:10 +0000)
committerRichard Kettlewell <rjk@terraraq.org.uk>
Mon, 28 Oct 2013 20:10:00 +0000 (20:10 +0000)
Makefile.am
README
README.raw [deleted file]
doc/disorder.3

index 4f98902..b9629ab 100644 (file)
@@ -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 eba453a..59ebf96 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
+++ /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:
index cbd2278..cbb3ea0 100644 (file)
@@ -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.