Skip to content
calternal docs

calternal-media

Bounded media-container type detection for calternal

Bounded media parsing and the shared content-type detector.

detect is the one place that decides a file’s type (#851). Files, Photos, Search, Tags, Embed, DAV and the download routes use the MIME value it returns, which Files stores in its Index. The owner rule is:

  1. When the bytes carry a known signature (images, camera RAW, video, audio, PDF, archives, ZIP and OLE office containers inspected one level, fonts, executables), that type wins over the file name.
  2. Plain text has no signature. Only then does the extension choose the text format, after a cheap structural check where one exists (ICS starts with BEGIN:VCALENDAR, VCF with BEGIN:VCARD, JSON with { or [).
  3. A name that disagrees with the bytes (photo.txt that is a JPEG) gets the content type. The file name is never changed.

The detector never opens a file on its own and reads at most DETECT_PREFIX_BYTES of the supplied prefix. Only an ISO movie whose moov box is outside that prefix asks the caller for a reader, so it can tell an audio-only .mp4 from a video (#620, #720).

HTML, XML and script never get an active MIME from this crate: they are stored as text/plain. SVG keeps image/svg+xml so the Files response policy can allow it only as an image load (DESIGN §2 and §4).

The track parser is ported from job/voicefiles-620; #816 bounds its grammar and total work. DESIGN §28 uses native media playback and §39 shares file attachment metadata with Calendar.

Source: crates/calternal-media/src/lib.rs

Structs

Section titled “Structs”

ContentType

Section titled “ContentType”
pub struct ContentType

A MIME type and its stable broad class, detected from content when possible.

Fields

  • pub mime: String: Lower-case MIME type used by the Files index and HTTP responses.
  • pub kind: ContentKind: Broad kind used by Files, Photos, Search and the web client.

Implements: Clone, Debug, Eq, PartialEq

Source: crates/calternal-media/src/lib.rs:67

Enums

Section titled “Enums”

ContentKind

Section titled “ContentKind”
pub enum ContentKind

The broad user-facing class that follows a detected MIME type.

Variants

  • Image: A still image, including camera RAW and HEIF/AVIF files.
  • Video: A moving picture or a container with a video track.
  • Audio: Audio without a video track.
  • Text: Text content that can be shown as text.
  • Document: A document format such as PDF or an Office file.
  • Archive: A compressed or packaged collection of files.
  • Other: A format that has no safer, more useful broad class.

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-media/src/lib.rs:48

Functions

Section titled “Functions”

detect

Section titled “detect”
pub fn detect(path: &str, first_bytes: &[u8]) -> ContentType

Detect one file’s MIME type and broad class from its existing read prefix.

path supplies only the name for rule 2 (text formats) and for subtypes inside a container family. The function reads at most DETECT_PREFIX_BYTES of first_bytes and never opens a file.

Source: crates/calternal-media/src/lib.rs:112

detect_with_reader

Section titled “detect_with_reader”
pub fn detect_with_reader<R: Read + Seek>(
    path: &str,
    first_bytes: &[u8],
    open: impl FnOnce() -> Option<R>,
) -> ContentType

detect, plus a lazy reader for the one case the prefix cannot answer: an ISO movie (.mp4, .mov, .3gp) whose moov box is after the prefix. open runs only then; it reads the box by seeking, at most 16 MiB of header, and never the media data. Background paths that already hold the file pass it here; a missing reader keeps the brand-based video type.

Source: crates/calternal-media/src/lib.rs:121

is_active_mime

Section titled “is_active_mime”
pub fn is_active_mime(mime: &str) -> bool

Return whether a MIME can execute active browser content when served inline. Files and DAV use this shared policy to keep user bytes inert on the app origin.

Source: crates/calternal-media/src/lib.rs:723

is_raw_image

Section titled “is_raw_image”
pub fn is_raw_image(mime: &str) -> bool

Return whether a stored image MIME names a camera RAW representation. Photos pairing and the CLIP job use it, so a suffix is never required to keep a RAW file in the correct projection (#851).

Source: crates/calternal-media/src/lib.rs:102

is_text_mime

Section titled “is_text_mime”
pub fn is_text_mime(mime: &str) -> bool

Return whether a MIME value represents searchable text.

JSON, YAML and similar formats have application MIME names in common registries. Keeping this policy beside detect stops each index from keeping its own suffix table (#851).

Source: crates/calternal-media/src/lib.rs:791

kind_for_mime

Section titled “kind_for_mime”
pub fn kind_for_mime(mime: &str) -> ContentKind

Map a MIME value to the single broad class used by Files, Photos, Search and Calendar. Photos admits Image and Video (and RAW, which is an image), so an audio-only .mp4 cannot enter it (#720).

Source: crates/calternal-media/src/lib.rs:747

Constants

Section titled “Constants”

DETECT_PREFIX_BYTES

Section titled “DETECT_PREFIX_BYTES”
pub const DETECT_PREFIX_BYTES: usize

The prefix length that callers keep for detect. Every signature in this crate fits in it, including the ZIP member walk, the TIFF RAW marker scan and the first Matroska/Ogg track headers. A larger prefix gives no better answer and costs memory on each write and each backfill read.

Source: crates/calternal-media/src/lib.rs:35

DETECTOR_VERSION

Section titled “DETECTOR_VERSION”
pub const DETECTOR_VERSION: i64

Bump this when the detector gives a different answer for the same bytes. Files compares it with the version stored in its Index and re-detects old rows once, as a projection rebuild that never writes a User file (#851).

Source: crates/calternal-media/src/lib.rs:40