root/trunk/libffado/README

FFADO v2.4
==========

The FFADO project aims to provide a free driver implementation for FireWire
(IEEE1394, iLink) based 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 pass-through 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 its multiprocessor variant
jackdmp.  At present there is no support for ALSA or pulseaudio, although
jack bridging solutions may help in some situations.

Access to the device internal configuration (the internal mixer and device
settings) is exposed using the ffado-dbus-server daemon.  This daemon
exposes the configurable parameters of all detected devices through DBUS. 
The ffado-mixer application in support/mixer/ presents a GUI to control these
parameters.

Features
--------

* 24-bit audio input/output (number of channels only limited by interface
  hardware)
* supports for all sample rates 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 "officially supported" label is only given to devices that fulfil the
following:
 * at least one of the developers has the device
 * the vendor provides development support (access to information)
 * the device works

The devices which are officially supported are:
 * ESI Quatafire 610
 * Terratec Producer Phase 88
 * Focusrite Saffire (original/white)
 * Focusrite Saffire Pro10
 * Focusrite Saffire Pro26
 * Focusrite Saffire Pro14, Pro40
 * ECHO AudioFire2, AudioFire4, AudioFire8, AudioFire12
 * Mackie Onyx Mixer FireWire expansion
 * RME Fireface 400, RME Fireface 800

The FFADO 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, the ECHO FireWorks platform or the TC Electronics DICE platform will
work, at least to a certain extent.  For some devices specific functions
have been added to augment the generic framework and provide enhanced
support, usually in the area of device and mixer control.

FFADO includes device-specific functionality for following devices.  The
code has been developed based on feedback received from users, and it has
been reported to work by users.  Note that FFADO may not support all device
functions.
 * Presonus Firebox and Inspire1394
 * Presonus FireStudio Tube, FireStudio Project
 * M-Audio Ozonic, FireWire Solo
 * M-Audio Profire 2626, 610
 * M-Audio Audiophile and 410 (latest firmware and startup workaround needed,
   see http://sourceforge.net/p/ffado/mailman/message/30807938)
 * M-Audio 1814 and ProjectMix (mixer only, audio streaming not supported. and
   FireWire 1814 needs startup workaround above)
 * Focusrite Saffire Pro24
 * Focusrite Saffire Pro24 DSP (audio streaming only, DSP control not available)
 * Yamaha GO44 and GO46

Devices that have been reported to (partially) work with the generic support:
 * Presonus FirePod / FP10
 * Alesis io14
 * TC Konnekt 8, Konnekt 24D, Konnekt Live

As a result of a significant reverse-engineering effort a selection of
devices from MOTU are supported.  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 who are hostile towards
Linux like 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. 
MOTU devices reported to work with FFADO are:
 * MOTU Traveler
 * MOTU 828mkII, MOTU Ultralite, MOTU 896HD, MOTU 8pre, MOTU 4pre
 * Audio only: MOTU Ultralite mk3, MOTU Traveler mk3, MOTU 896mk3, MOTU 828mk3
 * Audio only, FireWire interface only: MOTU Ultralite mk3 hybrid

"Audio only" means that FFADO can be used to stream audio to and from the
device, control sample rate and clock source.  Control of the mixer and DSP
functions is not presently supported.  It is planned but no ETA is available
at this stage.

Devices for which work is in progress.  These are not yet usable:
 * RME UFX and UCX FireWire devices

Usupported devices:
 * Presonus FireStation
 * Other TC Konnekt devices
 * Other Alesis devices
 * Metric Halo devices

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

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

FFADO uses the scons build system, which must be available on the system
when building FFADO.  It is not a runtime dependency.  Scons 2 is currently
used to build FFADO.  Work continues on making FFADO's scons scripts
compatible with both scons 2 and 3.  Testing and bug reports when using
scons 3 are welcomed.

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:

libxml++2   (>= 2.6.13)

These libraries here should be at least the version listed:

libraw1394  (>= 2.0.7),  https://ieee1394.wiki.kernel.org/
libiec61883 (>= 1.1.0),  https://ieee1394.wiki.kernel.org/
dbus-1      (>= 1.0),    http://dbus.freedesktop.org
dbus-c++    (>= 0),      http://sourceforge.net/apps/mediawiki/dbus-cplusplus/
libconfig   (>= 0),      http://www.hyperrealm.com/libconfig/

Currently only the jackd audio server is supported:
  jackd (>= 0.109.12), http://jackaudio.org

While jack1 0.109.12 will work, jack1 >= 0.122.0 or jack2 >= 1.9.9 are
recommended if support for jack's setbufsize functionality is desired. 

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  >= 4.0,            http://qt-project.org/
SIP >= 4.7.0,          http://www.riverbankcomputing.co.uk/software/sip/intro
PyQt (note below),     http://www.riverbankcomputing.co.uk/software/pyqt/intro 
dbus-python >= 0.82.0, http://dbus.freedesktop.org/releases/dbus-python/

The version of PyQt must be chosen to exactly match the version of Qt in use.
For Qt 4.x use PyQt 4.x.

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

Packages for building on Debian/Ubuntu distributions are installed with:

$ sudo apt-get install build-essential subversion scons libxml++2.6-dev \
               libiec61883-dev libdbus-1-dev libdbus-c++-bin \
               libdbus-c++-dev libconfig++-dev pyqt5-dev-tools \
               python3-dbus.mainloop.pyqt5 pyqt5-sip

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

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

$ scons
$ scons install      [as root or via sudo]

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

$ scons DEBUG=yes
$ scons install      [as root or via sudo]

Cleaning a build is done with:

$ scons -c -Q

More extended instructions can be found here:
http://subversion.ffado.org/wiki/InstallingFfadoFromSource

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".

NOTE: the beta versions are distributed with debugging enabled by default.

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:
- 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):

    $ jackd -d firewire
    no message buffer overruns
    jackd 0.111.0
    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 ..
    3106528665:  (ffado.cpp)[  99] ffado_streaming_init: libffado 1.999.20 built Apr 26 2008 20:26:32
    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.)

An important remark is that for good performance, one should always run jack
with the -R flag to enable realtime scheduling for critical threads:
    $ jackd -R -d firewire
In most cases this is now the default.

For best results across most hardware it is necessary to use a kernel
configured with the "Low latency desktop" option (CONFIG_PREEMPT) enabled. 
Most distributions provide this as an option, often called "low latency". 
In general it is no longer necessary to use an RT-patched kernel.

Ffado-mixer look and feel
-------------------------

The look and feel of ffado-mixer can be changed via QT themes.  When a dark
mode is required, install a suitable QT theme.  Some users have found the
dark theme from UKUI to work well with ffado-mixer (often available in
distributions through the qt5-ukui-platformtheme package).

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

First of all, check whether your problem is a known issue, and whether
it is a FFADO problem.  Use your chosen web search engine for this.

Many distributor kernels now include the alternative ALSA audio streaming
drivers for selected FireWire audio interfaces (snd-bebob, snd-dice, etc). 
These are developed independently of FFADO.  If these kernel modules are
loaded then FFADO's streaming engine cannot be used: using jackd's
"firewire" driver will fail because the kernel drivers have ownership of the
interface.  To continue to use FFADO's streaming system, the applicable
snd-* module must be unloaded from the kernel and prevented from loading on
boot.  Use "rmmod" to remove the module from the running system, and
blacklist the relevant snd-* module in a file under /lib/modprobe.d/ (or
your distribution's equivalent).

When seeking support from the developers keep in mind that none of the FFADO
developers are paid to work on FFADO or to support FFADO users.  Answering
the same question multiple times reduces the amount of time they have to
work on the code.  Before contacting the developers please see if your query
or problem has been seen before.  The following places are helpful:
 * http://www.ffado.org/
 * http://subversion.ffado.org/
 * your chosen search engine
   (the terms "ffado-devel" and "ffado-user" work well)

If you have tried to find a solution to your problem but couldn't or are
confused, don't hesitate to ask for help.  The preferred way is by signing
up to the mailing list as described on http://www.ffado.org/?q=contact.

Writing a bug report
--------------------

Note that the more effort you put in your bug report, the more effort we
will put into helping you.

Make sure you have compiled a DEBUG=yes version of
libffado. If not there is no way we can trace the problem.

When reporting a problem, please run jackd with the --verbose option,
and add the -v6 option to the firewire backend:
    $ jackd --verbose [...] -d firewire -v6 [...]

    ( [...] = other options )

This will generate an increadible amount of debug output that should
contain what we need to track down the problem. If you have troubles
saving the output, try redirecting it to a file:

    $ jackd --verbose -d firewire -v6 2> ffado-jack.log

this will create a ffado.log file containing the output. Use CTRL-C
to exit jack if necessary.

The distribution contains a tool to gather some information about your
system. When FFADO is installed on the system it can be run directly:

    $ ffado-diag > ffado-diag.log

It is also possible to run it from the source tree:

    $ cd support/tools
    $ python ffado-diag.py > ffado-diag.log

It will check your system for basic problems and gather some information
regarding your hardware configuration. This will allow us to diagnose
your problem faster.

Once the logs have been created you can create a support ticket at
http://subversion.ffado.org/newticket

Be sure to include the following information:
* the log file(s) (zipped/tar.gz'ed and attached)
* the device you're trying to use
* a description of what went wrong and how to reproduce it. You
  preferably try to figure out a sequence of steps that can reliably
  reproduce the issue on your system. A one-time failure is very difficult
  to diagnose and/or fix.
* the distribution and its version