Skip to content
This repository
Newer
Older
100644 193 lines (147 sloc) 8.92 kb
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
1 Folve - FUSE convolve
26fd15ac »
2012-09-21 o README fiddling.
2 =====================
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
3 Folve is a FUSE filesystem that convolves audio files on-the-fly.
5ef3f972 »
2012-09-21 o README -> README.md
4
5 Overview
6 --------
a9d3e538 »
2012-09-15 o Found a project name: "Folve". Some renamings because of that.
7
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
8 The Folve FUSE filesystem takes a path to a directory of FLAC files, and provides
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
9 these files at a mount point. Other file formats than FLAC should work as well,
10 but not all are working well for streaming yet (and before you ask: MP3 is not
11 supported. Use Ogg/Vorbis as it is patent free and provides better quality
12 than MP3).
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
13
14 When a FLAC file is accessed through the mount point, Folve automatically
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
15 convolves its original counterpart on-the-fly with a Finite Impulse
16 Response (FIR) filter. The FIR filter is based on the jconvolver convolution
17 engine.
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
18
19 Folve can use the same filter configuration files that jconvolver uses. Folve
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
20 requires a naming scheme, described later, for these files.
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
21
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
22 In essence, Folve provides a filesystem that convolves files as a media server
23 or application reads them; many media servers or applications do not provide
24 an independent convolve option, but they all can read files.
b6988530 »
2012-09-15 o README updates.
25
26 Filesystem accesses are optimized for streaming. If files are read sequentially,
27 we only need to convolve whatever is requested, which minimizes CPU use if
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
28 you do not need the full file. Simply playing a file in real-time will use very
b6988530 »
2012-09-15 o README updates.
29 little CPU (on my notebook ~3% on one core). So this should work as well on
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
30 low-CPU machines (like NAS servers; have not tried that yet).
b6988530 »
2012-09-15 o README updates.
31
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
32 Because input and output files are compressed, we cannot predict what the
9cd6d57c »
2012-09-22 o Clarify why we need to convolve up to the skip point.
33 relationship between file-offset and sample-number is; so skipping forward
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
34 requires to convolve everything up to the point (the convolver is pretty fast
35 though, so you'll hardly notice).
b6988530 »
2012-09-15 o README updates.
36
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
37 While indexing, some media servers try to skip to the end of the file (do not
b6988530 »
2012-09-15 o README updates.
38 know why, to check if the end is there ?), so there is code that detects this
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
39 case so that we do not end up convolving whole files just for this. Also, some
b6988530 »
2012-09-15 o README updates.
40 media servers continually watch the file size while playing, so we adapt
41 predictions of the final filesize depending on the observed compression ratio.
42
43 The files are decoded with libsndfile, convolved, and re-encoded with
44 libsndfile. Libsndfile is very flexible in reading/writing all kinds
45 of audio files, but the support for rich header tags is limited. To not loose
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
46 information from the FLAC headers when indexing Folve-served files with a
b6988530 »
2012-09-15 o README updates.
47 media server, Folve extracts and serves the headers from the original files
48 before continuing with the convolved audio stream.
49
50 Folve has been tested with some players and media servers (and
51 works around bugs in these). Still, this is the first version made public, so
52 expect rough edges. Please report observations with particular media servers
10d077fa »
2012-09-25 o Point to github for feedback.
53 or provide patches through github
54 <https://github.com/hzeller/folve>.
b6988530 »
2012-09-15 o README updates.
55
56 This project is notably based on
a9d3e538 »
2012-09-15 o Found a project name: "Folve". Some renamings because of that.
57
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
58 * FUSE: Filesystem in Userspace <http://fuse.sourceforge.net/>
49a4cd94 »
2012-09-25 o Provide an INSTALL.md that explains how to compile on older systems.
59 * Zita Convolver <http://kokkinizita.linuxaudio.org/linuxaudio/downloads/zita-convolver-3.1.0.tar.bz2>
d379c8ca »
2012-09-26 o typos, clarifications.
60 * JConvolver <http://apps.linuxaudio.org/apps/all/jconvolver>
61 * Program files in the Folve project named zita-*.{h,cc} are derivatives of
62 files found in the jconvolver project. They implement the compatible
63 configuration file parsing.
5ef3f972 »
2012-09-21 o README -> README.md
64 * LibSndfile r/w audio files <http://www.mega-nerd.com/libsndfile/>
65 * Microhttpd webserver library <http://www.gnu.org/software/libmicrohttpd/>
66
67
68 ### Compiling on Ubuntu (tested on 11.10 and 12.04) ###
98a57256 »
2012-09-08 o Start implementation. Just a basic forwarding filesystem for
69
49a4cd94 »
2012-09-25 o Provide an INSTALL.md that explains how to compile on older systems.
70 This requires the latest versions of some development libraries.
a9d3e538 »
2012-09-15 o Found a project name: "Folve". Some renamings because of that.
71
49a4cd94 »
2012-09-25 o Provide an INSTALL.md that explains how to compile on older systems.
72 sudo apt-get install libsndfile-dev libflac-dev libzita-convolver-dev \
b4eec5c1 »
2012-09-29 o libboost caused too many troubles in embedded systems with weak
73 libfuse-dev libmicrohttpd-dev
49a4cd94 »
2012-09-25 o Provide an INSTALL.md that explains how to compile on older systems.
74 make
75 sudo make install
76
77 For hints on how to compile on older systems see INSTALL.md.
98a57256 »
2012-09-08 o Start implementation. Just a basic forwarding filesystem for
78
c4e3edac »
2012-09-22 o Add 'make install'
79 (TODO: debian package)
b6988530 »
2012-09-15 o README updates.
80
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
81 ### Let's test it! ###
994393ec »
2012-09-22 o add demo highpass, lowpass
82 Folve requires at least two parameters: the directory where your original
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
83 FLAC files reside and the mount point of this filesystem.
cf1b0e09 »
2012-09-22 o README demo tweaking
84
31096bbf »
2012-10-04 o remove option -c and add -C: give a base directory for all filters.
85 Also, do be useful, you need to supply the directory that contains filter
86 directories with the `-C <config-dir>` option.
87 Very useful is the `-p <port>` that starts a HTTP status server. Let's use
88 some example filters from this distribution;
e3e01826 »
2012-09-22 o README tweaks.
89 if you are in the Folve source directory, you find the directory `demo-filters/`
caec6904 »
2012-10-04 o update README: more about -C
90 that contains subdirectories with filters. If we pass this directory to folve,
91 folve will search in this directory for named filters:
a9d3e538 »
2012-09-15 o Found a project name: "Folve". Some renamings because of that.
92
61ac2f53 »
2012-09-25 o update INSTALL doc.
93 mkdir /tmp/test-mount
31096bbf »
2012-10-04 o remove option -c and add -C: give a base directory for all filters.
94 ./folve -C demo-filters -p 17322 -f \
61ac2f53 »
2012-09-25 o update INSTALL doc.
95 /path/to/your/directory/with/flacs /tmp/test-mount
5476cc29 »
2012-09-09 o provide absolute path.
96
994393ec »
2012-09-22 o add demo highpass, lowpass
97 Now you can access the fileystem under that mount point; it has the same
f431dd5c »
2012-09-23 o Update filter section in README.md
98 structure as your original directory.
994393ec »
2012-09-22 o add demo highpass, lowpass
99
61ac2f53 »
2012-09-25 o update INSTALL doc.
100 mplayer /tmp/test-mount/foo.flac
994393ec »
2012-09-22 o add demo highpass, lowpass
101
102 Folve provides a HTTP status page; have a look at
103
104 http://localhost:17322/
105
e3e01826 »
2012-09-22 o README tweaks.
106 (or whatever port you chose with the `-p 17322` option)
daf681ae »
2012-09-23 o some more tweaks.
107 There you can switch the filter; after you changed it in the UI, re-open
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
108 the same FLAC file with your media player: you'll hear the difference.
cf1b0e09 »
2012-09-22 o README demo tweaking
109
e3e01826 »
2012-09-22 o README tweaks.
110 To terminate this instance of folve, you can just press CTRL-C as we've run it
111 in the foreground (the `-f` option did this). In real life, you'd run it as
f431dd5c »
2012-09-23 o Update filter section in README.md
112 daemon (without `-f` option), so then you can stop the daemon and unmount the
113 directory with the `fusermount` command:
cf1b0e09 »
2012-09-22 o README demo tweaking
114
61ac2f53 »
2012-09-25 o update INSTALL doc.
115 fusermount -u /tmp/test-mount
994393ec »
2012-09-22 o add demo highpass, lowpass
116
117 ### Filter Configuration ###
caec6904 »
2012-10-04 o update README: more about -C
118 With the `-C` option, you give folve a directory in which it looks for
119 subdirectories with named filter configurations.
120
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
121 Filters are WAV files containing an impulse response (IR). This is
f431dd5c »
2012-09-23 o Update filter section in README.md
122 used by jconvolver's convolution engine to create a
123 [Finite Impulse Response](http://en.wikipedia.org/wiki/Finite_impulse_response)
124 (FIR) filter and process your audio.
125
ac6e11c5 »
2012-09-25 o Some smallish clarifications.
126 Text configuration files refer to these WAV files and add parameters such as
f431dd5c »
2012-09-23 o Update filter section in README.md
127 filter gain and channel mapping. These configuration files are read by Folve.
249e162c »
2012-09-23 o README tweaks.
128 See the samples in the `demo-filters/` directory. The README.CONFIG in the
f431dd5c »
2012-09-23 o Update filter section in README.md
129 [jconvolver](http://apps.linuxaudio.org/apps/all/jconvolver)
130 project describes the details of the configuration format.
131
132 Since the filter is dependent on the sampling rate, we need to choose the right
133 filter depending on the input file we see. This is why you give Folve a whole
249e162c »
2012-09-23 o README tweaks.
134 configuration directory: it can contain multipe files depending on sample rate.
f431dd5c »
2012-09-23 o Update filter section in README.md
135
136 The files in the configuration directory need to follow a naming scheme to
137 be found by Folve. Their naming is:
31bd9ce1 »
2012-09-10 o README update.
138
d379c8ca »
2012-09-26 o typos, clarifications.
139 filter-<samplerate>-<channels>-<bits>.conf OR
140 filter-<samplerate>-<channels>.conf OR
141 filter-<samplerate>.conf
31bd9ce1 »
2012-09-10 o README update.
142
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
143 So if you have FLAC files with 44.1kHz, 16 bits and 2 channel stero,
3e883b73 »
2012-09-18 o Match filters in sequence
144 you need a filter configuration named one of these (in matching sequence):
31bd9ce1 »
2012-09-10 o README update.
145
d379c8ca »
2012-09-26 o typos, clarifications.
146 /filter/dir/filter-44100-2-16.conf OR
147 /filter/dir/filter-44100-2.conf OR
148 /filter/dir/filter-44100.conf
31bd9ce1 »
2012-09-10 o README update.
149
3e883b73 »
2012-09-18 o Match filters in sequence
150 The files are searched from the most specific to the least specific type.
31bd9ce1 »
2012-09-10 o README update.
151
daf681ae »
2012-09-23 o some more tweaks.
152 The Folve filesystem will determine the samplerate/bits/channels and
153 attempt to find the right filter in the filter directory. If there is a filter,
154 the output is filtered on-the-fly, otherwise the original file is returned.
155
156 (I am looking for filter construction tools on Linux; if you know some,
f431dd5c »
2012-09-23 o Update filter section in README.md
157 please let me know.)
31bd9ce1 »
2012-09-10 o README update.
158
5ef3f972 »
2012-09-21 o README -> README.md
159 ### General usage: ###
160
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
161 usage: folve [options] <original-dir> <mount-point-dir>
5ef3f972 »
2012-09-21 o README -> README.md
162 Options: (in sequence of usefulness)
caec6904 »
2012-10-04 o update README: more about -C
163 -C <cfg-dir> : Convolver base configuration directory.
164 Sub-directories name the different filters.
1971a4a2 »
2012-09-23 o No more radio buttons.
165 Select on the HTTP status page.
18295cec »
2012-09-22 o update ./folve -h
166 -p <port> : Port to run the HTTP status server on.
167 -r <refresh> : Seconds between refresh of status page;
168 Default is 10 seconds; switch off with -1.
169 -g : Gapless convolving alphabetically adjacent files.
d8104890 »
2012-10-10 o readme update.
170 -b <KibiByte>: Pre-buffer files by given KiB.
18295cec »
2012-09-22 o update ./folve -h
171 -D : Moderate volume Folve debug messages to syslog.
172 -f : Operate in foreground; useful for debugging.
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
173 -o <mnt-opt> : other generic mount parameters passed to FUSE.
174 -d : High volume FUSE debug log. Implies -f.
31bd9ce1 »
2012-09-10 o README update.
175
f431dd5c »
2012-09-23 o Update filter section in README.md
176 If you're listening to classical music, opera or live-recordings, then you
177 certainly want to switch on gapless convolving with `-g`. If a file ends with
178 not enough samples to fill the FIR filter input, the gap is bridged by
a33eb6ec »
2012-09-23 o Fix unwanted bullet point
179 including the first samples of the alphabetically next file in that
180 directory -- and the result is split between these two files.
e3e01826 »
2012-09-22 o README tweaks.
181
994393ec »
2012-09-22 o add demo highpass, lowpass
182 ### Misc ###
350e25ea »
2012-09-22 o wget or curl
183 To manually switch the configuration from the command line, you can use `wget`
184 or `curl`, whatever you prefer:
436f57d8 »
2012-09-22 o Have a default refresh time of 10 seconds.
185
c113afd1 »
2012-10-04 o Adapt curl, wget documentation
186 wget -q -O/dev/null http://localhost:17322/settings?f=highpass
187 curl http://localhost:17322/settings?f=SantaLucia
436f57d8 »
2012-09-22 o Have a default refresh time of 10 seconds.
188
c113afd1 »
2012-10-04 o Adapt curl, wget documentation
189 The parameter given to `f=` is the name of the subdirectory in your base
190 configuration directory. An empty string is no filter, i.e. 'pass through'.
191 (And no, there is no security built-in. If you want people from
8fb28ec7 »
2012-09-24 Making README.md more readable thanks to wordsmithing input from
192 messing with the configuration of your Folve-daemon, do not use `-p <port>` :)).
Something went wrong with that request. Please try again.