root/trunk/libffado/README

Revision 2672, 12.0 kB (checked in by jwoithe, 2 months ago)

README: fix URL to compilation guides. Thanks to Shalok Shalom for pointing out the error (via ffado-user mailing list).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
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/InstallingFfadoFromSource
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
Note: See TracBrowser for help on using the browser.