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

media_engine/doctor.py

@@ -0,0 +1,177 @@
+"""Integration diagnostics for Media Optimization Engine.
+
+Can be used either as a Django management command or directly with:
+    python -m media_engine.doctor
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    level: str = "ERROR"
+
+
+def _yesno(value: bool) -> str:
+    return "OK" if value else "FAIL"
+
+
+def _package_checks() -> list[Check]:
+    checks: list[Check] = []
+    try:
+        import media_engine
+        checks.append(Check("package", True, f"media_engine {getattr(media_engine, '__version__', 'unknown')}"))
+    except Exception as exc:
+        return [Check("package", False, str(exc))]
+
+    for module, label in [
+        ("PIL", "Pillow"),
+        ("PIL.AvifImagePlugin", "AVIF plugin"),
+        ("rest_framework", "Django REST Framework"),
+    ]:
+        found = importlib.util.find_spec(module) is not None
+        checks.append(Check(label, found, "installed" if found else "missing"))
+    return checks
+
+
+def run_diagnostics() -> list[Check]:
+    checks = _package_checks()
+    try:
+        from django.conf import settings
+        from django.apps import apps
+        from django.core.cache import cache
+        from django.core.files.base import ContentFile
+        from django.core.files.storage import default_storage
+        from django.db import connection
+        from django.db.migrations.executor import MigrationExecutor
+    except Exception as exc:
+        checks.append(Check("django runtime", False, f"Django unavailable: {exc}"))
+        return checks
+
+    if not settings.configured:
+        checks.append(Check(
+            "django settings",
+            False,
+            "settings are not configured; set DJANGO_SETTINGS_MODULE or run through manage.py",
+        ))
+        return checks
+
+    installed = "media_engine" in settings.INSTALLED_APPS or any(
+        str(item).startswith("media_engine.") for item in settings.INSTALLED_APPS
+    )
+    checks.append(Check(
+        "INSTALLED_APPS",
+        installed,
+        "media_engine registered" if installed else 'add "media_engine" to INSTALLED_APPS',
+    ))
+    if not installed:
+        return checks
+
+    checks.append(Check("app registry", apps.is_installed("media_engine"), "Django app loaded"))
+
+    try:
+        with connection.cursor() as cursor:
+            cursor.execute("SELECT 1")
+            cursor.fetchone()
+        checks.append(Check("database", True, connection.vendor))
+    except Exception as exc:
+        checks.append(Check("database", False, str(exc)))
+
+    try:
+        executor = MigrationExecutor(connection)
+        targets = executor.loader.graph.leaf_nodes("media_engine")
+        plan = executor.migration_plan(targets)
+        pending = [f"{m.app_label}.{m.name}" for m, backwards in plan if not backwards and m.app_label == "media_engine"]
+        checks.append(Check(
+            "migrations",
+            not pending,
+            "all applied" if not pending else "pending: " + ", ".join(pending),
+        ))
+    except Exception as exc:
+        checks.append(Check("migrations", False, str(exc)))
+
+    try:
+        key = "media_engine:doctor"
+        cache.set(key, "ok", timeout=10)
+        value = cache.get(key)
+        checks.append(Check("cache", value == "ok", settings.CACHES.get("default", {}).get("BACKEND", "unknown")))
+        cache.delete(key)
+    except Exception as exc:
+        checks.append(Check("cache", False, str(exc), level="WARN"))
+
+    try:
+        test_name = "media_engine/doctor/.write-test"
+        saved = default_storage.save(test_name, ContentFile(b"media-engine-doctor"))
+        exists = default_storage.exists(saved)
+        if exists:
+            default_storage.delete(saved)
+        checks.append(Check("storage", exists, f"writable via {default_storage.__class__.__name__}"))
+    except Exception as exc:
+        checks.append(Check("storage", False, str(exc)))
+
+    from .queueing import resolved_task_mode
+    configured_mode = getattr(settings, "MEDIA_ENGINE_TASK_MODE", "auto")
+    effective_mode = resolved_task_mode()
+    checks.append(Check("task mode", True, f"configured={configured_mode}; effective={effective_mode}"))
+
+    auto_fields = getattr(settings, "MEDIA_ENGINE_AUTO_FIELDS", {}) or {}
+    auto_discover = bool(getattr(settings, "MEDIA_ENGINE_AUTO_DISCOVER_IMAGE_FIELDS", False))
+    checks.append(Check("auto integration", True, f"configured_models={len(auto_fields)}; discover={auto_discover}"))
+
+    try:
+        from .processors.panorama.equirectangular import Panorama360Processor
+        checks.append(Check("panorama processor", True, Panorama360Processor.__name__))
+    except Exception as exc:
+        checks.append(Check("panorama processor", False, str(exc)))
+
+    try:
+        from PIL import features
+        checks.append(Check("WebP codec", bool(features.check("webp")), "Pillow WebP support"))
+    except Exception as exc:
+        checks.append(Check("WebP codec", False, str(exc), level="WARN"))
+
+    return checks
+
+
+def format_report(checks: Iterable[Check]) -> str:
+    rows = ["Media Optimization Engine doctor", "=" * 32]
+    failures = 0
+    warnings = 0
+    for c in checks:
+        status = _yesno(c.ok)
+        if not c.ok and c.level == "WARN":
+            status = "WARN"
+            warnings += 1
+        elif not c.ok:
+            failures += 1
+        rows.append(f"[{status:4}] {c.name}: {c.detail}")
+    rows.append("-" * 32)
+    rows.append(f"Result: {failures} error(s), {warnings} warning(s)")
+    return "\n".join(rows)
+
+
+def main() -> int:
+    settings_module = os.getenv("DJANGO_SETTINGS_MODULE")
+    if settings_module:
+        try:
+            import django
+            django.setup()
+        except Exception as exc:
+            print(f"Unable to initialize Django: {exc}", file=sys.stderr)
+            return 2
+    checks = run_diagnostics()
+    print(format_report(checks))
+    return 0 if all(c.ok or c.level == "WARN" for c in checks) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

media_engine/focal_detectors.py

@@ -0,0 +1,28 @@
+def detect_focal_point(image):
+    """Optional face-aware focal detector.
+
+    Install requirements-ai.txt to enable OpenCV face detection. If OpenCV is
+    not installed or no face is found, return (None, None) and the normal
+    center crop remains in effect.
+    """
+    try:
+        import cv2
+        import numpy as np
+    except Exception:
+        return None, None
+
+    rgb = image.convert('RGB')
+    arr = np.asarray(rgb)
+    gray = cv2.cvtColor(arr, cv2.COLOR_RGB2GRAY)
+    cascade = cv2.CascadeClassifier(
+        cv2.data.haarcascades + 'haarcascade_frontalface_default.xml'
+    )
+    faces = cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(32, 32))
+    if len(faces) == 0:
+        return None, None
+
+    x1 = min(int(x) for x, y, w, h in faces)
+    y1 = min(int(y) for x, y, w, h in faces)
+    x2 = max(int(x + w) for x, y, w, h in faces)
+    y2 = max(int(y + h) for x, y, w, h in faces)
+    return ((x1 + x2) / 2 / image.width, (y1 + y2) / 2 / image.height)

media_engine/health.py

@@ -0,0 +1,78 @@
+import time
+from django.conf import settings
+from django.core.cache import cache
+from django.core.files.base import ContentFile
+from django.core.files.storage import default_storage
+from django.db import connection
+from .control_plane import control_plane_status
+from .node import get_node_identity
+
+HEARTBEAT_KEY = 'media-engine:worker-heartbeat'
+
+
+def _check_database():
+    try:
+        with connection.cursor() as cursor:
+            cursor.execute('SELECT 1')
+            cursor.fetchone()
+        return {'state': 'healthy'}
+    except Exception as exc:
+        return {'state': 'unhealthy', 'error': str(exc)[:300]}
+
+
+def _check_cache():
+    try:
+        key = 'media-engine:health:cache'
+        cache.set(key, 'ok', timeout=10)
+        ok = cache.get(key) == 'ok'
+        return {'state': 'healthy' if ok else 'unhealthy'}
+    except Exception as exc:
+        return {'state': 'unhealthy', 'error': str(exc)[:300]}
+
+
+def _check_storage():
+    identity = get_node_identity()
+    name = f'media_engine/health/{identity.node_id}.txt'
+    try:
+        stored = default_storage.save(name, ContentFile(b'ok'))
+        ok = default_storage.exists(stored)
+        default_storage.delete(stored)
+        return {'state': 'healthy' if ok else 'unhealthy'}
+    except Exception as exc:
+        return {'state': 'unhealthy', 'error': str(exc)[:300]}
+
+
+def _check_worker():
+    try:
+        stamp = cache.get(HEARTBEAT_KEY)
+        if not stamp:
+            return {'state': 'degraded', 'reason': 'no_heartbeat'}
+        age = max(0, int(time.time() - float(stamp)))
+        max_age = int(getattr(settings, 'MEDIA_ENGINE_WORKER_HEARTBEAT_MAX_AGE', 120))
+        return {
+            'state': 'healthy' if age <= max_age else 'degraded',
+            'age_seconds': age,
+        }
+    except Exception as exc:
+        return {'state': 'degraded', 'error': str(exc)[:300]}
+
+
+def build_health_report(*, deep=False):
+    db = _check_database()
+    cache_status = _check_cache()
+    storage = _check_storage() if deep else {'state': 'healthy', 'check': 'shallow', 'backend': default_storage.__class__.__name__}
+    worker = _check_worker()
+    control = control_plane_status()
+    core_healthy = all(part.get('state') == 'healthy' for part in (db, cache_status, storage))
+    state = 'healthy' if core_healthy and worker.get('state') == 'healthy' else ('degraded' if core_healthy else 'unhealthy')
+    return {
+        'state': state,
+        'node': get_node_identity().as_dict(),
+        'database': db,
+        'cache': cache_status,
+        'storage': storage,
+        'worker': worker,
+        'control_plane': control,
+        'control_plane_required_for_runtime': False,
+        'deep_storage_check': bool(deep),
+    }

media_engine/image_ops.py

@@ -0,0 +1,142 @@
+import base64
+import io
+from dataclasses import dataclass
+from PIL import Image, ImageOps
+import numpy as np
+from blurhash import encode as blurhash_encode
+try:
+    import pillow_avif  # noqa: F401
+except Exception:
+    pillow_avif = None
+
+
+@dataclass
+class EncodedImage:
+    content: bytes
+    width: int
+    height: int
+    quality: int
+
+
+def normalized_image(source):
+    image = Image.open(source)
+    image.load()
+    image = ImageOps.exif_transpose(image)
+    if image.mode not in ('RGB', 'RGBA'):
+        image = image.convert('RGBA' if 'A' in image.getbands() else 'RGB')
+    return image
+
+
+def dominant_color(image):
+    thumb = image.convert('RGB').resize((1, 1), Image.Resampling.LANCZOS)
+    r, g, b = thumb.getpixel((0, 0))
+    return f'#{r:02x}{g:02x}{b:02x}'
+
+
+def make_blurhash(image):
+    small = image.convert('RGB').resize((32, 32), Image.Resampling.LANCZOS)
+    pixels = np.asarray(small)
+    return blurhash_encode(pixels, components_x=4, components_y=3)
+
+
+def placeholder_data_url(image):
+    small = image.convert('RGB')
+    small.thumbnail((32, 32), Image.Resampling.LANCZOS)
+    out = io.BytesIO()
+    small.save(out, format='WEBP', quality=25, method=4)
+    payload = base64.b64encode(out.getvalue()).decode('ascii')
+    return f'data:image/webp;base64,{payload}'
+
+
+def crop_to_ratio(image, ratio, focal_x=None, focal_y=None):
+    target_ratio = ratio[0] / ratio[1]
+    current_ratio = image.width / image.height
+    if abs(target_ratio - current_ratio) < 0.001:
+        return image
+
+    fx = 0.5 if focal_x is None else min(1.0, max(0.0, focal_x))
+    fy = 0.5 if focal_y is None else min(1.0, max(0.0, focal_y))
+
+    if current_ratio > target_ratio:
+        new_width = int(image.height * target_ratio)
+        max_left = image.width - new_width
+        left = int(max_left * fx)
+        left = min(max(0, left), max_left)
+        box = (left, 0, left + new_width, image.height)
+    else:
+        new_height = int(image.width / target_ratio)
+        max_top = image.height - new_height
+        top = int(max_top * fy)
+        top = min(max(0, top), max_top)
+        box = (0, top, image.width, top + new_height)
+    return image.crop(box)
+
+
+def resized(image, width, fit='contain', aspect_ratio=None, focal_x=None, focal_y=None):
+    working = image
+    if fit == 'cover' and aspect_ratio:
+        working = crop_to_ratio(working, aspect_ratio, focal_x=focal_x, focal_y=focal_y)
+    width = min(width, working.width)
+    if width == working.width:
+        return working.copy()
+    height = round(working.height * width / working.width)
+    return working.resize((width, height), Image.Resampling.LANCZOS)
+
+
+def _save_kwargs(fmt, quality):
+    fmt = fmt.lower()
+    if fmt == 'avif':
+        return {'format': 'AVIF', 'quality': quality, 'speed': 6}
+    if fmt == 'webp':
+        return {'format': 'WEBP', 'quality': quality, 'method': 6}
+    if fmt in ('jpg', 'jpeg'):
+        return {'format': 'JPEG', 'quality': quality, 'optimize': True, 'progressive': True}
+    if fmt == 'png':
+        return {'format': 'PNG', 'optimize': True}
+    raise ValueError(f'Unsupported output format: {fmt}')
+
+
+def _prepare_for_format(image, fmt):
+    if fmt.lower() in ('jpeg', 'jpg') and image.mode == 'RGBA':
+        canvas = Image.new('RGB', image.size, 'white')
+        canvas.paste(image, mask=image.getchannel('A'))
+        return canvas
+    if fmt.lower() in ('jpeg', 'jpg') and image.mode != 'RGB':
+        return image.convert('RGB')
+    return image
+
+
+def encode_with_budget(image, fmt, initial_quality, target_bytes=None, min_quality=35):
+    image = _prepare_for_format(image, fmt)
+
+    def encode(q):
+        out = io.BytesIO()
+        image.save(out, **_save_kwargs(fmt, q))
+        return out.getvalue()
+
+    quality = int(initial_quality)
+    content = encode(quality)
+    if not target_bytes or len(content) <= target_bytes or fmt.lower() == 'png':
+        return EncodedImage(content, image.width, image.height, quality)
+
+    low, high = min_quality, quality
+    best = None
+    best_q = min_quality
+    smallest = content
+    smallest_q = quality
+    while low <= high:
+        mid = (low + high) // 2
+        candidate = encode(mid)
+        if len(candidate) < len(smallest):
+            smallest = candidate
+            smallest_q = mid
+        if len(candidate) <= target_bytes:
+            best = candidate
+            best_q = mid
+            low = mid + 1
+        else:
+            high = mid - 1
+    if best is None:
+        best = smallest
+        best_q = smallest_q
+    return EncodedImage(best, image.width, image.height, best_q)

media_engine/integration.py

@@ -0,0 +1,34 @@
+from django.contrib.contenttypes.models import ContentType
+from django.db import transaction
+from django.core.files.base import File
+from .models import MediaBinding
+from .services import ingest_uploaded_file
+
+
+def ingest_model_field(instance, *, field_name, profile='default', role='content'):
+    field_file = getattr(instance, field_name, None)
+    if not field_file or not getattr(field_file, 'name', None):
+        return None
+    with field_file.storage.open(field_file.name, 'rb') as source:
+        wrapped = File(source, name=field_file.name.rsplit('/', 1)[-1])
+        asset, created = ingest_uploaded_file(
+            wrapped,
+            owner_ref=f'{instance._meta.label}:{instance.pk}:{field_name}',
+            profile=profile,
+            enqueue=False,
+        )
+    ct = ContentType.objects.get_for_model(instance, for_concrete_model=False)
+    previous = MediaBinding.objects.filter(
+        content_type=ct, object_id=str(instance.pk), field_name=field_name
+    ).select_related('asset').first()
+    unchanged = previous is not None and previous.asset_id == asset.id and previous.profile == profile
+    binding, _ = MediaBinding.objects.update_or_create(
+        content_type=ct,
+        object_id=str(instance.pk),
+        field_name=field_name,
+        defaults={'profile': profile, 'role': role, 'asset': asset},
+    )
+    if created or not unchanged:
+        from .queueing import enqueue_asset
+        transaction.on_commit(lambda: enqueue_asset(asset.id, profile=profile))
+    return binding

media_engine/locks.py

@@ -0,0 +1,20 @@
+import time
+from contextlib import contextmanager
+from django.core.cache import cache
+
+
+@contextmanager
+def cache_lock(key, timeout=120, wait_timeout=8):
+    token = f'lock:{key}'
+    acquired = False
+    deadline = time.monotonic() + wait_timeout
+    while time.monotonic() < deadline:
+        if cache.add(token, '1', timeout=timeout):
+            acquired = True
+            break
+        time.sleep(0.1)
+    try:
+        yield acquired
+    finally:
+        if acquired:
+            cache.delete(token)

media_engine/management/commands/audit_media_engine.py

@@ -0,0 +1,54 @@
+from django.conf import settings
+from django.core.management.base import BaseCommand
+from django.db.models import Sum
+from media_engine.models import MediaAsset, MediaVariant
+from media_engine.profiles import get_profile, requested_widths, all_formats
+
+
+class Command(BaseCommand):
+    help = 'Audit media assets and responsive variants.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--profile', default='default')
+        parser.add_argument('--fail-on-incomplete', action='store_true')
+
+    def handle(self, *args, **options):
+        profile_name = options['profile']
+        profile = get_profile(profile_name)
+        version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+        total = MediaAsset.objects.count()
+        ready_assets = 0
+        incomplete = 0
+        expected_total = 0
+        for asset in MediaAsset.objects.all().iterator():
+            expected = len(requested_widths(profile, asset.width)) * len(all_formats(profile))
+            expected_total += expected
+            ready = MediaVariant.objects.filter(
+                asset=asset,
+                profile=profile_name,
+                processor_version=version,
+                status=MediaVariant.Status.READY,
+            ).count()
+            if ready >= expected:
+                ready_assets += 1
+            else:
+                incomplete += 1
+
+        original_bytes = MediaAsset.objects.aggregate(v=Sum('original_size'))['v'] or 0
+        derivative_bytes = MediaVariant.objects.filter(status=MediaVariant.Status.READY).aggregate(v=Sum('file_size'))['v'] or 0
+        avif = MediaVariant.objects.filter(format='avif', status=MediaVariant.Status.READY).count()
+        webp = MediaVariant.objects.filter(format='webp', status=MediaVariant.Status.READY).count()
+        failed = MediaVariant.objects.filter(status=MediaVariant.Status.FAILED).count()
+
+        self.stdout.write(f'Pipeline version: {version}')
+        self.stdout.write(f'Original images: {total}')
+        self.stdout.write(f'Ready responsive images: {ready_assets}')
+        self.stdout.write(f'Missing/incomplete: {incomplete}')
+        self.stdout.write(f'Expected variants: {expected_total}')
+        self.stdout.write(f'AVIF variants: {avif}')
+        self.stdout.write(f'WebP variants: {webp}')
+        self.stdout.write(f'Failed variants: {failed}')
+        self.stdout.write(f'Original storage: {original_bytes / (1024 * 1024):.2f} MB')
+        self.stdout.write(f'Responsive derivatives: {derivative_bytes / (1024 * 1024):.2f} MB')
+        if options['fail_on_incomplete'] and incomplete:
+            raise SystemExit(2)

media_engine/management/commands/audit_panorama_media.py

@@ -0,0 +1,20 @@
+from django.core.management.base import BaseCommand
+from media_engine.models import MediaAsset, PanoramaTile
+
+
+class Command(BaseCommand):
+    help = 'Audit 360 panorama assets and multiresolution tile completeness.'
+
+    def handle(self, *args, **options):
+        assets = MediaAsset.objects.filter(media_kind='panorama')
+        total = assets.count()
+        ready = assets.filter(status='READY').count()
+        failed = assets.filter(status='FAILED').count()
+        tiles = PanoramaTile.objects.count()
+        ready_tiles = PanoramaTile.objects.filter(status='READY').count()
+        bytes_total = sum(PanoramaTile.objects.filter(status='READY').values_list('file_size', flat=True))
+        self.stdout.write(f'Panorama assets: {total}')
+        self.stdout.write(f'Ready panoramas: {ready}')
+        self.stdout.write(f'Failed panoramas: {failed}')
+        self.stdout.write(f'Tiles: {ready_tiles}/{tiles}')
+        self.stdout.write(f'Tile storage: {bytes_total / (1024 * 1024):.2f} MB')

media_engine/management/commands/backfill_panorama_media.py

@@ -0,0 +1,32 @@
+from django.core.management.base import BaseCommand
+from media_engine.models import MediaAsset
+from media_engine.queueing import enqueue_asset
+from media_engine.processors.panorama.detect import detect_equirectangular
+
+
+class Command(BaseCommand):
+    help = 'Detect existing 2:1 equirectangular assets and queue panorama multires processing.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--dry-run', action='store_true')
+        parser.add_argument('--limit', type=int, default=0)
+
+    def handle(self, *args, **options):
+        changed = 0
+        candidates = MediaAsset.objects.exclude(media_kind='panorama').order_by('created_at')
+        if options['limit']:
+            candidates = candidates[:options['limit']]
+        for asset in candidates:
+            detection = detect_equirectangular(asset.width, asset.height, asset.metadata_json)
+            if not detection.is_panorama:
+                continue
+            self.stdout.write(f'{asset.id} {asset.width}x{asset.height}: {detection.reason}')
+            if options['dry_run']:
+                continue
+            asset.media_kind = 'panorama'
+            asset.projection = detection.projection
+            asset.processor = 'panorama_360'
+            asset.save(update_fields=['media_kind', 'projection', 'processor', 'updated_at'])
+            enqueue_asset(asset.id, profile='panorama.multires', force=False)
+            changed += 1
+        self.stdout.write(self.style.SUCCESS(f'Queued panorama assets: {changed}'))

media_engine/management/commands/backfill_registered_media.py

@@ -0,0 +1,21 @@
+from django.core.management.base import BaseCommand
+from media_engine.integration import ingest_model_field
+from media_engine.registry import entries
+
+
+class Command(BaseCommand):
+    help = 'Ingest image fields declared through register_model_image().' 
+
+    def add_arguments(self, parser):
+        parser.add_argument('--limit', type=int)
+
+    def handle(self, *args, **options):
+        processed = 0
+        for entry in entries():
+            qs = entry.model._default_manager.all()
+            if options['limit']:
+                qs = qs[:options['limit']]
+            for obj in qs.iterator():
+                ingest_model_field(obj, field_name=entry.field_name, profile=entry.profile, role=entry.role)
+                processed += 1
+        self.stdout.write(self.style.SUCCESS(f'Processed {processed} registered model images.'))

media_engine/management/commands/backfill_responsive_images.py

@@ -0,0 +1,27 @@
+from django.core.management.base import BaseCommand
+from media_engine.models import MediaAsset
+from media_engine.tasks import generate_asset_variants
+from media_engine.queueing import enqueue_asset
+
+
+class Command(BaseCommand):
+    help = 'Generate missing responsive variants for existing MediaAsset rows.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--profile', default='default')
+        parser.add_argument('--force', action='store_true')
+        parser.add_argument('--sync', action='store_true')
+        parser.add_argument('--limit', type=int)
+
+    def handle(self, *args, **options):
+        qs = MediaAsset.objects.order_by('created_at')
+        if options['limit']:
+            qs = qs[:options['limit']]
+        count = 0
+        for asset in qs.iterator():
+            if options['sync']:
+                generate_asset_variants.apply(args=[str(asset.id), options['profile'], options['force']]).get()
+            else:
+                enqueue_asset(asset.id, profile=options['profile'], force=options['force'], backfill=True)
+            count += 1
+        self.stdout.write(self.style.SUCCESS(f'Queued {count} assets.'))

media_engine/management/commands/cleanup_image_derivatives.py

@@ -0,0 +1,30 @@
+from datetime import timedelta
+from django.conf import settings
+from django.core.files.storage import default_storage
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+from media_engine.models import MediaVariant
+
+
+class Command(BaseCommand):
+    help = 'Delete old derivative versions after a retention period.'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--days', type=int, default=30)
+        parser.add_argument('--confirm', action='store_true')
+
+    def handle(self, *args, **options):
+        version = getattr(settings, 'MEDIA_ENGINE_PIPELINE_VERSION', 1)
+        threshold = timezone.now() - timedelta(days=options['days'])
+        qs = MediaVariant.objects.filter(processor_version__lt=version, updated_at__lt=threshold)
+        self.stdout.write(f'Candidates: {qs.count()}')
+        if not options['confirm']:
+            self.stdout.write('Dry run. Re-run with --confirm to delete.')
+            return
+        removed = 0
+        for variant in qs.iterator():
+            if variant.file and default_storage.exists(variant.file.name):
+                default_storage.delete(variant.file.name)
+            variant.delete()
+            removed += 1
+        self.stdout.write(self.style.SUCCESS(f'Deleted {removed} old variants.'))