root/trunk/libffado/README

Revision 2719, 13.0 kB (checked in by jwoithe, 2 months ago)

README: update for version 2.4.0.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 FFADO v2.4
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 FFADO uses the scons build system, which must be available on the system
118 when building FFADO.  It is not a runtime dependency.  Scons 2 is currently
119 used to build FFADO.  Work continues on making FFADO's scons scripts
120 compatible with both scons 2 and 3.  Testing and bug reports when using
121 scons 3 are welcomed.
122
123 To build libffado you need several libraries. For all libraries a
124 version is provided which is a 'known good' version.  The first few
125 libraries it seems it is not necessary that the version must
126 match. The chances that it works also with an older versions are good:
127
128 libxml++2   (>= 2.6.13)
129
130 These libraries here should be at least the version listed:
131
132 libraw1394  (>= 2.0.7),  https://ieee1394.wiki.kernel.org/
133 libiec61883 (>= 1.1.0),  https://ieee1394.wiki.kernel.org/
134 dbus-1      (>= 1.0),    http://dbus.freedesktop.org
135 dbus-c++    (>= 0),      http://sourceforge.net/apps/mediawiki/dbus-cplusplus/
136 libconfig   (>= 0),      http://www.hyperrealm.com/libconfig/
137
138 Currently only the jackd audio server is supported:
139   jackd (>= 0.109.12), http://jackaudio.org
140
141 While jack1 0.109.12 will work, jack1 >= 0.122.0 or jack2 >= 1.9.9 are
142 recommended if support for jack's setbufsize functionality is desired.
143
144 Optionally, but recommended is that you install qjackctl:
145
146 qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl
147
148 To build the optional ffado device mixer control utility you also require:
149
150 Qt  >= 4.0,            http://qt-project.org/
151 SIP >= 4.7.0,          http://www.riverbankcomputing.co.uk/software/sip/intro
152 PyQt (note below),     http://www.riverbankcomputing.co.uk/software/pyqt/intro
153 dbus-python >= 0.82.0, http://dbus.freedesktop.org/releases/dbus-python/
154
155 The version of PyQt must be chosen to exactly match the version of Qt in use.
156 For Qt 4.x use PyQt 4.x.
157
158 SIP is only required to compile PyQt.  If using a binary package of PyQt
159 SIP should not be needed.
160
161 How to build
162 ------------
163
164 If you want to build the release version you can simply do following:
165
166 $ scons
167 $ scons install
168
169 If you want some debug information (because something seems not
170 to work correctly) you can try to do following:
171
172 $ scons DEBUG=yes
173 $ scons install
174
175 More extended instructions can be found here:
176 http://subversion.ffado.org/wiki/InstallingFfadoFromSource
177
178 NOTE: In order to build jackd with ffado support, you have
179 to install libffado before you build jackd. The backend to use in jackd is
180 firewire.
181
182 NOTE: the beta versions are distributed with debugging enabled by default.
183
184 DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
185 if it is not on by default. If device support for a specific device
186 is not turned on by default by the developers, it means that it is not
187 ready yet. Most of the time it is placeholder code for future devices.
188
189 Running jackd
190 -------------
191
192 The easiest way to run this is using qjackctl. There are only minor
193 differences with the other backends, however you should change some
194 of the default values:
195 - It is recommended to change the 'periods/buffer' field to 3, especially
196   if you use low period sizes (=< 128)
197 - It is recommended to raise the RT priority to 70.
198
199 In order to get it running from the command line, you need to provide some
200 arguments to jackd.
201
202 Run
203
204 $ jackd -d firewire --help
205
206 to see the backend options. You can easily figure out how to set them using
207 the remarks given above (for qjackctl).
208
209 For the other aspects of jackd usage, consult the jackd documentation.
210
211 Here is a sample session (without realtime support enabled):
212
213     $ jackd -d firewire
214     no message buffer overruns
215     jackd 0.111.0
216     Copyright 2001-2005 Paul Davis and others.
217     jackd comes with ABSOLUTELY NO WARRANTY
218     This is free software, and you are welcome to redistribute it
219     under certain conditions; see the file COPYING for details
220    
221     JACK compiled with System V SHM support.
222     loading driver ..
223     3106528665:  (ffado.cpp)[  99] ffado_streaming_init: libffado 1.999.20 built Apr 26 2008 20:26:32
224     libiec61883 warning: Established connection on channel 0.
225     You may need to manually set the channel on the receiving node.
226     libiec61883 warning: Established connection on channel 1.
227     You may need to manually set the channel on the transmitting node.
228
229 (Note: you can safely ignore the libiec61883 warnings, they are normal.)
230
231 An important remark is that for good performance, one should always run jack
232 with the -R flag to enable realtime scheduling for critical threads:
233     $ jackd -R -d firewire
234 In most cases this is now the default.
235
236 For best results across most hardware it is necessary to use a kernel
237 configured with the "Low latency desktop" option (CONFIG_PREEMPT) enabled.
238 Most distributions provide this as an option, often called "low latency".
239 In general it is no longer necessary to use an RT-patched kernel.
240
241 In case of problems
242 -------------------
243
244 First of all, check whether your problem is a known issue, and whether
245 it is a FFADO problem.  Use your chosen web search engine for this.
246
247 Many distributor kernels now include the alternative ALSA audio streaming
248 drivers for selected firewire audio interfaces (snd-bebob, snd-dice, etc).
249 These are developed independently of FFADO.  If these kernel modules are
250 loaded then FFADO's streaming engine cannot be used: using jackd's
251 "firewire" driver will fail because the kernel drivers have ownership of the
252 interface.  To continue to use FFADO's streaming system, the applicable
253 snd-* module must be unloaded from the kernel and prevented from loading on
254 boot.  Use "rmmod" to remove the module from the running system, and
255 blacklist the relevant snd-* module in a file under /lib/modprobe.d/ (or
256 your distribution's equivalent).
257
258 When seeking support from the developers keep in mind that none of the FFADO
259 developers are paid to work on FFADO or to support FFADO users.  Answering
260 the same question multiple times reduces the amount of time they have to
261 work on the code.  Before contacting the developers please see if your query
262 or problem has been seen before.  The following places are helpful:
263  * http://www.ffado.org/
264  * http://subversion.ffado.org/
265  * your chosen search engine
266    (the terms "ffado-devel" and "ffado-user" work well)
267
268 If you have tried to find a solution to your problem but couldn't or are
269 confused, don't hesitate to ask for help.  The preferred way is by signing
270 up to the mailing list as described on http://www.ffado.org/?q=contact.
271
272 Writing a bug report
273 --------------------
274
275 Note that the more effort you put in your bug report, the more effort we
276 will put into helping you.
277
278 Make sure you have compiled a DEBUG=yes version of
279 libffado. If not there is no way we can trace the problem.
280
281 When reporting a problem, please run jackd with the --verbose option,
282 and add the -v6 option to the firewire backend:
283     $ jackd --verbose [...] -d firewire -v6 [...]
284
285     ( [...] = other options )
286
287 This will generate an increadible amount of debug output that should
288 contain what we need to track down the problem. If you have troubles
289 saving the output, try redirecting it to a file:
290
291     $ jackd --verbose -d firewire -v6 2> ffado-jack.log
292
293 this will create a ffado.log file containing the output. Use CTRL-C
294 to exit jack if necessary.
295
296 The distribution contains a tool to gather some information about your
297 system. When FFADO is installed on the system it can be run directly:
298
299     $ ffado-diag > ffado-diag.log
300
301 It is also possible to run it from the source tree:
302
303     $ cd support/tools
304     $ python ffado-diag.py > ffado-diag.log
305
306 It will check your system for basic problems and gather some information
307 regarding your hardware configuration. This will allow us to diagnose
308 your problem faster.
309
310 Once the logs have been created you can create a support ticket at
311 http://subversion.ffado.org/newticket
312
313 Be sure to include the following information:
314 * the log file(s) (zipped/tar.gz'ed and attached)
315 * the device you're trying to use
316 * a description of what went wrong and how to reproduce it. You
317   preferrably try to figure out a sequence of steps that can reliably
318   reproduce the issue on your system. A one-time failure is very difficult
319   to diagnose and/or fix.
320 * the distribution and its version
Note: See TracBrowser for help on using the browser.