root/trunk/libffado/README

Revision 2811, 13.8 kB (checked in by jwoithe, 1 year ago)

Cosmetic: "firewire" should be "FireWire?" when used as the bus name.

Similarly to r2802 and r2810, "FireWire?" should be used when referring to
the name of the bus. This patch corrects this throughout the source tree
for completeness. While there are a small number of mostly debug output
strings affected, most of the changes are to comments or developer documents
where they are of little consequence. Thanks to Pander who suggested the
need to look into this on the ffado-devel mailing list.

At least in theory, remaining instances of "firewire" in the source tree
should remain as they are because they refer to case-sensitive identifiers
defined externally (such as the "firewire" jackd backend name).

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