Wiki Navigation
- Loading...
Overview
The NfoMetadataExtractors extract metadata from so called
nfo-files
.
Nfo-files
are files with the file name extension
.nfo
(or sometimes
.xml
or
.txt
). Their file names follow a certain pattern and they are located at a specific path relative to the actual media file or folder (
Resource
).
There are currently two NfoMetadataExtractors:
NfoMovieMetadataExtractor (extracting metadata from
nfo-files
for movies)
NfoSeriesMetadataExtractor (extracting metadata from
nfo-files
for series)
This page explains the facts that are common for all NfoMetadataExtractors, whereas the specific facts of a particular NfoMetadataExtractor are explained on the wiki pages linked above.
The NfoMetadataExtractors are contained in the NfoMetadataExtractors plugin. This plugin depends on the OnlineLibraries plugin because it uses the Newtonsoft.Json.dll contained in the OnlineLibraries plugin.
Settings
Every NfoMetadataExtractor has a settings file in the respective
Settings-Directory
. Besides the specific settings for specific NfoMetadataExtrators, which are explained on each NfoMetadataExtractor's specific wiki page linked above, it contains for every NfoMetadataExtractor the following common settings:
Name | Type | Default Value(s) | Explanation |
---|---|---|---|
NfoFileNameExtensions | HashSet<string> | .nfo , .xml , .txt | When a NfoMetadataExtrator tries to find a nfo-file with a given file name in a given directory, it will recognize files with these extensions as nfo-files . |
SeparatorCharacters | HashSet<char> | | , , , / | A single element in a nfo-file may contain multiple string values separated by a specific character, as e.g.: <genre>Horror / Comedy , Romance</genre> All SeparatorCharacters are recognized by the NfoMetadataExtractors as separators between multiple string values. They are stored in the settings file in form of their numerical ASCII code. |
IgnoreStrings | HashSet<string> | unknown | Some external programs generating nfo-files store a certain string as content of elements for which they do not have a value (instead of just leaving the element empty). The only such string we have seen so far is "unknown". We do not want to have this behavior in our MediaLibrary and therefore treat elements having one of the IgnoreStrings as content as if they were empty. |
EnableDebugLogging | bool | false in ReleaseBuilds, true in DebugBuilds | If set to true , the respective NfoMetadataExtractor generates an additional very detailed DebugLogFile in the Log-Directory . For details see Logging below. |
WriteRawNfoFileIntoDebugLog | bool | false | If set to true , the respective NfoMetadataExtractor writes the whole content of every processed nfo-file into the DebugLogFile . This setting has no effect if EnableDebugLogging is set to false . |
WriteStubObjectIntoDebugLog | bool | false | The NfoMetadataExtractors first store the metadata found in nfo-files in to so called StubObjects , before the information in the StubObjects is stored into the MediaItemAspects . If this setting is set to true , all StubObjects are written into the DebugLogFile in Json format once they are filled with all metadata that was found in the respective nfo-file . This setting has no effect if EnableDebugLogging is set to false . |
The settings are only read at startup. If you change the settings do not forget to restart MP2-Server or MP2-Client, respectively.
Logging
The NfoMetadataExtractors only log severe errors into the
MainLogFile
in order to not spam it with too many log messages.
However, if you set
EnableDebugLogging
to
true
in the respective NfoMetadataExtractor's settings file, the NfoMetadataExtractor generates a detailed
DebugLogFile
in the
Log-Directory
. The
DebugLogFile
of every NfoMetadataExtractor has a specific file name described on the respective NfoMetadataExtractor's wiki page linked above.
The
DebugLogFile
contains detailed information about the process of extracting metadata from
nfo-files
. The content of the
DebugLogFile
follows a certain pattern, which results from the way MetadataExtractors are used by the
Importer
. The
Importer
handles multiple
Reources
at the same time and calls the MetadataExtractors applicable to these
Resources
. As a consequence, the NfoMetadataExtractors may also handle multiple
Resources
at the same time. Since the log messages for all
Resources
are logged into the same
DebugLogFile
, the log messages of a single
Resource
are mixed with the log messages of other
Resources
. To be able to associate the log messages in the
DebugLogFile
with the extraction process for a specific
Resource
, every
Resource
for which the NfoMetadataExtractors try to extract metadata gets a unique
ResourceNumber
. This
ResourceNumber
is logged after the first colon of each log message in the form
[#x]
where x is the
ResourceNumber
. A typical log message in the
DebugLogFile
looks like this:
2015-07-05 14:18:14.117626 [Info.][21]: [#1]: Start extracting metadata for resource 'D:\Video.mkv' (forceQuickMode: False)
The example log message above is the first log message that is logged for every
Resource
such as here "D:\Video.mkv" having the
ResourceNumber
1. After this initial log message, every log message showing
[#1]
after the first colon contains information about the process of extracting metadata from
nfo-files
for the
Resource
"D:\Video.mkv". Ideally, the process of extracting metadata from
nfo-files
for this
Resource
finishes with the log message:
2015-07-05 14:18:15.032662 [Info.][23]: [#1]: Successfully finished extracting metadata
Note: As described above, there may be multiple log messages for other
Resources
(and, hence, showing different
ResourceNumbers
) between these lines, which are irrelevant for debugging the extraction process for this particular
Resource
.
If the
DebugLogFile
only contains log messages showing
[Info.]
after the time stamp, the NfoMetadataExtractor could do its job as expected. If there are log messages showing
[Warn.]
or even
[Error.]
the NfoMetadataExtractor encountered something unexpected and it may be worth to analyze the
DebugLogFile
in more detail.
Requirements
Besides specific requirements that each NfoMetadataExtractor has and that are explained on each NfoMeadataExtractor's specific wiki page linked above, all NfoMetadataExtractors have common requirements that need to be met so that they can properly extract metadata:
ResourceAccessor
Nfo-files
are separate files located at a specific path in the file system relative to the
Resource
. As a consequence, the
Resource
must be located within a file system such as on a local drive or a network drive. In other words, the
ResourceAccessor
pointing to the
Resource
must implement the
IFileSystemResourceAccessor
interface. If this is not the case, the NfoMetadataExtractor cannot extract metadata for the
Resource
.
Content of the
Nfo-File
The content of
nfo-files
in general (but unfortunately not entirely) follows the XML specification. This means that the file typically starts with a XML prolog showing information on the XML version and the encoding used in the
nfo-file
.
The XML prolog is followed by a root element with a certain
RootElementName
. The
RootElementName
depends on the
MediaCategory
of the
Resource
, for which the
nfo-file
contains metadata. For a movie the
RootElementName
is e.g. "movie".
Within the root element there are many child elements containing the actual metadata, such as IDs of online databases, names of actors, etc.
The shortest meaningful
nfo-file
for a movie would e.g. look like this:
<!--?xml version="1.0" encoding="UTF-16"?--> <movie> <tmdbid>52913</tmdbid> </movie>
If the XML prolog in the first line is omitted, the respective NfoMetadataExtractor (in this case the NfoMovieMetadataExtractor) will try to recognize the used encoding from the Byte Order Mark at the beginning of the file. If no Byte Order Mark is found, it will assume UTF-8 encoding. The second and fourth line show the root element. The third line contains a child element holding information on the ID of the movie at www.themoviedb.org. This ID is read by the NfoMovieMetadataExtractor and stored in the
MediaItemAspect
. It can then be used by MetadataExtractors applied after the NfoMovieMetadataExtractor, such as the MovieMetadataExtractor, to download additional information from the internet.
But the
nfo-file
can (and typically does) contain additional information such as actor names, MPAA rating, etc. itself. Unfortunately, depending on the external program that generated the
nfo-file
the child element names as well as their content's structure can be quite different. A general overview on the potential child elements of
nfo-files
can be found in our Glossary. A detailed description of all child elements that can be read by the NfoMetadataExtractors can be found in the source code, which is linked on each NfoMetadataExtractor's specific wiki page linked above.
Currently, the NfoMetadataExtractors can read much more child elements than we can store in our
MediaItemAspects
. The child elements we can actually store in
MediaItemAspects
are listed on each NfoMetadataExtractor's wiki page linked above. If the NfoMetadataExtractors, while parsing an
nfo-file
find a child element that they don't know, they log a warning in the
DebugLogFile
(if enabled as per above). In such case please post the
DebugLogFile
in the Forum together with the information, which external program in which version has generated the
nfo-file
so that we can add support for reading that child element.
As mentioned above,
nfo-files
are unfortunately not 100% compliant with the XML specification. In particular,
nfo-files
may contain multiple root elements, which is not allowed according to the XML specification. This is the case, if the
nfo-file
e.g. contains metadata for multiple episodes of a series (because the
Resource
also contains multiple series). The respective
nfo-file
would then look similar to this:
<!--?xml version="1.0" encoding="UTF-16"?--> <episodedetails> [...child elements for episode 1...] </episodedetails> <episodedetails> [...child elements for episode 2...] </episodedetails>
The NfoMetadataExtractors can read all metadata contained in such
nfo-files
, but only the metadata contained in the child elements of the first root element is used entirely. Only some metadata from the child elements of the second and further root elements is used. For further details please refer to the Imported Attributes section of the respective NfoMetadataExtractor's wiki page linked above.
Troubleshooting
If you realize that a NfoMetadataExtractor does not extract the metadata as you would like, please first check in the Imported Attributes section of the respective NfoMetadataExtractor's wiki page linked above, whether it is expected that the respective metadata is imported as you like it.
If this should be the case, but still it does not work, please remove the respective
MediaSource
, switch the
EnableDebugLogging
setting to
true
as described above, re-add the
MediaSource
, wait until the import has finished and post the
MainLogFile
as well as the
DebugLogFile
in our Forum.
If the
MediaSource
does not contain too many files and folders (and please don't do this for very large
MediaSources
because the
DebugLogFile
gets very big), please also switch the
WriteRawNfoFileIntoDebugLog
and the
WriteStubObjectIntoDebugLog
settings to
true
before re-adding the
MediaSource
.
This page has no comments.