X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/460b9539a7c15580e41a71bbc0f47ae776238915..46fb1b054b01374aafa506f6ad2be233e8d61d36:/README.streams

diff --git a/README.streams b/README.streams
index 4e6e425..8fbe6c7 100644
--- a/README.streams
+++ b/README.streams
@@ -1,5 +1,139 @@
-DisOrder and Internet Streams
-=============================
+* Introduction
+
+This file describes DisOrder's relationship to several different things that
+get called 'streams'.
+
+* RTP Streaming
+
+DisOrder is capable to transmitting RTP streams over a suitable network.
+
+** Server Setup
+
+To enable this make sure that all players use the speaker process, i.e. execraw
+rather than exec (or it won't work properly) and configure the network speaker
+backend:
+
+    api network
+    broadcast 172.17.207.255 9003
+    broadcast_from 172.17.207.2 9002
+
+The destination address (broadcast) can be:
+   - a broadcast address for a local network
+   - a multicast address
+
+The source address (broadcast_from) is optional but may be convenient in some
+cases.
+
+If the destination is a multicast address then you should set the TTL, for
+instance:
+
+   multicast_ttl 10
+
+(The destination can also be a unicast address but that's not a tested
+configuration.)
+
+** Playing The Stream
+
+To play, use the disorder-playrtp client.  If the destination address was a
+unicast or broadcast address then:
+
+   disorder-playrtp 9003
+
+If the destination address was a multicast address then you must specify that,
+for instance:
+
+   disorder-playrtp 224.2.3.4 9003
+
+If the client machine has a DisOrder configuration file allowing disorder(1) to
+connect to the server then the parameters are unnecessary: disorder-playrtp
+will figure out the details automatically.
+
+** Disobedience
+
+Disobedience is capable of running disorder-playrtp in the background (provided
+it is installed); look for the speaker icon.  If it detects that the server is
+using network play then its volume control will apply to the local volume, not
+the server's volume.
+
+If you run into trouble look for *.log files in the ~/.disorder directory.
+
+** Limitations
+
+Currently only 16-bit 44100Hz stereo is supported, which requires about
+1.4Mbit/s.  At the time of writing I've found this to work fine on 100Mbit/s
+ethernet and had reports of success with 10Mbit/s ethernet, but have not had
+any success with wireless.
+
+Possibly other lower-quality but lower-bandwidth encodings will be supported in
+future.
+
+If you have a very recent version of sox you may need to set the sox_generation
+option.  See disorder_config(5).
+
+
+* Icecast Streaming
+
+This can be achieved using the speaker_command option and Icecast (see
+http://www.icecast.org/).  It will only work if you use the speaker process,
+i.e. execraw for everything.
+
+I used:
+
+  speaker_command "ices2 /etc/disorder/ices.xml"
+
+where ices.xml is:
+
+  <?xml version="1.0"?>
+  <ices>
+      <background>0</background>
+      <logpath>/var/log/ices</logpath>
+      <logfile>disorder.log</logfile>
+      <loglevel>4</loglevel>
+      <consolelog>0</consolelog>
+      <stream>
+          <metadata>
+              <name>lyonesse</name>
+              <genre>Various</genre>
+              <description>lyonesse disorder output</description>
+          </metadata>
+          <input>
+              <module>stdinpcm</module>
+              <param name="rate">44100</param>
+              <param name="channels">2</param>
+              <param name="metadata">1</param>
+              <param name="metadatafilename">/var/disorder/icedata</param>
+          </input>
+          <instance>
+              <hostname>lyonesse.anjou.terraraq.org.uk</hostname>
+              <port>8000</port>
+              <password>SOURCE PASSWORD HERE</password>
+              <mount>/disorder.ogg</mount>
+              <reconnectdelay>2</reconnectdelay>
+              <reconnectattempts>5</reconnectattempts>
+              <maxqueuelength>80</maxqueuelength>
+              <encode>
+                  <nominal-bitrate>64000</nominal-bitrate>
+                  <samplerate>44100</samplerate>
+                  <channels>2</channels>
+                  <flush-samples>8820</flush-samples>
+              </encode>
+          </instance>
+      </stream>
+  </ices>
+
+This doesn't seem to get on very well with pausing but you're unlikely to want
+to pause a stream in any case.  I used IceCast 2.3.1 and Ices 2.0.1.  You can
+play the stream with XMMS or whatever.  The total setup seems to play rather
+behind the 'current' time, watch this space for a fix (or contribute one!)
+
+If you have a too-recent version of sox you may need to set the sox_generation
+option.
+
+Mark Wooding contributed the original support for this but it's been modified
+enough that he probably shouldn't be blamed for any bugs in the current code.
+
+
+* DisOrder and Republishing Internet Streams
 
 DisOrder doesn't have any built-in support for playing streams but you can make
 it do so.  I use the following in my configuration file:
@@ -25,8 +159,8 @@ You can then queue a stream like any other track.  It won't automatically
 interrupt the playing track, you have to scratch it manually.  Go back to
 normal play by scratching the stream.
 
+
 Local Variables:
-mode:text
+mode:outline
 fill-column:79
 End:
-arch-tag:ae95108d51c55288c4f6da4102343cd5