[Back to overview]

playhrt --help

playhrt (version 0.7 of frankl's stereo utilities)
USAGE:

  playhrt [options] 

  This program reads raw(!) stereo audio data from stdin, a file or the 
  network and plays it on a local (ALSA) sound device. 

  The program repeats in a given number of loops per second: reading
  a chunk of input data, preparing data for the audio driver, then it
  sleeps until a specific instant of time and after wakeup it hands data
  to the audio driver. In contrast to other player programs this is done
  with a very precise timing such that no buffers underrun or overrun an
  no reading or writing of data is blocking. Furthermore, the data are
  refreshed in RAM directly before turning them to the audio driver.

  The Linux kernel needs the highres-timer functionality enabled (on most
  systems this is the case).

  The program works in two modes, one with an internal buffer (of
  configurable size) and one which writes input data directly to the
  memory of the audio driver (see the --mmap option below). The second
  mode is recommended.

  USAGE HINTS
  
  It is recommended to give this program a high priority and not to run
  too many other things on the same computer during playback. A high
  priority can be specified with the 'chrt' command:

  chrt -f 99 playhrt .....

  (Depending on the configuration of your computer you may need root
  privileges for this, in that case use 'sudo chrt -f 99 playhrt ....' 
  or give 'chrt' setuid permissions.)

  While running this program the computer should run as few other things
  as possible. In particular we recommend to generate the input data
  on a different computer and to send them via the network to 'playhrt'
  using the program 'bufhrt' which is also contained in this package. 
  
  OPTIONS

  --host=hostname, -r hostname
      the host from which to receive the data , given by name or
      ip-address.

  --port=portnumber, -p portnumber
      the port number on the remote host from which to receive data.

  --stdin, -S
      read data from stdin (instead of --host and --port).

  --device=alsaname, -d alsaname
      the name of the sound device. A typical name is 'hw:0,0', maybe
      use 'aplay -l' to find out the correct numbers. It is recommended
      to use the hardware devices 'hw:...' if possible.

  --sample-rate=intval, -s intval
      the sample rate of the audio data. Default is 44100 as on CDs.

  --sample-format=formatstring, -f formatstring
      the format of the samples in the audio data. Currently recognised
      are 'S16_LE' (the sample format on CDs), 'S24_LE' 
      (signed integer data with 24 bits packed into 32 bit words, used by
      many DACs), 'S24_3LE' (also 24 bit integers but only using 3 bytes
      per sample), 'S32_LE' (true 32 bit signed integer samples).
      Default is 'S16_LE'.

  --number-channels=intval, -k intval
      the number of channels in the (interleaved) audio stream. The 
      default is 2 (stereo).

  --loops-per-second=intval, -n intval
      the number of loops per second in which 'playhrt' reads some
      data from the network into a buffer, sleeps until a precise
      moment and then writes a chunk of data to the sound device. 
      Typical values would be 1000 or 2000. Default is 1000.

  --non-blocking-write, -N
      write data to sound device in a non-blocking fashion. This can
      improve sound quality, but the timing must be very precise.

  --mmap, -M
      write data directly to the sound device via an mmap'ed memory
      area. In this mode --buffer-size and --input-size are ignored.
      If you hear clicks enlarge the --hw-buffer. This mode is 
      recommended.

  --buffer-size=intval, -b intval
      the size of the internal buffer for incoming data in bytes.
      It can make sense to play around with this value, a larger
      value (say up to some or many megabytes) can be useful if the 
      network is busy. Smaller values (a few kilobytes) may enable
      'playhrt' to mainly operate in memory cache and improve sound
      quality. Default is 65536 bytes. You may specify 0 or some small
      number, in which case 'playhrt' will compute and use a minimal
      amount of memory it needs, depending on the other parameters.

  --input-size=intval, -i intval
      the amount of data in bytes 'playhrt' tries to read from the
      network during each loop (if needed). If not given or small
      'playhrt' uses the smallest amount it needs. You may try some
      larger value such that it is not necessary to read data during
      every loop.

  --hw-buffer=intval, -c intval
      the buffer size (number of frames) used on the sound device.
      It may be worth to experiment a bit with this,
      in particular to try some smaller values. When 'playhrt' is
      called with --verbose it should report on the range allowed by
      the device. Default is 16384 (but there are devices where this
      is not valid).
 
  --period-size=intval -P intval
      the period size is the chunk size (number of frames) read by the
      sound device. The default is chosen by the hardware driver.
      Use only for final tuning (or not at all), this option can cause
      strange behaviour.

  --extra-bytes-per-second=floatval, -e floatval
      usually the number of bytes per second that must be written
      to the sound device is computed as the sample rate times the
      number of bytes per frame (i.e., one sample per channel).
      But the clocks of the computer and the DAC/Soundcard may
      differ a little bit. This parameter allows to specify a 
      correction of this number of bytes per second (negative means
      to write a little bit slower, and positive to write a bit
      faster to the sound device). See ADJUSTING SPEED below for
      hints. The default is 0.

  --in-net-buffer-size=intval, -N intval
      when reading from the network this allows to set the buffer
      size for the incoming data. This is for finetuning only, normally
      the operating system chooses sizes to guarantee constant data
      flow. The actual fill of the buffer during playback can be checked
      with 'netstat -tpn', it can be up to twice as big as the given
      intval.

  --extra-frames-out=intval, -o intval
      when in one loop not all data were written the program has to
      write some additional frames the next time. This specifies the
      maximal extra amount before an underrun of data is assumed.
      Default is 24.
  
  --verbose, -v
      print some information during startup and operation.
      This option can be given twice for more output about timing
      and availability of the audio buffer (in --mmap mode).

  --version, -V
      print information about the version of the program and abort.

  --help, -h
      print this help page and abort.

  EXAMPLES

  We read from myserver on port 5123 stereo data in 32-bit integer
  format with a sample rate of 192000. We want to run 1000 loops per 
  second (this is in particular a good choice for USB devices), our sound
  device is 'hw:0,0' and we want to write non-blocking to the device:

  playhrt --mmap --host=myserver --port=5123 \
      --loops-per-second=1000 \
      --device=hw:0,0 --sample-rate=192000 --sample-format=S32_LE \
      --non-blocking --verbose 

  To play a local CD quality flac file 'music.flac' you need another 
  program to unpack the raw audio data. In this example we use 'sox':

  sox musik.flac -t raw - | playhrt --mmap --stdin \
          --loops-per-second=1000 --device=hw:0,0 --sample-rate=44100 \
          --sample-format=S16_LE --non-blocking --verbose 

  Without the --mmap option playhrt can buffer the input data, and the
  size of the buffer can be chosen via the --buffer-size option.

  ADJUSTING SPEED

  Using the --mmap mode and a double --verbose --verbose option
  playhrt will show every few seconds how much space is available
  in the hardware buffer. This should stay roughly constant during
  playback. If it changes during playback or if a buffer underrun or
  overrun occurs then playhrt prints some suggestion for the value
  that should be given to the --extra-bytes-per-second option.

  If you get an underrun or overrun without the --mmap option, you
  should enlarge or reduce  the --extra-bytes-per-second parameter 
  by about:
      (value of --buffer-size) / (2 x number of seconds until underrun)