root/trunk/libffado/README

Revision 2026, 10.1 kB (checked in by jwoithe, 12 years ago)

Minor updates to MOTU references in README. The official spelling of Traveler uses the US convention (ie: one l). Remove references to the qt3 mixer since that's no longer in trunk.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
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 that have been reported to (partially) work with the generic support:
70 * Presonus FireBox
71 * Presonus FirePod / FP10
72 * Alesis io14
73 * TC Konnekt 8, Konnekt 24D, Konnekt Live
74
75 Usupported devices:
76 * Presonus FireStation
77 * Presonus FireStudio (all variants)
78 * Other TC Konnekt devices
79 * Other Alesis devices
80 * Metric Halo devices
81 * RME Firewire devices
82
83 We constantly try to persuade vendors to help us extend our device support.
84
85 Dependencies
86 ------------
87
88 To build libffado you need several libraries. For all libraries a
89 version is provided which is a 'known good' version.  The first few
90 libraries it seems it is not necessary that the version must
91 match. The chances that it works also with an older versions are good:
92
93 libxml++2   (>= 2.6.13)
94
95 These libraries here should be at least the version listed:
96
97 libraw1394  (>= 2.0.7),  https://ieee1394.wiki.kernel.org/
98 libiec61883 (>= 1.1.0),  https://ieee1394.wiki.kernel.org/
99 dbus-1      (>= 1.0),    http://dbus.freedesktop.org
100 dbus-c++    (>= 0),      http://sourceforge.net/apps/mediawiki/dbus-cplusplus/
101 libconfig   (>= 0),      http://www.hyperrealm.com/libconfig/
102 Currently only the jackd audio server is supported.
103
104 jackd (>= 0.109.12), http://jackaudio.org
105 [NOTE: at the time of writing, this is the development (SVN) version.]
106
107 Optionally, but recommended is that you install qjackctl:
108
109 qjackctl (>= 0.2.20.10), http://sourceforge.net/projects/qjackctl
110
111 To build the optional ffado device mixer control utility you also require:
112
113 Qt  >= 4.0,            http://trolltech.com/products/qt
114 SIP >= 4.7.0,          http://www.riverbankcomputing.co.uk/software/sip/intro
115 PyQt (note below),     http://www.riverbankcomputing.co.uk/software/pyqt/intro
116 dbus-python >= 0.82.0, http://dbus.freedesktop.org/releases/dbus-python/
117
118 The version of PyQt must be chosen to exactly match the version of Qt in use.
119 For Qt 4.x use PyQt 4.x.
120
121 SIP is only required to compile PyQt.  If using a binary package of PyQt
122 SIP should not be needed.
123
124 How to build
125 ------------
126
127 If you want to build the release version you can simply do following:
128
129 $ scons
130 $ scons install
131
132 If you want some debug information (because something seems not
133 to work correctly) you can try to do following:
134
135 $ scons DEBUG=yes
136 $ scons install
137
138 More extended instructions can be found here:
139 http://subversion.ffado.org/wiki/CompilationGuides
140
141 NOTE: In order to build jackd with ffado support, you have
142 to install libffado before you build jackd. The backend to use in jackd is
143 firewire.
144
145 NOTE: the beta versions are distributed with debugging enabled by default.
146
147 DISTRIBUTION PACKAGERS NOTE: Please do not enable support for devices
148 if it is not on by default. If device support for a specific device
149 is not turned on by default by the developers, it means that it is not
150 ready yet. Most of the time it is placeholder code for future devices.
151
152 Running jackd
153 -------------
154
155 The easiest way to run this is using qjackctl. There are only minor
156 differences with the other backends, however you should change some
157 of the default values:
158 - It is recommended to change the 'periods/buffer' field to 3, especially
159   if you use low period sizes (=< 128)
160 - It is recommended to raise the RT priority to 70.
161
162 In order to get it running from the command line, you need to provide some
163 arguments to jackd.
164
165 Run
166
167 $ jackd -d firewire --help
168
169 to see the backend options. You can easily figure out how to set them using
170 the remarks given above (for qjackctl).
171
172 For the other aspects of jackd usage, consult the jackd documentation.
173
174 Here is a sample session (without realtime support enabled):
175
176     $ jackd -d firewire
177     no message buffer overruns
178     jackd 0.111.0
179     Copyright 2001-2005 Paul Davis and others.
180     jackd comes with ABSOLUTELY NO WARRANTY
181     This is free software, and you are welcome to redistribute it
182     under certain conditions; see the file COPYING for details
183    
184     JACK compiled with System V SHM support.
185     loading driver ..
186     3106528665:  (ffado.cpp)[  99] ffado_streaming_init: libffado 1.999.20 built Apr 26 2008 20:26:32
187     libiec61883 warning: Established connection on channel 0.
188     You may need to manually set the channel on the receiving node.
189     libiec61883 warning: Established connection on channel 1.
190     You may need to manually set the channel on the transmitting node.
191
192 (Note: you can safely ignore the libiec61883 warnings, they are normal.)
193
194 An important remark is that for good performance, one should always run jack
195 with the -R flag to enable realtime scheduling for critical threads:
196     $ jackd -R -d firewire
197
198 In case of problems
199 -------------------
200
201 First of all, check whether your problem is in fact a problem, and
202 whether it is a FFADO problem. The magic tool for this is google.
203
204 User support is a rather annoying occupation, especially since it sucks
205 time from developers that are not paid for developing, let alone for doing
206 user support. Please make sure that you have checked the following places:
207     http://www.ffado.org/
208     http://subversion.ffado.org/
209     http://www.google.com/
210       (the terms "ffado-devel" "ffado-user" or "freebob-user" work great)
211 Some might consider this a bit arrogant or "newbie-unfriendly", but personally
212 I (Pieter Palmers) consider this a matter of politeness towards the developers.
213
214 If you have tried to find a solution to your problem, but you couldn't find
215 one or are confused, don't hesitate to ask for help. The preferred way is by
216 signing up to the mailing list as described on http://www.ffado.org/?q=contact.
217
218 Writing a bug report
219 --------------------
220
221 Note that the more effort you put in your bug report, the more effort we
222 will put into helping you.
223
224 Make sure you have compiled a DEBUG=yes version of
225 libffado. If not there is no way we can trace the problem.
226
227 When reporting a problem, please run jackd with the --verbose option,
228 and add the -v6 option to the firewire backend:
229     $ jackd --verbose [...] -d firewire -v6 [...]
230
231     ( [...] = other options )
232
233 This will generate an increadible amount of debug output that should
234 contain what we need to track down the problem. If you have troubles
235 saving the output, try redirecting it to a file:
236
237     $ jackd --verbose -d firewire -v6 2> ffado-jack.log
238
239 this will create a ffado.log file containing the output. Use CTRL-C
240 to exit jack if necessary.
241
242 The distribution contains a tool to gather some information about your
243 system. you can run it as follows:
244
245     $ cd support/tools
246     $ python ffado-diag.py > ffado-diag.log
247
248 It will check your system for basic problems and gather some information
249 regarding your hardware configuration. This will allow us to diagnose
250 your problem faster.
251
252 Once the logs have been created you can create a support ticket at
253 http://subversion.ffado.org/newticket
254
255 Be sure to include the following information:
256 * the log file(s) (zipped/tar.gz'ed and attached)
257 * the device you're trying to use
258 * a description of what went wrong and how to reproduce it. You
259   preferrably try to figure out a sequence of steps that can reliably
260   reproduce the issue on your system. A one-time failure is very difficult
261   to diagnose and/or fix.
262 * the distribution and its version
Note: See TracBrowser for help on using the browser.