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/>.
19 use lib '/home/ianb/projects/id3fs/id3fs/lib'; # FIXME: remove
21 use Getopt::Long qw(Configure);
27 $me=($0=~/(?:.*\/)?(.*)/)[0];
35 Configure(qw(bundling no_ignore_case));
36 my $optret=GetOptions(
37 "verbose|v" => sub { $verbose++; },
39 "database|f=s" => \$dbpath,
40 "t|tagdepth=s" => \$tagdepth,
41 "o=s" => sub {;}, # silently drop options passed by mount
44 usage() if(scalar(@ARGV) != 2 || !$optret || $help);
49 my $db=ID3FS::DB->new($me, $verbose, 0, $source, $dbpath);
52 my $fuse=ID3FS::Fuse->new($db, $source, $mountpoint, $verbose, $tagdepth);
54 # disassociate from terminal
60 exit if($pid); # parent
61 POSIX::setsid(); # child
65 print "$me: couldn't drop terminal: $!\n";
73 die("Usage: $me [-vh] [-f <dbfile>] [-t <tagdepth>] [--] <sourcedir> <mountpoint>\n".
74 " -t|--tagdepth=NUM\tMaximum number of tags in expression (default: 6)\n" .
75 " -f|--database=FILE\tPath to database file\n" .
76 " -v\t\t\tVerbose (repeat for more verbosity)\n".
77 " -h\t\t\tThis help\n".
78 " --\t\t\tEnd of options\n");
85 id3fsd - FUSE filesystem for browsing id3 tags
89 B<id3fsd> [B<-vh>] S<B<[-f >I<dbfile>]> [B<-->] I<SOURCEDIR> I<MOUNTPOINT>
93 id3fsd provides a browsable filesystem of your music files, organised
94 into sub-directories by id3 tags (or flac/ogg comments).
96 id3fsd allows you to construct boolean queries from a tag folksonomy
99 goth/AND/decade/1980s/
100 postrock/AND/NOT/rating/terrible/
101 thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/
102 prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/
103 location/sweden/AND/screamo/AND/postrock/
105 Multiple tags can be stored in the genre tag, separated by commas.
106 An index should first be created with L<id3fs-index(1)>, then id3fsd
107 can mount the files in I<SOURCEDIR> on the directory I<MOUNTPOINT>.
109 If not explicitly specified (with B<-f>), the index is searched for
110 at I<SOURCEDIR>/B<.id3fs>.
112 The resulting filesystem is read-only. Tags appear as directories,
113 and files appear as symlinks to the actual files in I<SOURCEDIR>.
117 To mount a view of F<~/music> on F<~/tags>:
120 $ id3fs-index ~/music
121 $ id3fsd ~/music ~/tags
123 You may need to be in the I<fuse> group, or be root.
131 Directory containing actual audio files and database file F<.id3fs>
132 (unless otherwise specified with B<-f>).
136 Directory to mount the id3fs view of the files.
138 =item S<B<-t >I<NUM>> | S<B<--tagdepth=>I<NUM>>
140 Maximum number of tags in an expression. A query with many ANDs and
141 NOTs can get quite slow. This option allows a cutoff before things get
142 too slow, as well as providing some eventual limit when processes
143 recurse into the filesystem. The default is 6.
145 =item S<B<-f >I<FILE>> | S<B<--database=>I<FILE>>
147 Use database in I<FILE>. The default is I<SOURCEDIR>/B<.id3fs>.
151 Enable verbose operation. Repeat for more verbosity. If verbose is
152 enabled, id3fsd does not detach from the terminal.
156 Show a short help message.
164 =head1 FILESYSTEM LAYOUT
166 A path in the filesystem consists of a tag query expression, followed
167 by directories containing the matching files, arranged by artist and
172 /krautrock/AND/year/1971/
173 /krautrock/AND/year/1971/Can
174 /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3
175 /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3
176 /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3
177 /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3
178 /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3
179 /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3
181 id3fs supports OR, AND and NOT. NOT has the highest precedence,
182 followed by AND, so F<foo/OR/NOT/bar/AND/baz> is parsed as
183 (foo OR ((NOT bar) AND baz)).
187 Tags are extracted from the B<genre> tag of audio files with
190 Within the genre frame/comment, tags are separated by commas.
192 Tags can have values, separated by a slash, eg I<metal/thrash>,
193 I<rating/5>. Certain special tags are automatically filled in from
198 The following tags are automatically derived from other metadata in
205 Extracted from the B<year> or B<DATE> tag. If not found defaults to
210 Also extracted from the B<year> or B<DATE> tag. If not found
211 defaults to B<decade/UNKNOWN>.
215 If a mp3 file has an ID3V1.1 genre tag, its value is assigned to
220 Type of audio file (mp3, ogg, flac). Always set.
224 =head2 Special Directories
230 All tracks that match the given tag expression, whether they have an
231 assigned artist and album or not.
235 Tracks matching the given expression that do not have an artist tag.
239 Tracks matching the given expression that do not have an album tag.
243 This is a special directory in the root of the filesystem, that
244 provides access to all the indexed files, regardless of tags assigned.
248 =head1 FUSE AND MOUNTING AUTOMATICALLY
250 For others to be able to view your id3fs mount(s), you need to set the
251 option B<user_allow_other> in F</etc/fuse.conf>.
253 To mount a filesystem automatically, put an entry in F</etc/fstab>
256 id3fsd#/source/dir /mount/point defaults 0 0
260 Because id3fs offers a combinatorial explosion of views of your files,
261 processes recursing into the mount point will take a B<long> time to
264 Ensure your backups, cron jobs, F</etc/updatedb.conf>, etc. are
265 configured to exclude the mount point.
269 Please report any found to ianb@erislabs.net
273 L<id3fs-index(1)>, L<http://fuse.sourceforge.net>
277 Ian Beckwith <ianb@erislabs.net>
279 Many thanks to Aubrey Stark-Toller for help wrangling SQL.
283 The latest version can be found at:
285 L<http://erislabs.net/ianb/projects/id3fs/>
289 Copyright (C) 2010 Ian Beckwith <ianb@erislabs.net>
291 This program is free software: you can redistribute it and/or modify
292 it under the terms of the GNU General Public License as published by
293 the Free Software Foundation, either version 3 of the License, or
294 (at your option) any later version.
296 This program is distributed in the hope that it will be useful,
297 but WITHOUT ANY WARRANTY; without even the implied warranty of
298 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
299 GNU General Public License for more details.
301 You should have received a copy of the GNU General Public License
302 along with this program. If not, see <http://www.gnu.org/licenses/>.