3 # id3fs - a FUSE-based filesystem for browsing audio metadata
4 # Copyright (C) 2010 Ian Beckwith <ianb@erislabs.net>
6 # This program is free software: you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation, either version 3 of the License, or
9 # (at your option) any later version.
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program. If not, see <http://www.gnu.org/licenses/>.
20 use Getopt::Long qw(Configure);
26 $me=($0=~/(?:.*\/)?(.*)/)[0];
34 Configure(qw(bundling no_ignore_case));
35 my $optret=GetOptions(
36 "verbose|v" => sub { $verbose++; },
38 "database|f=s" => \$dbpath,
39 "t|tagdepth=s" => \$tagdepth,
40 "o=s" => sub {;}, # silently drop options passed by mount
43 usage() if(scalar(@ARGV) != 2 || !$optret || $help);
48 my $db=ID3FS::DB->new($me, $verbose, 0, $source, $dbpath);
51 my $fuse=ID3FS::Fuse->new($db, $source, $mountpoint, $verbose, $tagdepth);
53 # disassociate from terminal
59 exit if($pid); # parent
60 POSIX::setsid(); # child
64 print "$me: couldn't drop terminal: $!\n";
72 die("Usage: $me [-vh] [-f <dbfile>] [-t <tagdepth>] [--] <sourcedir> <mountpoint>\n".
73 " -t|--tagdepth=NUM\tMaximum number of tags in expression (default: 6)\n" .
74 " -f|--database=FILE\tPath to database file\n" .
75 " -v\t\t\tVerbose (repeat for more verbosity)\n".
76 " -h\t\t\tThis help\n".
77 " --\t\t\tEnd of options\n");
84 id3fsd - FUSE filesystem for browsing id3 tags
88 B<id3fsd> [B<-vh>] S<B<[-f >I<dbfile>]> [B<-->] I<SOURCEDIR> I<MOUNTPOINT>
92 id3fsd provides a browsable filesystem of your music files, organised
93 into sub-directories by id3 tags (or flac/ogg comments).
95 id3fsd allows you to construct boolean queries from a tag folksonomy
98 goth/AND/decade/1980s/
99 postrock/AND/NOT/rating/terrible/
100 thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/
101 prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/
102 location/sweden/AND/screamo/AND/postrock/
104 Multiple tags can be stored in the genre tag, separated by commas.
105 An index should first be created with L<id3fs-index(1)>, then id3fsd
106 can mount the files in I<SOURCEDIR> on the directory I<MOUNTPOINT>.
108 If not explicitly specified (with B<-f>), the index is searched for
109 at I<SOURCEDIR>/B<.id3fs>.
111 The resulting filesystem is read-only. Tags appear as directories,
112 and files appear as symlinks to the actual files in I<SOURCEDIR>.
116 To mount a view of F<~/music> on F<~/tags>:
119 $ id3fs-index ~/music
120 $ id3fsd ~/music ~/tags
122 You may need to be in the I<fuse> group, or be root.
130 Directory containing actual audio files and database file F<.id3fs>
131 (unless otherwise specified with B<-f>).
135 Directory to mount the id3fs view of the files.
137 =item S<B<-t >I<NUM>> | S<B<--tagdepth=>I<NUM>>
139 Maximum number of tags in an expression. A query with many ANDs and
140 NOTs can get quite slow. This option allows a cutoff before things get
141 too slow, as well as providing some eventual limit when processes
142 recurse into the filesystem. The default is 6.
144 =item S<B<-f >I<FILE>> | S<B<--database=>I<FILE>>
146 Use database in I<FILE>. The default is I<SOURCEDIR>/B<.id3fs>.
150 Enable verbose operation. Repeat for more verbosity. If verbose is
151 enabled, id3fsd does not detach from the terminal.
155 Show a short help message.
163 =head1 FILESYSTEM LAYOUT
165 A path in the filesystem consists of a tag query expression, followed
166 by directories containing the matching files, arranged by artist and
171 /krautrock/AND/year/1971/
172 /krautrock/AND/year/1971/Can
173 /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3
174 /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3
175 /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3
176 /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3
177 /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3
178 /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3
180 id3fs supports OR, AND and NOT. NOT has the highest precedence,
181 followed by AND, so F<foo/OR/NOT/bar/AND/baz> is parsed as
182 (foo OR ((NOT bar) AND baz)).
186 Tags are extracted from the B<genre> tag of audio files with
189 Within the genre frame/comment, tags are separated by commas.
191 Tags can have values, separated by a slash, eg I<metal/thrash>,
192 I<rating/5>. Certain special tags are automatically filled in from
197 The following tags are automatically derived from other metadata in
204 Extracted from the B<year> or B<DATE> tag. If not found defaults to
209 Also extracted from the B<year> or B<DATE> tag. If not found
210 defaults to B<decade/UNKNOWN>.
214 If a mp3 file has an ID3V1.1 genre tag, its value is assigned to
219 Type of audio file (mp3, ogg, flac). Always set.
223 =head2 Special Directories
229 All tracks that match the given tag expression, whether they have an
230 assigned artist and album or not.
234 Tracks matching the given expression that do not have an artist tag.
238 Tracks matching the given expression that do not have an album tag.
242 This is a special directory in the root of the filesystem, that
243 provides access to all the indexed files, regardless of tags assigned.
247 =head1 FUSE AND MOUNTING AUTOMATICALLY
249 For others to be able to view your id3fs mount(s), you need to set the
250 option B<user_allow_other> in F</etc/fuse.conf>.
252 To mount a filesystem automatically, put an entry in F</etc/fstab>
255 id3fsd#/source/dir /mount/point defaults 0 0
259 Because id3fs offers a combinatorial explosion of views of your files,
260 processes recursing into the mount point will take a B<long> time to
263 Ensure your backups, cron jobs, F</etc/updatedb.conf>, etc. are
264 configured to exclude the mount point.
268 Please report any found to ianb@erislabs.net
272 L<id3fs-index(1)>, L<http://fuse.sourceforge.net>
276 Ian Beckwith <ianb@erislabs.net>
278 Many thanks to Aubrey Stark-Toller for help wrangling SQL.
282 The latest version can be found at:
284 L<http://erislabs.net/ianb/projects/id3fs/>
288 Copyright (C) 2010 Ian Beckwith <ianb@erislabs.net>
290 This program is free software: you can redistribute it and/or modify
291 it under the terms of the GNU General Public License as published by
292 the Free Software Foundation, either version 3 of the License, or
293 (at your option) any later version.
295 This program is distributed in the hope that it will be useful,
296 but WITHOUT ANY WARRANTY; without even the implied warranty of
297 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
298 GNU General Public License for more details.
300 You should have received a copy of the GNU General Public License
301 along with this program. If not, see <http://www.gnu.org/licenses/>.