diff --git a/README.md b/README.md index fd5478d..18cc291 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,45 @@ -Folve - Fuse Convolve +Folve - FUSE convolve ===================== -A fuse filesystem for on-the-fly convolving of audio files. +Folve is a FUSE filesystem that convolves audio files on-the-fly. Overview -------- -This fuse filesystem takes an original path to a directory with flac-files -and provides these files at the mount point. Accessing audio files will -automatically convolve these on-the-fly using the FIR zita convolver by -Fons Adriaensen. You can directly use filter configuration files that you have -for jconvolver/fconvolver (files in this directory starting with zita-* are -imported from his jconvolver project to parse the same configuration files). -These config files need have a special naming scheme, see below. - -Folve solves the problem that many media servers don't provide a convolving -option and their only interface to the outside world is to access a file -system. So here we provide a filesystem, convolving files while they read them :) -In general the beauty of simply accessing audio files that are transparently -convolved is very useful and powerful in other contexts too (e.g. you can just -copy a readily convolved file from it). +The Folve FUSE filesystem takes a path to a directory of FLAC files, and provides +these files at a mount point. + +When a FLAC file is accessed through the mount point, Folve automatically +convolves its original counterpart on-the-fly with a Finite Impulse Response (FIR) +filter. The FIR filter is based on the jconvolver convolution engine. + +Folve can use the same filter configuration files that jconvolver uses. Folve +requires a naming scheme, which is described later, for these configuration files. + +Folve provides a filesystem that convolves files as a media server or application +reads them; many media servers or applications do not provide an independent +convolve option, but they all can read files. Filesystem accesses are optimized for streaming. If files are read sequentially, we only need to convolve whatever is requested, which minimizes CPU use if -you don't need the full file. Simply playing a file in real-time will use very +you do not need the full file. Simply playing a file in real-time will use very little CPU (on my notebook ~3% on one core). So this should work as well on -low-CPU machines (like NAS servers; haven't tried that yet). +low-CPU machines (like NAS servers; have not tried that yet). -Because input and output files are compressed, we can't predict what the +Because input and output files are compressed, we cannot predict what the relationship between file-offset and sample-number is; so skipping forward requires to convolve everything up to the point (the zita convolver is pretty fast though, so you'll hardly notice). -While indexing, some media servers try to skip to the end of the file (don't +While indexing, some media servers try to skip to the end of the file (do not know why, to check if the end is there ?), so there is code that detects this -case so that we don't end up convolving whole files just for this. Also, some +case so that we do not end up convolving whole files just for this. Also, some media servers continually watch the file size while playing, so we adapt predictions of the final filesize depending on the observed compression ratio. The files are decoded with libsndfile, convolved, and re-encoded with libsndfile. Libsndfile is very flexible in reading/writing all kinds of audio files, but the support for rich header tags is limited. To not loose -information from the flac-headers when indexing Folve-served files with a +information from the FLAC headers when indexing Folve-served files with a media server, Folve extracts and serves the headers from the original files before continuing with the convolved audio stream. @@ -51,8 +50,11 @@ or send patches to . This project is notably based on - * Fuse: Filesystem in Userspace + * FUSE: Filesystem in Userspace * JConvolver audio convolver + * Program files in the Folve the project named zita-* are derivatives of + files found in the jconvolver project. They implement the configuration + file parsing. * LibSndfile r/w audio files * Microhttpd webserver library @@ -71,7 +73,7 @@ This project is notably based on ### Run ### Folve requires at least two parameters: the directory where your original -*.flac files reside and the mount point of this filesystem. +FLAC files reside and the mount point of this filesystem. Also, do be useful, you need to supply at least one configuration directory with the `-c ` option. Very useful is the `-p ` that starts @@ -96,7 +98,7 @@ Folve provides a HTTP status page; have a look at (or whatever port you chose with the `-p 17322` option) There you can switch the filter; after you changed it in the UI, re-open -the same flac file with your media player: you'll hear the difference. +the same FLAC file with your media player: you'll hear the difference. To terminate this instance of folve, you can just press CTRL-C as we've run it in the foreground (the `-f` option did this). In real life, you'd run it as @@ -128,7 +130,7 @@ be found by Folve. Their naming is: filter--.conf OR filter-.conf -So if you have flac files with 44.1kHz, 16 bits and 2 channel stero, +So if you have FLAC files with 44.1kHz, 16 bits and 2 channel stero, you need a filter configuration named one of these (in matching sequence): /filter/dir/filter-44100-2-16.conf OR @@ -146,7 +148,7 @@ please let me know.) ### General usage: ### - usage: folve [options] + usage: folve [options] Options: (in sequence of usefulness) -c : Convolver configuration directory. You can supply this option multiple times: @@ -157,8 +159,8 @@ please let me know.) -g : Gapless convolving alphabetically adjacent files. -D : Moderate volume Folve debug messages to syslog. -f : Operate in foreground; useful for debugging. - -o : other generic mount parameters passed to fuse. - -d : High volume fuse debug log. Implies -f. + -o : other generic mount parameters passed to FUSE. + -d : High volume FUSE debug log. Implies -f. If you're listening to classical music, opera or live-recordings, then you certainly want to switch on gapless convolving with `-g`. If a file ends with @@ -176,4 +178,4 @@ or `curl`, whatever you prefer: The parameter given to `f=` is the configuration in the same sequence you supplied on startup, starting to count from 1. Configuration 0 means 'no filter' (And no, there is no security built-in. If you want people from -messing with the configuration of your Folve-daemon, don't use `-p ` :)). +messing with the configuration of your Folve-daemon, do not use `-p ` :)). diff --git a/folve-main.cc b/folve-main.cc index 62f5b1c..ffc8bb2 100644 --- a/folve-main.cc +++ b/folve-main.cc @@ -187,7 +187,7 @@ static void folve_destroy(void *) { } static int usage(const char *prg) { - printf("usage: %s [options] \n", prg); + printf("usage: %s [options] \n", prg); printf("Options: (in sequence of usefulness)\n" "\t-c : Convolver configuration directory.\n" "\t You can supply this option multiple times:\n" @@ -199,8 +199,8 @@ static int usage(const char *prg) { "\t-D : Moderate volume Folve debug messages to syslog,\n" "\t and some more detailed configuration info in UI\n" "\t-f : Operate in foreground; useful for debugging.\n" - "\t-o : other generic mount parameters passed to fuse.\n" - "\t-d : High volume fuse debug log. Implies -f.\n", + "\t-o : other generic mount parameters passed to FUSE.\n" + "\t-d : High volume FUSE debug log. Implies -f.\n", folve_rt.refresh_time); return 1; }