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

media_engine/__init__.py

@@ -0,0 +1,7 @@
+__version__ = '1.4.0rc3'
+
+def register_model_image(*args, **kwargs):
+    from .registry import register_model_image as _register
+    return _register(*args, **kwargs)
+
+default_app_config = 'media_engine.apps.MediaEngineConfig'

media_engine/adapters/flutter/README.md

@@ -0,0 +1,10 @@
+# Flutter panorama adapter
+
+`models.dart` parses the generic MOE panorama manifest. A Flutter viewer can select the lowest level that satisfies current viewport width and devicePixelRatio, then request only visible tiles.
+
+Recommended policy:
+- show `preview` immediately;
+- select a level from viewport width x DPR;
+- request only tiles intersecting the current field of view;
+- keep adjacent tiles warm for smooth panning;
+- use AVIF where the Flutter image stack supports it, otherwise WebP.

media_engine/adapters/flutter/models.dart

@@ -0,0 +1,88 @@
+class PanoramaTile {
+  final int level;
+  final int x;
+  final int y;
+  final int width;
+  final int height;
+  final String url;
+
+  const PanoramaTile({
+    required this.level,
+    required this.x,
+    required this.y,
+    required this.width,
+    required this.height,
+    required this.url,
+  });
+
+  factory PanoramaTile.fromJson(int level, Map<String, dynamic> json) => PanoramaTile(
+        level: level,
+        x: json['x'] as int,
+        y: json['y'] as int,
+        width: json['width'] as int,
+        height: json['height'] as int,
+        url: json['url'] as String,
+      );
+}
+
+class PanoramaLevel {
+  final int level;
+  final int width;
+  final int height;
+  final int cols;
+  final int rows;
+  final int tileSize;
+  final Map<String, List<PanoramaTile>> formats;
+
+  const PanoramaLevel({
+    required this.level,
+    required this.width,
+    required this.height,
+    required this.cols,
+    required this.rows,
+    required this.tileSize,
+    required this.formats,
+  });
+
+  factory PanoramaLevel.fromJson(Map<String, dynamic> json) {
+    final level = json['level'] as int;
+    final rawFormats = Map<String, dynamic>.from(json['formats'] as Map);
+    return PanoramaLevel(
+      level: level,
+      width: json['width'] as int,
+      height: json['height'] as int,
+      cols: json['cols'] as int,
+      rows: json['rows'] as int,
+      tileSize: json['tile_size'] as int,
+      formats: rawFormats.map((key, value) => MapEntry(
+            key,
+            (value as List)
+                .map((e) => PanoramaTile.fromJson(level, Map<String, dynamic>.from(e as Map)))
+                .toList(),
+          )),
+    );
+  }
+}
+
+class PanoramaManifest {
+  final String assetId;
+  final String projection;
+  final String preview;
+  final List<PanoramaLevel> levels;
+
+  const PanoramaManifest({
+    required this.assetId,
+    required this.projection,
+    required this.preview,
+    required this.levels,
+  });
+
+  factory PanoramaManifest.fromJson(Map<String, dynamic> json) => PanoramaManifest(
+        assetId: json['asset_id'] as String,
+        projection: json['projection'] as String? ?? 'equirectangular',
+        preview: json['preview'] as String? ?? '',
+        levels: (json['levels'] as List? ?? const [])
+            .map((e) => PanoramaLevel.fromJson(Map<String, dynamic>.from(e as Map)))
+            .toList(),
+      );
+}

media_engine/adapters/marzipano/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_marzipano
+__all__ = ['to_marzipano']

media_engine/adapters/marzipano/manifest.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+
+def to_marzipano(manifest: dict) -> dict:
+    """Return a browser-friendly Marzipano description.
+
+    For ``panorama.marzipano`` the engine emits a true multires CubeGeometry
+    pyramid. Tiles stay explicit so this works with local storage, S3 and R2
+    without assuming a specific URL layout.
+    """
+    layout = manifest.get('layout', '')
+    if layout != 'cube-multires':
+        # Graceful preview fallback for a generic equirectangular pipeline.
+        return {
+            'type': 'equirectangular',
+            'preview': manifest.get('preview', ''),
+            'projection': manifest.get('projection', 'equirectangular'),
+            'levels': manifest.get('levels', []),
+        }
+
+    levels = []
+    tiles = []
+    preferred_format = 'webp'
+    for item in manifest.get('levels', []):
+        formats = item.get('formats', {})
+        selected = formats.get('webp') or formats.get('avif') or next(iter(formats.values()), [])
+        if not selected:
+            continue
+        if formats.get('webp') is None and formats.get('avif'):
+            preferred_format = 'avif'
+        levels.append({
+            'level': item['level'],
+            'size': item.get('size') or item.get('width'),
+            'tileSize': item.get('tile_size', 512),
+            'fallbackOnly': bool(item.get('fallback_only', False)),
+        })
+        for tile in selected:
+            tiles.append({
+                'z': item['level'],
+                'face': tile.get('face', ''),
+                'x': tile['x'],
+                'y': tile['y'],
+                'url': tile['url'],
+            })
+
+    return {
+        'type': 'cube-multires',
+        'preview': manifest.get('preview', ''),
+        'projection': manifest.get('projection', 'equirectangular'),
+        'format': preferred_format,
+        'geometry': {'type': 'cube', 'levels': levels},
+        'tiles': tiles,
+    }

media_engine/adapters/pannellum/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_pannellum
+__all__ = ['to_pannellum']

media_engine/adapters/pannellum/manifest.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+def to_pannellum(manifest: dict) -> dict:
+    levels = manifest.get('levels', [])
+    if not levels:
+        return {'type': 'equirectangular', 'panorama': manifest.get('preview', '')}
+    max_level = max(level['level'] for level in levels)
+    tile_size = levels[0].get('tile_size', 512)
+    base = {
+        'type': 'multires',
+        'multiRes': {
+            'basePath': '',
+            'path': '{z}/{x}_{y}.webp',
+            'fallbackPath': '{z}/{x}_{y}.webp',
+            'extension': 'webp',
+            'tileResolution': tile_size,
+            'maxLevel': max_level,
+            'cubeResolution': levels[-1].get('width', 0),
+        },
+        'preview': manifest.get('preview', ''),
+    }
+    return base

media_engine/adapters/threejs/__init__.py

@@ -0,0 +1,2 @@
+from .manifest import to_threejs
+__all__ = ['to_threejs']

media_engine/adapters/threejs/manifest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+def to_threejs(manifest: dict) -> dict:
+    return {
+        'type': 'equirectangular-multires',
+        'preview': manifest.get('preview', ''),
+        'levels': manifest.get('levels', []),
+        'projection': manifest.get('projection', 'equirectangular'),
+    }

media_engine/admin.py

@@ -0,0 +1,36 @@
+from django.contrib import admin
+from .models import MediaAsset, MediaVariant, MediaBinding, PanoramaTile
+
+
+class MediaVariantInline(admin.TabularInline):
+    model = MediaVariant
+    extra = 0
+    readonly_fields = ('profile', 'width', 'height', 'format', 'file_size', 'quality', 'status', 'processor_version')
+
+
+@admin.register(MediaAsset)
+class MediaAssetAdmin(admin.ModelAdmin):
+    list_display = ('id', 'original_name', 'status', 'width', 'height', 'original_size', 'processor_version', 'created_at')
+    list_filter = ('status', 'processor_version', 'created_at')
+    search_fields = ('original_name', 'original_sha256', 'owner_ref')
+    readonly_fields = ('original_sha256', 'width', 'height', 'original_size', 'dominant_color', 'blurhash', 'placeholder_data_url')
+    inlines = [MediaVariantInline]
+
+
+@admin.register(MediaVariant)
+class MediaVariantAdmin(admin.ModelAdmin):
+    list_display = ('asset', 'profile', 'width', 'height', 'format', 'status', 'file_size', 'processor_version')
+    list_filter = ('profile', 'format', 'status', 'processor_version')
+
+
+@admin.register(MediaBinding)
+class MediaBindingAdmin(admin.ModelAdmin):
+    list_display = ('content_type', 'object_id', 'field_name', 'profile', 'role', 'asset')
+    list_filter = ('profile', 'role', 'content_type')
+
+
+@admin.register(PanoramaTile)
+class PanoramaTileAdmin(admin.ModelAdmin):
+    list_display = ('asset', 'profile', 'level', 'col', 'row', 'format', 'status', 'file_size')
+    list_filter = ('profile', 'format', 'status', 'level')
+    search_fields = ('asset__original_sha256', 'asset__original_name')

media_engine/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+
+class MediaEngineConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "media_engine"
+
+    def ready(self):
+        from . import signals  # noqa: F401
+        from .autoregister import configure_auto_integration
+        configure_auto_integration()

media_engine/auth.py

@@ -0,0 +1,33 @@
+import hmac
+from django.conf import settings
+from rest_framework.permissions import BasePermission
+
+
+def configured_api_keys():
+    value = getattr(settings, 'MEDIA_ENGINE_API_KEYS', '')
+    if isinstance(value, (tuple, list, set)):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return [item.strip() for item in str(value).split(',') if item.strip()]
+
+
+def extract_api_key(request):
+    auth = request.headers.get('Authorization', '').strip()
+    if auth.lower().startswith('bearer '):
+        return auth.split(' ', 1)[1].strip()
+    return request.headers.get('X-Media-Engine-Key', '').strip()
+
+
+def valid_api_key(value):
+    keys = configured_api_keys()
+    if not keys:
+        return False
+    return any(hmac.compare_digest(value or '', key) for key in keys)
+
+
+class MediaEngineApiKeyPermission(BasePermission):
+    message = 'A valid Media Optimization Engine API key is required.'
+
+    def has_permission(self, request, view):
+        if not getattr(settings, 'MEDIA_ENGINE_REQUIRE_API_KEY', False):
+            return True
+        return valid_api_key(extract_api_key(request))

media_engine/autoregister.py

@@ -0,0 +1,108 @@
+"""Portable automatic Django ImageField integration.
+
+The package never has to know the host project's models at build time.
+A project may explicitly list fields in ``MEDIA_ENGINE_AUTO_FIELDS`` or enable
+opt-in ImageField discovery. Registered fields are connected to the normal MOE
+post-save pipeline and therefore follow the host's task mode:
+
+* local DEBUG / task mode ``auto`` -> inline (eager)
+* production -> Celery
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+
+from django.apps import apps
+from django.conf import settings
+from django.db.models import ImageField
+
+from .registry import register_model_image
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_EXCLUDED_APPS = {
+    "admin",
+    "auth",
+    "contenttypes",
+    "sessions",
+    "messages",
+    "staticfiles",
+    "media_engine",
+}
+
+
+def _field_profile(field_name: str) -> tuple[str, str]:
+    name = field_name.lower()
+    if "360" in name or "panorama" in name:
+        return "panorama.multires", "panorama"
+    if any(token in name for token in ("avatar", "profile", "logo", "icon")):
+        return "avatar", "content"
+    if any(token in name for token in ("hero", "cover", "banner")):
+        return "hero", "hero"
+    return "default", "content"
+
+
+def _register_explicit_config() -> int:
+    configured = getattr(settings, "MEDIA_ENGINE_AUTO_FIELDS", {}) or {}
+    if not isinstance(configured, Mapping):
+        raise TypeError("MEDIA_ENGINE_AUTO_FIELDS must be a mapping")
+
+    count = 0
+    for model_label, fields in configured.items():
+        model = apps.get_model(model_label)
+        if model is None:
+            logger.warning("MOE auto integration: unknown model %s", model_label)
+            continue
+
+        if isinstance(fields, (list, tuple, set)):
+            fields = {name: {} for name in fields}
+        if not isinstance(fields, Mapping):
+            raise TypeError(f"MEDIA_ENGINE_AUTO_FIELDS[{model_label!r}] must be a mapping or list")
+
+        for field_name, options in fields.items():
+            options = options or {}
+            if not isinstance(options, Mapping):
+                raise TypeError(f"MOE options for {model_label}.{field_name} must be a mapping")
+            inferred_profile, inferred_role = _field_profile(field_name)
+            register_model_image(
+                model,
+                field_name,
+                profile=str(options.get("profile") or inferred_profile),
+                role=str(options.get("role") or inferred_role),
+            )
+            count += 1
+    return count
+
+
+def _register_discovered_fields() -> int:
+    if not getattr(settings, "MEDIA_ENGINE_AUTO_DISCOVER_IMAGE_FIELDS", False):
+        return 0
+
+    excluded = set(getattr(settings, "MEDIA_ENGINE_AUTO_DISCOVER_EXCLUDE_APPS", ()) or ())
+    excluded |= DEFAULT_EXCLUDED_APPS
+    count = 0
+
+    for model in apps.get_models():
+        if model._meta.app_label in excluded:
+            continue
+        for field in model._meta.get_fields():
+            if not isinstance(field, ImageField):
+                continue
+            profile, role = _field_profile(field.name)
+            register_model_image(model, field.name, profile=profile, role=role)
+            count += 1
+    return count
+
+
+def configure_auto_integration() -> dict[str, int]:
+    """Register configured host fields once during Django app startup."""
+    explicit = _register_explicit_config()
+    discovered = _register_discovered_fields()
+    if explicit or discovered:
+        logger.info(
+            "MOE automatic integration registered %s explicit and %s discovered ImageField(s)",
+            explicit,
+            discovered,
+        )
+    return {"explicit": explicit, "discovered": discovered}

media_engine/control_plane.py

@@ -0,0 +1,274 @@
+"""Optional external control-plane integration.
+
+Runtime image processing NEVER calls the control plane. This module is invoked only
+by an explicit management command or a background Celery sync task. The engine
+always uses local settings plus the last-known-good local snapshot.
+"""
+
+import json
+import os
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from django.conf import settings
+from django.core.cache import cache
+
+from .node import get_node_identity
+
+STATUS_CACHE_KEY = 'media-engine:control-plane:status'
+CIRCUIT_CACHE_KEY = 'media-engine:control-plane:circuit-open-until'
+CONFIG_CACHE_KEY = 'media-engine:control-plane:last-known-good'
+_ALLOWED_FORMATS = {'avif', 'webp', 'jpeg', 'jpg'}
+_ALLOWED_FITS = {'contain', 'cover'}
+
+
+def _config_dir() -> Path:
+    return Path(getattr(settings, 'MEDIA_ENGINE_CONFIG_DIR', '/var/lib/media-engine/config'))
+
+
+def _path(name: str) -> Path:
+    return _config_dir() / name
+
+
+def _safe_cache_get(key, default=None):
+    try:
+        return cache.get(key, default)
+    except Exception:
+        return default
+
+
+def _safe_cache_set(key, value, timeout=None):
+    try:
+        cache.set(key, value, timeout=timeout)
+    except Exception:
+        pass
+
+
+def _atomic_write_json(path: Path, payload: dict):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(prefix=f'.{path.name}.', dir=str(path.parent))
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as handle:
+            json.dump(payload, handle, ensure_ascii=False, indent=2, sort_keys=True)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, path)
+    finally:
+        if os.path.exists(tmp_name):
+            os.unlink(tmp_name)
+
+
+def _read_json(path: Path, default=None):
+    try:
+        with path.open('r', encoding='utf-8') as handle:
+            value = json.load(handle)
+            return value if isinstance(value, dict) else (default or {})
+    except (FileNotFoundError, OSError, ValueError, TypeError):
+        return default or {}
+
+
+def _validate_profile(name: str, value: dict) -> dict:
+    if not isinstance(name, str) or not name or not isinstance(value, dict):
+        raise ValueError('Invalid profile payload.')
+    result = {}
+    if 'widths' in value:
+        widths = sorted({int(w) for w in value['widths'] if 16 <= int(w) <= 8192})
+        if not widths:
+            raise ValueError(f'Profile {name}: widths cannot be empty.')
+        result['widths'] = widths
+    if 'formats' in value:
+        formats = [str(fmt).lower() for fmt in value['formats']]
+        if not formats or any(fmt not in _ALLOWED_FORMATS for fmt in formats):
+            raise ValueError(f'Profile {name}: invalid formats.')
+        result['formats'] = formats
+    if 'fallback_format' in value:
+        fallback = str(value['fallback_format']).lower()
+        if fallback not in _ALLOWED_FORMATS:
+            raise ValueError(f'Profile {name}: invalid fallback format.')
+        result['fallback_format'] = fallback
+    if 'fit' in value:
+        fit = str(value['fit']).lower()
+        if fit not in _ALLOWED_FITS:
+            raise ValueError(f'Profile {name}: invalid fit.')
+        result['fit'] = fit
+    if 'aspect_ratio' in value:
+        ratio = value['aspect_ratio']
+        if not isinstance(ratio, (list, tuple)) or len(ratio) != 2:
+            raise ValueError(f'Profile {name}: invalid aspect_ratio.')
+        result['aspect_ratio'] = [max(1, int(ratio[0])), max(1, int(ratio[1]))]
+    for mapping_name in ('quality', 'target_bytes'):
+        if mapping_name in value:
+            mapping = value[mapping_name]
+            if not isinstance(mapping, dict):
+                raise ValueError(f'Profile {name}: {mapping_name} must be an object.')
+            cleaned = {}
+            for key, item in mapping.items():
+                cleaned[str(key)] = int(item)
+            result[mapping_name] = cleaned
+    return result
+
+
+def validate_remote_config(payload: dict) -> dict:
+    if not isinstance(payload, dict):
+        raise ValueError('Control-plane payload must be an object.')
+    version = int(payload.get('version', 0))
+    if version < 1:
+        raise ValueError('Control-plane config version must be >= 1.')
+
+    result = {
+        'version': version,
+        'updated_at': payload.get('updated_at'),
+        'profiles': {},
+        'feature_flags': {},
+    }
+    profiles = payload.get('profiles', {})
+    if profiles:
+        if not isinstance(profiles, dict):
+            raise ValueError('profiles must be an object.')
+        result['profiles'] = {name: _validate_profile(name, value) for name, value in profiles.items()}
+
+    flags = payload.get('feature_flags', {})
+    if flags:
+        if not isinstance(flags, dict):
+            raise ValueError('feature_flags must be an object.')
+        allowed = {'auto_focal'}
+        result['feature_flags'] = {key: bool(value) for key, value in flags.items() if key in allowed}
+
+    # Security-critical settings such as storage credentials, API keys, DB/Redis,
+    # and hostnames are deliberately NOT accepted from the control plane.
+    return result
+
+
+def load_last_known_good() -> dict:
+    cached = _safe_cache_get(CONFIG_CACHE_KEY)
+    if isinstance(cached, dict):
+        return cached
+    value = _read_json(_path('current.json'), default={})
+    _safe_cache_set(CONFIG_CACHE_KEY, value, timeout=60)
+    return value
+
+
+def load_previous_config() -> dict:
+    return _read_json(_path('previous.json'), default={})
+
+
+def control_plane_status() -> dict:
+    cached = _safe_cache_get(STATUS_CACHE_KEY)
+    if isinstance(cached, dict):
+        return cached
+    return _read_json(_path('status.json'), default={'state': 'unknown'})
+
+
+def _set_status(payload: dict):
+    payload = dict(payload)
+    payload['node_id'] = get_node_identity().node_id
+    payload['recorded_at_epoch'] = int(time.time())
+    _safe_cache_set(STATUS_CACHE_KEY, payload, timeout=None)
+    try:
+        _atomic_write_json(_path('status.json'), payload)
+    except OSError:
+        pass
+
+
+def _circuit_open() -> bool:
+    until = _safe_cache_get(CIRCUIT_CACHE_KEY, 0) or 0
+    if not until:
+        status = _read_json(_path('status.json'), default={})
+        until = status.get('circuit_open_until_epoch', 0) or 0
+    return float(until) > time.time()
+
+
+def _open_circuit(error: str):
+    seconds = int(getattr(settings, 'MEDIA_ENGINE_CONTROL_PLANE_CIRCUIT_SECONDS', 300))
+    until = int(time.time()) + max(10, seconds)
+    _safe_cache_set(CIRCUIT_CACHE_KEY, until, timeout=seconds)
+    _set_status({
+        'state': 'degraded',
+        'last_error': error[:1000],
+        'circuit_open_until_epoch': until,
+        'last_known_good_version': load_last_known_good().get('version'),
+    })
+
+
+def sync_from_control_plane(force=False) -> dict:
+    if not getattr(settings, 'MEDIA_ENGINE_CONTROL_PLANE_ENABLED', False):
+        result = {'state': 'disabled', 'changed': False}
+        _set_status(result)
+        return result
+    if _circuit_open() and not force:
+        return {'state': 'circuit_open', 'changed': False, 'using_last_known_good': True}
+
+    base_url = getattr(settings, 'MEDIA_ENGINE_CONTROL_PLANE_URL', '').rstrip('/')
+    if not base_url:
+        result = {'state': 'disabled', 'changed': False, 'reason': 'missing_url'}
+        _set_status(result)
+        return result
+
+    identity = get_node_identity()
+    query = urllib.parse.urlencode({
+        'node_id': identity.node_id,
+        'project_slug': identity.project_slug,
+        'tenant_slug': identity.tenant_slug,
+        'deployment_id': identity.deployment_id,
+    })
+    url = f'{base_url}/api/v1/media-engine/config/?{query}'
+    headers = {
+        'Accept': 'application/json',
+        'User-Agent': f'MediaOptimizationEngine/{getattr(settings, "MEDIA_ENGINE_VERSION", "1.4.0")}',
+    }
+    token = getattr(settings, 'MEDIA_ENGINE_CONTROL_PLANE_TOKEN', '')
+    if token:
+        headers['Authorization'] = f'Bearer {token}'
+
+    request = urllib.request.Request(url, headers=headers, method='GET')
+    timeout = float(getattr(settings, 'MEDIA_ENGINE_CONTROL_PLANE_TIMEOUT_SECONDS', 3))
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if response.status != 200:
+                raise RuntimeError(f'HTTP {response.status}')
+            remote = json.loads(response.read().decode('utf-8'))
+        validated = validate_remote_config(remote)
+        current = load_last_known_good()
+        changed = current != validated
+        if changed:
+            if current:
+                _atomic_write_json(_path('previous.json'), current)
+            _atomic_write_json(_path('current.json'), validated)
+            _safe_cache_set(CONFIG_CACHE_KEY, validated, timeout=None)
+        result = {
+            'state': 'healthy',
+            'changed': changed,
+            'version': validated['version'],
+            'using_last_known_good': True,
+            'last_error': '',
+            'circuit_open_until_epoch': 0,
+        }
+        _safe_cache_set(CIRCUIT_CACHE_KEY, 0, timeout=1)
+        _set_status(result)
+        return result
+    except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError, ValueError, RuntimeError) as exc:
+        _open_circuit(str(exc))
+        return {
+            'state': 'degraded',
+            'changed': False,
+            'using_last_known_good': True,
+            'last_error': str(exc),
+            'last_known_good_version': load_last_known_good().get('version'),
+        }
+
+
+def rollback_to_previous() -> dict:
+    previous = load_previous_config()
+    if not previous:
+        raise RuntimeError('No previous control-plane configuration exists.')
+    current = load_last_known_good()
+    if current:
+        _atomic_write_json(_path('rollback-source.json'), current)
+    _atomic_write_json(_path('current.json'), previous)
+    _safe_cache_set(CONFIG_CACHE_KEY, previous, timeout=None)
+    _set_status({'state': 'rolled_back', 'version': previous.get('version'), 'changed': True})
+    return previous