sbin/id3fsd

   1 #!/usr/bin/perl -w
   2 #
   3 # id3fs - a FUSE-based filesystem for browsing audio metadata
   4 # Copyright (C) 2010  Ian Beckwith <ianb@erislabs.net>
   5 #
   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.
  10 #
  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.
  15 #
  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/>.
  18
  19 use lib '/home/ianb/projects/id3fs/id3fs/lib';
  20 use strict;
  21 use Getopt::Long qw(Configure);
  22 use ID3FS::DB;
  23 use ID3FS::Fuse;
  24 use vars qw($me);
  25 $me=($0=~/(?:.*\/)?(.*)/)[0];
  26
  27 our $VERSION="1.00";
  28 my $verbose=0;
  29 my $help=0;
  30 my $dbpath=undef;
  31 my $tagdepth=undef;
  32
  33 Configure(qw(bundling no_ignore_case));
  34 my $optret=GetOptions(
  35     "verbose|v"    => sub { $verbose++; },
  36     "help|h"       => \$help,
  37     "database|f=s" => \$dbpath,
  38     "t|tagdepth=s" => \$tagdepth,
  39     "o=s"          => sub {;}, # silently drop options passed by mount
  40     );
  41
  42 usage() if(scalar(@ARGV) != 2 || !$optret || $help);
  43
  44 my $source=shift;
  45 my $mountpoint=shift;
  46
  47 my $db=ID3FS::DB->new($me, $verbose, 0, $source, $dbpath);
  48 exit unless($db);
  49
  50 my $fuse=ID3FS::Fuse->new($db, $source, $mountpoint, $verbose, $tagdepth);
  51 $fuse->run();
  52
  53 sub usage
  54 {
  55     die("Usage: $me [-vqh] [-f <dbfile>] [--] <sourcedir> <mountpoint>\n".
  56         " -v\t\t\tVerbose (repeat for more verbosity)\n".
  57         " -h\t\t\tThis help\n".
  58         " -f|--database=FILE\tPath to database file\n" .
  59         " --\t\t\tEnd of options\n");
  60 }
  61
  62 __END__
  63
  64 =head1 NAME
  65
  66 id3fsd - FUSE filesystem for browsing id3 tags
  67
  68 =head1 SYNOPSIS
  69
  70 B<id3fsd> [B<-vh>] S<B<[-f >I<dbfile>]> [B<-->] I<SOURCEDIR> I<MOUNTPOINT>
  71
  72 =head1 DESCRIPTION
  73
  74 id3fsd provides a browsable filesystem of your music files, organised
  75 into sub-directories by id3 tags (or flac/ogg comments).
  76
  77 id3fsd allows you to construct boolean queries from a tag folksonomy
  78 such as:
  79
  80   goth/AND/decade/1980s/
  81   postrock/AND/NOT/rating/terrible/
  82   thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/
  83   prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/
  84   location/sweden/AND/screamo/AND/postrock/
  85
  86 Multiple tags can be stored in the genre tag, separated by commas.
  87 An index should first be created with L<id3fs-index(1)>, then id3fsd
  88 can mount the files in I<SOURCEDIR> on the directory I<MOUNTPOINT>.
  89
  90 If not explicitly specified (with B<-f>), the index is searched for
  91 at I<SOURCEDIR>/B<.id3fs>.
  92
  93 The resulting filesystem is read-only. Tags appear as directories,
  94 and files appear as symlinks to the actual files in I<SOURCEDIR>.
  95
  96 =head1 QUICKSTART
  97
  98 To mount a view of F<~/music> on F<~/tags>:
  99
 100   $ mkdir ~/tags
 101   $ id3fs-index ~/music
 102   $ id3fsd ~/music ~/tags
 103
 104 You may need to be in the I<fuse> group, or be root.
 105
 106 =head1 OPTIONS
 107
 108 =over 4
 109
 110 =item B<-v>
 111
 112 Enable verbose operation. Repeat for more verbosity.
 113
 114 =item B<-h>
 115
 116 Show a short help message.
 117
 118 =item S<B<-f >I<FILE>> | S<B<--database=>I<FILE>>
 119
 120 Use database in I<FILE>. The default is I<SOURCEDIR>/B<.id3fs>.
 121
 122 =item B<-->
 123
 124 End of options.
 125
 126 =back
 127
 128 =head1 FILESYSTEM LAYOUT
 129
 130 A path in the filesystem consists of a tag query expression, followed
 131 by directories containing the matching files, arranged by artist and
 132 album.
 133
 134 Example paths:
 135
 136   /krautrock/AND/year/1971/
 137   /krautrock/AND/year/1971/Can
 138   /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3
 139   /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3
 140   /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3
 141   /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3
 142   /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3
 143   /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3
 144
 145 =head2 Tags
 146
 147 Tags are extracted from the B<genre> tag of audio files with
 148 L<id3fs-index(1)>.
 149
 150 Within the genre frame/comment, tags are separated by commas.
 151
 152 Tags can have values, separated by a slash, eg I<metal/thrash>,
 153 I<rating/5>. Certain tags are automatically filled in from other file
 154 metadata, see L</"Special Tags>.
 155
 156 =head2 Special Directories
 157
 158 =over 4
 159
 160 =item B<ALL>
 161
 162 This is a special directory in the root of the filesystem, that
 163 provides access to all the indexed files, regardless of tags assigned.
 164
 165 =item B<TRACKS>
 166
 167 All tracks that match the given tag expression, whether they have an
 168 assigned artist and album or not.
 169
 170 =item B<NOARTIST>
 171
 172 Tracks matching the given expression that do not have an artist tag.
 173
 174 =item B<NOALBUM>
 175
 176 Tracks matching the given expression that do not have an album tag.
 177
 178 =back
 179
 180 =head2 Special Tags
 181
 182 Several tags are automatically derived from other metadata in the
 183 audio files:
 184
 185 =over 4
 186
 187 =item B<year>
 188
 189 Extracted from the B<year> or B<DATE> tag. If not found defaults to
 190 B<year/UNKNOWN>.
 191
 192 =item B<decade>
 193
 194 Also extracted from the B<year> or B<DATE> tag. If not found
 195 defaults to B<decade/UNKNOWN>.
 196
 197 =item B<v1genre>
 198
 199 If a mp3 file has an ID3V1.1 genre tag, its value is assigned to
 200 v1genre.
 201
 202 =item B<audiotype>
 203
 204 Type of audio file (mp3, ogg, flac). Always set.
 205
 206 =back
 207
 208 =head1 FUSE AND MOUNTING AUTOMATICALLY
 209
 210 For others to be able to view your id3fs mount(s), you need to set the
 211 option B<user_allow_other> in F</etc/fuse.conf>.
 212
 213 To mount a filesystem automatically, put an entry in F</etc/fstab>
 214 like:
 215
 216   id3fsd#/source/dir    /mount/point    defaults   0   0
 217
 218 =head1 CAVEATS
 219
 220 Because id3fs offers a combinatorial explosion of views of your files,
 221 processes recursing into the mount point will take a B<long> time to
 222 traverse it.
 223
 224 Ensure your backups, cron jobs, F</etc/updatedb.conf>, etc. are
 225 configured to exclude the mount point.
 226
 227 =head1 EXAMPLES
 228
 229 To mount an id3fs filesystem which indexes B<~/music/albums> on
 230 B<~/music/tags>:
 231
 232 First create the index:
 233
 234     id3fs-index -v ~/music/albums
 235
 236 If you have a large collection of music, this may take some time.
 237
 238 Then create the mountpoint:
 239
 240     mkdir ~/music/tags
 241
 242 and mount the filesystem:
 243
 244     id3fsd ~/music/albums ~/music/tags
 245
 246 Then explore the tags in ~/music/tags/
 247
 248 =head1 BUGS
 249
 250 Please report any found to ianb@erislabs.net
 251
 252 =head1 SEE ALSO
 253
 254 L<id3fs-index(1)>, L<http://fuse.sourceforge.net>
 255
 256 =head1 AUTHOR
 257
 258 Ian Beckwith <ianb@erislabs.net>
 259
 260 Many thanks to Aubrey Stark-Toller for help wrangling SQL.
 261
 262 =head1 AVAILABILITY
 263
 264 The latest version can be found at:
 265
 266 L<http://erislabs.net/ianb/projects/id3fs/>
 267
 268 =head1 COPYRIGHT
 269
 270 Copyright (C) 2010  Ian Beckwith <ianb@erislabs.net>
 271
 272 This program is free software: you can redistribute it and/or modify
 273 it under the terms of the GNU General Public License as published by
 274 the Free Software Foundation, either version 3 of the License, or
 275 (at your option) any later version.
 276
 277 This program is distributed in the hope that it will be useful,
 278 but WITHOUT ANY WARRANTY; without even the implied warranty of
 279 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 280 GNU General Public License for more details.
 281
 282 You should have received a copy of the GNU General Public License
 283 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 284
 285 =cut