Organizing Library Files

TealPlay allows for complete control over the organization of the media library. The file system is used as the primary means of organization, while metadata files are used to supply additional information. Note that TealPlay only supports file systems that are locally mounted on the computer running the application. There is no direct access to network shares for loading the library. Instead, a network share needs to be mounted to a local folder or drive letter by the operating environment.

Basic Concepts

TealPlay supports two categories of content for the media library:

1. Containers organize related content into logical groups. A container has a 1-to-1 relationship with a folder (also known as a directory) on the file system.
2. Each media file that can be played is a playable in TealPlay. Playables are always found inside containers, although the media file for a given playable might or might not be present on the file system. It is possible for a playable to be a remote streaming URL or live feed from a device.

In the library tree view, containers form the inner nodes of the tree, while playables are found at leaf nodes. Containers are recognizable by the little arrows indicating whether or not they are expanded to show their contents:

The corresponding files and folders/directories in the file system are organized as follows:

Lectures/
    mmurphy2/
        container.ini
        csci270/
            container.ini
            Physical Layer.ini
            Physical Layer.mp4
            The Data Link Layer.ini
            The Network Layer.ini
            The Network Layer.mp4
Movies/
Music/
        

In this example, the files with the .ini extensions supply metadata about the containers (files named container.ini) or playables (other INI files). The format of these files is documented on the metadata page. In this case, we have metadata for the two inner containers (mmurphy2 and csci270) that provide friendlier names in TealPlay than what we see in the directory listings. We find two media files inside the csci270 container with their associated metadata files. Note that there is no media file for The Data Link Layer: the INI file specifies a remote URL from which that video can be played.

Playable files are categorized into one of three types: audio files, image files, and video files. Audio and video files are played as ordinary media, while image files are used to create slideshows. There are some special cases involving image files that are used as artwork for audio files, video files, or containers (see below).

Container Hierarchy

The top-level containers displayed in the TealPlay library tree are the folders set as library paths on the Library tab in TealPlay Settings (accessed from Tools...Settings). There is no requirement that the top-level container names be unique. It is possible, for example, to have two top-level containers named Movies. This same rule actually applies at all levels in TealPlay. It is up to you to decide how to name your containers, which means it is also up to you to keep the names unique to make the library easy to use.

In some cases, media files might be scattered around the file system in different directories (folders), as some media might be stored on different drives or different partitions. There are two ways to handle this situation:

1. Create separate top-level containers for each media directory by adding the directory directly to the library in the Settings window.
2. Add one directory directly to the library and use symbolic links within that directory to point to the other directories. Symbolic links can be created using the ln -s command on Linux and Mac systems or the mklink command on Windows 10 and higher.

TealPlay does not impose a hard limit on the depth of container nesting, but you will probably find that the library becomes more difficult to use if there are so many levels of containers that it becomes necessary to scroll left and right to view them. TealPlay also doesn't predefine any container types or require that only one kind of media be present in a single container. It is possible to have one container with a mixture of audio, image, and video files, although some limitations will apply to the container metadata if using NFO files.

In order to prevent infinite recursion during media scans, TealPlay only visits a directory one time, regardless of how many symbolic links to that same directory that it finds. It is therefore not possible to use symbolic links to put the same container into multiple parent containers within the library. On the other hand, it is possible to duplicate a playable between containers (or even within the same container) using symbolic links. If you need the same content to appear in more than one library location, it is necessary to create links to the individual media (and metadata) files. This approach to library management is not recommended in the general case but might support certain niche cases, especially for institutional use.

Artwork Files

Audio and video files may have associated artwork following conventions established by Kodi. Artwork files are detected by name. Any image file matching one of the following patterns is assumed to be artwork:

The difference between sidecar artwork and standalone artwork is that sidecar artwork is applied to the media file having the same stem as the artwork. Standalone artwork is applied to the container. Unlike Kodi, TealPlay allows all kinds of artwork to be applied to all kinds of containers and playables. At the present time, however, TealPlay only actually displays a small subset of artwork files. This behavior is expected to improve with further development.

Note that TealPlay does not support animated artwork or artwork in separate directories from the media file or container. However, TealPlay does support any type of image file readable by Qt for artwork. Artwork files are not limited to PNG or JPEG format.

Finally, files that are recognized as artwork will not be displayed in the library. These image files can still be added to a playlist manually, and the resulting playlist can be saved to create a loadable artwork slideshow.