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
streamed to hardware outputs via ALSA or JACK.  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.

AC3Jack currently builds for both Linux and Mac OS X.


REQUIREMENTS

Make sure to get the -devel packages too, if your linux distribution provides them.

JACK - http://jackaudio.org  (source)   or for Macs, http://jackosx.com
  This needs to be installed in order to build ac3jack, and of course
  you will need to be running a jackd to run it.

AFTEN - http://aften.sourceforge.net -- version > 0.0.8
  Currently, the libaften_static.a is not installed with make install, you need to copy it to
  /usr/local/lib/  before building ac3jack.

wxWidgets - http://wxwidgets.org

boost  - http://boost.org

liblo  - http://liblo.sourceforge.net/
	Used to provide OSC support.

libxml2 - probably already on your system

libsigc++-1.2  - note that this is an older version you may have to
	install separately, but try it first you might have it.  http://libsigc.sourceforge.net




USAGE

The main ac3jack executable now has a GUI for easy control of the various options at runtime.
There is also a command line version called ac3jack_cli.  Both are capable of being controlled remotely
via OSC using the messages specified in the OSC.txt file.

On both Linux and Mac you will need to be running a JACK server in order to use this tool. 
On Mac, the JackPilot application that comes with JackOSX will let you start the JACK server.

GUI Usage:

ac3jack [-h] [-V] [-H <str>] [-P <num>] [-J <str>] [-S <str>]
  -h, --help                    show this help
  -V, --version                 show version only
  -H, --connect-host=<str>      connect to remote ac3jack on given host
  -P, --connect-port=<num>      connect to remote ac3jack on given port
  -J, --jack-name=<str>         jack client name, default is ac3jack_1
  -S, --jack-server-name=<str>  specify JACK server name

All other options are controlled from the GUI and can be changed at any time.


Command Line version Usage:

ac3jack_cli [options...] [portname ...]
Options:
  -o <str> , --output=<str>    output filename for AC3 file.  If 'stdout', then it is sent to standard output.
  -c <num> , --channels=<num>  number of AC-3 output channels (1-6). default is 5 (5.0)
  -b <num> , --bitrate=<num>   bitrate of AC-3 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
  -R , --raw-jack-out          will write raw deinterleaved ac3 out two jack ports.  careful!
  -S , --spdif-out             will open a local audio device SPDIF for live AC3 output
  -C <num> , --spdif-out-card  optionally specify the card # SPDIF device to use with -S option
  -j <str> , --jack-name=<str> jack client name, default is ac3jack
  -P <num> , --osc-port=<num>  OSC server port to use (default is 12314)
  -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

However, if doing live streaming to hardware consider using the highest quality bitrate of 640.

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

An LFE channel may be added with an additional flag.


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_cli -o file.ac3

This will create the ac3jack client with 5 inputs, (L,R,C,LS,RS) 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.  

  ac3jack_cli -S
      
This will create the ac3jack client with 6 inputs, (L,R,C,LS,RS) to
which you can connect with your favorite JACK patchbay (eg. qjackctl).
The -C option to ac3jack_cli causes it to try to open the
SPDIF portion of your sound card for raw output and send the stream
through it. 

Some sound cards may not allow the SPDIF to be accessed when JACK is
using it.  In this case, to do realtime streaming you must either have
two sound cards, with JACK running on one, and the -C <card_num>
option to specify the audio interface to open the SPDIF output on.
Alternatively, if you have a multichannel interface that exposes the
SPDIF outputs on specific channels, you can use the Raw JACK Out
option to have ac3jack send the raw spdif PCM output to two JACK ports
that you can connect to your SPDIF channels using a JACK patchbay.

This option is also for audio interfaces that have SPDIF but don't
advertise AC3 passthrough to the OS or that don't allow its use
simultaneously with JACK.  You must connect the L and R ports to a
pair of hardware channels that route to the SPDIF output.

WARNING! Do NOT connect these jack ports to analog channels with
speakers attached, or damage might occur! It is wise to keep your
target receiver muted until it locks on the AC3 stream.

