root/branches/libffado-2.0/README

Revision 1390, 10.3 kB (checked in by ppalmers, 15 years ago)

fix typo

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