[Back to overview]
playhrt --help
playhrt (version 0.8 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 and
no reading or writing of data is blocking. Furthermore, the data are
refreshed in RAM directly before copying 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 70 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.
--no-delay-stats, -j
disables statistics about delayed loops, see DELAYED LOOPS below.
Only use this after finishing fine tuning of your parameters.
--no-buf-stats, -y
in --mmap mode tries to self adjust and suggest better values
of the --extra-bytes-per-second parameter by checking the average
size of space available in the hardware buffer. The --no-buf-stats
option disables this check and adjustment. So, use this option
only after finding the correct --extra-bytes-per-second parameter.
--stripped, -X
experimental option: only to be used when no statistics functions
are switched on. With this option specific code is run which has the
code for statistics stripped.
--in-net-buffer-size=intval, -K 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.
--sleep=intval, -D intval
causes playhrt to sleep for intval microseconds (1/1000000 sec)
after opening the sound device and before starting playback.
This may sometimes be useful to give other programs time to
fill the input buffer of playhrt. Default is no sleep.
--max-bad-reads=intval, -m intval
playhrt counts how often the read of a block of input data returns
fewer data than requested. If this count exceeds the number given
with this option then playhrt will stop. The default is 4 (because
it is normal that the first block and one or two blocks at the end
return fewer data).
--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)
DELAYED LOOPS
It may happen that in some read-preparation-sleep loops the sleep starts
after the intended wakeup time (too long computations, system interrupts
or other reasons). playhrt counts such loops as "delayed loops" and
reports them in --verbose mode. These can be ignored if their number is
a small proportion of all loops, say, up to a few percent. If delayed
lopps occur their number will become smaller with lower verbosity level
and the detection of such loops can be disabled (and maybe further
reduced with the --no-delay-stats option.