OGGFILTER(1)            FreeBSD General Commands Manual           OGGFILTER(1)

NAME
     oggfilter -- filter a list of ogg/vorbis files using various criteria

SYNOPSIS
     oggfilter [-l | --min-length period] [-L | --max-length period]
               [-b | --min-bitrate bitrate] [-B | --max-bitrate bitrate]
               [-x | --expression regexp] [-X | --exclude-expression regexp]
               [-d | --directory directory] [-P | --processes count]
               [-v | --invert] [-I | --no-ignorecase] [-0 | --print0]

     oggfilter {-h | --help}

DESCRIPTION
     The oggfilter utility reads sequentially a list of ogg/vorbis files from
     standard input  and filters this list using various criteria defined via
     command line options. All ogg/vorbis files matching these criteria are
     written to standard output.

     All specified criteria are combined using logical AND.

     These are the available command line options:

     -l | --min-length period
                 Matches every ogg/vorbis file with a play time longer than
                 the specified period.  period may be expressed as seconds or
                 in minutes:seconds syntax.

     -L | --max-length period
                 Matches every ogg/vorbis file with a play time shorter than
                 the specified period.  period may be expressed as seconds or
                 in minutes:seconds syntax.

     -b | --min-bitrate bitrate
                 Matches every ogg/vorbis file with a nominal bitrate higher
                 than bitrate kbps

     -B | --max-bitrate bitrate
                 Matches every ogg/vorbis file with a nominal bitrate lower
                 than bitrate kbps

     -x | --expression regexp
                 Matches every ogg/vorbis file containing at least one vorbis-
                 comment matching the extended regular expression regexp.  The
                 regular expression matching is case-insensitive unless the -I
                 flag is given. See re_format(7) for a complete discussion of
                 the extended regular expression format. This option may be
                 specified multiple times.

     -X | --exclude-expression regexp
                 This is the inversion of the -x flag. It excludes any
                 ogg/vorbis files containing at least one vorbiscomment match-
                 ing the extended regular expression regexp.  This option may
                 be specified multiple times.

     -d | --directory directory
                 Prepends every line read from standard input with directory
                 if the first character of the line is not a slash.

     -v | --invert
                 Invert the result set - return all ogg/vorbis files not
                 matching the specified criteria.

     -P | --processes count
                 Instructs oggfilter to spawn count worker processes. This may
                 speed up the processing on multi processor machines.  A good
                 choice is to set count equal to the amount of processor cores
                 available. By default oggfilter runs as a single process.

     -I | --no-ignorecase
                 This flag makes all expressions provided via -x and -X case
                 sensitive.

     -0 | --print0
                 This flag emits the matching filenames followed by an ASCII
                 NUL character instead of a newline character. You may use
                 this to use xargs(1) in conjunction with oggfilter.

     -h | --help
                 Print the synopsis of oggfilter and exit. This overrides any
                 other options.

ENVIRONMENT
     oggfilter peruses the LANG and LC_ALL environment variables to determine
     the systems locale. This is mandatory for expression matching.

EXAMPLES
     To get a list of all your ogg/vorbis files tagged with genre ``Thrash
     Metal'' use the following command line:

           find /my/music -type f -name '*.ogg' | oggfilter -x '^genre=thrash
           metal$'

     To filter a list of ogg/vorbis files for files not tagged as ``Neo Folk''
     or ``Power Metal'' you may use:

           oggfilter -v -E -x '^genre=(neo folk|power metal)$' < playlist.m3u

     To get a list of all your ogg/vorbis files tagged with genre ``Thrash
     Metal'' and containing ``death'' in it's title use the following command
     line:

           oggfilter -x '^genre=thrash metal$' -x '^title=.*death.*' <
           playlist.m3u

     To get a list of all your ogg/vorbis files tagged with genre ``Thrash
     Metal'' and not containing ``death'' in it's title use the following com-
     mand line:

           oggfilter -x '^genre=thrash metal$' -X '^title=.*death.*' <
           playlist.m3u

     To get a list of all ogg/vorbis files with a maximum playtime of 5 min-
     utes and a minimum playtime of 3 minutes you may use:

           oggfilter -l 180 -L 5:00 < playlist.m3u

     To get a list of ogg/vorbis files encoded with a minimal nominal bitrate
     of 120 kbps use:

           oggfilter -b 120 < playlist.m3u

     If you are piping from a playlist containing relative paths you can tell
     oggfilter to prepend a base path to the read ogg/vorbis files:

           oggfilter -d /my/music -x '^genre=.*metal$' < relative.m3u

PORTABILITY
     oggfilter was written in ANSI/C so it should compile on every unix-like
     platform supporting an ANSI/C compiler and libvorbis. But this was writ-
     ten on a FreeBSD system and has not been tested on other platforms.

     The supplied Makefile is a BSD-style Makefile and uses the FreeBSD infra-
     structure. This is not portable, but as oggfilter is pretty simple there
     should be no problem to write a simple Makefile for other platforms.

DIAGNOSTICS
     The oggfilter utility exits 0 on success, and >0 if an error occurs.

SEE ALSO
     re_format(7), vorbiscomment(1), ogginfo(1), setlocale(3), environ(7),
     xargs(1)

AUTHORS
     Tobias Rehbein <tobias.rehbein@web.de>

BUGS
     oggfilter will only work correctly in locales using 8-bit charsets or
     multi byte charsets backwards compatible with ASCII, most notably UTF-8.

     Regular expression matching will only work if the vorbis comments are
     representable in the locale charset.

     Expect some rough edges as this was my first take on a C program.

     If you find a bug drop me a mail or file an issue at
           http://github.com/blabber/oggfilter/issues

FreeBSD 8.2                     March 25, 2009                     FreeBSD 8.2