- Introduction
- What You Need To Do
- * Using TVDB SID and IMDB "tt" numbers
- * Run-length Extraction
- * ISO Rips
- * VIDEO_TS and BDMV Rips
- * Fanart
- Some Observations on How EVA uses TAG data
- TagMaker Operation
- Notes for Users of the Executable Versions
- * Windows (XP, Vista, Win7)
- * Max OSX (i386 and PPC)
- * Linux (all versions)
- Updates
What You Need To Do
Auto-tagging depends on an exact match with the name in the IMDB or TVDB. The name used for the match will be parsed from the media filename, but you can override this with a more explicit value using the "Actual Title" field. For TV shows, a Season and Episode number are required as well. The convention set in the original Briden tool and continued in TagMaker is to include this data in each file name. For example:"Dexter (S02E013) - Dex, Lies, and Videotape.avi"
The format is flexible with regard to use of spaces and punctuation characters and the leading zeroes, series name and/or episode title parts illustrated above can be omitted. At a minimum, the file could be named just "S2E3.avi".
TagMaker is going to try hard to parse out the series, season, and episode. For obvious reasons, we call this "SxxEyy" data and currently it MUST be part of the file name; you can't supply it in the "Actual title" field, though you can provide the exact series name there. In some cases, this will be the most sensible thing to do. For example, the the new series of "Battlestar Galactica" is indexed in the TVDB under "Battlestar Galactica (2003)" and that's exactly what you need to enter.
Using TVDB SID and IMDB "tt" numbers
In extreme cases, it will be necessary to enter the database ID of the movie or series ID instead of the title. Where nothing seems to work, lookup the TV show or Movie on-line in a web browser. If you succeed, the address bar of the browser will contian something like this:http://thetvdb.com/?tab=season&seriesid=79349&seasonid=17604&lid=7
Enter "79349" (without the quote marks) as the actual title and good things should happen. IMDB movie ID's have a "tt" prefix before a 6 digit number and you must include both to match on ID. Using the ID will be necessary when non Latin-1 characters appear in a title (the TVDB "Carnivale" problem).
Run-length Extraction
The Duration field allows you to enter a time in hours, minutes and seconds that will be displayed on screen when a media file is highlighted. This uses an undocumented feature of the EVA/Neo, so we can't guarentee if will continue to function across firmware releases. The entry format is:hh:mm:ss
The hours figure may be omitted if zero, but the minutes and seconds must be entered as two digit values with leading zeroes when required. If there are no "hours", EVA will display "xx m yy s" on screen. If hours are present, the seconds are omitted and only hours and minutes displayed.
IMDB and TMDB provide a run length for movies that we can harvest and set automatically. The TVDB does not have this data, so TagSuite/TagMaker will extract the run length from metadata contained in most media files. The current known exceptions from which duration cannot (yet) be extracted are ISO, TS, and MTS (M2TS is now ok though). ISO is a special case (see below). For the others, manual entry is required (but we're working on it ;-).
ISO Rips
If you have "ripped" TV series DVD's to disc in "iso" format, TagSuite is just not going to be able to auto-tag them on the series name alone. Options are:- Extract the episodes using something like VID2EVA and name them with SxxEyy data
- Include the first episode of the disc in the iso filename using SxxEyy format
- Lookup the Series or Season page on thetvdb.com and cut and paste this into a TagEdit TAG created using the "File|New from File..." option to create a tag. You can also grab the image and other data, provided it exists!
VIDEO_TS and BDMV Rips
TagSuite will be able to correctly tag movies ripped from DVD as VIDEO_TS and BDMV images provided you place the VIDEO_TS or BDMV directory and all its data in a folder named for the movie it contains. TagSuite will use the parent folder(s) as the search name, so shortening it may defeat a lookup. The TAG file (and fanart.jpg if the model type is set to Neo-550) will be placed in the appropriate directory for the image type. If the rip is a TV series, the same problems and restrictions listed for ISO Rips will apply.Fanart
The concept of "Fanart" was introduced by Netscape with the Neo-350 and 550 models. A "fanart" image is a jpg placed in a folder containing one or more media files with TAG files. It is a large image (generally full HD size) which is used as a background image when the user presses the "Info" button over a media selection. If there is no fanart available, the image from the TAG is stretched to fullscreen as the backdrop, which can be quite ugly.In order for TagSuite to create the fanart.jpg images, you need to do the following:
- Set the model type to Neo-550 in the Configure dialog
- Check the "Create Fanart" option in the Configure dialog
- Select "Overwrite Existing" to create or replace fanart images
- Selecting "Update Existing" will create fanart only if does not exist
Some Observations on How EVA uses TAG data
First, the capitalization of the ID3 file extension "TAG" is significant; nothing else will be recognized by the EVA firmware. Next, the lists you see on screen while browsing are built during a Full Scan for Media (located under Supervisor functions). If you edit an existing TAG file title, or re-tag in batch, changes will not appear until you do another full scan. You can however change an image without rescanning. A Short Scan for new media does just that; it finds only new media files (with or without associated TAG files) and ads them to the existing cached lists.The EVA firmware supports the presence of a single image file named "folder.jpg" in any folder. This will appear when the folder is highlighted during browsing. Individual media TAG files in the folder may have their own images which will display as the corresponding media selection is highlighted.
The "Genre" list is also built during the "Full Scan" using all the idistinct terms found in the individual TAG files. You can supply as many comma separated types as you like. This can be a curse when auto-tagging uses synonyms that cause the genre list to expand while separating logically similar titles. For example, "SF", "Sci-fi", "Scifi", "Science-Fiction" in the TAG genre fields of differient files will cause the movie or TV show to appear only under the term(s) used (arguments aside regarding "Sci-fi" being distinct from "Science Fiction" ;-)
Maintaining consistency in a large media collection can be difficult and time consuming. To assist, the companion TagEdit utility will generate a full list of all the genre names from all TAG files given a starting point directory. Under each genre name, the media files associated with it are listed. Special lists contain the TAG files with no genre types set, media files with no associated TAG file, and TAG files with no associated media file. These "orphans" will cause the EVA to popup an ugly "not found" message. You should remove them and do another Full Scan. The list dynamically connects with the editor so you can select a name on the list and have the corresponding TAG file automatically opened in the editor pane where the genre can be set or changed using a drop-down list selector containing all the terms which the EVA will see. It does not get any easier than this.
It is possible to add metadata to mpeg4 files using tools such as iTunes (and other better ones). The EVA will read metadata from media files when no corresponding TAG file exists and use selected name/value pairs to populate the fields normally extracted from the ID3 tag frames. The results may not be what is expected though. The EVA Title which is used to sort and index media files is set from 'Album' in the mp4 metadata. The EVA description is pupulated by the mp4 Title value. Confused? Don't blame you. Better to use TAG files for large media, although embedded metadata in audio and image files is less resource hungry. Just need to experiment to get the sorted result you want.
TagMaker Operation
The sections below explain each GUI control with the corresponding command line option shown in square braces, where applicable. Users of the command line version may use the use the "double-dash" option string, or a single dash followed by enough characters to make the option unique.Path [--in]
This is the only mandatory parameter. It may be either the location of a media file (of type "avi", "xvid", "mov", "mp4", "ps", "ts", "iso", "mkv", "asf", "divx", "wmv", "m2ts", "mts", "mpg", or "dvr-ms"). or a directory containing any number of these file types. TagMaker will attempt to create TAG files with the same name as the specified file(s), but with the extension replaced by "TAG". These will be written to the same directory location as the file(s). At the end of the run, a summary will be output giving the number of files found, tagged, and skipped.The program will parse the filename, removing the type and any data of the form SxxEyy where XX and YY represent a two digit series and episode number respectively. The lookup of the IMDb or TVDB will proceed with the parsed file name. Lookups are case insensitive. If this produces no match, the file will be skipped (see next two options).
For convenience, the last six paths used will appear in the drop-down combo box list and will be "rememberd" after a restart. If any path becomes unavailable between uses, it will be removed from the list during loading.
Source Selection [--tv, --nfo --mc]
To create TAG files, TagSuits will retrieve data from the on-line resources, Internet Movie Database (IMDB), Television Database (TVDB), or read the data direct from the XML data files created by an XBMC derived application, or "Media Center Master". For the GUI application, the drop-down selection controls which will be used. The choices are IMDb, TVDB, NC (XBMC ".nfo" files), or MC ("mymovies.xml" files). Selecting items will enable/disable various other options specific to the choice made. If MC is selected, the TAG files will be created in the "right place" in the case of SD and BD rips and include any "folder.jpg" data. Any "fanart.jpg" files will also me moved to the right place if required. The command line tool (tagtool2) defaults to the IMDB. Outher data resources are selected with the appropriate option. Selecting both more than one source option will cause an error exit.Actual Title [--actual-title]
When it is known that the parsed filename(s) will not relate to the actual show title, you can specify the real title using this option. In TV mode, the file name(s) will be parsed to extract SXXEYY data for identifying episodes of a series, but all other parts of the media file name are ignored. This means that it is possible to create incorrect tags if an inappropriate title is given.Important Note: When doing a batch run, the title will apply to all media files found, so you could end up with all movies in a directory having the same TAG data regardless of their name! For this reason and your safety, the Actual Title field is reset to blank after each run, however the last 6 titles used appear in the drop-down list and will be "remembered" after a restart.
Use folder as name [--folder-title]
If the folder which contains the file(s) exactly corresponds to the IMDb or TVDB lookup name, you can use this opton to override both -actual-title and -title values.Note: When tagging DVD's ripped to VIDEO_TS format, the title used to perform the lookup is automatically set to the name of the directory containing the VIDEO_TS directory (which contains the IFO, BUP, and VOB files). If this fails to match, you can select an individual IFO file (the VIDEO_TS.IFO is best) and supply a search title using the Actual Title field.
Batch mode [no equivalent]
This simply flags to the GUI what sort of File Browsing widget to use. When checked, you will be asked to select a directory. Unchecked, you must select a single media file. The command line utility does not need this hint, being able to tell the difference between a file and a directory. Note that batch processing will process ALL valid video media file types in the specified directory, and all sub-directories found under the specified directory. Once a batch sun has been commenced, it cannot currently be interupted.Existing TAG files [--overwrite-existing and --update-existing]
The GUI provides a choice when a TAG file for a media selection already exists: Skip, Overwrite, or Update. Skip and Overwrite are obvious. If Update is selected, only specific fields will be changed. The set of fields to be updated is specified using checkbox settings in the Configure dialog (button lower right).For the command line tool, the --update-existing option requires a quoted, space separated list of
the ID3 fields to be updated. The mapping of valid ID3 field to (human readable type) is:
TALB (title), TIT2 (description), TPE1 (cast), TYER (year) TCON (genre), PRIV (rating), TPE3 (director),
TLEN (duration), APIC (cover image).
It is an error to specify both --update-existing and --overwrite-existing options together.
Include IMDb/TVDB rating [--add-rating]
This option prefixes the plot description text with the rating value voted for the show in question by user community of the two on-line resouces. IMDB also provides a value in minutes for the program's duration which is included in the prefix. Some find this useful; some don't.Include Role for actors [--add-role]
When set (tagtool2 command line), the role played by each actor will be added after the actor's name, in brackets. For the GUI interface (TagMaker), this is a setting in the Configuration dialog (see later) accessed through a pushbutton in the lower right of the application. Note that TVDB does not provide this data, so the option will have no effect on TV series data.Use canonical name [--use-canonical-title]
When the EVA finds a TAG file for a media file, it uses the "Title" found in the TAG data instead of the file name for on-screen listings. Normally, the title field will simply be the media file name less any path data. Setting this option causes the title to be set to that retrieved from the IMDB, or TVDB. In the case of TV series, the canonical title is "<series-name> SxxEyy: <episode-title>" where xx and yy are the series and episode numbers respectively.Use of this option is highly recommended as it makes the EVA listing far more informative than a possibly arcane file name!
Include series name in title [--inc-series-name]
This option is only available in TV Mode when Use canonical title is set. If set, the title will comprise the full Canonical name as described above, namely: "<series-name> SxxEyy: <episode-title>". Many EVA users keep TV series episodes in a folder named after the series, so including the series name in the title is somewhat redundant. Setting this option to OFF will shorten the title to "SxxEyy: <episode-title>", which is not a bad idea given the large font size used to display titles on the EVA.The downside is the actual show title data is seemingly lost, except in the context of EVA folder browsing. This means that if you browse by anything else (title, image, genre), then all of the S01E01's will appear together, followed by S01E02's, etc.
Exclude image [--exclude-image]
When selected, no image data will be added to the TAG file. This makes the file shorter and allows better images than the default IMDb/TVDB ones (if any) to be added later with TagEdit. Better images can be found by doing a web search for Posters for the movie or capturing selected frames from TV shows.Save image separately [--folder-image]
Forces any image associated with data found to be written to a file named 'folder.jpg" in the same directory as the TAG file. This option may not be used in batch mode and forces the "Exclude image" option to ON.Purge cache [--purge]
XML data retrieved from the TVDB is cached in a file named <HOME>/.tagtool/tvdb.db. I've observed times when this cache can become "contaminated" and lookups of TV series which worked previously suddenly produce no matches. Deleting the cache forces it to be recreated with fresh data, fixing the problem. This option is provided as an easy alternate to locating and deleting the cache manually.Normalize Name [--normalize_name]
To assist natural sort ordering of EVA/NEO displays, this option moves stop-words "the" and "a" to the end of the name. Eg: "The Thing" becomes "Thing (The)".Summarize Plot [--summarize-plot]
Available in Film (IMDb) and XBMC (nfo translation) modes only, forces the TAG plot description to use the summarized version. The full length plot can be quite long, but sometimes the summary version is uselessly brief, or just as long![--interactive]
This is applicable to the command line tool only. When set, and lookups are unable to uniquely identify show data from available filename or title data, the user will be propmted for a title. The DB numeric identifier may also be used, or "n" entered to skip.[--locale]
As well as English, the TVBD provides program data in numerous languages. The language is based on the ISO-3166 two-character country codes. If you set this to other than "en" for English, all TAG data will be fetched in the nominated language ("fr" for French, for example). No checking that the entered code is valid and available is performed. Note that at this time. the IMDb does not support multi-lingual text, but we've made this a global option in the hopes that someday it might.[--quiet]
Suppresses all but the Summary output from a tagtool2 run.[--verbose]
Normally tagtool2 console output will be roughly the same as that seen in the GUI tool log tab. Setting this option raises the amount of noise which may help when things are not working.Controls
At the bottom of the GUI tool are some tabbed information frames and four push buttons. Their use should be obvious, but for the raw beginners:Summary
This Tab will show "Working..." while TAG files are being created. Upon completion, it lists the number of of media files processed, TAG files created, and media files skipped. The total time for the run is alos displayed.Run Log
This tab gives a very detailed sequence of events during the tag run. It can indicate why a run is taking a while (eg, a lot of data are being downloaded from TVDB), and why some media files were not Tagged. Many will find the next two screens more convenient.Created Files
This tab lists the TAG files created, one per line. You can right-click over any line to popup an "Edit" button. Selecting this button by moving the mouse pointer over it before releasing the button will automatically load the TAG file into the editor pane (TagSuite only; TagMaker has no Editor pane).Skipped Files
This tab lists media files found, but not tagged. If the reason is not obvious to you, the answer can be found in the "Run Log" tab pane.Exit
Save the current settings for next time and shut down. Pressing the window close gadget has the same effect.Save Log...
The contents of the Log and Summary display panes will be written to a simple text file. A candidate name is provided, but you can change this. The location (directory) you choose will also be remembered. Use this control when requesting help as to why something is not going as expected.Configure
This opens a dialog that allows the user to select which fields are modified when updating and existing TAG file, the Country Name for IMDb MPAA ratings, the Language code for text fetched from the TVDB, and the Netgear model the tags are being created for. The model setting controls things like maximum length for data fields, creation of "fanart", and a flag which will cause the role played by an actor to be added after the name (bracketed) in the Cast listing. Note that TVDB does not provide this data. IMDB and TMDB do, though including the role can cause the cast list to expand beyond what EVA/Neo can display. All settings in the Configuration are preserved between restarts, naturally.Help
Display this text, or a default text if the main data is not available for some reason.Start
Start a tagging run. Control is locked out until the run completes, meaning that if you want to monitor detailed progress, select the "Log" tab before pressing Start. You can press it after the run commences, but response and switching will be slow.Notes for Users of the Executable Versions
In all cases we suggest that you extract the archive (zip or tag.gz) to some appropriate temporary location, then copy the binary files to a convenient place. After this, the extracted data may be deleted, though we Strongly advise taking the time to read the TAGSUITE_README.txt file (also available on-line at the Tagsuite Home page). Should you decide to retain the executable binaries in the archive extract, note that the files in the "test" and "src" trees are not required for operation and may be safely deleted unless you are curious about how it all works.Windows (XP, Vista, Win7)
The ".exe" versions included in the zip download have been built with the ActiveState application builder which packages all the Perl support required into the file, hence its size. Mostly these work as advertised, but strange glitches have been observed on some systems. To launch one of the GUI applications, double click the .exe file. If you get a dialog during startup that gives 'retry' and 'continue' options, generally choosing 'continue' is the right thing to do.Mac OSX (i386, PPC)
The ".app" versions included in the zip download have been built with the ActiveState application builder which packages all the Perl support required into the file, hence its size. To launch one of the GUI applications, double click the .app name (A directory, actually).Linux (all versions)
The binary applications included in the tar.gz download have been built with the ActiveState application builder which packages all the Perl support required into the file, hence its size. You can double click the GUI tools to start them, but more sophistication is expected of Linus users. The best choice is to copy the binaries to an appropriate location on your normal search path such as usr/local/bin. This allows them to be invoked from anywhere (or any script). They can then easily be replaced by later versions following the same procedure.Updates
For more information about TagSuite, TagMaker, Tagedit and tagtool2, including the latest source and binary releases, visit the TagSuite home page at: http://itee.uq.edu.au/~chernich/tagsuite.html.Questions can be directed to the author (ron@modelenginenews.org). If you are having trouble tagging something, use the option to write a log file from the failing run and attach this to your email.