links

< home >
< unix stuff >
< code >
< writing >
< archive >
< music >
< photos >
< recipes >
< site map >
< about badcomputer >

sneetchalizer

The sneetchalizer is a Ruby script which converts between several different audio file formats and tries to preserve meta tags if they exist or create them if they don't. The script can handle any number of file and/or directory arguments. sneetchalizer is the glue that binds together various audio encoders/decoders:

lame

for mp3 encoding/decoding (MPEG-1 Audio Layer 3)

gogo

for mp3 encoding (MPEG-1 Audio Layer 3)

bladeenc

for mp3 encoding (MPEG-1 Audio Layer 3)

oggenc and oggdec

for ogg encoding/decoding (Ogg Vorbis)

faac and faad

for m4a, m4b, mp4 and aac encoding/decoding (MPEG-4 Part 14)

flac

for flac encoding/decoding (Free Lossless Audio Codec)

mplayer

for wma decoding (Windows Media Audio)

mac

for ape encoding/decoding (Monkey's Audio)

mppenc and mppdec

for Musepack encoding/decoding

wavpack and wvunpack

for Wavpack encoding/decoding

speexenc and speexdec

for Speex encoding/decoding (Note: you must build with "Ultra-wideband" support for this to work)

ttaenc

for True Audio encoding/decoding

ofr and ofs

for OptimFROG and OptimFROG DualStream encoding/decoding

sox

for aif, au, cdr and mp2 encoding/decoding

* You can retrieve mp3 id3 tags if you install Guillaume Pierronnet's ruby-mp3info library, Robin Stoker's id3lib-ruby library, or Tilo Sloboda's ID3 library for Ruby. They will be searched for and used in that same order.
* You can retrieve wma meta-tags if you install my wmainfo-rb library (>= 0.3).
* You can retrieve flac meta-tags if you install my flacinfo-rb library.
* You can retrieve m4a/aac et al meta-tags if you install Jason Terk's MP4Info library.
* You can retrieve ogg meta-tags if you install Guillaume Pierronnet's ruby-ogginfo library.
* You can retrieve ape, mpp, mpc, ofr, ofs, tta, and wv meta-tags if you install Jeremy Evans' ruby-apetag library.

You can view the source code.

download

Current version:

• sneetchalizer-0.9.0 [MD5] [CHANGES]

Older versions:

• sneetchalizer-0.8.0 [MD5] [CHANGES]
• sneetchalizer-0.7.2 [MD5][CHANGES]
• sneetchalizer-0.7.1 [MD5] [CHANGES]
• sneetchalizer-0.7.0 [MD5] [CHANGES]
• sneetchalizer-0.6.0 [MD5] [CHANGES]
• sneetchalizer-0.5.2 [MD5] [CHANGES]
• sneetchalizer-0.5.1 [MD5] [CHANGES]
• sneetchalizer-0.5.0 [MD5] [CHANGES]
• sneetchalizer-0.4.3 [MD5] [CHANGES]
• sneetchalizer-0.4.2 [MD5] [CHANGES]
• sneetchalizer-0.4 [MD5] [CHANGES]
• sneetchalizer-0.3 [MD5] [CHANGES]
• sneetchalizer-0.2 [MD5] [CHANGES]

I have also written an ebuild file for those who run Gentoo. If you have the 'wma' USE flag set then the ebuild will depend on wmainfo-rb's ebuild file. If you have 'flac' USE flag set it will rely on flacinfo-rb's ebuild.

• sneetchalizer-0.9.0.ebuild
• wmainfo-rb-0.5.ebuild
• flacinfo-rb-0.4.ebuild

usage and examples

sneetchalizer command line flags/options:

General options:

-h or --help

Print quick or full usage details respectively.

-r or --recursive

Search directory arguments recursively for files to convert.

-d or --delete

delete input files after successful conversion. May not be safe yet!!!

-v or --verbose

makes sneetchalizer more chatty.

-s or --show-output

shows output from conversion tool.

-p or --pretend

don't convert anything. sneetchalizer will go through the motions and print out the commands it would run. Useful for preview- ing a complex command line to ensure it does what you intend. You should interpret this option's output with a grain of salt. For example, if you include the '--sanitize' option, the files will not really be renamed when using --pretend, and as such the command's output will not reflect that the filenames would be changed during an actual run.

-t or --terminate

terminate sneetchalizer options. This is useful if you have to convert '--coolDir' or '-groovySong.mp3'. This is the only option whose order on the command line is significant.

-D ARG or --out-directory=ARG

write all outfiles to a directory argument. This is useful if you want to (re)encode files directly to a mounted portable device.

--strict and --pedantic

many errors that sneetchalizer may encounter are recoverable, such as specifying a directory as argument that contains no files to convert, or conversion failures in general. By default the script will print an error message and move on to the next file. If you use '--strict' then sneetchalizer will bail out at the first sign of trouble except for tag errors. With '--pedantic' the script will stop even on tag errors.

--stasis

Preserve timestamp (mtime) of original file.

--threads [N]

Experimental. Use threads to create concurrent jobs. This option takes an optional integer argument which represents the number of threads to launch. The default is two. Preliminary tests suggest there is little advantage (and even diminishing returns) when setting this number greater than the number of cores/CPUs you have. Due to the asychronous nature of threads the --verbose and --show-output flags will be silently disabled and most screen output is supressed.

--sanitize

Removes ,, ;, :, ', ", %, @, #, and ` from filenames and tags.

-n [FORMAT] or --rename[=FORMAT]

rename all outfiles (and temporary wavs) according to FORMAT. FORMAT is a string with special designators to be pulled from the file tags. The following options are available:

• %t Song title
• %b Album title
• %n Track number
• %a Artist name
• %y Year
• %g Genre
• %c Comment field

Directories may be created with this command, as in "%b/%n - %t". The default value of FORMAT is "%n %t".

Bitrate/Quality/Compression options:

-b or --bitrate

mp3/ogg/m4a bitrate.

-q or --quality

mp3/ogg quality.

quality and bitrate are passed directly to lame or oggenc depending on mp3 or ogg output format respectively. Both tools can handle either a bitrate or quality argument, so it is important to understand what values are valid for the underlying tool in your specific use case. faac will accept a bitrate argument, but not a quality argument. These options will be silently ignored for any output formats other than mp3, ogg or m4a. Make sure you know what you are doing if you decide to use both in one run, and read each tools manpage for valid values. If these options are omitted the tools builtin defaults are used (-q3 for oggenc and -q5 for lame).

-c or --compression

flac/mac compression level.

this option allows you to pass a compression argument to flac and mac. See 'flac --help' and/or 'mac --help' if you don't know what this means.

Format Options:

--out=format

output format. Default is wav.

--in=format[,format..]

input format(s). Default is wav.

Valid output formats are: "aac", "aif", "aifc", "aiff", "aiffc", "ape", "au", "cdr", "cdda", "copy", "flac", "m4a", "m4b", "mpc", "mp4", "mpp", "mp3", "mp2", "ofr", "ofs", "ogg", "snd", "spx", "tta", "wav", "wv". Valid input formats are all of the above plus "wma". You can specify multiple input formats using a comma: 'mp3,m4a,wma'. Input format is only neccesary when passing directory arguments, as file arguments are handled by context (read: file extension). The "copy" output option copies files directly, bypassing decoding/encoding steps (useful in conjunction with --rename).

Tagging Options:

--tt or --title

Set 'title' tag.

--ta or --artist

Set 'artist' tag.

--tl or --album

Set 'album' tag.

--ty or --year

Set 'year' tag.

--tc or --comment

Set 'comment' tag.

--tg or --genre

Set 'genre' tag.

--tn or --trackn

Set 'track number' tag.

The short and long versions are different in an important way: Using the long version will clobber any existing tags. The short version will only set the tag if the existing tag has no value. Note that these tags will be placed in _every_ outfile during the run.

Alternative Encoder/Decoder Options:

--gogo

use gogo to encode mp3 files.

--bladeenc

use bladeenc to encode mp3 files.

The default is still 'lame'. If 'lame' is not found, the script will search for one of these two encoders regardless if these options are passed or not.

Special Options:

--in-optionhook=ARG

add ARG to infile conversion command. Possibly dangerous!

--out-optionhook=ARG

add ARG to outfile conversion command. Possibly dangerous!

These two options are a hook to pass additional options to the underlying conversion tools. ARG is passed directly to the shell (right after the command name) so escape it if neccesary. The underlying tool will depend on input and output format, for example, if --in is ogg and --out is mp3 then --in-optionhook's value would get passed to oggdec and --out-optionhook's value would be passed to lame. Using these options are at your own risk, and bug reports involving them will be ignored.

Example usage:

$ sneetchalizer song.mp3

The most simple possible example, creates 'song.wav'.

$ sneetchalizer --out=ogg --in=flac -q5 /some/music/dir

This example converts every flac file in '/some/music/dir' to ogg format at quality 5.

$ sneetchalizer -d --out=mp3 --in=ogg,m4a,wma -b 160 .

Converts every ogg, m4a, and wma file in the current directory to a 160 kbps constant bitrate mp3 file. The original files are deleted.

$ sneetchalizer --out=mp3 --out-optionhook="--preset extreme" /some/wavs

Here we encode every wav in '/some/wavs' to mp3 format passing '--preset extreme' directly to lame.

$ sneetchalizer --in=ogg --out=ogg --quality=1 norvegianWood.ogg /some/more/oggs

Using the same --in and --out format allows us to resample/encode the file at a different bitrate or quality. Note that this will overwrite the original file so only do this on a copy, or use '-D' to write files to another directory.

$ sneetchalizer --in=ogg --out=m4a -D /mnt/ipod/ /some/oggs

Here we re-encode some ogg files to m4a format and write them to our mounted iPod.

bugs

The ID3v2 spec suggests that you can specify an arbitrary genre, (and sneetchalizer tells lame to write v2 tags) however, lame does not seem to implement this. Consequently, if your original file's genre tag is not one of the ID3 specs (stupid!) predefined genres it will be coerced to (12) which means 'Other'. There is nothing I can do about this.

If your filenames or tags contain certain special characters the script may break. If you find such a character feel free to send me a bug report, as at some point in the future I will attempt to have the script escape them. If your filenames/tags contain non-printing control characters the script will almost certainly break. If this is the case fix your filenames! You can use 'ls -q' to discover these. If they are in the tags I am unsure what I can do. By default the script will create a scratch tag when it encounters tag errors, so you will likely lose the original tag.

I am fairly clueless when it comes to unicode, so I am unsure of the effect unicode characters in filenames/tags will have. If you are a unicode wizard who feels like sending me a patch to allow unicode characters you will forever be immortalized on this webpage, in the README, and in the script itself!

If you intend to script or debug sneetchalizer you may be interested in the exit codes. These are documented at the bottom of the script itself.

Send bug reports, comments, feature requests and money to: sneetch [at] badcomputer [dot] org

stats

It is Thursday July 24, 2008 9:30 am
This page served 14158 times
This page last modified: April 27, 2008 11:14 am
Your IP address is: 38.103.63.16
You are browsing using: CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
You are browsing from: United States.
badcomputer.org's uptime: 09:30:19 up 12 days, 19:57, 3 users, load average: 1.04, 1.04, 1.00