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.

AUTHOR

       zita-j2n, zita-n2j and this manual page were written by Fons Adriaensen <fons@linuxaudio.org>.

                                                    July 2014                                   ZITA-NJBRIDGE(1)