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';
21 use Getopt::Long qw(Configure);
25 $me=($0=~/(?:.*\/)?(.*)/)[0];
33 Configure(qw(bundling no_ignore_case));
34 my $optret=GetOptions(
35 "verbose|v" => sub { $verbose++; },
37 "database|f=s" => \$dbpath,
38 "t|tagdepth=s" => \$tagdepth,
39 "o=s" => sub {;}, # silently drop options passed by mount
42 usage() if(scalar(@ARGV) != 2 || !$optret || $help);
47 my $db=ID3FS::DB->new($me, $verbose, 0, $source, $dbpath);
50 my $fuse=ID3FS::Fuse->new($db, $source, $mountpoint, $verbose, $tagdepth);
55 die("Usage: $me [-vh] [-f <dbfile>] [-t <tagdepth>] [--] <sourcedir> <mountpoint>\n".
56 " -t|--tagdepth=NUM\tMaximum number of tags in expression (default: 10)\n" .
57 " -f|--database=FILE\tPath to database file\n" .
58 " -v\t\t\tVerbose (repeat for more verbosity)\n".
59 " -h\t\t\tThis help\n".
60 " --\t\t\tEnd of options\n");
67 id3fsd - FUSE filesystem for browsing id3 tags
71 B<id3fsd> [B<-vh>] S<B<[-f >I<dbfile>]> [B<-->] I<SOURCEDIR> I<MOUNTPOINT>
75 id3fsd provides a browsable filesystem of your music files, organised
76 into sub-directories by id3 tags (or flac/ogg comments).
78 id3fsd allows you to construct boolean queries from a tag folksonomy
81 goth/AND/decade/1980s/
82 postrock/AND/NOT/rating/terrible/
83 thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/
84 prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/
85 location/sweden/AND/screamo/AND/postrock/
87 Multiple tags can be stored in the genre tag, separated by commas.
88 An index should first be created with L<id3fs-index(1)>, then id3fsd
89 can mount the files in I<SOURCEDIR> on the directory I<MOUNTPOINT>.
91 If not explicitly specified (with B<-f>), the index is searched for
92 at I<SOURCEDIR>/B<.id3fs>.
94 The resulting filesystem is read-only. Tags appear as directories,
95 and files appear as symlinks to the actual files in I<SOURCEDIR>.
99 To mount a view of F<~/music> on F<~/tags>:
102 $ id3fs-index ~/music
103 $ id3fsd ~/music ~/tags
105 You may need to be in the I<fuse> group, or be root.
113 Directory containing actual audio files and database file F<.id3fs>
114 (unless otherwise specified with B<-f>).
118 Directory to mount the id3fs view of the files.
120 =item S<B<-t >I<NUM>> | S<B<--tagdepth=>I<NUM>>
122 Maximum number of tags in an expression. A query with many ANDs and
123 NOTs can get quite slow. This option allows a cutoff before things get
124 too slow, as well as providing some eventual limit when processes
125 recurse into the filesystem. The default is 10.
127 =item S<B<-f >I<FILE>> | S<B<--database=>I<FILE>>
129 Use database in I<FILE>. The default is I<SOURCEDIR>/B<.id3fs>.
133 Enable verbose operation. Repeat for more verbosity. If verbose is
134 enabled, id3fsd does not detach from the terminal.
138 Show a short help message.
146 =head1 FILESYSTEM LAYOUT
148 A path in the filesystem consists of a tag query expression, followed
149 by directories containing the matching files, arranged by artist and
154 /krautrock/AND/year/1971/
155 /krautrock/AND/year/1971/Can
156 /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3
157 /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3
158 /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3
159 /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3
160 /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3
161 /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3
165 Tags are extracted from the B<genre> tag of audio files with
168 Within the genre frame/comment, tags are separated by commas.
170 Tags can have values, separated by a slash, eg I<metal/thrash>,
171 I<rating/5>. Certain tags are automatically filled in from other file
172 metadata, see L</"Special Tags>.
174 =head2 Special Directories
180 This is a special directory in the root of the filesystem, that
181 provides access to all the indexed files, regardless of tags assigned.
185 All tracks that match the given tag expression, whether they have an
186 assigned artist and album or not.
190 Tracks matching the given expression that do not have an artist tag.
194 Tracks matching the given expression that do not have an album tag.
200 Several tags are automatically derived from other metadata in the
207 Extracted from the B<year> or B<DATE> tag. If not found defaults to
212 Also extracted from the B<year> or B<DATE> tag. If not found
213 defaults to B<decade/UNKNOWN>.
217 If a mp3 file has an ID3V1.1 genre tag, its value is assigned to
222 Type of audio file (mp3, ogg, flac). Always set.
226 =head1 FUSE AND MOUNTING AUTOMATICALLY
228 For others to be able to view your id3fs mount(s), you need to set the
229 option B<user_allow_other> in F</etc/fuse.conf>.
231 To mount a filesystem automatically, put an entry in F</etc/fstab>
234 id3fsd#/source/dir /mount/point defaults 0 0
238 Because id3fs offers a combinatorial explosion of views of your files,
239 processes recursing into the mount point will take a B<long> time to
242 Ensure your backups, cron jobs, F</etc/updatedb.conf>, etc. are
243 configured to exclude the mount point.
247 Please report any found to ianb@erislabs.net
251 L<id3fs-index(1)>, L<http://fuse.sourceforge.net>
255 Ian Beckwith <ianb@erislabs.net>
257 Many thanks to Aubrey Stark-Toller for help wrangling SQL.
261 The latest version can be found at:
263 L<http://erislabs.net/ianb/projects/id3fs/>
267 Copyright (C) 2010 Ian Beckwith <ianb@erislabs.net>
269 This program is free software: you can redistribute it and/or modify
270 it under the terms of the GNU General Public License as published by
271 the Free Software Foundation, either version 3 of the License, or
272 (at your option) any later version.
274 This program is distributed in the hope that it will be useful,
275 but WITHOUT ANY WARRANTY; without even the implied warranty of
276 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
277 GNU General Public License for more details.
279 You should have received a copy of the GNU General Public License
280 along with this program. If not, see <http://www.gnu.org/licenses/>.