Personal Video Database

Boxcutter for Roksbox
Version 0.91 - 11/17/2013


For support and questions, feel free to post in these forums, and be sure to put 'Boxcutter' somewhere in the subject line. For a quicker/guaranteed response, send me a message through the forum's private messaging system.


WHAT IS BOXCUTTER?

Boxcutter is a Windows command-line executable which processes XML export files from Personal Video Database, in order to better organize multiple episodes of TV series on the Roku Roksbox app (when using the single 'videos.xml' method of organizing your video files).

In short, it turns TV series on Roksbox into their own subcategories, with all episodes organized beneath them.


COULD I HAVE AN EXAMPLE OF WHAT IT DOES?

Sure. Say I have video files for each of the 14 glorious episodes of 'Firefly' (highly recommended!) on my hard drive under the following directory structure:

<Roksbox Video Root Folder>/Firefly

If I create a Master Movie record for the show in PVD, it will successfully bring in all sorts of information, including the title and description for each episode. This is the main reason for using PVD: it's great at finding and consolidating movie data.

If I then attempt to export that information to Roksbox using the default XML template, however, PVD can't quite do what I need, since it's not made EXCLUSIVELY for use with Roksbox. It doesn't export the episode information (although it can be made to), and it will have already glommed each of the file paths into a single, pipe-delimited format that Roksbox doesn't recognize.

What this means is that if you want to get episode information into Roksbox, you'd have to modify the template to generate the episode data, and then you'd STILL have to manually edit the exported XML to fix the file paths and category information.

Boxcutter handles all of this for you.


WHAT DO I NEED?

For starters, you'll need Personal Video Database. You'll also need to have several episodes of a TV show indexed in the application.

Boxcutter makes a number of assumptions on how your TV shows are organized. The most important assumption is that your main TV series record has a pipe-delimited Path property, which includes the file paths for all episodes of the TV show that you've indexed. An easy way to do this, is to place all of your videos for a particular TV show into their own directory, and then when you're creating the Movie Master in PVD, make sure to point to that directory, rather than any individual video files.

If you don't provide a regular expression when you run the executable, Boxcutter also assumes that your video files are ordered by episode in the file system, and that there are no gaps in them.

The easiest way to make sure this is the case, is by naming your video files according to the following convention...

   SeriesName_SxxEyy.m4v
   
... or some variation thereof, where 'xx' is a two-digit season number, and 'yy' is the two digit episode number within that season.
   
Finally, Boxcutter assumes that you'll be exporting your XML file from PVD using the two templates that are provided in this distribution ('Boxcutter XML.ptm' AND 'Boxcutter Episode.ptm'). These templates ensure that the data is in a format that Boxcutter can work with, and should be placed in the following file locations:

   <Personal Video Database Install Folder>/Plugins/Templates/Boxcutter XML.ptm
   <Personal Video Database Install Folder>/Plugins/Templates/Pages/Boxcutter Episode.ptm
   
When you export your movie data from PVD, make sure that the 'Boxcutter XML' template is selected, and Boxcutter should have no problems doing its thing.
   
   
HOW DOES IT WORK?

The command line executable can be run as follows:

BOXCUTTER [path/to/source/folder/or/file] [path/to/target/Roksbox/video/folder] [-epregex "regexString"]

The two path parameters are optional. If no parameters are provided, the executable will assume that both the source directory and the target directory are the directory that it's running in.

If you provide a source folder for the first parameter, then the executable will automatically look for a source file called 'videos.xml' within that folder, as well as a sub-directory called 'images'.

If you provide a direct path to a source file instead, then the executable will use THAT as the source, and assume that the 'images' directory exists in the same folder.

In each of these cases, unless a separate path to the Roksbox video folder is provided (through the inclusion of the second parameter) the executable will assume that the output folder is the same as the source folder, and any files that share a name with the executable's output (videos.xml, primarily) will be overwritten.

Finally, if the optional '-epregex' parameter is provided (along with a string representing a regular expression in the same format that Javascript uses; for example: /(Tom|Dick|Harry)/gi) then Boxcutter will use it to match up filenames in a path with specific season/episode data. Note that Boxcutter will look for the season number in the first grouping provided by the regular expression, and the episode in the second grouping.

If you're missing any video files, and have gaps between episodes, providing a regular expression is the ONLY way to ensure that the episode data will be linked to the correct video file. There's a sample batch file in this distribution (boxcutter_regex.bat) which provides an example of how to use Boxcutter with regular expressions.

When the executable finishes running, the following files will have been created and/or updated:

1.) A new 'videos.xml' file containing all of the films that were originally indexed in your database, as well as all TV episodes. The episodes' Genre tags will be modified to make use of the Roksbox subcategory feature, and their Path tags will contain the sole file path to the episode's video file.

2.) A directory structure under the target 'images' directory which corresponds with the hierarchy of categories and subcategories in your original source file, factoring in TV series as new subcategories. XML files which describe the series will be also be created, and poster art for the series will be replicated.

3.) The original poster art from all of your movie listings, relocated to the target 'images' directory, if the source and target 'images' directory aren't one and the same.

For a more detailed description of how Roksbox subcategories are configured, please visit the following URL:

   http://roksbox.com/home/index.php?option=com_content&view=article&id=123&Itemid=97
   
   
CAN I FURTHER ORGANIZE MY VIDEO FILES BY SEASON?

I might implement it as a feature at some point in the future, but my immediate goal was to replicate how most Roku services (like Netflix) organize individual episodes across multiple seasons of a show. So as of now, no, Boxcutter does not add extra subcategories for seasons.


WHERE CAN I GET A COPY OF BOXCUTTER?

Attached to this very forum post. Have fun with it, and let me know what you think!


CHANGE LOG FROM VERSION 0.9 TO VERSION 0.91

-- Added support for regular expressions with '-epregex' parameter.
-- Fix for the creation of Roksbox series subcategories, when a comma or square bracket was in the series name.

Found it. 

To answer my own question for future forum browsers...

Right click the imported Movie Master. Select 'Files' > 'Organize files by episodes'