Moira¹ identifies file formats using fast, custom binary inspection and assigns MIME types so downstream systems (preview generation, file handling, and application dispatch) can route files correctly.

Its primary goal is to speed up detection speed of many common file formats (PDF, PNG, MP4, etc). When Moira cannot identify a file type, it falls back to libmagic, which itself falls back to the Shared MIME-info database if necessary.²

Moira often outperforms libmagic on speed and can also recognize additional, older formats (for example, legacy image files) that libmagic may miss — useful when previewing archival file collections.

Moira is enabled by default. To disable it, set FastMagic to false in the main configuration file.

¹ The name Moira comes from the Greek word moira, related to destiny. In Greek mythology, the Moirai (Clotho, Lachesis, and Atropos) weave human fate. By assigning a MIME type, Moira likewise determines a file's “destiny” — for example, how it will be opened or how a preview will be generated.

² The Shared MIME-info database is consulted via mimetype(1) or xdg-mime(1), in that order. If neither tool is available on the system, this check is skipped.

The remainder of this document outlines the principles guiding MIME type assignments.

Before assigning a custom MIME type to an identified format, consult existing standards in this order:

1. IANA Media Types Registry (https://www.iana.org/assignments/media-types/)
2. file(1) magic database and its MIME type assignments
3. Shared MIME-info database (https://gitlab.freedesktop.org/xdg/shared-mime-info/)

Use the first match found. Only create a custom type if none of these sources define one for the format.

For formats with IANA-registered MIME types, use them exactly as registered:

For formats recognized by file(1) or Shared MIME-info but not IANA-registered, use the established type:

For formats identified by fast-magic but not found in any of the above sources, assign a custom type using the x- prefix following these guidelines:

Choose the primary category based on the format's fundamental nature:

• video/x-*: Video formats (containers, codecs, proprietary video)
• audio/x-*: Audio formats (containers, codecs, proprietary audio)
• image/x-*: Image formats (bitmaps, vectors, proprietary graphics)
• text/x-*: Text-based formats (markup, code, documents)
• application/x-*: Everything else (compressed archives, executables, data formats, mixed-media)

Type names should be:

• Descriptive: Clearly identify the format or source application
• Lowercase with hyphens: Follow MIME type conventions
• Concise: Avoid redundancy (e.g., use video/x-bink not video/x-bink-video-format)

The x- prefix (per RFC 6838) indicates:

• Non-standard: The type is not IANA-registered
• Real identification: The format has been genuinely identified, not guessed
• Future-ready: If the format gains adoption, this type is a natural candidate for standardization without renaming

Do not use x- as a catch-all for "unknown" formats. Assign custom types only when you've positively identified the format through magic signatures or structural analysis.

MIME types assigned by fast-magic are semantic labels designed for flexible routing. Consuming systems (like preview handlers) can:

• Use regex patterns to group related types (video/.*)
• Define fallback chains per type (video/x-bink=ffmpeg;mplayer)
• Extend mappings without modifying fast-magic

Example from clifm preview config:

video/.*=ffmpeg;mpv;mplayer
audio/.*=ffmpeg;sox
image/.*=convert;imagemagick

When submitting new magic signatures or formats to fast-magic:

1. Verify the format identification: Ensure your magic signature correctly identifies the target format with minimal false positives
2. Research existing MIME types: Check IANA, file(1), and Shared MIME-info before proposing a custom type
3. Follow the naming convention: Use the appropriate category and describe the format clearly
4. Document your choice: Include a comment explaining why you selected that specific MIME type
5. Consider alignment: If your proposed type differs from file(1) or Shared MIME-info for the same format, discuss the rationale in your contribution

Custom x- prefixed types may eventually become standardized. If a format you've identified gains wider adoption:

• The type remains stable (no renaming needed)
• Consider submitting the format and proposed MIME type to the Shared MIME-info database
• Document any standardization changes for users

• RFC 6838: Media Type Specifications and Registration Procedures
• IANA Media Types Registry: https://www.iana.org/assignments/media-types/
• file(1) Manual: https://man7.org/linux/man-pages/man1/file.1.html
• Shared MIME-info Database: https://gitlab.freedesktop.org/xdg/shared-mime-info/

This is a first sketch—you'd want to refine it based on your actual fast-magic codebase, add any specific quirks or edge cases you've encountered, and potentially expand sections based on how developers actually use the module. Does this capture the philosophy you're working with?