Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 192 lines (146 sloc) 8.868 kb
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
1 Folve - FUSE convolve
26fd15a Henner Zeller o README fiddling.
authored
2 =====================
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
3 Folve is a FUSE filesystem that convolves audio files on-the-fly.
5ef3f97 Henner Zeller o README -> README.md
authored
4
5 Overview
6 --------
a9d3e53 Henner Zeller o Found a project name: "Folve". Some renamings because of that.
authored
7
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
8 The Folve FUSE filesystem takes a path to a directory of FLAC files, and provides
ac6e11c Henner Zeller o Some smallish clarifications.
authored
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).
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
13
14 When a FLAC file is accessed through the mount point, Folve automatically
ac6e11c Henner Zeller o Some smallish clarifications.
authored
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.
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
18
19 Folve can use the same filter configuration files that jconvolver uses. Folve
ac6e11c Henner Zeller o Some smallish clarifications.
authored
20 requires a naming scheme, described later, for these files.
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
21
ac6e11c Henner Zeller o Some smallish clarifications.
authored
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.
b698853 Henner Zeller o README updates.
authored
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
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
28 you do not need the full file. Simply playing a file in real-time will use very
b698853 Henner Zeller o README updates.
authored
29 little CPU (on my notebook ~3% on one core). So this should work as well on
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
30 low-CPU machines (like NAS servers; have not tried that yet).
b698853 Henner Zeller o README updates.
authored
31
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
32 Because input and output files are compressed, we cannot predict what the
9cd6d57 Henner Zeller o Clarify why we need to convolve up to the skip point.
authored
33 relationship between file-offset and sample-number is; so skipping forward
ac6e11c Henner Zeller o Some smallish clarifications.
authored
34 requires to convolve everything up to the point (the convolver is pretty fast
35 though, so you'll hardly notice).
b698853 Henner Zeller o README updates.
authored
36
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
37 While indexing, some media servers try to skip to the end of the file (do not
b698853 Henner Zeller o README updates.
authored
38 know why, to check if the end is there ?), so there is code that detects this
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
39 case so that we do not end up convolving whole files just for this. Also, some
b698853 Henner Zeller o README updates.
authored
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
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
46 information from the FLAC headers when indexing Folve-served files with a
b698853 Henner Zeller o README updates.
authored
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
10d077f Henner Zeller o Point to github for feedback.
authored
53 or provide patches through github
54 <https://github.com/hzeller/folve>.
b698853 Henner Zeller o README updates.
authored
55
56 This project is notably based on
a9d3e53 Henner Zeller o Found a project name: "Folve". Some renamings because of that.
authored
57
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
58 * FUSE: Filesystem in Userspace <http://fuse.sourceforge.net/>
49a4cd9 Henner Zeller o Provide an INSTALL.md that explains how to compile on older systems.
authored
59 * Zita Convolver <http://kokkinizita.linuxaudio.org/linuxaudio/downloads/zita-convolver-3.1.0.tar.bz2>
d379c8c Henner Zeller o typos, clarifications.
authored
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.
5ef3f97 Henner Zeller o README -> README.md
authored
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) ###
98a5725 Henner Zeller o Start implementation. Just a basic forwarding filesystem for
authored
69
49a4cd9 Henner Zeller o Provide an INSTALL.md that explains how to compile on older systems.
authored
70 This requires the latest versions of some development libraries.
a9d3e53 Henner Zeller o Found a project name: "Folve". Some renamings because of that.
authored
71
49a4cd9 Henner Zeller o Provide an INSTALL.md that explains how to compile on older systems.
authored
72 sudo apt-get install libsndfile-dev libflac-dev libzita-convolver-dev \
b4eec5c Henner Zeller o libboost caused too many troubles in embedded systems with weak
authored
73 libfuse-dev libmicrohttpd-dev
49a4cd9 Henner Zeller o Provide an INSTALL.md that explains how to compile on older systems.
authored
74 make
75 sudo make install
76
77 For hints on how to compile on older systems see INSTALL.md.
98a5725 Henner Zeller o Start implementation. Just a basic forwarding filesystem for
authored
78
c4e3eda Henner Zeller o Add 'make install'
authored
79 (TODO: debian package)
b698853 Henner Zeller o README updates.
authored
80
ac6e11c Henner Zeller o Some smallish clarifications.
authored
81 ### Let's test it! ###
994393e Henner Zeller o add demo highpass, lowpass
authored
82 Folve requires at least two parameters: the directory where your original
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
83 FLAC files reside and the mount point of this filesystem.
cf1b0e0 Henner Zeller o README demo tweaking
authored
84
31096bb Henner Zeller o remove option -c and add -C: give a base directory for all filters.
authored
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;
e3e0182 Henner Zeller o README tweaks.
authored
89 if you are in the Folve source directory, you find the directory `demo-filters/`
caec690 Henner Zeller o update README: more about -C
authored
90 that contains subdirectories with filters. If we pass this directory to folve,
91 folve will search in this directory for named filters:
a9d3e53 Henner Zeller o Found a project name: "Folve". Some renamings because of that.
authored
92
61ac2f5 Henner Zeller o update INSTALL doc.
authored
93 mkdir /tmp/test-mount
31096bb Henner Zeller o remove option -c and add -C: give a base directory for all filters.
authored
94 ./folve -C demo-filters -p 17322 -f \
61ac2f5 Henner Zeller o update INSTALL doc.
authored
95 /path/to/your/directory/with/flacs /tmp/test-mount
5476cc2 Henner Zeller o provide absolute path.
authored
96
994393e Henner Zeller o add demo highpass, lowpass
authored
97 Now you can access the fileystem under that mount point; it has the same
f431dd5 Henner Zeller o Update filter section in README.md
authored
98 structure as your original directory.
994393e Henner Zeller o add demo highpass, lowpass
authored
99
61ac2f5 Henner Zeller o update INSTALL doc.
authored
100 mplayer /tmp/test-mount/foo.flac
994393e Henner Zeller o add demo highpass, lowpass
authored
101
102 Folve provides a HTTP status page; have a look at
103
104 http://localhost:17322/
105
e3e0182 Henner Zeller o README tweaks.
authored
106 (or whatever port you chose with the `-p 17322` option)
daf681a Henner Zeller o some more tweaks.
authored
107 There you can switch the filter; after you changed it in the UI, re-open
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
108 the same FLAC file with your media player: you'll hear the difference.
cf1b0e0 Henner Zeller o README demo tweaking
authored
109
e3e0182 Henner Zeller o README tweaks.
authored
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
f431dd5 Henner Zeller o Update filter section in README.md
authored
112 daemon (without `-f` option), so then you can stop the daemon and unmount the
113 directory with the `fusermount` command:
cf1b0e0 Henner Zeller o README demo tweaking
authored
114
61ac2f5 Henner Zeller o update INSTALL doc.
authored
115 fusermount -u /tmp/test-mount
994393e Henner Zeller o add demo highpass, lowpass
authored
116
117 ### Filter Configuration ###
caec690 Henner Zeller o update README: more about -C
authored
118 With the `-C` option, you give folve a directory in which it looks for
119 subdirectories with named filter configurations.
120
ac6e11c Henner Zeller o Some smallish clarifications.
authored
121 Filters are WAV files containing an impulse response (IR). This is
f431dd5 Henner Zeller o Update filter section in README.md
authored
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
ac6e11c Henner Zeller o Some smallish clarifications.
authored
126 Text configuration files refer to these WAV files and add parameters such as
f431dd5 Henner Zeller o Update filter section in README.md
authored
127 filter gain and channel mapping. These configuration files are read by Folve.
249e162 Henner Zeller o README tweaks.
authored
128 See the samples in the `demo-filters/` directory. The README.CONFIG in the
f431dd5 Henner Zeller o Update filter section in README.md
authored
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
249e162 Henner Zeller o README tweaks.
authored
134 configuration directory: it can contain multipe files depending on sample rate.
f431dd5 Henner Zeller o Update filter section in README.md
authored
135
136 The files in the configuration directory need to follow a naming scheme to
137 be found by Folve. Their naming is:
31bd9ce Henner Zeller o README update.
authored
138
d379c8c Henner Zeller o typos, clarifications.
authored
139 filter-<samplerate>-<channels>-<bits>.conf OR
140 filter-<samplerate>-<channels>.conf OR
141 filter-<samplerate>.conf
31bd9ce Henner Zeller o README update.
authored
142
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
143 So if you have FLAC files with 44.1kHz, 16 bits and 2 channel stero,
3e883b7 Henner Zeller o Match filters in sequence
authored
144 you need a filter configuration named one of these (in matching sequence):
31bd9ce Henner Zeller o README update.
authored
145
d379c8c Henner Zeller o typos, clarifications.
authored
146 /filter/dir/filter-44100-2-16.conf OR
147 /filter/dir/filter-44100-2.conf OR
148 /filter/dir/filter-44100.conf
31bd9ce Henner Zeller o README update.
authored
149
3e883b7 Henner Zeller o Match filters in sequence
authored
150 The files are searched from the most specific to the least specific type.
31bd9ce Henner Zeller o README update.
authored
151
daf681a Henner Zeller o some more tweaks.
authored
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,
f431dd5 Henner Zeller o Update filter section in README.md
authored
157 please let me know.)
31bd9ce Henner Zeller o README update.
authored
158
5ef3f97 Henner Zeller o README -> README.md
authored
159 ### General usage: ###
160
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
161 usage: folve [options] <original-dir> <mount-point-dir>
5ef3f97 Henner Zeller o README -> README.md
authored
162 Options: (in sequence of usefulness)
caec690 Henner Zeller o update README: more about -C
authored
163 -C <cfg-dir> : Convolver base configuration directory.
164 Sub-directories name the different filters.
1971a4a Henner Zeller o No more radio buttons.
authored
165 Select on the HTTP status page.
18295ce Henner Zeller o update ./folve -h
authored
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.
170 -D : Moderate volume Folve debug messages to syslog.
171 -f : Operate in foreground; useful for debugging.
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
172 -o <mnt-opt> : other generic mount parameters passed to FUSE.
173 -d : High volume FUSE debug log. Implies -f.
31bd9ce Henner Zeller o README update.
authored
174
f431dd5 Henner Zeller o Update filter section in README.md
authored
175 If you're listening to classical music, opera or live-recordings, then you
176 certainly want to switch on gapless convolving with `-g`. If a file ends with
177 not enough samples to fill the FIR filter input, the gap is bridged by
a33eb6e Henner Zeller o Fix unwanted bullet point
authored
178 including the first samples of the alphabetically next file in that
179 directory -- and the result is split between these two files.
e3e0182 Henner Zeller o README tweaks.
authored
180
994393e Henner Zeller o add demo highpass, lowpass
authored
181 ### Misc ###
350e25e Henner Zeller o wget or curl
authored
182 To manually switch the configuration from the command line, you can use `wget`
183 or `curl`, whatever you prefer:
436f57d Henner Zeller o Have a default refresh time of 10 seconds.
authored
184
c113afd Henner Zeller o Adapt curl, wget documentation
authored
185 wget -q -O/dev/null http://localhost:17322/settings?f=highpass
186 curl http://localhost:17322/settings?f=SantaLucia
436f57d Henner Zeller o Have a default refresh time of 10 seconds.
authored
187
c113afd Henner Zeller o Adapt curl, wget documentation
authored
188 The parameter given to `f=` is the name of the subdirectory in your base
189 configuration directory. An empty string is no filter, i.e. 'pass through'.
190 (And no, there is no security built-in. If you want people from
8fb28ec Henner Zeller Making README.md more readable thanks to wordsmithing input from
authored
191 messing with the configuration of your Folve-daemon, do not use `-p <port>` :)).
Something went wrong with that request. Please try again.