From 994377a7cc7464bb0156a004b10ccf65df0cb89c Mon Sep 17 00:00:00 2001 From: Ian Beckwith Date: Tue, 19 Oct 2010 13:40:09 +0100 Subject: [PATCH] id3fsd: update man page --- sbin/id3fsd | 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 124 insertions(+), 6 deletions(-) diff --git a/sbin/id3fsd b/sbin/id3fsd index a699cb2..93d2d6c 100755 --- a/sbin/id3fsd +++ b/sbin/id3fsd @@ -36,6 +36,7 @@ my $optret=GetOptions( "help|h" => \$help, "database|f=s" => \$dbpath, "t|tagdepth=s" => \$tagdepth, + "o=s" => sub {;}, # silently drop options passed by mount ); usage() if(scalar(@ARGV) != 2 || !$optret || $help); @@ -73,6 +74,16 @@ B [B<-vh>] SI]> [B<-->] I I id3fsd provides a browsable filesystem of your music files, organised into sub-directories by id3 tags (or flac/ogg comments). +id3fsd allows you to construct boolean queries from a tag folksonomy +such as: + + goth/AND/decade/1980s/ + postrock/AND/NOT/rating/terrible/ + thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/ + prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/ + location/sweden/AND/screamo/AND/postrock/ + +Multiple tags can be stored in the genre tag, separated by commas. An index should first be created with L, then id3fsd can mount the files in I on the directory I. @@ -82,7 +93,15 @@ at I/B<.id3fs>. The resulting filesystem is read-only. Tags appear as directories, and files appear as symlinks to the actual files in I. -FIXME: better description, allow_others/fuse.conf, fstab, explain genre tag +=head1 QUICKSTART + +To mount a view of F<~/music> on F<~/tags>: + + $ mkdir ~/tags + $ id3fs-index ~/music + $ id3fsd ~/music ~/tags + +You may need to be in the I group, or be root. =head1 OPTIONS @@ -106,6 +125,105 @@ End of options. =back +=head1 FILESYSTEM LAYOUT + +A path in the filesystem consists of a tag query expression, followed +by directories containing the matching files, arranged by artist and +album. + +Example paths: + + /krautrock/AND/year/1971/ + /krautrock/AND/year/1971/Can + /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3 + /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3 + /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3 + /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3 + /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3 + /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3 + +=head2 Tags + +Tags are extracted from the B tag of audio files with +L. + +Within the genre frame/comment, tags are separated by commas. + +Tags can have values, separated by a slash, eg I, +I. Certain tags are automatically filled in from other file +metadata, see L. + +=head2 Special Directories + +=over 4 + +=item B + +This is a special directory in the root of the filesystem, that +provides access to all the indexed files, regardless of tags assigned. + +=item B + +All tracks that match the given tag expression, whether they have an +assigned artist and album or not. + +=item B + +Tracks matching the given expression that do not have an artist tag. + +=item B + +Tracks matching the given expression that do not have an album tag. + +=back + +=head2 Special Tags + +Several tags are automatically derived from other metadata in the +audio files: + +=over 4 + +=item B + +Extracted from the B or B tag. If not found defaults to +B. + +=item B + +Also extracted from the B or B tag. If not found +defaults to B. + +=item B + +If a mp3 file has an ID3V1.1 genre tag, its value is assigned to +v1genre. + +=item B + +Type of audio file (mp3, ogg, flac). Always set. + +=back + +=head1 FUSE AND MOUNTING AUTOMATICALLY + +For others to be able to view your id3fs mount(s), you need to set the +option B in F. + +To mount a filesystem automatically, put an entry in F +like: + + id3fsd#/source/dir /mount/point defaults 0 0 + +=head1 CAVEATS + +Because id3fs offers a combinatorial explosion of views of your files, +processes recursing into the mount point will take a B time to +traverse it. + +Ensure your backups, cron jobs, F, etc. are +configured to exclude the mount point. + =head1 EXAMPLES To mount an id3fs filesystem which indexes B<~/music/albums> on @@ -127,8 +245,6 @@ and mount the filesystem: Then explore the tags in ~/music/tags/ -FIXME: fstab - =head1 BUGS Please report any found to ianb@erislabs.net @@ -141,19 +257,21 @@ L, L Ian Beckwith +Many thanks to Aubrey Stark-Toller for help wrangling SQL. + =head1 AVAILABILITY The latest version can be found at: -B +L =head1 COPYRIGHT -Copyright 2010 Ian Beckwith +Copyright (C) 2010 Ian Beckwith This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 3 of the License, or +the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, -- 2.11.0