libffado/README

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