[Back to overview]
bufhrt --help
bufhrt (version 0.8 of frankl's stereo utilities)
USAGE:
bufhrt [options] [--shared <snam1> <snam2> [...]]
This program reads data from stdin, a file or a network connection and
writes it to stdout, a file or the network in precisely timed chunks.
To be accurate, the Linux kernel should have the highres-timer enabled
(which is the case in most Linux distributions).
The default input is stdin. Otherwise specify a file or a network
connection. Furthermore, the number of bytes to be written per second
must be given. In a given number of loops per second the program
reads a chunk of data (if needed), sleeps until a specific instant of
time and writes a chunk of data after waking up. The data which are
buffered in RAM are refreshed just before writing them.
The default output is stdout, otherwise specify a network port or file
name.
There are also two special modes. One is to read the data from shared
memory, written by the 'writeloop' utility (see --shared option). The
other is to first collect input into a buffer and then to write data
without reading more input, see the --interval option.
USAGE HINTS
For critical applications (e.g., sending audio data to our player program
'playhrt') 'bufhrt' may be started with a high priority for the real
time scheduler: chrt -f 99 bufhrt .....
See the documentation of 'playhrt' for more details.
OPTIONS
--port-to-write=intval, -p intval
the network port number to which data are written instead of stdout.
--outfile=fname, -o fname
write to this file instead of stdout.
--bytes-per-second=intval, -m intval
the number of bytes to be written to the output per second.
(Alternatively, in case of stereo audio data, the options
--sample-rate and --sample-format can be given instead.)
--loops-per-second=intval, -n intval
the number of loops per second in which this program is reading
data, sleeping and then writing a chunk of data. Default is 1000.
--buffer-size=intval, -b intval
the size of the buffer between reading and writing data in bytes.
Default is 65536. If reading the input is instable then a larger
buffer can be useful. Otherwise, it should be small to fit in
memory cache.
--file=fname, -F fname
the name of a file that should be read instead of standard input.
--host-to-read=hname, -H hname
the name or ip-address of a machine. If given, you have to specify
--port-to-read as well. In this case data are not read from stdin
but from this host and port.
--port-to-read=intval, -P intval
a port number, see --host-to-read.
--stdin, -S
read data from stdin. This is the default.
--shared <snam1> <snam2> ...
input is read from shared memory. The names <snam1>, ..., of the
memory files must be specified after all other options. This
option can be used together with 'writeloop' which writes the
data to the memory files (see documentation of 'writeloop').
For transfering music data this option may lead to better sound
quality than using 'catloop' and a pipe to 'bufhrt' with --stdin
input. We have made good experience with using three shared memory
chunks whose combined length is a bit smaller than the CPUs
L1-cache. In this mode 'bufhrt' does not combine data from
several memory files as output in one loop. Therefore,
'writeloop' should be used with a '--file-size' parameter
which is a multiple of the output per loop of 'bufhrt'.
--input-size=intval, -i intval
the number of bytes to be read per loop (when needed). The default
is to use the smallest amount needed for the output.
--extra-bytes-per-second=floatval, -e floatval
sometimes the clocks in the sending machine and the receiving
machine are not absolutely synchronous. This option allows
to specify an amount of extra bytes to be written to the output
per second (negativ for fewer and positive for more bytes).
The program adjusts the duration of the read-sleep-write rounds.
--interval, -I
use interval mode, typically together with a large --buffer-size.
Per interval the buffer is filled without writing data, and then
the buffer content is written out in a sleep-write loop (without
reading input). See below for an example.
--dsync, -d
output file will be opened with O_DSYNC option, this is a hint to
the system to write data to the hardware immediately.
--in-net-buffer-size=intval, -K intval
--out-net-buffer-size=intval, -L intval
this if for finetuning only. It specifies the buffer size to
use for data read from the network, or data written to the
network, respectively. The actual fill of the buffers while
the program is running can be checked with 'netstat -tpn'.
Usually the operation system chooses sensible values itself.
--verbose, -v
print some information during startup and operation.
--version, -V
print information about the version of the program and abort.
--help, -h
print this help page and abort.
EXAMPLES
Sending stereo audio data (192/32 format) from a filter program to
a remote machine, using a small buffer and smallest possible input
chunks (here 32 bit means 4 byte per channel and sample, so we have
2x4x192000 = 1536000 bytes of audio data per second):
...(filter)... | bufhrt --port-to-write 5888 \
--bytes-per-second=1536000 --loops-per-second=2000 \
--buffer-size=8096
A network buffer, reading from and writing to network:
bufhrt --host-to-read=myserver --port-to-read=5888 \
--buffer-size=20000 --bytes-per-second=1536000 \
--loops-per-second=2000 --port-to-write=5999
We use interval mode to copy music files to a hard disk. (Yes, different
copies of a music file on the same disk can sound differently . . .):
bufhrt --interval --file music.flac --dsync --outfile=music_better.flac \
--buffer-size=500000000 --loops-per-second=2000 \
--bytes-per-second=6144000
And here is an example how 'bufhrt' can work together with 'writeloop'
(note that the memory file size is 6 * 1536, 6 times the data to be
written per loop).
...(filter)... | writeloop --block-size=1536 \
--file-size=9216 --shared /bl1 /bl2 /bl3 &
bufhrt --bytes-per-second=1536000 --loops-per-second=1000 \
--port-to-write=5999 --extra-bytes-per-second=12 \
--shared /bl1 /bl2 /bl3