Add missing bits to scripts/setup, and teach it to install the CGI on

[disorder] / README.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:

 player /export/radio/*.oggradio shell 'xargs ogg123 -q < "$TRACK"'
 collection fs iso-8859-1 /export/radio

After setting this up you'll need to re-read the config file and provoke a
rescan:

  disorder reconfigure rescan /export/radio

/export/radio contains a file for each stream, containing the URL to use:

 lyonesse$ cat /export/radio/CUR1350.oggradio
 http://cur.chu.cam.ac.uk:8000/cur.ogg

You'll probably want to prevent random play of streams:

 disorder set /export/radio/CUR1350.oggradio pick_at_random 0

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:outline
fill-column:79
End: