UPnP with People: Open Source Media Sharing with MediaTomb


If you buy a “smart” TV or DVR these days, the odds are that it will support UPnP for hassle-free media sharing. Thus devices like TiVos can locate each other and share recordings across the LAN, and a lot of Linux music and video players support connecting to UPnP shares as well. Give it a moment’s thought, however, and you’ll probably ask yourself “does it need a specialized device, or can I turn my existing Linux box into a full-blown UPnP server for my existing content?” Well, good news: not only can you, but it is pretty painless to do.

UPnP stands for “Universal Plug and Play,” and encompasses a family of network protocols that PCs and embedded devices like set-top boxes can use to discover each other and share services. The low-level parts of the stack are familiar territory: DHCP for network configuration, a simple HTTP-like service discovery protocol, event notifications, and so on. The media-sharing functionality is technically an extension to UPnP called UPnP AV, and is a recommendation of the industry trade group Digital Living Network Alliance (DNLA), which you may have seen in advertisements.

UPnP AV defines “media servers” and “control points”/”renderers” that roughly correspond to masters and clients in a typical client-server relationship. A renderer could be a dumb device like a TV monitor, but most devices offer both control point and rendering functionality. To make your media accessible everywhere, you will need to run a UPnP AV media server package on the machine where your content is stored, and use your client devices (or applications) to connect to it as control points.

For Linux users, there are several packages to choose from. They vary chiefly on whether or not they support audio, video, and still images (or some subset of the three), how they are administered, and whether or not they can perform on-the-fly transcoding. Transcoding is an important feature because many UPnP control points support a fixed set of codecs. You may have your videos in WebM and your audio in Vorbis or FLAC, but some of your UPnP devices — say, a home theater receiver — only support H.264 and MP3.

Some media center applications come with at least partial UPnP support built-in. MythTV and XBMC can both act as media server and pipe out content to UPnP control points, although they must be running in order to do so. This is not a problem for MythTV because the UPnP server is part of the back-end process, but XBMC is a GUI application that you probably don’t want to run day and night. On the other hand, XBMC is trivial to set up, while MythTV requires a significant time investment.

Enter the Tomb

My favorite option for the moment is MediaTomb, a GPL-licensed package that supports audio, video, and stills, has flexible on-the-fly transcoding support, and is easily administered through a web-based front end. The latest release is 0.21.1, which is from 2010, but there are not any major pieces of functionality missing, so you should be good to go until there is a significant UPnP specification update.

You can download the source code from the project site, but check to see if your distribution provides a package first. The developers supply packages for Fedora, Debian, Ubuntu, Gentoo, Mandriva, openSUSE, and several other distributions (even some BSD options!), which should cover just about everyone.

MediaTomb UI


To set it up, first ensure that UDP port 1900 is not blocked by your machine’s firewall, and that any ports you specify in the configuration file /etc/mediatomb/config.xml are free. MediaTomb will happily select a high-numbered available port (starting with 49152) to run on whenever the process is started, and UPnP’s service-discovery mechanism makes the choice transparent to the control points, but you might desire a static port for convenience. UDP port 1900 is UPnP’s service discovery protocol’s reserved port.

MediaTomb will usually run without requiring modifications to its configuration file, but there are a few settings worth double-checking. For example, by default the application uses SQLite for storage; if you prefer, you can change this to MySQL by changing the enable="no" to a "yes" in the MySQL directive. Of course, you will then need to add the appropriate MySQL user and password credentials to the configuration file to match. You also need to set transcoding to "yes" if any of your clients will need it.

You will definitely want to set ui enabled="yes" to switch on the web administration front end, but you can safely turn it back off after you have everything configured and running to your satisfaction. You can also enable or disable accounts (to prevent unauthorized access), but be aware that the login connection is not encrypted, so the password data is only as secure as your network. Lastly, there are several specific UPnP devices that require special quirk-mode support for the ways in which they behave different from the vanilla protocol. These include the Playstation 3 and several D-Link players — there are documented lines in config.xml for each; all you need to do is uncomment them.

On the Air

MediaTomb registers as a service that can be started, stopped, or restarted using the standard Linux init system. On Debian-like OSes, this means sudo /etc/init.d/mediatomb start|restart|stop. Once you have the general configuration details in place, you can either reboot or start the service, then proceed to the web UI.

Most importantly, you will need to tell MediaTomb where your content is. Be sure you organize your material in a convenient manner — big directories with 10,000 items in them are not easily browsed, particularly on hardware devices, and you may want to make sure you separate home and work-related material (or any other such semantic distinctions) before you make all of it accessible to the network.

You can access the web UI most easily from a browser on the same machine that is running MediaTomb; visit http://localhost:49152 (or substitute the appropriate port number if you changed the default setting in the config file). You can dig into the documentation and bind the UI to a specific IP address so that it will be accessible from other machines, but this does not change its functionality at all.

What you will see is a two-pane window with a tree-style browser widget on the left and an empty space to the right. At the top, you can click to alternate between “Database” and “Filesystem” views. To add files, simple choose Filesystem, then navigate into the filesystem hierarchy on the left. When you reach the folder that you wish to add, the right-hand pane will display the folder’s contents.

You can add individual files by clicking the “+” next to their name, or add the entire directory by clicking the “+” at the top of the pane. The button next to it shows a plus encircled by “recycle arrows” — clicking this instead will tell MediaTomb to add the directory and to watch it for changes. You can set the re-scan parameters to fire on any inode changes, or to periodically rescan by elapsed time.

When you add a directory, MediaTomb will scan it and add all of the metadata it finds to its internal database. Directory adds are recursive, so this could take a long time for a large library. When you click back over to the Database view, however, you can see the fruits of its labor: your content is cataloged and organized, with separate views available for Artists, Albums, Genres, and Years for audio, and directory views for photos and video. The various views are what MediaTomb serves up to clients when they connect an ask for content. Consequently, you might want to edit the details associated with particular items to make sure they appear correctly. You can do this by clicking on the pencil-and-paper icon next to each item in the Database view.

Extra Credit

At this point, MediaTomb serves up your content to any UPnP control points or displays without intervention. If you set your directories to auto-scan, you can disable the UI and never worry about it until you replace a hard disk. In fact, it is probably a good idea to turn off the UI, because the filesystem browser, if left running, would let anyone with access to the server take a peak at your entire file structure (although it would not let them see file contents).

The next task on the path to UPnP mastery is transcoding. The config.xml file contains a <transcoding> stanza that defines several “profile mappings” — instructions to report certain problematic file types to connecting clients as if they were something else, and a conversion utility to transcode them to the output format on the fly. UPnP clients should be able to see unplayable content, simply rendering incompatible formats as grayed-out entries, but not everyone is up to snuff, so MediaTomb has to provide some workarounds. The UPnP specification does permit the server to report more than one format for each entry, but dumb enough clients may not be able to cope with more than one entry per title. Thus the config file has to include logic to always list the auto-transcoded version of each title first, so that less capable clients will see it and be able to play it back.

Exactly how you set up your transcoding settings is of course up to you. If you store your media in a lossless format like FLAC, then you lose nothing by transcoding everything on-the-fly to all clients. On the other hand, transcoding from Vorbis to MP3 results in a quality degradation due to the double-lossy-encoding problem. The only real problem is deciding how to cope with multiple control point clients that have different codec capabilities. If you just use a single client, you have nothing to worry about. MediaTomb is also flexible enough to support just about any encoder as the transcoding helper application; for most media it uses the excellent VLC.

You have alternatives for LAN-based media sharing: NFS or Samba, DAAP, etc. — and although UPnP will let devices around the house access your files, it will not help you with other media tasks like synchronizing portable music players. The protocol’s best feature is the ease with which you can make content available to “smart” devices over which you do not have direct control — like TVs and stereos. Yes, the lack of control that comes with consumer DNLA products is lamentable, but this is yet another way where Linux and open source can help bridge the gap.