Transcoding HOWTO

Basic Concept

The basic concept of server side conversion is easy. mt-daapd scans music files (including files that iTunes or other clients don't understand) and advertises them when the client connects. When the client tries to play one of the songs that the client doesn't understand, then mt-daapd can convert those files into a file format that the client can play.

This allows clients to be able to play file types they otherwise couldn't.

In order for this process to work transparently, there are two things that mt-daapd must do.

  1. read descriptive tag information from the audio 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.

  2. convert from one file type to another. mt-daapd does this using plugins or transcode scripts, documented in sections below below.

Level of support

The current stable build (0.2.4.1 as of November 2007) does not have support for transcoding built in. Follow the instructions below to add it in.

The current nightly build (svn 1696 as of Mon, 29 October 2007) includes support for transcoding .m4a, .m4p, .ogg, .flac audio files. If you install this build, or any likely later one, you don't need to read any of the rest of this page in order to play those formats.

If you want to add transcoding support to a build that doesn't have it, or add transcoding support for a format not already supported, then the rest of this document will help you figure out how to do this.

Tag information

mt-daapd can read the tags for the following types of files

Current stable can read tag info from the following formats:

Current svn build (1498) also has the ability to read the following formats:

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.

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. It uses ffmpeg plugin to transcode every filetype mentioned in ssc_codectypes.

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

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:

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 trans

NOTE: If your format isn't in the codeclist in the config file you must pick the codec type "unkn".

To transcode ogg:

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:

Troubleshooting

Here are some symptoms of problems, and corrections to attempt.

If all else fails, ask in the forums!

File doesn't play in iTunes, and doesn't look like a music file in iTunes

Refer to the two sections below:

  1. mt-daapd configuration doesn't correctly invoke transcoding

  2. transcode script isn't working

mt-daapd configuration doesn't correctly invoke transcoding

Possible cause: 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:

  1. your ssc_extensions/codectypes doesn't include that extension type OR
  2. you didn't force a rescan by deleting the songs.gdb (or songs.db) OR
  3. 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)

Transcode script isn't working

Possible cause: the transcode script is giving errors, or it is generating an incorrect audio file.

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.

Config File has no [plugins] section

If your Config File has no [plugins] section, then you may be using the stable build, which doesn't have support for plugins or transcoding built in. Try using a more recent nightly build instead. See above under Levels of support.

Transcoding HOWTO (last edited 2007-11-10 04:55:03 by sr-14)