root/tags/2.0-beta1/README

FFADO v2.x
==========

The FFADO project aims to provide a free driver implemenation for FireWire 
(IEEE1394, iLink) based (semi-) professional audio interfaces. The focus of
the project are on audio/music production rather than consumer audio. This
means that, although we intend to supported all features at some point, 
consumer features are considered less important. The most obvious example of
a consumer feature is AC3/DTS passthrough support, which is unsupported at 
the moment.

This package provides the libffado shared library that provides a unified
programming interface to configure and use all supported devices. Currently
this library is used by the 'firewire' backends of the jack audio connection
kit sound server (jackaudio.org). This backend provides audio and midi support,
and is available both in jackd and it's multiprocessor variant jackdmp.
(note: At the moment there is no support for ALSA nor for pulseaudio.)

Access to the device internal configuration (e,g, internal mixer) is exposed
using the ffado-dbus-server daemon. This daemon exposes the configurable 
parameters of all detected devices through DBUS. The ffadomixer application in
support/mixer presents a GUI to control these parameters (only for officially
supported devices).

Features
--------
* 24-bit audio input/output (unlimited number of channels)
* supports for all samplerates a device supports
* MIDI input/output (unlimited number of channels)
* Support for S/PDIF and ADAT/SMUX I/O
* Internal mixer and device control support for all officially supported 
  devices (NOTE: no support for internal DSP)
* Support for device aggregation (limited to devices on the same bus)

Device Support
--------------

The devices officially supported are:
* ESI Quatafire 610
* Terratec Producer Phase 88
* Focusrite Saffire (original/white)
* Focusrite Saffire PRO10
* Focusrite Saffire PRO26
* ECHO AudioFire2
* Mackie Onyx Mixer FireWire expansion

The 'officially supported' label is only given to devices that fullfil the
following:
* at least one of the developers has the device
* the vendor provides development support (access to information)
* the device works

Through reverse-engineering the following devices will also work:
* MOTU traveller
* MOTU 828mkII
Note: the support for these devices is based on a significant reverse
engineering effort. This means that the developers had no support from the
device vendor, and this of course limits the extent to which problems can
be solved. You have been warned. Please do not buy devices for which support
is based upon reverse engineering, nor from vendors that are Linux-hostile
(e.g. MOTU). Value the support that some vendors provide and buy their
stuff. Check ffado.org for details. It can't be said enough: currently it is
extremely unwise to buy a MOTU device if you intend to use Linux.

The driver is written to provide generic support for all devices it might be
able to handle. This means that most devices based on the BridgeCo BeBoB or
the ECHO FireWorks platform will work, at least to a certain extent.

Devices that have been reported to (partially) work with the generic support:
* Presonus FireBox
* Presonus FirePod / FP10
* Focusrite Saffire LE
* ECHO AudioFire8
* ECHO AudioFire12

Usupported devices:
* Presonus FireStation
* Presonus FireStudio (all variants)
* TC Konnekt (all variants)
* Alesis devices
* Metric Halo devices
* RME Firewire devices

We constantly try to persuade vendors to help us extend our device support.

Dependencies
------------

To build libffado you need several libraries. For all libraries a
version is provided which is a 'known good' version.  The first few
libraries it seems it is not necessary that the version must
match. The chances that it works also with an older versions are good:

alsa        (>= 1.0.0)
libxml++2   (>= 2.13.0)

These libraries here should be at least the version listed:

libraw1394  (>= 1.3.0),  http://www.linux1394.org
libiec61883 (>= 1.1.0),  http://www.linux1394.org
libavc1394  (>= 0.5.3),  http://sourceforge.net/projects/libavc1394
dbus-1      (>= 1.0),    http://dbus.freedesktop.org

Currently only the jackd audio server is supported.

jackd (>= 0.107.6), http://jackaudio.org

Optionally, but recommended is that you install qjackctl:

qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl

To build the optional ffado device mixer control utility you also require:

Qt          (>= 3.0),     http://trolltech.com/products/qt
SIP         (>= 4.7.0),   http://www.riverbankcomputing.co.uk/sip/index.php
PyQt        (note below), http://www.riverbankcomputing.co.uk/pyqt/
dbus-python (>= 0.82.0),  http://dbus.freedesktop.org/releases/dbus-python/

The version of PyQt must be chosen to match the version of Qt in use.
For Qt 4.x use PyQt 4.x while for all other Qt versions from 1.43.

SIP is only required to compile PyQt.  If using a binary package of PyQt
SIP should not be needed.

How to build
------------

Building the code is straight forward if PKG_CONFIG_PATH, LD_LIBRARY_PATH
and INCLUDE_PATH is correctly set up.

E.g on my system I have installed libraw1394, libiec61883 and libavc1394
under /usr/local:

$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
$ export LD_LIBRARY_PATH=/usr/local/lib

If you want to build the release version you can do following:

$ scons
$ scons install

If you want some debug information (because something seems not
to work correctly) you can try to do following:

$ scons DEBUG=yes
$ scons install

NOTE: In order to build jackd with ffado support, you have 
to install libffado before you build jackd. The backend to use in jackd is
firewire.

DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
if it is not on by default. If device support for a specific device
is not turned on by default by the developers, it means that it is not
ready yet. Most of the time it is placeholder code for future devices.

Running jackd
-------------

The easiest way to run this is using qjackctl. There are only minor 
differences with the other backends, however you should change some
of the default values:
- The 'interface' field should contain only a number. This number is
  the port number of the IEEE1394 host controller the audio device
  is connected to. For most people this will be '0', but if you have
  multiple controllers, you have to change this number.
- The 'Input channels' and 'Output channels' fields indicate if the
  backend should provide capture and/or playback channels. If you set
  these to 0, no channels are created. In order to enable capture and/or
  playback, you have to set them to a nonzero value.
- It is recommended to change the 'periods/buffer' field to 3, especially
  if you use low period sizes (=< 128)
- It is recommended to raise the RT priority to 70.

In order to get it running from the command line, you need to provide some 
arguments to jackd.

Run 

$ jackd -d firewire --help

to see the backend options. You can easily figure out how to set them using
the remarks given above (for qjackctl).

For the other aspects of jackd usage, consult the jackd documentation.

Here is a sample session (without realtime support enabled):

[wagi@halo ~]$ jackd -d firewire
jackd 0.102.9
Copyright 2001-2005 Paul Davis and others.
jackd comes with ABSOLUTELY NO WARRANTY
This is free software, and you are welcome to redistribute it
under certain conditions; see the file COPYING for details

JACK compiled with System V SHM support.
loading driver ..
Freebob using Firewire port 0, node -1
libiec61883 warning: Established connection on channel 0.
You may need to manually set the channel on the receiving node.
libiec61883 warning: Established connection on channel 1.
You may need to manually set the channel on the transmitting node.

(Note: you can safely ignore the libiec61883 warnings, they are normal.)

In case of problems
-------------------

Under the tests directory there is a test program. You should first
try to run this.

If you don't have installed libffado then you can adapt your
LD_LIBRARY_PATH environment variable to

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../src/.libs

Then you can try running the program without having to install it.

With the release version you see something like this:

wagi@cruxam:~/src/libffado/tests$ ./test-ffado discover
verbose level = 0
Using ffado library version: libffado 0.9.0

  port = 2, devices_on_bus = 1
  get info for device = 0, node = 1
Direction:              0 (capture)

Connection Info
===============

Number of connections:  1

  Connection  0
  -------------
    [ 0] Id:         0
    [ 0] Port:       2
    [ 0] Node:       1
    [ 0] Plug:       0
    [ 0] Dimension:  7
    [ 0] Samplerate: 44100
    [ 0] IsoChannel: -1
    [ 0] IsMaster:   0
    [ 0] Number of stream infos: 8

    StreamId  Position Location Format Type DPort Name
    --------------------------------------------------
    [ 0]:[ 0] 0x01     0x01     0x06   0x02 0x00  MicIn 1+2 left
    [ 0]:[ 1] 0x04     0x02     0x06   0x02 0x00  MicIn 1+2 right
    [ 0]:[ 2] 0x02     0x01     0x06   0x03 0x00  LineIn 1+2 left
    [ 0]:[ 3] 0x05     0x02     0x06   0x03 0x00  LineIn 1+2 right
    [ 0]:[ 4] 0x00     0x01     0x06   0x04 0x00  SpdifIn 1 left
    [ 0]:[ 5] 0x03     0x02     0x06   0x04 0x00  SpdifIn 1 right
    [ 0]:[ 6] 0x06     0x01     0x0d   0x0a 0x00  MidiIn2
    [ 0]:[ 7] 0x06     0x02     0x0d   0x0a 0x00  MidiIn2


Direction:              1 (playback)

Connection Info
===============

Number of connections:  1

  Connection  0
  -------------
    [ 0] Id:         0
    [ 0] Port:       2
    [ 0] Node:       1
    [ 0] Plug:       0
    [ 0] Dimension:  11
    [ 0] Samplerate: 44100
    [ 0] IsoChannel: -1
    [ 0] IsMaster:   0
    [ 0] Number of stream infos: 12

    StreamId  Position Location Format Type DPort Name
    --------------------------------------------------
    [ 0]:[ 0] 0x01     0x01     0x06   0x03 0x00  MultiChannel 7.1 Front left
    [ 0]:[ 1] 0x06     0x02     0x06   0x03 0x00  MultiChannel 7.1 Front right
    [ 0]:[ 2] 0x02     0x03     0x06   0x03 0x00  MultiChannel 7.1 Center
    [ 0]:[ 3] 0x07     0x04     0x06   0x03 0x00  MultiChannel 7.1 Subwoofer
    [ 0]:[ 4] 0x03     0x05     0x06   0x03 0x00  MultiChannel 7.1 Rear left
    [ 0]:[ 5] 0x08     0x06     0x06   0x03 0x00  MultiChannel 7.1 Rear right
    [ 0]:[ 6] 0x04     0x07     0x06   0x03 0x00  MultiChannel 7.1 Surround left
    [ 0]:[ 7] 0x09     0x08     0x06   0x03 0x00  MultiChannel 7.1 Surround right
    [ 0]:[ 8] 0x00     0x01     0x06   0x04 0x00  SpdifOut 1 left
    [ 0]:[ 9] 0x05     0x02     0x06   0x04 0x00  SpdifOut 1 right
    [ 0]:[10] 0x0a     0x01     0x0d   0x0a 0x00  MidiOut2
    [ 0]:[11] 0x0a     0x02     0x0d   0x0a 0x00  MidiOut2


If you don't get this, check if you have multiple host controllers, and 
use the -p parameter to specify them. If you get any error messages, the 
best way to help us figure out what the problem might be is to build the 
debug version (scons ENABLE_DEBUG=1). You can then rerun the test
application (with -v5) and send us its output.