Library Metadata

TealPlay automatically locates information about containers and playables from sources on the file system. There are 4 main ways that TealPlay can obtain this information:

• TealPlay INI files, which provide the most flexibility
• NFO files, which are a widely used de facto standard
• Audio tags
• Media file names

INI and NFO files are most frequently used as sidecar files, or files that accompany playable media to provide more information about that media. A sidecar file has the same stem as the media file it describes, where the stem is the part of the filename before the period and extension at the end. Alternatively, TealPlay INI files can also be used as standalone media sources, in which the INI file itself specifies a URL to remote or local media.

TealPlay INI files have certain advantages over NFO files in terms of customization, since they permit fine-grained control over information display. For example, the tooltip text, which is shown when hovering over a library item in the playlist, can be set to a custom value using INI. The primary downside to INI is that no other tools currently support it. Since TealPlay doesn't support creating metadata files, INI files must currently be written by hand. At least the INI format is significantly easier to write than the XML-based NFO format.

TealPlay INI Metadata

TealPlay provides a metadata format that is highly customizable and easy to write with any basic text editor. This format uses a single INI file for each metadata item. Two types of INI files are available: container and playable. As discussed in the section on library organization, containers act like folders to organize information in TealPlay, while playables represent media files that can be played.

INI files organize information into sections, keys, and values. Each TealPlay INI file has only one section ([container] or [playable]) with one or more keys mapped to values. An INI file is a plain-text file, created with a text editor (like Notepad on Windows) using the following form:

[section]
key1 = value1
key2 = value2
        

A value in an INI file can span multiple lines if each subsequent line is indented. It is most pleasing to the eye to line up the continuing lines with the start of the first line of the value, like so:

[section]
key = This value contains multiple lines,
      each of which after the first is indented.
      Lining up the indentation with the start of
      the first line is recommended.
        

TealPlay INI files are designed to be extensible as well as both backward- and forward-compatible. Sections of the INI file other than [container] or [playable] are simply ignored, as are any unknown keys. Future changes to the INI format should not break existing versions of TealPlay.

Container INI Files

There is at most one container INI file in a folder, and it must be named container.ini. This file has a single [container] section that has at least a name key in it. A minimal example container INI file describing lecture videos would look like this:

[container]
name = Lectures
        

Although the name is the only required key in a container INI file, all the following keys are supported by the current version of TealPlay:

Playable INI Files

Playable INI files fall into two groups: sidecar files and standalone files. Sidecar files are INI files that provide information about a separate media file that is also present in the same directory as the INI file. A sidecar file has the same stem, or filename without the extension, as its corresponding media file. For example, if a media file has the name lecture1.mp4, then the sidecar INI file must be named lecture1.ini.

Standalone INI files provide links to playable streams and other media via a url key in the file. These files can have any name except for a name that shares a stem with a media file in the current directory. TealPlay will find these files automatically and will create playable items based upon their URLs.

A minimal (sidecar) INI file for a playable looks like this:

[playable]
name = Lecture 1: The Airspeed Velocity of an Unladen Swallow
        

Once again, only the name is strictly required for a sidecar INI file. A standalone playable INI file would also require a URL to have any effect. The supported keys for a playable INI file are mostly the same as they are for a container INI file:

Here is a working example of a standalone INI file that references remotely accessible media:

[playable]
description = Overview of the <em>Data Link layer</em> in the OSI Model for networking.
genre = documentary; education
name = The Data Link Layer
url = https://archive.org/download/the-data-link-layer/The%20Data%20Link%20Layer.mp4
        

Subtitles

TealPlay normally discovers subtitle files automatically, provided they have the same stem as the media files to which they belong. However, it is also possible to specify subtitle files in the INI file. Specification of subtitles will be necessary for remote streaming media that uses the url key, but TealPlay can't actually load or use these subtitles just yet.

A subtitle mapping in the INI file uses a multiline value (remember to indent!), where each line contains a language, followed by a colon (:), followed by the path or URL to the subtitle file for that language. For example, if subtitles were available in two languages (English and French) for a playable, the INI file might look like this:

[playable]
name = Lecture 1: The Airspeed Velocity of an Unladen Swallow
subtitles = English: /path/to/lecture1.English.srt
            French: /path/to/lecture1.French.srt
        

Descriptions and Tooltips

Since multiline values are supported in INI files, descriptions and tooltips can be written with multiple indented lines. These keys can contain HTML tags, although they shouldn't contain major structural tags like <html> or <body>. They can, however, contain formatting tags and tables. Not all tags in the HTML standard are supported. See the Qt Supported HTML Subset for a list.

Genre, Mood, Style, Tags, and Theme

Every container and playable described by an INI file can have genres, moods, styles, tags, and themes assigned. This approach varies from the official specification for NFO files, in which only certain kinds of media can have each type of descriptor. In the INI format, use a semicolon-separated list to specify more than one value:

[playable]
name = Lecture 1: The Airspeed Velocity of an Unladen Swallow
genre = comedy; education; science
mood = lighthearted
tag = Monty Python; lecture
        

Sort Order

When containers and playables are sorted relative to each other within the same parent container, the sort process uses the index, followed by the sort_as key, followed by the name. Lower index numbers are therefore listed first. When index numbers are not available, a string comparison is used first on the sort_as key and then on the name itself. Python sorting uses ASCII order, so uppercase letters are ordered before their lowercase equivalents.

NFO Files

Although TealPlay's own INI format provides the greatest level of customization, existing media center applications often use a loosely standardized XML-based format for storing media metadata. This format is known as NFO (for "information") and is documented in the Kodi Wiki. Various tools exist for obtaining NFO files for existing media using a process called scraping. Since TealPlay doesn't perform library management functions, it doesn't support scraping. However, TealPlay can make use of many NFO files produced by other tools.

One major limitation of the NFO format is that it doesn't exactly follow XML specifications. NFO files can have multiple top-level elements, thereby violating the XML standard. For an example of such a file, see the multi-episode.nfo example from Kodi's NFO file template page. Since TealSite's library scanner uses an XML parser to read NFO files, multi-episode files are not supported and will be rejected by the parser. It is important to check that external tools that produce NFO files are producing valid XML documents. Also, NFO files can only be used as sidecar files to locally stored media in TealPlay. Use INI metadata to store information about remote streams (including the stream URL).

Audio Tags

Metadata about most kinds of playable audio files are extracted automatically using tinytag, which is bundled with TealPlay. The tinytag library provides support for the most popular tag formats, including the ID3 tags present in MP3 files. TealPlay looks for the media title attribute to determine if metadata are available. As long as the media file metadata supplies a title, TealPlay will try to extract the track number, artist, and album name.

Filenames

If no metadata are available for a given playable, then the playable's file name is used as a source of information. For audio files, a track number is extracted if the file has a name in the form 1 - First Track.extension, where the track number is separated from the rest of the name by a dash. In this example, the title of the media would be extracted as First Track.

For image and video files, as well as for audio files that do not match the above pattern, the media stem (filename without the extension) is used as the title of the media. Thus, a file named Lecture 1.webm would be given the title Lecture 1 if no other source of metadata is available.