frankl's stereo pages

[Overview] [Player] [RACE] [LoCo] [DRC]

Utilities for playing and streaming music on Linux

Contents of this page

• Aim
• License
• Download
• Description of the problem
• The basic ideas
• Testing the programs
• Short description of the programs
• Getting started
• Prerequisites
• General comments on example scripts
• Warming up with audacious and aplay
• Simple player script play_simple
• Customizing the --extra-bytes-per-second parameter for playhrt
• Player script with writeloop and catloop
• Player script with volrace
• Player script with upsampling, convolver and other tricks
• Player script for two computer setup (with insecure listen_loop script)
• Player script for two computer setup (using ssh)
• Customizing the --extra-bytes-per-second parameter for bufhrt
• Network buffer with bufhrt
• Improving music files on a hard disk with improvefile
• Some general tuning tips

Aim

License

The software here is free software, it comes with full source code, you can change and redistribute it, and it can be downloaded and used without costs. The precise conditions are described in the GNU GPL. Of course, in particular: using the software distributed here is completely on your own risk. As with any new component in your stereo system, keep the volume very low during first tests.

Download

The software is available via this git-repository. For bug reports, problem reports and suggestions use its issue tracker.

Alternatively, you can download the files of version 0.8 of the package here: frankl_stereo-0.8.tar.gz.

Installation instructions are in the file INSTALL inside the code directory. This includes a description of software packages needed for the installation.

When all needed packages are installed on your Linux system, the installation should just look like:

    git clone https://github.com/frankl-audio/frankl_stereo.git
    cd frankl_stereo
    make REFRESH=X8664    # on x86 machines, or
    make REFRESH=AA64     # on arch64 machines (e.g. Raspberry Pi 4)

Description of the problem

The basic ideas

The first idea is to process and transfer audio data in chunks of constant size, each within an interval of time of constant length. For this we use the high resolution timers on modern computer hardware which are made available in Linux by clock_nanosleep and related functions. For example, the program playhrt which sends audio data to a DAC or soundcard has a main loop where in each round a chunk of data is read, then the program sleeps until a certain point of (wall clock) time and after wakeup sends the data to the hardware driver. So, the hardware driver receives (almost) constant sized chunks of input data in very regular time intervals.

The second idea is to refresh the representation of audio data in RAM or on a hard disk by (logically unnecessary) reading and rewriting of data. In the model explained above the hope is to increase the amplitude of the signals (and so also the steepness of slopes and so to reduce the related jitter).

Testing the programs

I'm aware that the model I have explained above is very much simplified. In reality, the processing of data is very complicated. The processed bits are transformed between various physical representations and encodings, data are buffered in various places on hard- and software level (e.g., several levels of caches on a harddisk, network card or in RAM, software buffers in application programs and in hardware drivers, and so on). Having this in mind it seems completely hopeless to produce audible differences between programs which all perform a "bit-perfect" music playback. Fortunately, I started my experiments despite such doubts. (Ok, and encouraged by knowing that others are trying similar things for the Windows or Mac platform, e.g. jplay, MQn, Amarra.)

I have evaluated and compared various versions of my (and other) programs only by listening tests. The starting reference were the standard Linux programs audacious and aplay.

It would be nice to do some sort of technical measurements, which underpin and explain audible differences. But that is probably extremely challenging and certainly outside my technical possibilities.

I was repeatedly surprised how significant audible differences can be in this context. And this not only in my "high-end" stereo setup, but even on a notebook computer or monitor with its lower quality speakers behind the display.

Short description of the programs

playhrt

reads an audio stream from the network, stdin or a file and plays it on a sound device

bufhrt

reads data from stdin, a file, shared memory or the network and writes them to stdout, to a network port or to a file

cat64

reads almost any music file (more precisely, those know to the libsndfile library) and outputs its samples in 64-bit floating point format

resample_soxr

resamples input from stdin or music file and outputs result in 64-bit floating point format (a very high quality resampler and proper 64-bit processing; note that sox only uses 32-bit integer encoding internally); this includes the functionality of cat64 and volrace

writeloop and catloop

reads data from stdin and writes it cyclically to some files or to shared memory, and vice versa (e.g., to buffer data in a ramdisk or RAM)

volrace

implements a simple form of the RACE algorithm and can be used for volume control

cptoshm and shmcat

can be used to buffer data in RAM via shared memory

highrestest

a small utility to check if your Linux setup supports high resolution timers (the names playhrt and bufhrt indicate that a high res timer is used)

play_XXXX

various example scripts which call programs mentioned above and which are explained below

improvefile

is an example script which shows how bufhrt can be used to "improve" music files stored on a hard disk

Getting started

Prerequisites

We assume that you are on a Linux system with the programs provided here installed. Furthermore, you should be able to play sounds via a soundcard or external sound device with some installed player program (e.g., audacious). You should also have a few other programs: sox, aplay, flac, and maybe brutefir (if you want to play with convolving), or some version of nc (if you want a two-computer playback setup).

On Debian and related distributions (Debian, Ubuntu, Mint, Raspian, ...) you may use (as root user, or with a sudo in front):

apt-get install sox libsox-fmt-mp3 brutefir flac netcat-openbsd

On other systems there is certainly a similar command.

Furthermore, we assume that your Linux kernel supports the high resolution timers of modern hardware. This is usually the case, you can test it by calling the small utility progam highrestest which is contained in this package. It will print some information.

General comments on example scripts

Warming up with audacious and aplay

audacious mymusic.flac

sox mymusic.flac -t raw - | aplay -t raw -f S16_LE -c 2 -r 44100 -D hw:0,0

Use the manpage of sox and the manpage of aplay if you want to learn more about these programs.

The sox program can also decode many other formats. For flac-files you can alternatively use flac which has --skip and --until options to decode only a part of a file. Here is an example (a backslash before a newline character means that the next line should be appended, this allows to format very long input lines nicely).

flac --totally-silent --force-raw-format --sign=signed --endian=little \
     -d -c mymusic.flac | aplay -t raw -f S16_LE -c 2 -r 44100 -D hw:0,0

Problem with pulseaudio

Simple player script play_simple

#!/bin/bash

#########################################################################
##  frankl (C) 2015              play_simple
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
EXTRABYTESPLAY=0
VERBOSE="--verbose --verbose"

sox  "$1" -t raw -r 44100 -c 2 -e signed -b 16 - | playhrt \
      --stdin \
      --device=${CARD} \
      --sample-rate=44100 \
      --sample-format=S16_LE \
      --loops-per-second=1000 \
      --mmap \
      --non-blocking-write \
      ${VERBOSE} \
      --extra-bytes-per-second=${EXTRABYTESPLAY} \
      --hw-buffer=16384

play_simple mymusic.flac

Customizing the --extra-bytes-per-second parameter for playhrt

playhrt: average available buffer: 8495 (1031175 sec 282972195 nsec)

Player script with writeloop and catloop

#!/bin/bash

#########################################################################
##  frankl (C) 2015              play_writecatloop
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
EXTRABYTESPLAY=0
VERBOSE="--verbose --verbose"

trap "trap - SIGTERM && kill -- -$$ " SIGINT SIGTERM EXIT

rm -f /dev/shm/bl{1,2,3} /dev/shm/sem.bl{1,2,3}*
sox  "$1" -t raw -r 44100 -c 2 -e signed -b 16 - | \
      writeloop --block-size=1024 --file-size=4096 --shared /bl1 /bl2 /bl3 &

# maybe the start of the background command takes a little time
sleep 0.1

catloop --block-size=1024 --shared /bl1 /bl2 /bl3 | \
      playhrt \
           --stdin \
           --device=${CARD} \
           --sample-rate=44100 \
           --sample-format=S16_LE \
           --loops-per-second=1000 \
           --mmap \
           --non-blocking-write \
           ${VERBOSE} \
           --extra-bytes-per-second=${EXTRABYTESPLAY} \
           --hw-buffer=16384

Player script with volrace

In this example we introduce volume control during playback and the RACE algorithm. The parameters are given in the file /tmp/VOLRACE which is created when it does not exist. Once the music is running you can edit that file (or change or overwrite it by some script) to change the parameters on the fly (and volrace will fade to the new values). If the file contains only one parameter then RACE is disabled. The first parameter for the volume can be negative in which case the phase of the music will be inverted.

The default parameters may be interesting on a notebook with builtin speakers, it creates a 3D-image as in Ambiophonics. In a standard stereo setup try 0.6 13 0.22, for headphones use only the first volume parameter or set the third parameter to 0.0.

This script also demonstrates how sox can convert the music to 64-bit floating point samples, this is needed by volrace, and would also be useful for other filters (e.g., a convolver for room correction). And vice versa it shows how to cut the samples to 16-bit integers with the application of dithering and noise shaping.

Alternatively, instead of sox one could also use cat64 or resample_soxr from this package.

#!/bin/bash 

#########################################################################
##  frankl (C) 2015              play_volrace
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
EXTRABYTESPLAY=0
VERBOSE="--verbose --verbose"

trap "trap - SIGTERM && kill -- -$$ " SIGINT SIGTERM EXIT

rm -f /dev/shm/bl{1,2,3} /dev/shm/sem.bl{1,2,3}*

if ! test -e /tmp/VOLRACE ; then
  echo "0.6 4 0.75" > /tmp/VOLRACE
fi

sox  "$1" -t raw -r 44100 -c 2 -e float -b 64 - | \
      volrace --param-file=/tmp/VOLRACE | \
      sox -t raw -r 44100 -c 2 -e float -b 64 - \
          -t raw -e signed -b 16 - dither -f high-shibata | \
      writeloop --block-size=1024 --file-size=4096 --shared /bl1 /bl2 /bl3 &

# maybe the start of the background command takes a little time
sleep 0.1

catloop --block-size=1024 --shared /bl1 /bl2 /bl3 | \
      playhrt \
           --stdin \
           --device=${CARD} \
           --sample-rate=44100 \
           --sample-format=S16_LE \
           --loops-per-second=1000 \
           --mmap \
           --non-blocking-write \
           ${VERBOSE} \
           --extra-bytes-per-second=${EXTRABYTESPLAY} \
           --hw-buffer=16384

Player script with convolver, upsampling and other tricks

In this example we apply further processing to the music signal before playing it. First we resample any input to a specified sample rate (192000) and then we use a convolver, which may be fed with a room correction filter and/or a LoCo filter, or which may implement a crossover in the digital domain (in the latter case you would need a multi channel sound card for the output).

Resampling should be done with high quality, in our example script we use resample_soxr from this package (this is true 64-bit processing, while for example sox would only use 32-bit integers internally). Adjust the value of the variable SAMPLERATE if you want other output than 192000.

The convolving is done with brutefir which is called with a configuration file. You can find an example of such a configuration file on the LoCo page. Specify your config file in the variable BRUTEFIRCONFIG in the script. In the example we assume that brutefir produces output samples in S32_LE format.

Of course, if you just want to try the upsampling and no convolving then delete or comment the line with brutefir in the script.

A further change compared to the previous example scripts is that we first copy the music file into RAM and play it from there. Of course this could be done with simple copying into a ramdisk, like (assuming /tmp is a ramdisk):

FILENAME=`basename $1`
cp $1 /tmp/${FILENAME}

and then playing /tmp/${FILENAME} instead of $1.

But in our example we use the programs cptoshm and shmcat provided by this package (and assuming that we want to play a flac-file). This avoids some operating system and file system overhead.

#!/bin/bash 

#########################################################################
##  frankl (C) 2015              play_upsample_convolve
##
##  See README or http://frank_l.bitbucket.org/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
EXTRABYTESPLAY=0
SAMPLERATE=192000
# configure brutefir with output format needed by your DAC
# (here we assume S32_LE)
BRUTEFIRCONFIG=
VERBOSE="--verbose --verbose"

# find input sample rate - only needed when resample_soxr is not used below
ORIGRATE=`sox --i "$1" | grep "Sample Rate" | cut -d: -f2 | sed -e "s/ //g"`

trap "trap - SIGTERM && kill -- -$$ " SIGINT SIGTERM EXIT

cptoshm --file="$1" --shmname=/play.flac

rm -f /dev/shm/bl{1,2,3} /dev/shm/sem.bl{1,2,3}* 

if ! test -e /tmp/VOLRACE ; then
  echo "0.6 4 0.75" > /tmp/VOLRACE
fi

# old version, without resample_soxr
#shmcat --shmname=/play.flac | \
#      sox -t flac - -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - | \
#      sox -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - \
#          -t raw - vol 0.8 rate -v -I ${SAMPLERATE} | \
#      volrace --param-file=/tmp/VOLRACE | \
#      brutefir ${BRUTEFIRCONFIG} -quiet | \
#      writeloop --block-size=1024 --file-size=4096 --shared /bl1 /bl2 /bl3 &

resample_soxr --shmname=/play.flac --param-file=/cache/VOLRACE \
           --outrate=${SAMPLERATE}  --fading-length=100000  | \
      brutefir ${BRUTEFIRCONFIG} -quiet | \
      writeloop --block-size=1024 --file-size=4096 --shared /bl1 /bl2 /bl3 &

# allow some startup time for background command
sleep 0.5

# if this is started from an environment that uses the pulseaudio
# sound server, you can substitute 'playhrt' below by 
# 'pasuspender -- playhrt'
catloop --block-size=1024 --shared /bl1 /bl2 /bl3 | \
      playhrt \
           --stdin \
           --device=${CARD} \
           --sample-rate=${SAMPLERATE} \
           --sample-format=S32_LE \
           --loops-per-second=1000 \
           --mmap \
           --non-blocking-write \
           ${VERBOSE} \
           --extra-bytes-per-second=${EXTRABYTESPLAY} \
           --hw-buffer=8192

Player script for two computer setup (with insecure listen_loop script)

The first variant works by starting once a simple script listen_loop on the audio machine that runs a loop which listens on the network for some input and then executes this input. (Warning: do not use this on a computer which can be connected from untrusted machines because everyone with network connection to the audio machine can start arbitrary commands on it.) The communication between the two computers is done with the UNIX utility nc (also called netcat). The script looks as follows:

#!/bin/bash 

#########################################################################
##  frankl (C) 2015              listen_loop
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

while true; do
  command=`nc -l -p 5501` 
  eval "$command"
done 

Login to the audio machine and start this script in the background. You may do this in a tmux or screen session, then you can logout and login again and still check the output of the remote commands.

listen_loop &

A corresponding player script on the convolver machine sends an appropriate call of playhrt to be executed on the audio machine. We modify play_upsample_convolve from above to get an example. Instead of playhrt we now call bufhrt on the convolver machine.
The other example scripts from above can be adjusted similarly to play on a remote machine.

HINT: there is an error in this script: change shmcat /play.flac 32768 to shmcat --shmname=/play.flac

#!/bin/bash 

#########################################################################
##  frankl (C) 2015              play_remote
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
VERBOSE="--verbose --verbose"
EXTRABYTESBUF=10
EXTRABYTESPLAY=0
AUDIOCOMPUTER="<put here name of your audio machine>"
SAMPLERATE=192000
SAMPLEFORMAT=S32_LE
# this is 192000 * 4 * 2 (32 bit samples, 2 channels)
BYTESPERSECOND=1536000
BRUTEFIRCONFIG="<path to your brutefir config>"
HOST=`hostname`
PORT=5570

# find input sample rate
ORIGRATE=`sox --i "$1" | grep "Sample Rate" | cut -d: -f2 | sed -e "s/ //g"`

trap "trap - SIGTERM && kill -- -$$ " SIGINT SIGTERM EXIT

cptoshm --file="$1" --shmname=/play.flac

rm -f /dev/shm/bl{1,2,3} /dev/shm/sem.bl{1,2,3}* 

if ! test -e /tmp/VOLRACE ; then
  echo "0.6 4 0.75" > /tmp/VOLRACE
fi

shmcat /play.flac 32768 |
      sox  -t flac -  -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - | \
      sox -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - \
          -t raw - vol 0.8 rate -v -I ${SAMPLERATE} | \
      volrace --param-file=/tmp/VOLRACE | \
      brutefir ${BRUTEFIRCONFIG} -quiet | \
      writeloop --block-size=1536 --file-size=9216 --shared /bl1 /bl2 /bl3 &

sleep 0.5

# tell audio computer what to do, short sleep as startup time for sender
REMOTE="sleep 0.3;\
        playhrt ${VERBOSE} --host=${HOST} --port=${PORT} \
                     --sample-rate=${SAMPLERATE} \
                     --sample-format=${SAMPLEFORMAT} \
                     --loops-per-second=1000 \
                     --device=${CARD} --hw-buffer=7680 \
                     --extra-bytes-per-second=${EXTRABYTESPLAY} \
                     --non-blocking-write --mmap "

echo "${REMOTE}" |  nc -q 0 ${AUDIOCOMPUTER} 5501 
# instead of
#            catloop --block-size=1024 --shared /bl1 /bl2 /bl3 | \
# we use the --shared option of bufhrt.
bufhrt --bytes-per-second=${BYTESPERSECOND} \
       --loops-per-second=2000 --port=${PORT} \
       --extra-bytes-per-second=${EXTRABYTESBUF} \
       ${VERBOSE} \
       --shared /bl1 /bl2 /bl3 

A few more comments on the play_remote script. If bufhrt is called with --shared option then the size of the shared memory chunks should be divisible by the number of bytes to be sent per loop (in our example we send 1536 bytes per loop and the size of the shared memory blocks is 6*1536 = 9216 bytes).

Player script for two computer setup (using ssh)

In my setup the audio computer is only connected to the convolver computer, and the listen_loop approach above is no security risk. For a more secure access to the audio computer one can use the secure shell ssh. There are several possibilities to configure ssh such that no password is needed for login. Consult the web if you do not know how to do this.

The remote player script becomes a little more tricky in this case, because remote background processes started via ssh are by default terminated when the shell terminates. To avoid this the remote programs must be called with nohup and standard input and output must be redirected. Here is the play_remote_ssh script as alternative to play_remote above.

HINT: there is an error in this script: change shmcat /play.flac 32768 to shmcat --shmname=/play.flac

#!/bin/bash 

#########################################################################
##  frankl (C) 2015              play_remote_ssh
##
##  See README or http://frankl.luebecknet.de/stereoutils/player.html
##  for explanations.
#########################################################################

CARD="hw:0,0"
EXTRABYTESBUF=200
EXTRABYTESPLAY=0
VERBOSE="--verbose --verbose"
AUDIOCOMPUTER=<name of your audio computer>
SAMPLERATE=192000
SAMPLEFORMAT=S32_LE
# this is 192000 * 4 * 2 (32 bit samples, 2 channels)
BYTESPERSECOND=1536000
BRUTEFIRCONFIG=<path to your brutefir configuration>
HOST=`hostname`
PORT=5570
PLAYHRTLOGFILE=/tmp/playhrt.log

# find input sample rate
ORIGRATE=`sox --i "$1" | grep "Sample Rate" | cut -d: -f2 | sed -e "s/ //g"`

trap "trap - SIGTERM && kill -- -$$ " SIGINT SIGTERM EXIT

cptoshm --file="$1" --shmname=/play.flac

rm -f /dev/shm/bl{1,2,3} /dev/shm/sem.bl{1,2,3}* 

if ! test -e /tmp/VOLRACE ; then
  echo "0.6 4 0.75" > /tmp/VOLRACE
fi

shmcat /play.flac 32768 |
      sox  -t flac -  -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - | \
      sox -t raw -r ${ORIGRATE} -c 2 -e float -b 64 - \
          -t raw - vol 0.8 rate -v -I ${SAMPLERATE} | \
      volrace --param-file=/tmp/VOLRACE | \
      brutefir ${BRUTEFIRCONFIG} -quiet | \
      writeloop --block-size=1536 --file-size=9216 --shared /bl1 /bl2 /bl3 &

sleep 0.5

# tell audio computer what to do 
REMOTE="nohup sleep 0.8 >/dev/null 2>/dev/null </dev/null ;\
        nohup playhrt ${VERBOSE} --host=${HOST} --port=${PORT} \
                     --sample-rate=${SAMPLERATE} \
                     --sample-format=${SAMPLEFORMAT} \
                     --loops-per-second=1000 \
                     --device=${CARD} --hw-buffer=7680 \
                     --extra-bytes-per-second=${EXTRABYTESPLAY} \
                     --non-blocking-write --mmap \
                     >/dev/null 2>${PLAYHRTLOGFILE} </dev/null "

#echo "${REMOTE}" |  nc -q 0 ${AUDIOCOMPUTER} 5501 

REMOTE='sh -c "( (  '${REMOTE}' ) & )"'

echo "${REMOTE}"

ssh ${AUDIOCOMPUTER} "${REMOTE}"

bufhrt --bytes-per-second=${BYTESPERSECOND} \
       --loops-per-second=2000 --port-to-write=${PORT} \
       --extra-bytes-per-second=${EXTRABYTESBUF} \
       ${VERBOSE} \
       --shared /bl1 /bl2 /bl3 

Customizing the --extra-bytes-per-second parameter for bufhrt

Network buffer with bufhrt

Improving music files on a hard disk with improvefile

In some experiments I noticed that two bit-identical copies of the same music file on the same SSD, harddisk or other medium can sound differently(!). To my surprise this can still be true when the files are heavily processed (upsampled, convolved, ...) for playback. My guess is that on a hard disk there is a huge bandwidth of possibilities how the same bit pattern can be represented by magnetized particles on a harddisk (similarly for voltages in memory cells of SSD, USB-stick or memory card) and that different representations influence the timing and amplitude of the output signal of the harddisk when the data are read. (I do not think that fragmentation of the file system or error correction plays a role here). There is a longer thread on this topic in this forum (in German).

After a lot of testing I can improve the sound quality of music files on the SSD in my stereo system quite significantly with the help of bufhrt. This is done as in the following script improvefile.

#!/bin/bash

#########################################################################
##  frankl (C) 2015
##  
##  USAGE:
##    improvefile orig new
##  This script generates a (bit-identical) copy of a file 'orig' to
##  the file 'new'.
##  
#########################################################################

if test -e "$2" ; then
  echo "the file $2 already exists, please delete it first"
  exit
fi

bufhrt --file="$1" --outfile="$2" --buffer-size=50000000 \
       --loops-per-second=2000 --bytes-per-second=6144000 --interval 

The script needs to be used only once (not before every playback). The effect on sound quality will probably decrease when the file is copied (with some system program) to another disk or sent over the network to another computer.

The script uses the --interval option of bufhrt. This causes that the program in intervals only reads data until the (large) buffer is filled and then writes out the buffer (without reading more input) in well timed blocks which are refreshed in RAM before writing. If you have a lot of RAM you can increase the --buffer-size and you can experiment with the --bytes-per-second parameter (which should be somewhat lower than the maximal write speed of your disk).

I use bufhrt with similar arguments to store pre-convolved files on my SSD (that is, in a script like play_upsample_convolve above I substitute the final call of playhrt with a call to bufhrt with output file on the harddisk).

Some general tuning tips

none /ramdisk tmpfs defaults,size=800M,mode=1777,exec,nosuid 0 0

sysctl -w "kernel.shmmax=1782579200"