media-optimization-engine 1.4.0__py3-none-any.whl

media_engine/registry.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from django.db import transaction
+from django.db.models.signals import post_save
+
+_REGISTRY = []
+_REGISTRY_KEYS = set()
+
+
+@dataclass
+class RegistryEntry:
+    model: object
+    field_name: str
+    profile: str
+    role: str
+
+
+def register_model_image(model, field_name, profile='default', role='content'):
+    key = (model._meta.label_lower, field_name)
+    if key in _REGISTRY_KEYS:
+        return next(entry for entry in _REGISTRY if (entry.model._meta.label_lower, entry.field_name) == key)
+
+    model._meta.get_field(field_name)
+    entry = RegistryEntry(model=model, field_name=field_name, profile=profile, role=role)
+    _REGISTRY.append(entry)
+    _REGISTRY_KEYS.add(key)
+
+    def handler(sender, instance, created=False, raw=False, update_fields=None, **kwargs):
+        if raw:
+            return
+        if update_fields is not None and field_name not in update_fields:
+            return
+
+        def _ingest():
+            from .integration import ingest_model_field
+            ingest_model_field(instance, field_name=field_name, profile=profile, role=role)
+
+        transaction.on_commit(_ingest)
+
+    post_save.connect(
+        handler,
+        sender=model,
+        weak=False,
+        dispatch_uid=f'media-engine:{model._meta.label_lower}:{field_name}',
+    )
+    return entry
+
+
+def entries():
+    return list(_REGISTRY)

media_engine/runtime_config.py

@@ -0,0 +1,37 @@
+from copy import deepcopy
+from django.conf import settings
+from .control_plane import load_last_known_good
+
+
+def _merge_profile(base: dict, override: dict) -> dict:
+    result = deepcopy(base)
+    for key, value in (override or {}).items():
+        if key in {'quality', 'target_bytes'} and isinstance(value, dict):
+            merged = dict(result.get(key, {}))
+            for subkey, subvalue in value.items():
+                if key == 'target_bytes':
+                    try:
+                        subkey = int(subkey)
+                    except (TypeError, ValueError):
+                        pass
+                merged[subkey] = subvalue
+            result[key] = merged
+        else:
+            result[key] = value
+    return result
+
+
+def effective_profiles() -> dict:
+    profiles = deepcopy(getattr(settings, 'MEDIA_ENGINE_PROFILES', {}))
+    snapshot = load_last_known_good()
+    for name, override in snapshot.get('profiles', {}).items():
+        if name in profiles:
+            profiles[name] = _merge_profile(profiles[name], override)
+        else:
+            profiles[name] = deepcopy(override)
+    return profiles
+
+
+def effective_feature_flags() -> dict:
+    snapshot = load_last_known_good()
+    return dict(snapshot.get('feature_flags', {}))

media_engine/serializers.py

@@ -0,0 +1,29 @@
+from rest_framework import serializers
+from .models import MediaAsset
+from .manifest import build_manifest
+
+
+class MediaUploadSerializer(serializers.Serializer):
+    file = serializers.ImageField()
+    profile = serializers.CharField(required=False, default='default')
+    owner_ref = serializers.CharField(required=False, allow_blank=True, default='')
+    focal_x = serializers.FloatField(required=False, min_value=0, max_value=1)
+    focal_y = serializers.FloatField(required=False, min_value=0, max_value=1)
+    media_kind = serializers.ChoiceField(required=False, choices=['image', 'panorama'])
+    projection = serializers.ChoiceField(required=False, choices=['equirectangular', 'cubemap'])
+
+
+class MediaAssetSerializer(serializers.ModelSerializer):
+    manifest = serializers.SerializerMethodField()
+
+    class Meta:
+        model = MediaAsset
+        fields = [
+            'id', 'status', 'original_name', 'mime_type', 'width', 'height',
+            'original_size', 'media_kind', 'projection', 'processor', 'dominant_color', 'blurhash', 'focal_x', 'focal_y',
+            'processor_version', 'last_error', 'created_at', 'updated_at', 'manifest',
+        ]
+
+    def get_manifest(self, obj):
+        profile = self.context.get('profile', 'default')
+        return build_manifest(obj, profile=profile)

media_engine/services.py

@@ -0,0 +1,187 @@
+import hashlib
+import io
+from pathlib import Path
+from django.conf import settings
+from django.core.files.base import ContentFile
+from django.core.files.storage import default_storage
+from django.db import transaction, IntegrityError
+from django.utils import timezone
+from .image_ops import normalized_image, dominant_color, make_blurhash, placeholder_data_url, resized, encode_with_budget
+from .metrics import IMAGES_INGESTED, ORIGINAL_BYTES, VARIANTS_GENERATED, VARIANT_FAILURES, GENERATION_SECONDS, DERIVATIVE_BYTES
+from .models import MediaAsset, MediaVariant
+from .profiles import get_profile, requested_widths, all_formats
+from .storage_paths import safe_extension, original_storage_name, derivative_storage_name
+from .validators import inspect_upload
+from .locks import cache_lock
+from .runtime_config import effective_feature_flags
+
+
+def ingest_uploaded_file(uploaded_file, *, owner_ref='', focal_x=None, focal_y=None, profile='default', enqueue=True, media_kind='', projection=''):
+    raw, fmt, mime, width, height = inspect_upload(uploaded_file)
+    sha = hashlib.sha256(raw).hexdigest()
+    extension = safe_extension(fmt)
+    version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+
+    existing = MediaAsset.objects.filter(original_sha256=sha).first()
+    if existing and getattr(settings, 'MEDIA_ENGINE_DEDUPLICATE', True):
+        if enqueue:
+            from .queueing import enqueue_asset
+            transaction.on_commit(lambda: enqueue_asset(existing.id, profile=profile))
+        return existing, False
+
+    storage_name = original_storage_name(sha, extension)
+    if not default_storage.exists(storage_name):
+        default_storage.save(storage_name, ContentFile(raw))
+
+    image = normalized_image(io.BytesIO(raw))
+    from .processors.panorama.detect import detect_equirectangular
+    detection = detect_equirectangular(width, height, getattr(image, 'info', {}) or {})
+    if not media_kind:
+        media_kind = 'panorama' if (profile.startswith('panorama.') or detection.is_panorama) else 'image'
+    if media_kind == 'panorama' and not projection:
+        projection = detection.projection or 'equirectangular'
+    feature_flags = effective_feature_flags()
+    auto_focal = feature_flags.get('auto_focal', getattr(settings, 'MEDIA_ENGINE_AUTO_FOCAL', False))
+    if auto_focal and focal_x is None and focal_y is None:
+        from .focal_detectors import detect_focal_point
+        auto_x, auto_y = detect_focal_point(image)
+        focal_x = auto_x
+        focal_y = auto_y
+    try:
+        asset = MediaAsset.objects.create(
+            original_sha256=sha,
+            original_file=storage_name,
+            original_name=Path(getattr(uploaded_file, 'name', '')).name,
+            mime_type=mime,
+            width=width,
+            height=height,
+            original_size=len(raw),
+            media_kind=media_kind,
+            projection=projection,
+            processor='panorama_360' if media_kind == 'panorama' else 'standard_image',
+            metadata_json={
+                'panorama_detection_confidence': detection.confidence,
+                'panorama_detection_reason': detection.reason,
+            },
+            dominant_color=dominant_color(image),
+            blurhash=make_blurhash(image),
+            placeholder_data_url=placeholder_data_url(image),
+            focal_x=focal_x,
+            focal_y=focal_y,
+            processor_version=version,
+            owner_ref=owner_ref,
+        )
+        created = True
+        IMAGES_INGESTED.inc()
+        ORIGINAL_BYTES.inc(len(raw))
+    except IntegrityError:
+        asset = MediaAsset.objects.get(original_sha256=sha)
+        created = False
+    if enqueue:
+        from .queueing import enqueue_asset
+        transaction.on_commit(lambda: enqueue_asset(asset.id, profile=profile))
+    return asset, created
+
+
+def generate_variant(asset, *, profile_name, width, fmt, force=False):
+    version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+    profile = get_profile(profile_name)
+    lock_key = f'media-engine:{asset.id}:{version}:{profile_name}:{width}:{fmt}'
+    with cache_lock(lock_key) as acquired:
+        if not acquired:
+            return None
+        existing = MediaVariant.objects.filter(
+            asset=asset,
+            profile=profile_name,
+            width=width,
+            format=fmt,
+            processor_version=version,
+            status=MediaVariant.Status.READY,
+        ).first()
+        if existing and not force:
+            return existing
+
+        variant, _ = MediaVariant.objects.get_or_create(
+            asset=asset,
+            profile=profile_name,
+            width=width,
+            format=fmt,
+            processor_version=version,
+            defaults={'height': 0, 'status': MediaVariant.Status.PROCESSING},
+        )
+        variant.status = MediaVariant.Status.PROCESSING
+        variant.last_error = ''
+        variant.save(update_fields=['status', 'last_error', 'updated_at'])
+
+        try:
+            with default_storage.open(asset.original_file.name, 'rb') as source:
+                image = normalized_image(source)
+            work = resized(
+                image,
+                width,
+                fit=profile.get('fit', 'contain'),
+                aspect_ratio=profile.get('aspect_ratio'),
+                focal_x=asset.focal_x,
+                focal_y=asset.focal_y,
+            )
+            quality = profile.get('quality', {}).get(fmt, 75)
+            target = profile.get('target_bytes', {}).get(width)
+            with GENERATION_SECONDS.labels(format=fmt, profile=profile_name).time():
+                encoded = encode_with_budget(work, fmt, quality, target_bytes=target)
+            path = derivative_storage_name(asset.original_sha256, version, profile_name, width, fmt)
+            if default_storage.exists(path):
+                default_storage.delete(path)
+            stored = default_storage.save(path, ContentFile(encoded.content))
+            variant.file = stored
+            variant.height = encoded.height
+            variant.file_size = len(encoded.content)
+            variant.quality = encoded.quality
+            variant.status = MediaVariant.Status.READY
+            variant.last_error = ''
+            variant.save()
+            VARIANTS_GENERATED.labels(format=fmt, profile=profile_name).inc()
+            DERIVATIVE_BYTES.labels(format=fmt).inc(len(encoded.content))
+            return variant
+        except Exception as exc:
+            variant.status = MediaVariant.Status.FAILED
+            variant.last_error = str(exc)
+            variant.save(update_fields=['status', 'last_error', 'updated_at'])
+            VARIANT_FAILURES.labels(format=fmt, profile=profile_name).inc()
+            raise
+
+
+def generate_standard_variants(asset, profile_name='default', force=False):
+    profile = get_profile(profile_name)
+    expected = []
+    errors = []
+    asset.status = MediaAsset.Status.PROCESSING
+    asset.last_error = ''
+    asset.save(update_fields=['status', 'last_error', 'updated_at'])
+    for width in requested_widths(profile, asset.width):
+        for fmt in all_formats(profile):
+            expected.append((width, fmt))
+            try:
+                generate_variant(asset, profile_name=profile_name, width=width, fmt=fmt, force=force)
+            except Exception as exc:
+                errors.append(f'{width}.{fmt}: {exc}')
+
+    ready_count = MediaVariant.objects.filter(
+        asset=asset,
+        profile=profile_name,
+        processor_version=getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1),
+        status=MediaVariant.Status.READY,
+    ).count()
+    asset.status = MediaAsset.Status.READY if ready_count >= len(expected) and not errors else (MediaAsset.Status.PARTIAL if ready_count else MediaAsset.Status.FAILED)
+    asset.last_error = '\n'.join(errors[-20:])
+    asset.processed_at = timezone.now()
+    asset.processor_version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+    asset.save(update_fields=['status', 'last_error', 'processed_at', 'processor_version', 'updated_at'])
+    from .manifest import invalidate_manifest
+    invalidate_manifest(asset.id)
+    return asset
+
+
+def generate_all_variants(asset, profile_name='default', force=False):
+    from .processors.registry import get_processor
+    processor = get_processor(asset, profile_name)
+    return processor.process(asset, profile_name, force=force)

media_engine/signals.py

@@ -0,0 +1,5 @@
+# Project-specific model registrations can be imported here from your integration app.
+# Example:
+# from myapp.models import Product
+# from .registry import register_model_image
+# register_model_image(Product, 'cover', profile='hero', role='hero')

media_engine/spec/openapi.yaml

@@ -0,0 +1,191 @@
+openapi: 3.1.0
+info:
+  title: Media Optimization Engineer API
+  version: 1.4.0
+  description: >-
+    Autonomous media optimization API for Django/Python projects and standalone nodes.
+    Normal image processing and delivery do not depend on an optional external control plane.
+servers:
+  - url: /
+paths:
+  /.well-known/media-optimization-engine.json:
+    get:
+      summary: Discover the engine and its machine-readable endpoints.
+      responses:
+        '200':
+          description: Discovery document.
+  /api/v1/system/capabilities/:
+    get:
+      summary: Node formats, profiles and supported features.
+      responses:
+        '200':
+          description: Capability document.
+  /api/v1/system/health/:
+    get:
+      summary: Local node health. Control-plane failures do not make local runtime unhealthy.
+      responses:
+        '200':
+          description: Healthy or locally degraded node.
+        '503':
+          description: A local core dependency is unhealthy.
+  /api/v1/system/version/:
+    get:
+      summary: Engine, pipeline and node version metadata.
+      responses:
+        '200':
+          description: Version document.
+  /api/v1/images/:
+    post:
+      summary: Upload an original image and enqueue responsive optimization.
+      security:
+        - bearerApiKey: []
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file:
+                  type: string
+                  format: binary
+                profile:
+                  type: string
+                  default: default
+                  enum: [default, avatar, card, hero, panorama.preview, panorama.multires, panorama.marzipano, panorama.cube]
+                owner_ref:
+                  type: string
+                media_kind:
+                  type: string
+                  enum: [image, panorama]
+                projection:
+                  type: string
+                  enum: [equirectangular, cubemap]
+                focal_x:
+                  type: number
+                  minimum: 0
+                  maximum: 1
+                focal_y:
+                  type: number
+                  minimum: 0
+                  maximum: 1
+      responses:
+        '200':
+          description: Existing deduplicated asset.
+        '201':
+          description: New asset accepted.
+        '400':
+          description: Invalid upload.
+        '403':
+          description: Invalid/missing API key when authentication is required.
+  /api/v1/images/{id}/:
+    get:
+      summary: Retrieve asset metadata and manifest.
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+        - in: query
+          name: profile
+          schema: {type: string, default: default}
+      responses:
+        '200': {description: Asset metadata.}
+        '404': {description: Asset not found.}
+    patch:
+      summary: Update focal coordinates.
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                focal_x: {type: number, minimum: 0, maximum: 1}
+                focal_y: {type: number, minimum: 0, maximum: 1}
+      responses:
+        '200': {description: Updated asset.}
+  /api/v1/images/{id}/manifest/:
+    get:
+      summary: Retrieve immutable responsive derivative manifest.
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+        - in: query
+          name: profile
+          schema: {type: string, default: default}
+      responses:
+        '200': {description: Responsive manifest.}
+  /api/v1/images/{id}/regenerate/:
+    post:
+      summary: Enqueue a forced regeneration for a profile.
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+      responses:
+        '202': {description: Regeneration queued.}
+  /api/v1/images/{id}/render/:
+    get:
+      summary: Fallback on-demand derivative generation and redirect.
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+        - in: query
+          name: profile
+          schema: {type: string, default: default}
+        - in: query
+          name: width
+          schema: {type: integer, default: 640}
+        - in: query
+          name: format
+          schema: {type: string, default: avif, enum: [avif, webp, jpeg]}
+      responses:
+        '302': {description: Redirect to immutable derivative.}
+        '202': {description: Generation already in progress.}
+  /api/v1/images/{id}/panorama/:
+    get:
+      summary: Get a 360 panorama multiresolution manifest
+      security:
+        - bearerApiKey: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: {type: string, format: uuid}
+        - in: query
+          name: adapter
+          required: false
+          schema:
+            type: string
+            enum: [generic, pannellum, marzipano, threejs]
+      responses:
+        '200':
+          description: Panorama manifest
+
+components:
+  securitySchemes:
+    bearerApiKey:
+      type: http
+      scheme: bearer
+      bearerFormat: APIKey

media_engine/static/media_engine/adaptive-media.js

@@ -0,0 +1,77 @@
+(() => {
+  const root = document.documentElement;
+  const connection =
+    navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+
+  if (connection) {
+    root.dataset.moeSaveData = connection.saveData ? '1' : '0';
+    root.dataset.moeEffectiveType = connection.effectiveType || '';
+  }
+
+  const observed = new WeakSet();
+
+  const applyRenderedSize = (picture) => {
+    const width = Math.ceil(picture.getBoundingClientRect().width);
+    if (!width) return;
+
+    const sizes = width + 'px';
+    picture.querySelectorAll('source[srcset]').forEach((source) => {
+      source.sizes = sizes;
+    });
+
+    const image = picture.querySelector('img[srcset]');
+    if (image) {
+      image.sizes = sizes;
+    }
+
+    picture.dataset.moeRenderedWidth = String(width);
+    picture.dataset.moeDpr = String(window.devicePixelRatio || 1);
+  };
+
+  const resizeObserver =
+    typeof ResizeObserver === 'undefined'
+      ? null
+      : new ResizeObserver((entries) => {
+          entries.forEach((entry) => applyRenderedSize(entry.target));
+        });
+
+  const register = (picture) => {
+    if (!picture || observed.has(picture)) return;
+    observed.add(picture);
+    applyRenderedSize(picture);
+    if (resizeObserver) {
+      resizeObserver.observe(picture);
+    }
+  };
+
+  const scan = (rootNode) => {
+    if (rootNode.matches && rootNode.matches('picture[data-moe-adaptive="1"]')) {
+      register(rootNode);
+    }
+    if (rootNode.querySelectorAll) {
+      rootNode
+        .querySelectorAll('picture[data-moe-adaptive="1"]')
+        .forEach(register);
+    }
+  };
+
+  const start = () => {
+    scan(document);
+
+    if (typeof MutationObserver !== 'undefined') {
+      new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+          mutation.addedNodes.forEach((node) => {
+            if (node.nodeType === 1) scan(node);
+          });
+        });
+      }).observe(document.documentElement, { childList: true, subtree: true });
+    }
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', start, { once: true });
+  } else {
+    start();
+  }
+})();

media_engine/static/media_engine/media-cache-sw.js

@@ -0,0 +1,17 @@
+const CACHE = 'media-engine-immutable-v1';
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url);
+  if (event.request.method !== 'GET') return;
+  if (!url.pathname.includes('/media_engine/derivatives/')) return;
+
+  event.respondWith(
+    caches.open(CACHE).then(async (cache) => {
+      const hit = await cache.match(event.request);
+      if (hit) return hit;
+      const response = await fetch(event.request);
+      if (response.ok) cache.put(event.request, response.clone());
+      return response;
+    })
+  );
+});

media_engine/storage_paths.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+
+
+def safe_extension(fmt):
+    return {'JPEG': 'jpg', 'JPG': 'jpg', 'PNG': 'png', 'WEBP': 'webp', 'AVIF': 'avif'}.get(fmt.upper(), fmt.lower())
+
+
+def original_storage_name(sha256_hex, extension):
+    return f'media_engine/originals/{sha256_hex[:2]}/{sha256_hex[2:4]}/{sha256_hex}.{extension}'
+
+
+def derivative_storage_name(sha256_hex, version, profile, width, fmt):
+    return f'media_engine/derivatives/{sha256_hex[:2]}/{sha256_hex[2:4]}/v{version}/{profile}/{width}.{fmt}'