libffado/README

   1 FFADO v2.2
   2 ==========
   3
   4 The FFADO project aims to provide a free driver implemenation for FireWire
   5 (IEEE1394, iLink) based audio interfaces.  The focus of the project are on
   6 audio/music production rather than consumer audio.  This means that although
   7 we intend to supported all features at some point, consumer features are
   8 considered less important.  The most obvious example of a consumer feature
   9 is AC3/DTS passthrough support, which is unsupported at the moment.
  10
  11 This package provides the libffado shared library that provides a unified
  12 programming interface to configure and use all supported devices.  Currently
  13 this library is used by the 'firewire' backends of the jack audio connection
  14 kit sound server (jackaudio.org).  This backend provides audio and midi
  15 support, and is available both in jackd and its multiprocessor variant
  16 jackdmp.  At present there is no support for ALSA or pulseaudio, although
  17 jack bridging solutions may help in some situations.
  18
  19 Access to the device internal configuration (the internal mixer and device
  20 settings) is exposed using the ffado-dbus-server daemon.  This daemon
  21 exposes the configurable parameters of all detected devices through DBUS.
  22 The ffado-mixer application in support/mixer/ presents a GUI to control these
  23 parameters.
  24
  25 Features
  26 --------
  27 * 24-bit audio input/output (number of channels only limited by interface
  28   hardware)
  29 * supports for all samplerates a device supports
  30 * MIDI input/output (unlimited number of channels)
  31 * Support for S/PDIF and ADAT/SMUX I/O
  32 * Internal mixer and device control support for all officially supported
  33   devices (NOTE: no support for internal DSP)
  34 * Support for device aggregation (limited to devices on the same bus)
  35
  36 Device Support
  37 --------------
  38
  39 The 'officially supported' label is only given to devices that fulfil the
  40 following:
  41  * at least one of the developers has the device
  42  * the vendor provides development support (access to information)
  43  * the device works
  44
  45 The devices which are officially supported are:
  46  * ESI Quatafire 610
  47  * Terratec Producer Phase 88
  48  * Focusrite Saffire (original/white)
  49  * Focusrite Saffire Pro10
  50  * Focusrite Saffire Pro26
  51  * Focusrite Saffire Pro14, Pro40
  52  * ECHO AudioFire2, AudioFire4, AudioFire8, AudioFire12
  53  * Mackie Onyx Mixer FireWire expansion
  54  * RME Fireface 400, RME Fireface 800
  55
  56 The FFADO driver is written to provide generic support for all devices it
  57 might be able to handle.  This means that most devices based on the BridgeCo
  58 BeBoB, the ECHO FireWorks platform or the TC Electronics DICE platform will
  59 work, at least to a certain extent.  For some devices specific functions
  60 have been added to augment the generic framework and provide enhanced
  61 support, usually in the area of device and mixer control.
  62
  63 FFADO includes device-specific functionality for following devices.  The
  64 code has been developed based on feedback received from users, and it has
  65 been reported to work by users.  Note that FFADO may not support all device
  66 functions.
  67  * Presonus Firebox and Inspire1394
  68  * Presonus FireStudio Tube, FireStudio Project
  69  * M-Audio Ozonic, Firewire Solo
  70  * M-Audio Profire 2626
  71  * M-Audio Audiophile and 410 (latest firmware and startup workaround needed,
  72    see http://sourceforge.net/p/ffado/mailman/message/30807938)
  73  * M-Audio 1814 and ProjectMix (mixer only, audio streaming not supported. and
  74    Firewire 1814 needs startup workaround above)
  75  * Focusrite Saffire Pro24
  76  * Focusrite Saffire Pro24DSP (audio streaming only, DSP control not available)
  77  * Yamaha GO44 and GO46
  78
  79 Devices that have been reported to (partially) work with the generic support:
  80  * Presonus FirePod / FP10
  81  * Alesis io14
  82  * TC Konnekt 8, Konnekt 24D, Konnekt Live
  83
  84 As a result of a significant reverse-engineering effort a selection of
  85 devices from MOTU are supported.  The developers had no support from the
  86 device vendor and this of course limits the extent to which problems can be
  87 solved.  You have been warned.  Please do not buy devices for which support
  88 is based upon reverse engineering, nor from vendors who are hostile towards
  89 Linux like MOTU.  Value the support that some vendors provide and buy their
  90 stuff.  Check ffado.org for details.  It can't be said enough: currently it
  91 is extremely unwise to buy a MOTU device if you intend to use Linux.
  92 MOTU devices reported to work with FFADO are:
  93  * MOTU Traveler
  94  * MOTU 828mkII, MOTU Ultralite, MOTU 896HD, MOTU 8pre, MOTU 4pre
  95  * Audio only: MOTU Ultralite mk3, MOTU Traveler mk3, MOTU 896mk3, MOTU 828mk3
  96  * Audio only, firewire interface only: MOTU Ultralite mk3 hybrid
  97
  98 "Audio only" means that FFADO can be used to stream audio to and from the
  99 device, control sample rate and clock source.  Control of the mixer and DSP
 100 functions is not presently supported.  It is planned but no ETA is available
 101 at this stage.
 102
 103 Devices for which work is in progress.  These are not yet usable:
 104  * RME UFX and UCX firewire devices
 105
 106 Usupported devices:
 107  * Presonus FireStation
 108  * Other TC Konnekt devices
 109  * Other Alesis devices
 110  * Metric Halo devices
 111
 112 We constantly try to persuade vendors to help us extend our device support.
 113
 114 Dependencies
 115 ------------
 116
 117 To build libffado you need several libraries. For all libraries a
 118 version is provided which is a 'known good' version.  The first few
 119 libraries it seems it is not necessary that the version must
 120 match. The chances that it works also with an older versions are good:
 121
 122 libxml++2   (>= 2.6.13)
 123
 124 These libraries here should be at least the version listed:
 125
 126 libraw1394  (>= 2.0.7),  https://ieee1394.wiki.kernel.org/
 127 libiec61883 (>= 1.1.0),  https://ieee1394.wiki.kernel.org/
 128 dbus-1      (>= 1.0),    http://dbus.freedesktop.org
 129 dbus-c++    (>= 0),      http://sourceforge.net/apps/mediawiki/dbus-cplusplus/
 130 libconfig   (>= 0),      http://www.hyperrealm.com/libconfig/
 131
 132 Currently only the jackd audio server is supported:
 133   jackd (>= 0.109.12), http://jackaudio.org
 134
 135 While jack1 0.109.12 will work, jack1 >= 0.122.0 or jack2 >= 1.9.9 are
 136 recommended if support for jack's setbufsize functionality is desired.
 137 [NOTE: at the time of writing, jack1 0.122.0 and jack2 1.9.9 are the
 138 development (SVN) versions.]
 139
 140 Optionally, but recommended is that you install qjackctl:
 141
 142 qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl
 143
 144 To build the optional ffado device mixer control utility you also require:
 145
 146 Qt  >= 4.0,            http://qt-project.org/
 147 SIP >= 4.7.0,          http://www.riverbankcomputing.co.uk/software/sip/intro
 148 PyQt (note below),     http://www.riverbankcomputing.co.uk/software/pyqt/intro
 149 dbus-python >= 0.82.0, http://dbus.freedesktop.org/releases/dbus-python/
 150
 151 The version of PyQt must be chosen to exactly match the version of Qt in use.
 152 For Qt 4.x use PyQt 4.x.
 153
 154 SIP is only required to compile PyQt.  If using a binary package of PyQt
 155 SIP should not be needed.
 156
 157 How to build
 158 ------------
 159
 160 If you want to build the release version you can simply do following:
 161
 162 $ scons
 163 $ scons install
 164
 165 If you want some debug information (because something seems not
 166 to work correctly) you can try to do following:
 167
 168 $ scons DEBUG=yes
 169 $ scons install
 170
 171 More extended instructions can be found here:
 172 http://subversion.ffado.org/wiki/CompilationGuides
 173
 174 NOTE: In order to build jackd with ffado support, you have
 175 to install libffado before you build jackd. The backend to use in jackd is
 176 firewire.
 177
 178 NOTE: the beta versions are distributed with debugging enabled by default.
 179
 180 DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
 181 if it is not on by default. If device support for a specific device
 182 is not turned on by default by the developers, it means that it is not
 183 ready yet. Most of the time it is placeholder code for future devices.
 184
 185 Running jackd
 186 -------------
 187
 188 The easiest way to run this is using qjackctl. There are only minor
 189 differences with the other backends, however you should change some
 190 of the default values:
 191 - It is recommended to change the 'periods/buffer' field to 3, especially
 192   if you use low period sizes (=< 128)
 193 - It is recommended to raise the RT priority to 70.
 194
 195 In order to get it running from the command line, you need to provide some
 196 arguments to jackd.
 197
 198 Run
 199
 200 $ jackd -d firewire --help
 201
 202 to see the backend options. You can easily figure out how to set them using
 203 the remarks given above (for qjackctl).
 204
 205 For the other aspects of jackd usage, consult the jackd documentation.
 206
 207 Here is a sample session (without realtime support enabled):
 208
 209     $ jackd -d firewire
 210     no message buffer overruns
 211     jackd 0.111.0
 212     Copyright 2001-2005 Paul Davis and others.
 213     jackd comes with ABSOLUTELY NO WARRANTY
 214     This is free software, and you are welcome to redistribute it
 215     under certain conditions; see the file COPYING for details
 216
 217     JACK compiled with System V SHM support.
 218     loading driver ..
 219     3106528665:  (ffado.cpp)[  99] ffado_streaming_init: libffado 1.999.20 built Apr 26 2008 20:26:32
 220     libiec61883 warning: Established connection on channel 0.
 221     You may need to manually set the channel on the receiving node.
 222     libiec61883 warning: Established connection on channel 1.
 223     You may need to manually set the channel on the transmitting node.
 224
 225 (Note: you can safely ignore the libiec61883 warnings, they are normal.)
 226
 227 An important remark is that for good performance, one should always run jack
 228 with the -R flag to enable realtime scheduling for critical threads:
 229     $ jackd -R -d firewire
 230 In most cases this is now the default.
 231
 232 For best results across most hardware it is necessary to use a kernel
 233 configured with the "Low latency desktop" option (CONFIG_PREEMPT) enabled.
 234 Most distributions provide this as an option, often called "low latency".
 235 In general it is no longer necessary to use an RT-patched kernel.
 236
 237 In case of problems
 238 -------------------
 239
 240 First of all, check whether your problem is in fact a problem, and whether
 241 it is a FFADO problem.  The magic tool for this is google.
 242
 243 When seeking support from the developers keep in mind that none of the FFADO
 244 developers are paid to work on FFADO or to support FFADO users.  Answering
 245 the same question multiple times reduces the amount of time they have to
 246 work on the code.  Before contacting the developers please see if your query
 247 or problem has been seen before.  The following places are helpful:
 248  * http://www.ffado.org/
 249  * http://subversion.ffado.org/
 250  * http://www.google.com/
 251    (the terms "ffado-devel" and "ffado-user" work well)
 252
 253 If you have tried to find a solution to your problem but couldn't or are
 254 confused, don't hesitate to ask for help.  The preferred way is by signing
 255 up to the mailing list as described on http://www.ffado.org/?q=contact.
 256
 257 Writing a bug report
 258 --------------------
 259
 260 Note that the more effort you put in your bug report, the more effort we
 261 will put into helping you.
 262
 263 Make sure you have compiled a DEBUG=yes version of
 264 libffado. If not there is no way we can trace the problem.
 265
 266 When reporting a problem, please run jackd with the --verbose option,
 267 and add the -v6 option to the firewire backend:
 268     $ jackd --verbose [...] -d firewire -v6 [...]
 269
 270     ( [...] = other options )
 271
 272 This will generate an increadible amount of debug output that should
 273 contain what we need to track down the problem. If you have troubles
 274 saving the output, try redirecting it to a file:
 275
 276     $ jackd --verbose -d firewire -v6 2> ffado-jack.log
 277
 278 this will create a ffado.log file containing the output. Use CTRL-C
 279 to exit jack if necessary.
 280
 281 The distribution contains a tool to gather some information about your
 282 system. you can run it as follows:
 283
 284     $ cd support/tools
 285     $ python ffado-diag.py > ffado-diag.log
 286
 287 It will check your system for basic problems and gather some information
 288 regarding your hardware configuration. This will allow us to diagnose
 289 your problem faster.
 290
 291 Once the logs have been created you can create a support ticket at
 292 http://subversion.ffado.org/newticket
 293
 294 Be sure to include the following information:
 295 * the log file(s) (zipped/tar.gz'ed and attached)
 296 * the device you're trying to use
 297 * a description of what went wrong and how to reproduce it. You
 298   preferrably try to figure out a sequence of steps that can reliably
 299   reproduce the issue on your system. A one-time failure is very difficult
 300   to diagnose and/or fix.
 301 * the distribution and its version