Configuring YAMJ for your Media Player

Yet Another Movie Jukebox (YAMJ) -- What Little I Know

[If you are looking for more advanced, multi-library configurations of YAMJ, be sure to check out our other page where we show you how to use NFS, SMB (CIFS) and USB shares with or without the internal hard drive.]

Flattr this

I hope I can help. Let me start by saying I am definitely NOT a YAMJ expert. Yet what I have learned has allowed me to use YAMJ in a very effective way to manage media files on a media player. I hope some of this will be useful, even if your configuration is not identical to mine. From what I've found, there is some persistent confusion about YAMJ so I hope to eliminate that.

A couple quick notes about my hardware configuration before we get started. Don't worry too much if your configuration isn't identical to this. I think you will learn enough to make YAMJ work in many different situations. I will generally refer to the media player as the Popcorn Hour or PCH but YAMJ should work on any player that can display html files (e.g. HDX 1000 or Apple iPhone).

What's described here is shown in Figure 1 and based on the following

Basic YAMJ configuration

Figure 1. Basic YAMJ Configuration

Some Basic Principles

I hesitate to call these "rules" or "absolutes" but I believe some of these, by themselves, can clear up a lot of confusion.

     1. YAMJ is never installed on, or executed from, the Popcorn Hour media player.
     2. All YAMJ does is create a static web page that is later browsed using the Popcorn Hour.
     3. If YAMJ does not run correctly or the YAMJ-generated web page does not function correctly, 
        there was likely an incorrect configuration used for the location of the source media files.

Those principles are very important, particular the first two. You should now see that the media player is simply a repository for media files and a place to store the YAMJ-generated web page. The media player doesn't really have anything to do with YAMJ, not directly anyway. We are simply using its ability to browse HTML pages to make the media experience a WHOLE lot more enjoyable. So much so that once you get YAMJ working, you will never want to use your media player without it.

      "So what if I don't have an internal hard drive in my player?"

Not a problem. Personally, I like to have everything self-contained because with the static web page saved to the internal hard drive, I can take the PCH with me (off network) and have both the media files and a nice way to browse them. Let me restate that. With the configuration I am showing here, you can have only the PCH/television, removing everything else in Figure 1 (including the network), and still have a fully functional Jukebox media player.

I realize one of the huge benefits of having a Networked Media Tank is...well... the network! Yet I think you will see, it is simply a matter of configuration in YAMJ to have it look at the internal hard drive or a networked drive. It is all relative.

     "I don't understand. If I don't install YAMJ on the media player, how does it build jukebox information for my media files?"

Perhaps a more detailed drawing will help. See Figure 2 below. Click on the image for a higher resolution version.

YAMJ operational paradigm

Figure 2. YAMJ in Operation

Figure 2 is a very simplified representation for a specific application of YAMJ but some things are worth pointing out.

First, the steps labeled as (1), (2) and (3) are actually iterated for each media file although there is some parallel processing of these steps. The generation of the web page, step (4), is done after all the media files have been interrogated.

Also, you'll note that while I show it interrogating the PCH for media files, there is no reason it can't interrogate a file server somewhere on the network. It can even interrogate hard drives local to the PC running YAMJ.

Let's Roll

Here is our plan of attack in a nutshell:

  1. Install YAMJ and MediaInfo on the host PC and map our PCH drive containing the media files.
  2. Configure YAMJ so it knows where to find the media files and knows where to store the static web page.
  3. Executing YAMJ and having it build the Jukebox.
  4. Maintaining the Jukebox and some tips for getting/keeping things working smoothly.

Installing and Initial Set Up

I am not going to say a lot about installing YAMJ because there really is no install. Just unpack it on your hard drive. There are also plenty of other help pages on the web for this. I will add the following points however:

Note that the official installation instructions make reference to using a specific version of the MediaInfo executable. I used the very latest version (much newer than the recommended one) and it worked perfectly fine.

One thing you do need to do at this point: You want to map a network path from the YAMJ PC to the drive containing the media files. In our example here, that drive resides on the PCH. If using a Windows machine, you can do this by mapping the PCH as a shared drive letter. Just make sure you have SMB (CIFS) sharing enabled on the PCH. If you are using a Linux host, you can mount the PCH as an NFS share. Again, you'll need to enable the correct service on the PCH so network hosts can mount the PCH as a remote share. Of course this mapping is only necessary when you want to run YAMJ, it is not necessary to have any connection after the jukebox is built.

Configuring YAMJ

No surprise, this is the most important step we will discuss. At this point I should note that there is a GUI available for YAMJ. YAMJ itself uses a command line interface (CLI). The GUI may be helpful for some people as it can expedite the config process but configuring is really simple so I don't see a need for the GUI. The GUI doesn't do anything for the actual execution of YAMJ -- it is still a CLI.

You will see a ton of words in this section. That's just me. This is really simple, I just use a lot of words because I want you to understand what you are doing and how flexible YAMJ is.

Although we'll show you the exact details later, there are four things you need to decide at this point:

Some of these things we will need to code into the configuration files and others we will use when we run YAMJ on the PC.

      "Great. Now that we've made all those decisions, what do we do with the four pieces of information?"

Go into the YAMJ directory and depending on which version you have, you might find the file labeled libraries.xml. Newer versions don't have this file at all, they have an example-library.xml file. If libraries.xml is there, rename it to something else. We will be building our own. You can get all the details here but this important file is used to point YAMJ to two of those locations we decided above. Note that some of the official documentation refers to this file as "library.xml" which I believe adds to the confusion but technically would work.

Create a new text file or empty file in the YAMJ directory and name it libraries.xml. Open it with your favorite text editor (e.g. Notepad) and start with something like this:

       <exclude name="sample,tmp/,temp/,RECYCLE.BIN/"/>

Without completely rehashing all the details available here, I'll point out a couple important things here.

First, remember we decided we were going to mount the PCH as our Z: Drive and have YAMJ use that remote share as the media file repository?


There you go. The <path> parameter defines where your media file repository (library) is. We pointed it to the Video directory because that's where are media files are on the PCH.

Next, remember we said we intended to have the PCH play files off its own hard drive?


What? That wasn't totally intuitive? ;-)

That goofy path inside the <nmtpath> parameter is what you need to point the PCH to its own hard drive when it is time to play the actual file. When will it need this information? It uses this when you are browsing the jukebox and press "PLAY" on the remote. That funny path is embedded (by YAMJ) into the html code so when you press PLAY, the PCH can find the file you're asking it to play.

A complete list of valid paths is available here and I will point out that this path is different for the C-series PCH and the A-series PCH and obviously for players other than the PCH. Not intuitive at all and probably why this is where most people have problems with YAMJ -- everything seems to work but they can't get the PCH to play the media file when the press the PLAY button.

[NOTE: The forward-thinking hacker will note that this parameter can be used to point the PCH to a different, remote location when you push PLAY. So you could browse the YAMJ static web page on the PCH but use it to play files off a remote server. If you'd like to see how to do that, have a look at our other page.]

One final note on this file. Like any good, cascaded XML file, you can have multiple <library> tags inside the <libraries> tags. This means you can have YAMJ operate on multiple media libraries and build a single jukebox web page to support all of them. Got a USB drive in addition to your internal drive? This is how you do both of them. Pretty neat.

Okay. That was it for major configuration. Did we really need a GUI for that? I think not. I'll also let you in on a little secret at this point: we didn't even need to build a libraries file! Assuming we have a single library, we can do all this on the command line when we execute YAMJ. But it is good to build it so we establish the nmtpath(s).

WAIT A MINUTE! What about the skin choice? What about the destination directory for the web page?

Well, the destination directory will be used when we actually execute YAMJ, we won't put that in a config file [Note: actually you can put this in the file if you want]. The skins are selected in a different file. That's optional, not mandatory, but I'll touch on it quickly because it is also super simple.

On older versions of YAMJ, you will find a file in the YAMJ root directory. Newer versions of YAMJ have this file under the \properties\ directory. In these newer versions, you'll want to create your own file in the YAMJ root directory. Then go into the newly created file and change (or create) only the parameters you need and they will override the defaults.

There is a ton of stuff you can play with in the properties file. We are looking for

You guessed it. All you have to do is point that to the skin directory you want to use. There are a few skins that come with YAMJ, you'll find them under the (big surprise) \skins\ directory. You can of course add any downloaded skins under that directory. Without belaboring the point here, changing the skin to the default SD skin is as simple as:

Executing YAMJ

Executing the YAMJ code can be as easy as a single-word command if you want to use the defaults in the properties file. We will actually add a few parameters to the command line but if you are really interested, see the README.TXT that comes with YAMJ.

So get yourself to a command prompt on the YAMJ PC. For Windows you want to do START / RUN / cmd in XP or START / cmd in Vista. In Linux you might be at the command prompt already but will likely need to find the way to get there from your GUI. Once there, change directories (cd) to the YAMJ directory, wherever you installed it.

Remember that fourth parameter we decided on back when we were configuring? Here is where we use that.

C:\YAMJ\MovieJukebox libraries.xml -o Z:\Video

The MovieJukebox portion actually executes a little batch file that contains all the Java commands to kick things off. The libraries.xml tells it to use the libraries config file we built up above. And the Z:\Video following the -o switch tells it to put our output (the jukebox static web page) to our specified location -- the PCH drive. There is some very complete documentation here.

You should now see YAMJ going to work. It will look at each file in your specified location, go out to the web (IMDb and other places) gathering data, and finally create your jukebox web page saved to your specified location.

When it is finished, get your PCH up on your screen and go to the Select Source screen. Then, select the local hard drive (HARD_DISK) as the source, browse to the right-most icon which is Other Media (as opposed to video or pictures or music), browse to the Video folder and click on the index.htm file. You should be looking at your new jukebox!

Note: You can place some of these run-time parameters into your file. You can also change the nmtroot path in the same file. See the following paramters:




Maintaining Your Jukebox and Some Tips

===> How you name your files is extremely important. If YAMJ is having a hard time finding details on your media files, the first thing you want to check is the naming conventions you are using. [Even if they are named correctly, it might still have problems. See the next tip also.] The rules for naming files can be found here but it is pretty simple and pretty logical.

All these examples should be fine:

       Taxi Driver 1976.mkv



There are also some tips for naming television shows on this page. Basically you just put the season number (S) and the episode number (E) right after the title in the form of: SnnEnn. So these are all perfectly workable examples:

All In The Family S01E01      All.In.The.Family.S02E11      Mary_Tyler_Moore_S01E07

===> YAMJ not correctly identifying media files or finding no information at all. It seems that I have about 5% of my files that, despite being named correctly, are not correctly identified by YAMJ. Don't loose any sleep over this, there is an easy fix. Simply create a text file in the same directory as the media file and use the same base name but put a .nfo extension on it.

So if for some reason YAMJ is not correctly cataloging our Taxi Driver file, all we need to do is make sure the two files are in the same directory

Taxi Driver 1976.mkv

Taxi Driver 1976.nfo

And what goes inside the .nfo file? Simply the URL to the IMDb page for that film. So in this case, all we have in the Taxi Driver 1976.nfo file is the following:

It is that simple. Next time you run YAMJ, it will see the nfo file and go to the URL you've placed in there. It should then correctly identify the media file. There is a lot more you can do with .nfo files. See this page for all the details.

===> Re-running YAMJ and adding/deleting files in your collection. So what do you do when you add new media files? They don't automatically appear in your jukebox pages just because you pushed the files to the PCH. You need to re-run YAMJ. This will execute much faster than your first run. It will only work on files that are new and will not go out to the web or create new html files for media that it has already seen.

What about when you remove a file? Again, the static web page that YAMJ generated will have no way of knowing that you removed a media file. The easiest way to handle this is to re-run YAMJ with the -c switch on the command line.

C:\YAMJ\MovieJukebox libraries.xml -o Z:\Video -c

That will clean out any unused files from the Jukebox directory after the run. Alternatively of course you can manually go into the Jukebox directory and delete the corresponding files (they will have the media file name embedded in them).

===> Strange errors while building the web page. I'll explain an error that I see about 1 out of 10 times when I run YAMJ. I have not seen this discussed elsewhere so it may be peculiar to my installation but I suspect it is caused by a slow network connection. Let me explain.

YAMJ goes through the library with no issues. It begins to build the web page as indicated by "Indexing libraries..." and Java errors start to scroll up the screen. It will error on anywhere from one to about ten of my movie files. This includes movie files that are NOT new. When I go into the Jukebox directory on the PCH, I find several .htm files with zero byte size. I delete those zero byte files and re-run YAMJ and it usually works fine.

I have never seen this error when I connect to my PCH via copper. I only see this error when I am working over a (admittedly slow) 802.11 WiFi connection. I suspect something in this slow network connection between the PCH and the PC is causing the Java code to blow errors. If you experience these errors, try a faster connection between your PCH and the PC and see if it fixes it.

===> Why is something like YAMJ not organic in the PCH? The PCH has network capability and can obviously find its way around the Internet. It obviously understands HTML. It is running Linux and could support YAMJ-like code (Java or executable) in some form. So why doesn't the PCH come with some form of jukebox built in? Why are we browsing through files like some 80's vintage GUI? I can think of a few technical hurdles to doing this but like I said way up at the top of this page: After using something like YAMJ, I don't know why anyone would ever want to use their PCH without a jukebox.

Might be worth a campaign....

Wounded Warriors SOF
Copyright 2009

Vectors at