| blob | 1fc2d311b1276a48e9907a910c0b8dcb472a198d |
1 .\"
2 .\" "THE BEER-WARE LICENSE" (Revision 42):
3 .\" <tobias.rehbein@web.de> wrote this file. As long as you retain this notice
4 .\" you can do whatever you want with this stuff. If we meet some day, and you
5 .\" think this stuff is worth it, you can buy me a beer in return.
6 .\" Tobias Rehbein
7 .\"
8 .
9 .Dd March 25, 2009
10 .Os
11 .Dt OGGFILTER 1
12 .
13 .Sh NAME
14 .
15 .Nm oggfilter
16 .Nd filter a list of ogg/vorbis files using various criteria
17 .
18 .
19 .Sh SYNOPSIS
20 .
21 .Nm
22 .Op Fl l | Fl -min-length Ar period
23 .Op Fl L | Fl -max-length Ar period
24 .Op Fl b | Fl -min-bitrate Ar bitrate
25 .Op Fl B | Fl -max-bitrate Ar bitrate
26 .Op Fl x | Fl -expression Ar regexp
27 .Op Fl X | Fl -exclude-expression Ar regexp
28 .Op Fl d | Fl -directory Ar directory
29 .Op Fl P | Fl -processes Ar count
30 .Op Fl v | Fl -invert
31 .Op Fl I | Fl -no-ignorecase
32 .Op Fl 0 | Fl -print0
33 .Pp
34 .Nm
35 .Brq Fl h | Fl -help
36 .
37 .
38 .Sh DESCRIPTION
39 .
40 The
41 .Nm
42 utility reads sequentially a list of ogg/vorbis files from standard input and
43 filters this list using various criteria defined via command line options. All
44 ogg/vorbis files matching these criteria are written to standard output.
45 .Pp
46 All specified criteria are combined using logical AND.
47 .Pp
48 These are the available command line options:
49 .
50 .Bl -tag
51 .It Fl l | Fl -min-length Ar period
52 Matches every ogg/vorbis file with a play time longer than the specified
53 .Ar period .
54 .Ar period
55 may be expressed as seconds or in minutes:seconds syntax.
56 .
57 .It Fl L | Fl -max-length Ar period
58 Matches every ogg/vorbis file with a play time shorter than the specified
59 .Ar period .
60 .Ar period
61 may be expressed as seconds or in minutes:seconds syntax.
62 .
63 .It Fl b | Fl -min-bitrate Ar bitrate
64 Matches every ogg/vorbis file with a nominal bitrate higher than
65 .Ar bitrate
66 kbps
67 .
68 .It Fl B | Fl -max-bitrate Ar bitrate
69 Matches every ogg/vorbis file with a nominal bitrate lower than
70 .Ar bitrate
71 kbps
72 .
73 .It Fl x | Fl -expression Ar regexp
74 Matches every ogg/vorbis file containing at least one vorbiscomment matching
75 the extended regular expression
76 .Ar regexp .
77 The regular expression matching is case-insensitive unless the
78 .Fl I
79 flag is given. See
80 .Xr re_format 7
81 for a complete discussion of the extended regular expression format. This option
82 may be specified multiple times.
83 .
84 .It Fl X | Fl -exclude-expression Ar regexp
85 This is the inversion of the
86 .Fl x
87 flag. It excludes any ogg/vorbis files containing at least one vorbiscomment
88 matching the extended regular expression
89 .Ar regexp .
90 This option may be specified multiple times.
91 .
92 .It Fl d | Fl -directory Ar directory
93 Prepends every line read from standard input with
94 .Ar directory
95 if the first character of the line is not a slash.
96 .
97 .It Fl v | Fl -invert
98 Invert the result set - return all ogg/vorbis files not matching the specified
99 criteria.
100 .
101 .It Fl P | Fl -processes Ar count
102 Instructs
103 .Nm
104 to spawn
105 .Ar count
106 worker processes. This may speed up the processing on multi processor machines.
107 A good choice is to set
108 .Ar count
109 equal to the amount of processor cores available. By default
110 .Nm
111 runs as a single process.
112 .
113 .It Fl I | Fl -no-ignorecase
114 This flag makes all expressions provided via
115 .Fl x
116 and
117 .Fl X
118 case sensitive.
119 .
120 .It Fl 0 | Fl -print0
121 This flag emits the matching filenames followed by an ASCII NUL character
122 instead of a newline character. You may use this to use
123 .Xr xargs 1
124 in conjunction with
125 .Nm .
126 .
127 .It Fl h | Fl -help
128 Print the synopsis of
129 .Nm
130 and exit. This overrides any other options.
131 .
132 .El
133 .
134 .
135 .Sh ENVIRONMENT
136 .
137 .Nm
138 peruses the
139 .Ev LANG
140 and
141 .Ev LC_ALL
142 environment variables to determine the systems locale. This is mandatory for
143 expression matching.
144 .
145 .Sh EXAMPLES
146 .
147 To get a list of all your ogg/vorbis files tagged with genre
148 .Dq Thrash Metal
149 use the following command line:
150 .Pp
151 .Dl find /my/music -type f -name '*.ogg' | oggfilter -x '^genre=thrash metal$'
152 .Pp
153 To filter a list of ogg/vorbis files for files not tagged as
154 .Dq Neo Folk
155 or
156 .Dq Power Metal
157 you may use:
158 .Pp
159 .Dl oggfilter -v -E -x '^genre=(neo folk|power metal)$' < playlist.m3u
160 .Pp
161 To get a list of all your ogg/vorbis files tagged with genre
162 .Dq Thrash Metal
163 and containing
164 .Dq death
165 in it's title use the following command line:
166 .Pp
167 .Dl oggfilter -x '^genre=thrash metal$' -x '^title=.*death.*' < playlist.m3u
168 .Pp
169 To get a list of all your ogg/vorbis files tagged with genre
170 .Dq Thrash Metal
171 and not containing
172 .Dq death
173 in it's title use the following command line:
174 .Pp
175 .Dl oggfilter -x '^genre=thrash metal$' -X '^title=.*death.*' < playlist.m3u
176 .Pp
177 To get a list of all ogg/vorbis files with a maximum playtime of 5 minutes and
178 a minimum playtime of 3 minutes you may use:
179 .Pp
180 .Dl oggfilter -l 180 -L 5:00 < playlist.m3u
181 .Pp
182 To get a list of ogg/vorbis files encoded with a minimal nominal bitrate of
183 120 kbps use:
184 .Pp
185 .Dl oggfilter -b 120 < playlist.m3u
186 .Pp
187 If you are piping from a playlist containing relative paths you can tell
188 .Nm
189 to prepend a base path to the read ogg/vorbis files:
190 .Pp
191 .Dl oggfilter -d /my/music -x '^genre=.*metal$' < relative.m3u
192 .
193 .
194 .Sh PORTABILITY
195 .
196 .Nm
197 was written in ANSI/C so it should compile on every unix-like platform
198 supporting an ANSI/C compiler and libvorbis. But this was written on a
199 .Fx
200 system and has not been tested on other platforms.
201 .Pp
202 The supplied Makefile is a BSD-style Makefile and uses the
203 .Fx
204 infrastructure. This is not portable, but as
205 .Nm
206 is pretty simple there should be no problem to write a simple Makefile for
207 other platforms.
208 .
209 .
210 .Sh DIAGNOSTICS
211 .
212 .Ex -std
213 .
214 .
215 .Sh SEE ALSO
216 .
217 .Xr re_format 7 ,
218 .Xr vorbiscomment 1 ,
219 .Xr ogginfo 1 ,
220 .Xr setlocale 3 ,
221 .Xr environ 7 ,
222 .Xr xargs 1
223 .
224 .
225 .Sh AUTHORS
226 .
227 .An "Tobias Rehbein" Aq tobias.rehbein@web.de
228 .
229 .
230 .Sh BUGS
231 .
232 .Nm
233 will only work correctly in locales using 8-bit charsets or multi byte charsets
234 backwards compatible with ASCII, most notably UTF-8.
235 .Pp
236 Regular expression matching will only work if the vorbis comments are
237 representable in the locale charset.
238 .Pp
239 Expect some rough edges as this was my first take on a C program.
240 .Pp
241 If you find a bug drop me a mail or file an issue at
242 .Dl http://github.com/blabber/oggfilter/issues
243 .
244 .