mimetype

MIME type lookup and byte-signature detection for Gleam.

The public API intentionally separates:

extension / filename lookup, which is cheap and deterministic
magic-number detection, which inspects the leading bytes
combined helpers, which prefer content-based detection and fall back to metadata when the byte signature is unknown

Values

charset

pub fn charset(mime_type: String) -> Result(String, Nil)

Return the charset parameter from a MIME type string.

Charset values are normalized to lowercase for convenience.

default_mime_type

</>

pub const default_mime_type: String

Fallback MIME type used when neither metadata nor byte signatures provide a more specific answer.

detect

</>

pub fn detect(bytes: BitArray) -> String

Detect a MIME type from the leading bytes of a blob.

This checks a curated set of common magic-number signatures. Currently supported MIME types are: application/pdf, application/zip, application/gzip, application/x-bzip2, application/x-xz, application/x-7z-compressed, application/x-rar-compressed, application/vnd.ms-cab-compressed, application/x-tar, application/zstd, application/vnd.sqlite3, application/vnd.apache.parquet, application/ogg, application/wasm, application/x-elf, audio/wav, audio/aiff, audio/mpeg, audio/flac, audio/midi, audio/mp4, image/png, image/jpeg, image/gif, image/bmp, image/tiff, image/x-icon, image/webp, image/avif, image/heic, video/x-msvideo, video/webm, video/quicktime, and video/mp4.

If no signature matches, the default fallback MIME type is returned.

detect_strict

</>

pub fn detect_strict(bytes: BitArray) -> Result(String, Nil)

Detect a MIME type from the leading bytes of a blob.

This strict variant returns Error(Nil) when no supported magic-number signature matches.

detect_with_extension

</>

pub fn detect_with_extension(
  bytes: BitArray,
  extension: String,
) -> String

Detect a MIME type from bytes, falling back to an explicit extension when the content signature is unknown.

This helper prefers the byte signature over the extension if the two disagree.

detect_with_extension_strict

</>

pub fn detect_with_extension_strict(
  bytes: BitArray,
  extension: String,
) -> Result(String, Nil)

Detect a MIME type from bytes, falling back to an explicit extension when the content signature is unknown.

This strict variant returns Error(Nil) only when neither the byte signature nor the normalized extension are known.

detect_with_filename

</>

pub fn detect_with_filename(
  bytes: BitArray,
  filename: String,
) -> String

Detect a MIME type from bytes, falling back to the filename extension when the content signature is unknown.

This helper prefers the byte signature over the filename if the two disagree.

detect_with_filename_strict

</>

pub fn detect_with_filename_strict(
  bytes: BitArray,
  filename: String,
) -> Result(String, Nil)

Detect a MIME type from bytes, falling back to the filename extension when the content signature is unknown.

This strict variant returns Error(Nil) only when neither the byte signature nor the filename extension are known.

essence

</>

pub fn essence(mime_type: String) -> String

Return the bare MIME type without any parameters.

This trims surrounding whitespace, lowercases the media type, and strips anything after the first ;.

extension_to_mime_type

</>

pub fn extension_to_mime_type(extension: String) -> String

Look up a MIME type from a file extension.

The input may include a leading dot and is normalized to lowercase before lookup. Unknown extensions fall back to application/octet-stream.

extension_to_mime_type_strict

</>

pub fn extension_to_mime_type_strict(
  extension: String,
) -> Result(String, Nil)

Look up a MIME type from a file extension.

This strict variant returns Error(Nil) when the normalized extension is not present in the generated database.

filename_to_mime_type

</>

pub fn filename_to_mime_type(path: String) -> String

Look up a MIME type from the last extension component of a path or filename.

Query strings and URL fragments are ignored. Hidden files without a real extension, such as .gitignore, fall back to application/octet-stream.

filename_to_mime_type_strict

</>

pub fn filename_to_mime_type_strict(
  path: String,
) -> Result(String, Nil)

Look up a MIME type from the last extension component of a path or filename.

This strict variant returns Error(Nil) when the path does not contain a usable extension or the extension is unknown.

is_audio

</>

pub fn is_audio(mime_type: String) -> Bool

Return True when the MIME type’s top-level media type is audio.

is_image

</>

pub fn is_image(mime_type: String) -> Bool

Return True when the MIME type’s top-level media type is image.

is_text

</>

pub fn is_text(mime_type: String) -> Bool

Return True when the MIME type’s top-level media type is text.

is_video

</>

pub fn is_video(mime_type: String) -> Bool

Return True when the MIME type’s top-level media type is video.

mime_type_to_extensions

</>

pub fn mime_type_to_extensions(mime_type: String) -> List(String)

Return all known extensions for a MIME type.

The input is trimmed, lowercased, and stripped of any MIME parameters (such as ; charset=utf-8) before lookup. Unknown MIME types return the empty list.

mime_type_to_extensions_strict

</>

pub fn mime_type_to_extensions_strict(
  mime_type: String,
) -> Result(List(String), Nil)

Return all known extensions for a MIME type.

This strict variant returns Error(Nil) when the normalized MIME type is not present in the generated database.

parameter

</>

pub fn parameter(
  mime_type: String,
  key: String,
) -> Result(String, Nil)

Look up a parameter value from a MIME type string.

Parameter names are matched case-insensitively. This returns Error(Nil) when the key is empty or the parameter is missing.