zita-j2n - Online in the Cloud

PROGRAM:

NAME

zita-j2n, zita-n2j - Jack clients to transport multichannel audio over a local network.

SYNOPSIS

zita-j2n [ options ] ip-address ip-port
zita-n2j [ options ] ip-address ip-port
zita-j2n [ options ] ip-address ip-port interface
zita-n2j [ options ] ip-address ip-port interface

DESCRIPTION

General
The zita-j2n (sender) and zita-n2j (receiver) applications allow to exchange up to 64
channels of full-quality uncompressed audio streams between two or more systems running
the Jack audio server. Sender and receiver(s) can each have their own sample rate and
period size, and no word clock sync between them is assumed. The receiver uses adaptive
resampling to convert the audio stream(s) to its local sample rate.

There is no master/slave relationship between sender and receiver(s). This is an explicit
design goal. In all respects the net result of using zita-njbridge is similar to having
analog audio connections between the sound cards of the systems using it. Nothing a sender
can do will affect the receiver(s), apart from the audio signals being available or
reverting to silence if there is no sender. Xruns or skipped cycles will not affect the
synchronisation or resampling. Jack freewheeling on either end will temporarily suspend
operation.

Zita-njbridge can be used in two ways: one-to-one, or one-to-many. Both IPv4 and IPv6 are
supported.

For a one-to-one setup the first form of the commands shown above should be used. The
protocol used is UDP and the ip-address argument required for both sender and receiver is
that of the receiver. A host name can be used instead of a numerical IP adresses, this
will be looked up using getaddrinfo().

For a one-to-many setup the second form must be used The ip-address argument should be a
valid multicast address, and the mandatory interface argument selects the network
interface to be used.

Resampler filter length.
The receiver uses the zita-resampler library to resample signals to its local rate. The
length of the multiphase low-pass filter used as part of the resampling algorithm
determines the audio bandwidth, and adds to latency. It can also have a significant impact
on CPU load if many channels are received.

Zita-njbridge will select a filter length based on the lower of the sender and receiver
sample rates. For sample rates of 44.1 Khz and above the value chosen will result in an
attenuation of no more than 0.1 dB up to 20 kHz. The --filt option allows to override the
automatic configuration, but this will normally not be necessary.

Latency issues.
When connecting two Jack systems with unsynchronised periods the minimum additional
latency under worst case conditions is the sum of the two period times. Additional latency
means any latency required to make the connection work without interruption. The round-
trip latency from an ideal (zero excess latency) analog input on the sender to an ideal
(idem) analog output on the receiver will be twice this value. Worst case conditions means
that the both sender and receiver can run at arbitrary times within their respective
periods.

Zita-njbridge is designed to provide a defined and constant additional latency. The target
value is the sum of the two periods, plus resampling delay, plus any extra buffering
specified by the user. The actual latency will be this value plus the average network
delay. The latter is unknown so there is no way to compensate for it. This would be
possible using either a return channel, or some way to sync clocks on the two systems
which could then be used to measure the average network delay. The current release of
zita-njbridge does not provide this as it is meant for use on a local network. A dedicated
or lightly loaded gigabit Ethernet can provide typical network delays well below a
millisecond.

The --buff option of zita-n2j adds the specified number of milliseconds to the target
latency. The default value is 10 ms which is more than enough on a moderately loaded
Gigabit local network. This can be set to zero, for example when it is known that the
sender will always run near the start of its Jack period and the network delay jitter is
less than this period.

If there is any network delay jitter above 10ms, increasing the extra buffer time will be
necessary to avoid occasional interruption of the received audio streams.

The latency does not depend on the when exactly the sender runs within its Jack period.
This is similar to playback to a soundcard: when the playback samples are written well
before they are due this does not decrease the latency, the data is just buffered until
the end of the period. In the case of zita-njbridge the remaining time is available for
network delay. This is why, when the sender is only lightly loaded and network delay is
small, it is possible to use --buff 0 at the receivers.

Use on wide area or wireless networks.
The current implementation is designed to be used on local networks that provide more or
less reliable delivery of packets, with low or moderate delay. Occasional lost packets
will not impact the synchronisation or resampling, but any samples arriving out of order
will be ignored (they will have been replaced by silence before). Extra buffering (using
the --buff option) will allow an uninterrupted signal in the presence of delay jitter, at
the price of additional latency. Zita-njbridge may be usable on long distance internet
connections, but keep in mind it was not designed for this.

Performance on wireless networks is purely a matter of chance. Again zita-njbridge is not
designed for such use.

OPTIONS

Common options
--help
Print command line and options summary.

--jname name
Select the Jack client client name. Default is 'zita-j2n' or 'zita-n2j'.

--jserv server
Select the Jack server to connect to.

zita-j2n options
--chan channels
The number of channels to transmit, the default is 2 channels.

--16bit
Send audio as 16-bit signed integer samples.

--24bit
Send audio as 24-bit signed integer samples. This is the default format.

--float
Send audio as 32-bit floating point samples (Jack's internal format).

--mtu MTU
Inform zita-j2n of the path MTU, allowing it to use packets up to that size. The
default value is 1500. Note that large MTU values on a shared network may increase
network delay jitter.

--hops hops
Set the maximum number of hops for multicast packets. Defaults to one, i.e.
multicast is to the local net only.

zita-n2j options
--chan list
A list of channels numbers in ascending order and separated by comma or dash
characters, the latter indicating a range. Channel numbers start at 1. Only the
requested channels will be resampled and have a corresponding Jack port. Channels
not provided by the sender will output silence. The default channel list is '1,2'.

--buff time
Increase the target latency by the given time, in milliseconds. The default is 10
ms. See the description above for what exactly this means.

--filt delay
Set the resampler filter delay, in samples at the lower of the two sample rates, in
the range 16..96. See above for details.

--info
Print additional diagnostic information. Three values will be printed twice per
second: The average resampler control loop error in frames, the resampler ratio
correction factor, and the minumum number of frames available in the receive
buffer.

Use zita-j2n online using onworks.net services