Hack 88 Navigating the Media Filesystem

The Media Filesystem (MFS) is the database and filesystem that the TiVo uses to hold all of its useful information.

Alongside its Linux filesystem, TiVo runs a custom hybrid filesystem and database called the Media Filesystem (MFS). The MFS is where the TiVo stuffs all its recorded programming and knowledge. Here you'll find the programs appearing in your Now Playing List, databases of famous actors, your Thumbs Up/Thumbs Down show ratings, WishLists, Season Passes, messages�everything that makes your TiVo a TiVo.

The reason for using a custom filesystem is not fully known, but most people speculate it's twofold. First, it allows for very large video files to be stored safely. If you've ever turned off your computer without shutting it down, you've no doubt noticed just how long it takes to come up the next time. It's checking to make sure its filesystem is intact and nothing's out of step or just plain corrupt. With its specialized filesystem, TiVo gets around this problem and manages to boot in a reasonable amount of time, which is vital for something considered more of an entertainment system component than a computer.

Second, the MFS allows for rich metadata to be associated with media files, including Thumbs Up ratings, lists of actors, directors, genres, and so forth�everything TiVo makes available to us about the shows we're watching and TiVo, Inc. about our preferences. On the whole, TiVo's MFS is both a simple filesystem and a rich media database at the same time. You'll find it packed with directories (tyDir), objects (tyObj), files, and streams�each and every item with its own unique key, the filesystem ID (FSID) [Hack #84].

The mls Command

The standard TiVo shell provides us with an analog of the Unix ls ("list directory contents") command: mls ("MFS ls"). mls provides a listing of the contents of a particular directory. There's one caveat, however: the tivosh environment is rather primitive and has no concept of a current directory (the directory you're in). This means you have to provide a full path every time you call mls. So, whether you're actually in /Recording/NowShowingByTitle (where all the recorded television shows under TiVo OS 3.x are kept) or elsewhere, you still need to type mls /Recording/NowShowingByTitle to see its contents.

Let's take a look around at the bounty TiVo has brought us, shall we? From the Bash prompt, launch the TiVo shell and use mls to list the contents of /Recording/NowShowingByTitle:

bash-2.02# tivosh
% mls /Recording/NowShowingByTitle
Directory of /Recording/NowShowingByTitle starting at ''

    Name Type 
    FsId Date Time Size
    ---- ---- - 
    --- ---- ---- ----    
    1:2003 MTV MOVIE AWARDS:87788:91001:1717520         tyDb  1717520  06/
08/03 15:33   1172
    1:24:87806:96401:1662160                            tyDb[RETURN]
    1662160  06/05/03 21:14   1028    
    1:AMAZING RACE 4:87791:13601:1692463                tyDb[RETURN]
    1692463  06/06/03 17:02   1032    
    1:ARMENIANS A STORY OF SURVIVAL:88341:24401:700897  tyDb[RETURN]
    700897  08/11/02 14:44   1076    
    1:COMING ATTRACTIONS:87794:74801:1699840                tyDb[RETURN]
    1699840  06/06/03 05:36    900    
    1:DAWSONS CREEK:87813:13601:1651146                     tyDb[RETURN]
    1651146  05/15/03 01:59   1236  
...

Essentially, TiVo looks in /Recording/NowShowingByClassic for shows in reverse chronological order to compile its Now Playing List. MPlayer [Hack #84] does the same thing to get a list of all programming available for streaming.

Note that mls will list only the first 50 entries in a directory. You can get beyond the first 50 as they happen to appear in alphabetical order by specifying a prefix and/or wildcard for mls to use when selecting which files to show. For example, to see all the shows that start at Kojak (alphabetically speaking), you'd type:

% mls "/Recording/NowShowingByTitle/1:KOJAK*"

Note the use of double quotes and the wildcard (*).

We've previously explored only a small section of the MFS via FTP [Hack #81]. There's a lot more to meander and explore. Table 7-1 lists some of the more interesting nooks and crannies.

Table 7-1. A listing of the more interesting MFS directories and their contents

MFS directory	Contents
/Component	Infrared codes for the IR blaster and programmable remote
/Famous	A list of famous actors and directors
/GuideIndexV2	The indexes used to sort shows by title, keyword, actor, and so forth�useful for finding particular airings of a program
/MenuItem	The "extra" menu item you sometimes see appear on the TiVo Central menu, telling you about new previews and products
/MessageItem	The mail you receive from TiVo, Inc.
/Person	Definitions of actors, directors, and writers, used by the preferences engine
/Preference	Your Thumbs Up/Thumbs Down ratings
/Recording	Listings of all recordings scheduled by the viewer and automatically by the TiVo, organized by show title, date, and so forth
/Resource	The fonts, images, sounds, and backgrounds used in constructing the TiVo user interface
/Schedule	Guide data, organized by station and day
/SeasonPass	All the information about your Season Passes
/SwSystem	Information about the specific version of the TiVo OS you are running
/Theme	The viewer's WishLists

If you have TiVoWeb [Hack #65] installed, you can alternatively use your browser to navigate this terrain. From the TiVoWeb main menu, select MFS for the built-in MFS web-based browser, shown in Figure 7-1.

Figure 7-1. Browsing the MFS through TiVoWeb

Everything is nicely laid out with the same information you'd see on the command line. Instead of letting your typing fingers do the walking, you can just click your way through the MFS.

Starting out from the root directory (/) you can keep using mls or TiVoWeb to explore subdirectories until you run into MFS objects [Hack #89], inspected in quite a different manner.