Media Categories

Different media categories expose different enrichments. Unsupported enrichments are omitted from the response — not set to null. This is a core platform semantic.

Category-Specific Enrichment Matrix

Enrichment	Image	Video	Audio	Provider (YouTube)
preview.thumbnail	✅ generated	✅ generated	— omitted	✅ provider-native
preview.placeholder (blurhash)	✅ generated	✅ generated	— omitted	— omitted
preview.palette	✅ computed	✅ computed	— omitted	— omitted
preview.waveform	— omitted	— omitted	✅ planned (null)	— omitted
preview.spectrogram	— omitted	— omitted	✅ planned (null)	— omitted
metadata.image	✅	— omitted	— omitted	— omitted
metadata.video	— omitted	✅	— omitted	— omitted
metadata.audio	— omitted	— omitted	✅	— omitted

Omission vs Null

Omitted = the enrichment is not supported for this media category. The field does not appear in the response.

Null = the enrichment is supported and registered but hasn't completed yet (progressive null semantics).

Image Enrichments

Image resources expose visual metadata and preview intelligence:

// FULL profile — Image response
{
  "data": {
    "metadata": {
      "filename": "photo.jpg",
      "size": { "bytes": 204800, "formatted": "200 KB" },
      "image": {
        "colorSpace": "srgb",
        "hasAlpha": false
      }
    },
    "preview": {
      "thumbnail": {
        "url": "/public/thumbnails/generated.jpg",
        "dimensions": "320x180"
      },
      "placeholder": {
        "type": "blurhash",
        "value": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
      },
      "palette": {
        "dominant": "#112233"
      },
      "dominantColor": "#112233"
    }
  }
}

Unsupported namespaces for image: metadata.video, metadata.audio, preview.waveform, preview.spectrogram — all omitted.

Image Enrichment Lifecycle Stages

Stage	Source	Description
metadata:image	Extracted	Color space, alpha detection, dimensions
preview:thumbnail	Generated	Scaled preview image
preview:blurhash	Generated	Low-res placeholder hash
preview:palette	Computed	Dominant color extraction

Video Enrichments

Video resources expose temporal and visual metadata:

// FULL profile — Video response
{
  "data": {
    "metadata": {
      "filename": "BigBuckBunny_320x180.mp4",
      "size": { "bytes": 56733664, "formatted": "54.1 MB" },
      "video": {
        "duration": { "seconds": 30, "formatted": "0:30" },
        "fps": 24,
        "bitrate": { "bps": 1000000, "formatted": "1 Mbps" }
      }
    },
    "playback": {
      "strategy": "native",
      "component": "video",
      "streamable": true,
      "downloadable": true
    },
    "preview": {
      "thumbnail": {
        "url": "/public/thumbnails/video.jpg",
        "dimensions": "320x180"
      },
      "placeholder": {
        "type": "blurhash",
        "value": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
      },
      "palette": null               // supported, pending extraction
    }
  }
}

Unsupported namespaces for video: metadata.image, metadata.audio, preview.waveform, preview.spectrogram — all omitted.

Video Processing Characteristics

Video is classified as heavy media. This means:

• FAST profile returns partial status with pending enrichments
• STANDARD profile returns 202 Accepted with a job reference
• FULL profile blocks synchronously until all enrichments complete
• Background workers handle thumbnail generation, palette extraction, and media analysis

Audio Enrichments

Audio resources expose audio-specific metadata and planned waveform visualization:

// FULL profile — Audio response
{
  "data": {
    "metadata": {
      "filename": "audio.ogg",
      "size": { "bytes": 1024, "formatted": "1 KB" },
      "audio": {
        "duration": { "seconds": 30, "formatted": "0:30" },
        "bitrate": { "bps": 128000, "formatted": "128 kbps" },
        "sampleRate": 44100
      }
    },
    "playback": {
      "strategy": "native",
      "component": "audio",
      "streamable": true,
      "downloadable": true
    },
    "preview": {
      "waveform": null,              // planned, not yet available
      "spectrogram": null            // planned, not yet available
    }
  }
}

Unsupported namespaces for audio: metadata.image, metadata.video, preview.thumbnail, preview.placeholder, preview.palette, preview.dominantColor — all omitted.

Audio Preview Namespace

The audio preview namespace is meaningful because it contains planned enrichments (waveform, spectrogram) that are currently unavailable (null). Visual preview enrichments (thumbnail, blurhash, palette) are unsupported for audio and therefore omitted entirely.

Audio Registry Isolation

The enrichment registry for audio resources never creates visual preview lifecycle stages. Unsupported stages like preview:thumbnail, preview:blurhash, and preview:palette are not registered, and therefore never appear in completedStages or pendingStages.

Provider Resources (YouTube)

Provider-detected resources expose provider-native intelligence rather than generated enrichments:

// FAST profile — YouTube response
{
  "data": {
    "identity": {
      "url": "https://youtu.be/GLTTI1NFHus?si=...",
      "canonicalUrl": "https://www.youtube.com/watch?v=GLTTI1NFHus",
      "mime": "text/html"
    },
    "semantic": {
      "kind": "embed-media",
      "semanticType": "embedded-video",
      "title": "Provider Native Title"
    },
    "provider": {
      "name": "youtube",
      "confidence": 1,
      "detectionMethod": "url-parser"
    },
    "playback": {
      "strategy": "iframe",
      "component": "iframe",
      "embedUrl": "https://www.youtube.com/embed/GLTTI1NFHus",
      "streamable": false,
      "downloadable": false
    },
    "preview": {
      "thumbnail": {
        "url": "https://i.ytimg.com/vi/GLTTI1NFHus/hqdefault.jpg"
      }
    }
  }
}

Provider resources have unique characteristics:

• No heavy media processing — YouTube and similar providers complete enrichment immediately
• Provider-native thumbnail — sourced from YouTube's CDN, not generated
• Provider-native title — sourced from oEmbed, not extracted
• No metadata.video block — the platform doesn't download the actual video binary
• provider block present — only exists for provider-detected URLs, never for direct media