Transcoding HOWTO
From MtdWiki
Note
You will need a version of mt-daapd that supports transcoding. Current stable (0.2.3) does not. You'll need to move to nightlies from 2005-03-05 (http://nightlies.mt-daapd.org/dl.php?FILE=mt-daapd-cvs-20050305.tar.gz) (version with gdbm backend) or current nightlies (http://nightlies.mt-daapd.org) (with sqlite backend).
| Table of contents |
Basic Concept
The concept behind transcoding is simple. You may have some files in your music library that iTunes or another mt-daapd client can't play (ogg or flac, for example). One (poor) solution would be to convert all your files into mp3/wav so these clients could play them. Alternatively, What if when the client tried to play an incompatible file, you could have mt-daapd send a wav-format stream of file instead, leaving your local library untouched?
This way you could keep your songs in any format you'd like, yet at the same time have them playable by any client.
In order for this process to work transparently, there are two things that have to happen. One is that mt-daapd has to be able to read the tag information from the file in question. Every type of audio file stores that tag information differently, though, and the mt-daapd has to be updated to be able to read tags for a specific type of file.
The next thing that has to happen is that mt-daapd has to have a way to convert from one file type to another. It does this using plugins or transcode scripts, documented later.
Tag Info
mt-daapd can read the tags for the following types of files
Current stable can read tag info from the following formats:
- mp3 (id3v1/id3v2 -- as supported by libid3tag)
- aac/m4a/m4p
- flac (only when compiled with flac support: see Configure Flags)
- ogg (only when compiled with oggvorbis support: see Configure Flags)
- wma (very early -- not as robust as others)
Current svn build (1498) also has the ability to read the following formats:
- url (it can read title, and bitrate (and url) from the stream)
- xml (mt-daapd seems to be able to read some Itunes library's)
Note on .wav and .aif files: These files do not contain tag information. Mt-daapd however does get bit-rate, duration etc.
If your format isn't in the list, mt-daapd can not read the tags. The files will show up in I-tunes, but just with the filename as title. Since no duration of the song is known, it defaults to 10 minutes. It will however detect that a song has ended. If the tags of your cannot be read you will probably have to write your own plugin/scan code to do this.
Just because it CAN read the tag info from these types of files doesn't mean it will by default. To make mt-daapd index these files, you still have to add those files extensions to the "extensions" config item in your mt-daapd.conf.
If you do this, you should be able to connect with iTunes and see these types of files in your songs list. This will include songs you normally didn't see there -- ogg files, flac files, etc. You won't be able to play them, however. You can click on them, but iTunes won't play them. That's because iTunes won't play ogg files or flac files -- even if the quicktime components are installed. So on to the next step.
ffmpeg Plugins (recommended for most people using nightly builds)
The current nightly builds come with a nice set of plugins. This allows mt-daapd to convert the more commonly used formats to .wav without the use of a large transcode script.
Plugins use ffmpeg to transcode many different file types and require little if any intervention on the user's part. This is the best solution unless for some reason you cannot use ffmpeg.
ffmpeg can transcode the following formats:
* ogg files * flac files * alac files * (there might be more I do not know of)
Be sure to include 'ssc-ffmpeg.so' in the 'plugins = ' section of your config. (And of course install ffmpeg on your machine)
Transcoding Scripts (no ffmpeg)
If you cannot use ffmpeg or ffmpeg does not support the format your files are encoded in, transcode scripts are the solution.
A transcode script is nothing more than a program that gets run whenever a user clicks on a song of a type that should be transcoded. The transcode script will output a .wav file to stdout so mt-daapd can stream it.
You need to disable ffmpeg plugin and append 'ssc-script.so' to your 'plugins = ' section of your config file to enable the use of transcode scripts.
Standard Transcoding Scripts
There are two different sample transcode scripts in the /contrib directory. One is called mt-daapd-ssc.sh, and the other mt-daapd-ssc.pl.
The mt-daapd-ssc.sh script transcodes the following formats: ogg and flac. It isn't much, but the advantage of this script is that it is easily adaptable to other more exotic formats.
The other transcode script, mt-daapd-ssc.pl, is more featureful, and transcodes just about everything: flac, aac, ogg, shn, au, apple lossless, etc. It (of course) requires perl, mplayer, ffmpeg, and alac-decoder depending on what types of media you are trying to transcode. This one makes more sense if you have a machine that can run it. It's not as easily hackable as the .sh one.
Writing Your Own Transcoding Script
If the plugins or standard transcode scripts don't give you the functionality you need you can write your own transcode script or modify a standard transcode script, it isn't that hard. If you look in the example mentioned above, you'll get a good idea how it works.
NOTE: This is the only way for transcoding more exotic audio files, or using your own player to do it.
Before you can start writing your own script you need to understand how mt-daapd uses your script:
When a user clicks on a song, mt-daapd runs the transcode script with the following arguments:
Arg 1: filename of file to transcode Arg 2: offset into the wav stream (in bytes) Arg 3: total length of the song (in seconds)
The .wav output must be dumped to stdout, as that is what will be sent to the client.
Assume that the file /mp3/somesong.ogg is the song to be transcoded, and that the transcode script is specified as "/usr/sbin/transcode.sh". When a user clicks on that song in iTunes, mt-daapd will run:
/usr/sbin/transcode.sh /mp3/somesong.ogg 0 320
This assumes that mt-daapd determined from the tag-scanning portion that the song was 320 seconds long. Then script /usr/sbin/transcode.sh must respond by dumping the .wav audio of songsong.ogg to stdout.
Although it may be better to edit the simple standard transcode script, I'm going to explain how to build a transcode script from scratch.
#!/bin/sh flac --silent --decode --stdout "$1"
The problem is that most x-to-wav programs don't fix up the wav headers properly, so they outputted wav has the wrong length. This confuses at least the Roku, so there is a helper program included called "wavstreamer" that will help fix up headers given the size of the output (this is why the song length is passed to the helper script).
So the real minimum flac transcode script would be:
#!/bin/sh flac --silent --decode --stdout "$1" | wavstreamer -o $2 -l $3
That's it. That fixes header problems, plus handles the offset (in case someone seeks to a specific offset in the file).
Putting it all Together
The config file entries that tie this all together are the following:
extensions -- the extensions to index (not used anymore) ssc_extensions -- the extensions that should be transcoded ssc_codectypes -- the codectype to decode (see config file for details) ssc_prog -- the server-side conversion script to be run when transcoding plugins -- the plugins mt-daapd should use (for example ffmpeg)
NOTE: If your format isn't in the codeclist in the config file you must pick the codec type "unkn".
To transcode ogg:
- configure mt-daapd with --enable-oggvorbis
- copy contrib/mt-daapd-ssc.pl to /usr/local/sbin
- set extensions to include ".ogg" (.mp3,.m4a,.m4p,.ogg might be a good value)
- set ssc_codectype to "ogg" (in older versions set ssc_extensions to ".ogg")
- set ssc_prog to "/usr/local/sbin/mt-daapd-ssc.pl"
Delete your songs.gdb/songs.db/songs3.db to force a full rescan, and that's it.
For flac, much the same, but you'll need to use --enable-flac, and use .flac rather than .ogg in the examples above.
If you're getting an error about an invalid directive, ssc_extensions, you're probably running a newer nightly build that now uses scc_codectypes as opposed to ssc_extensions.
So, in your mt-daapd.conf the new entries would look like this:
- ssc_prog /usr/local/sbin/mt-daapd-ssc.pl
- ssc_codectypes flac,shn,ogg,alac
Troubleshooting
So it doesn't work. Usually one of two problems:
1) mt-daapd doesn't know it's supposed to transcode.
Look at a file that should be transcoded... when you display info on it in iTunes, does it show up as a wav file? If not, then:
- your ssc_extensions/codectypes doesn't include that extension type OR
- you didn't force a rescan by deleting the songs.gdb (or songs.db) OR
- a plugin is trying to decode things it isn't supposed to. Check your 'plugins' entry in the configfile. (see above text for instructions to setting proper plugins)
2) transcode script isn't working.
run the transcode script by hand:
/usr/local/sbin/mt-daapd-ssc.pl /path/to/song 0 0
do you get an error message? Then fix it! (missing files, or perl dependencies). If it actually generates what looks like a .wav file, then pipe it to a file:
/usr/local/sbin/mt-daapd-ssc.pl /path/to/song 0 0 > /tmp/out.wav
Try and play that file from a regular media player. Does it work? If not, then something hosed with transcode script.
If all else fails, ask in the forums!
