Configuration and settings for the attachment scanner

Introduction

With v2.8 of !MovieJukebox there is an attachment scanner which can be used to process and use attachments from within a matroska file.

For the attachment scanner the MKVToolnix tool set is needed. Yout can download it from here:

Installation

To get the attachment scanner to work, you must have installed MKVToolnix on your system or placed the relevant executables into yout YAMJ directory in the subfolder "mkvToolnix".

You should then enable the attachement scanner with the following property:

attachment.scanner.enable=true

If you have already installed MKVToolnix then you can set the mkvtoolnix home to the directory where the executables are.

Windows Example

attachment.mkvtoolnix.home=C:\Programs\MKVToolnix

Linux Example

attachment.mkvtoolnix.home=/usr/bin

Supported attachment types

Until now following types are supported as attachments:

• NFO File
• Poster Image
• Fanart Image
• Banner Image
• Poster Image for a Set
• Fanart Image for a Set
• Banner Image for a Set
• Video images for TV shows

Content detection

To determine the type of an attachment (i.e. fanart) the filename of the attachment and the mime type will be inspected.

NFO detection

An attachment will be assumed as NFO file, if:

• mimeType is text/xml, application/xml or text/html
• filename ends with ".nfo"

Note that attached NFOs will only be used if there are no local NFO files for your movie.

Image detection

Images are only detemined as relevant image if the mime type is "image/jpeg", "image/png", "image/gif" or "image/x-ms-bmp".

Also the filename must match an explicit token:

• fanart: will be detected as fanart image
• poster: will be detected as poster image
• cover: will be detected as poster image
• banner: will be detected as banner image
• fanart.set: will be detected as fanart image for a set
• poster.set: will be detected as poster image for a set
• banner.set: will be detected as banner image for a set
• videoimage: will be detected as video image for tv show episodes
• videoimage_X: will be detected as part X of a multipart episoe

Examples

file name  : movie.nfo
mime type  : application/xml
identified : NFO

file name  : fanart.jpg 
mime type  : image/jpeg
identified : FANART

file name  : movie.poster.gif
mime type  : image/gif
identified : POSTER

file name  : banner
mime type  : image/jpeg
identified : BANNER

file name  : movie.fanart.set.jpg
mime type  : image/jpeg
identified : SET_FANART

file name  : something.jpg
mime type  : image/jpeg
identified : UNKNOWN (will not be regarded as valid attachment)

file name  : videoimage_1.jpg
mime type  : image/jpeg
identified : VIDEOIMAGE, part 1

file name  : videoimage.jpg
mime type  : image/jpeg
identified : VIDEOIMAGE, part unknown

Note that attached image files will only be used, if there are no local image files for the movie in your movie library.

If the SET images are processed and there is not SET image, then the corresponding image will be used; i.e. if you haven't an attached SET_FANART then the FANART will be used as set fanart. This is the same behaviour used for local file handling.

Best practices =

Very good results have been achieved with following constructions. Note that for movies and TV shows it's only relevant that the first movie file contains the banner, fanart or banner image (and possible set images).

Perhaps you will not need to attach all kind of files; this depends on your favorite skin.

Movie (not in a set)

movie.nfo
poster.jpg
fanart.jpg
banner.jpg

Movie (within a set)

movie.nfo
poster.jpg
fanart.jpg
banner.jpg
poster.set.jpg
fanart.set.jpg
banner.set.jpg

TV Show (first episode of the season)

tvshow.nfo
episodedetails.nfo (may be more than one for multipart files)
poster.jpg
fanart.jpg
banner.jpg
poster.set.jpg
fanart.set.jpg
banner.set.jpg
videoimage.jpg

TV Show (other episode in the season)

For non-multipart episodes:

episodedetails.nfo (may be more than one for multipart files)
videoimage.jpg

For multipart episodes:

episodedetails.nfo (may be more than one for multipart files)
videoimage_1.jpg
videoimage_2.jpg

Temporary directory

The default temporary directory is the sub directory "attachments" in the YAMY temporary directory. Note, that this directory will cleaned up when YAMJ finishes; even if the attachments temp directory should be cleaned or not.

If you want to keep the extracted attachments for later use, you can use following settings:

attachment.temp.directory=/var/attachments
attachment.temp.cleanup=false

Known limitations

Video images

Video images will be extracted in every run cause until now there is no detection if a videoimage attachments has to be extracted or not. To reduce the number of extractions you can use a temporary directory outside the YAMJ temp directory and disable the cleanup.

Set images

Set images only work for movies, which belong to exactly one set. If the movie should belong to 2 different sets, then you must use the common set image handling with local files.

Double extraction

Assume a clean jukebox. During the first run the attachment urls will be set in the i.e. fanartURL of the movie xml file. The next scan changes the movie xml and in this case the fanartURL will be overwritten with the fanart url of the fanart in the jukebox folder.

Reason is, that an attachment is not determined as local file in the second scan and therefore the jukebox image file will be used.

False images

False images can be extracted from the !AttachmentScanner when the recheck is disabled and the movie file has been replaced with another file (with same file name) but with different attachments.