ac3jack - realtime AC3 stream encoder for JACK

Written by Jesse Chappell <jesse@essej.net>

Please see the file COPYING for license details.
For generic building and installation instructions please see the
INSTALL file. 


DESCRIPTION

ac3jack is a tool for creating an AC3 (Dolby Digital) multichannel
stream from its JACK input ports.  Using this tool, an AC3 stream (up
to 5.1 channels) is created in realtime and either written to a file or
streamed to standard output.  When streamed to stdout and piped
through the ALSA tool 'ac3dec -C', the AC3 stream can be passed out
the SPDIF port on your audio interface for connection to a
multichannel surround receiver.  In this way, you can achieve full 5.1
surround mixing and monitoring of your JACK applications with a
single digital cable, and no need for hardware supporting discrete
inputs and outputs.

Of course AC3 is a compressed audio stream, so quality suffers
somewhat, but it is the price you pay for easy surround sound.  After
all, if it is good enough for DVD and film soundtracks, it must be OK.

REQUIREMENTS

JACK - http://jackit.sourceforge.net   -- version >= 0.80
  This needs to be installed in order to build ac3jack, and of course
  you will need to be running a jackd to run it.

FFMPEG - http://ffmpeg.sourceforge.net  -- version >= 0.4.6
  Note that you'll need to make sure the header files are installed,
  some packages do not install the headers for some reason.  A make
  install from the source code will do this.


USAGE

ac3jack -o <str> [-c <num>] [-b <num>]  [-d <num>] [-t] [-j <str>] [-B <num>] [-q] [-h]

Options:
  -o <str> , --output=<str>    specify file to write output AC3 stream, 'stdout' will write to standard output
  -c <num> , --channels=<num>  number of AC3 output channels (2-6). default is 6 (5.1)
  -b <num> , --bitrate=<num>   bitrate of AC3 stream (kbits/s). default is 448
  -d <num> , --duration=<num>  duration of output stream (secs). default is 0 (forever)
  -t , --jack-transport        use jack transport state (rolling/stopped) to control stream output
  -j <str> , --jack-name=<str> jack client name, default is ac3jack
  -B <num> , --bufsize=<num>   internal buffer size (samples), if overrun problems occur try a large value
  -q , --quiet                 do not output status to stderr
  -h , --help                  this usage output
  -V , --version               show version only


NOTES

The allowable bitrates for AC3 encoding are nominally variable from
32-640 kbits/s, but there are common conventions and recommendations
for bitrate based on channel count.
  2ch             = 192
  5.1 (6 channel) = 448

The sample rates allowable are 32, 44.1, and 48kHz.  Note that for use
as part of DVD soundtracks multiplexed with MPEG2 files, only 48kHz is
allowed.  Currently the sample rate is selected by the native rate of
the active JACK server.

The channels options will make the following input ports with each
given channel count:
 1 - Left
 2 - Left, Right
 3 - Left, Right, Center
 4 - Left, Right, LeftSurround, RightSurround
 5 - Left, Right, Center, LeftSurround, RightSurround
 6 - Left, Right, Center, LeftSurround, RightSurround, LFE


If the -t (--jack-transport) option is used, ac3jack will only write
to the output when the JACK Transport state is Rolling.

OUTPUT TO FILE

 ac3jack -o file.ac3

This will create the ac3jack client with 6 inputs, (L,R,C,LS,RS,and
LFE) to which you can connect with your favorite JACK patchbay
(eg. qjackctl).   It will create an AC3 stream and the output will be
written to the file specified. 


REALTIME OUTPUT TO SURROUND RECIEVER VIA SPDIF

The following command line can be used to send the AC3 stream through
your audio interface (sound card) SPDIF output.  You must have the
tool 'ac3dec' installed from the alsa-tools package available from
http://alsa-project.org.  Chances are you have it already.

  ac3jack -o stdout | ac3dec -C
      
This will create the ac3jack client with 6 inputs, (L,R,C,LS,RS,and
LFE) to which you can connect with your favorite JACK patchbay
(eg. qjackctl).   It will create an AC3 stream and the output will be
piped to the ac3dec command.  The -C option to ac3dec causes it to try
to open the SPDIF portion of your sound card for raw output and send
the stream through it.  You should see something like the following
on the terminal on successful use:

  ac3jack encoding with 6 channels, 48kHz, 448 kbit/s bitrate, output to stdout
  Using PCM device 'plug:iec958:{AES0 0x2 AES1 0x82 AES2 0x0 AES3 0x2}'
  AC3 Stream 48 KHz 448 kbps

Some sound cards may not allow the SPDIF to be accessed when JACK is
using it.  If you get no output from the SPDIF, or you never see the
line including somthing like "AC3 Stream 48 KHz 448 kbps" you are one
of the unlucky ones.  In this case, to do realtime streaming you must
have two sound cards, with JACK running on one, and the -c (lowercase)
option used with ac3dec to choose the other card for the SPDIF output.

