Libraries and Metadata

OmniLux manages multiple media types from one server and one account experience. This guide covers the operator side of that system: library roots, metadata enrichment, naming, and storage visibility.

Supported media types

Type	Metadata source	File formats
Movies	TMDB	MKV, MP4, AVI, WMV, MOV
TV Shows	TMDB, TVDB	MKV, MP4, AVI, WMV, MOV
Music	MusicBrainz	FLAC, MP3, AAC, OGG, OPUS, WAV
Books	Open Library	EPUB, PDF, MOBI, AZW3
Audiobooks	Audnexus	M4B, MP3, FLAC, OGG
Comics	ComicVine	CBZ, CBR, PDF
Games	IGDB	ROM files (varies by platform)

Library roots

Library roots are the top-level directories OmniLux scans. Each root is assigned a media type.

Adding a library root

1. Go to Settings > Library
2. Click Add Library Root
3. Set the path, media type, and display name
4. Click Save

Removing a library root

Removing a library root removes the metadata from OmniLux's database. Your files are never deleted.

1. Go to Settings > Library
2. Click the trash icon on the library root
3. Confirm removal

Organizing directories

Recommended directory structure:

/data/
  movies/
    Movie Name (2024)/
      Movie Name (2024).mkv
  tv/
    Show Name/
      Season 01/
        Show Name - S01E01 - Episode Title.mkv
  music/
    Artist/
      Album (2024)/
        01 - Track Name.flac
  games/
    snes/
      Game Name.sfc
    psx/
      Game Name.bin

Metadata enrichment

OmniLux automatically matches your files to metadata from external providers.

Automatic matching

When a new file is discovered during a scan, OmniLux:

1. Parses the filename for title, year, season, episode, etc.
2. Searches the appropriate metadata provider
3. Matches the best result based on name similarity and year
4. Downloads poster art, backdrop, descriptions, genres, cast, and ratings

Manual metadata editing

If automatic matching gets it wrong:

1. Navigate to the media item
2. Click Edit Metadata
3. Search for the correct match, or manually edit fields
4. Changes are saved locally and won't be overwritten by future refreshes

Metadata refresh

Metadata is refreshed automatically every 24 hours to pick up updated ratings, descriptions, and artwork. You can also trigger a manual refresh from the media detail page.

File organization rules

OmniLux can automatically rename and sort your files based on metadata.

• Auto-rename: Rename files to match metadata (e.g., Movie Name (2024).mkv)
• Auto-sort: Move files into the correct directory structure
• Naming templates are configurable per media type in Settings > Library > Naming

WARNING

File organization moves and renames actual files on disk. Make sure your library root directories are writable by OmniLux before enabling these features.

Storage analytics

The library dashboard shows:

• Total storage used per media type
• File count and average file size
• Codec distribution (H.264, H.265, AV1, etc.)
• Resolution distribution (720p, 1080p, 4K, etc.)
• HDR content breakdown
• Duplicate detection