Metadata-Version: 2.4
Name: media-optimization-engine
Version: 1.4.1
Summary: Media Optimization Engineer for Django/Python: automatic model-field optimization, responsive picture/srcset rendering, AVIF/WebP derivatives, 360 media, autonomous nodes, and CDN-ready storage.
Author-email: Achille Kabasele <pepexykabasele@gmail.com>
Maintainer-email: Achille Kabasele <pepexykabasele@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Kabasele754/media-optimization-engine
Project-URL: Repository, https://github.com/Kabasele754/media-optimization-engine
Project-URL: Issues, https://github.com/Kabasele754/media-optimization-engine/issues
Project-URL: Documentation, https://github.com/Kabasele754/media-optimization-engine/tree/master/docs
Keywords: django,media,image-optimization,avif,webp,panorama,360,marzipano,cdn,cloudflare-r2
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django<6.1,>=4.2.30
Requires-Dist: djangorestframework<4,>=3.14
Requires-Dist: Pillow<13,>=10.3
Requires-Dist: pillow-avif-plugin<2,>=1.5
Requires-Dist: numpy<3,>=1.26
Requires-Dist: blurhash<2,>=1.1
Provides-Extra: celery
Requires-Dist: celery<6,>=5.4; extra == "celery"
Requires-Dist: redis<7,>=5; extra == "celery"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
Provides-Extra: s3
Requires-Dist: boto3<2,>=1.35; extra == "s3"
Requires-Dist: django-storages[s3]<2,>=1.14; extra == "s3"
Provides-Extra: r2
Requires-Dist: boto3<2,>=1.35; extra == "r2"
Requires-Dist: django-storages[s3]<2,>=1.14; extra == "r2"
Provides-Extra: observability
Requires-Dist: prometheus-client<1,>=0.21; extra == "observability"
Provides-Extra: all
Requires-Dist: celery<6,>=5.4; extra == "all"
Requires-Dist: redis<7,>=5; extra == "all"
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "all"
Requires-Dist: boto3<2,>=1.35; extra == "all"
Requires-Dist: django-storages[s3]<2,>=1.14; extra == "all"
Requires-Dist: prometheus-client<1,>=0.21; extra == "all"
Dynamic: license-file

# Media Optimization Engineer 1.4

Media Optimization Engineer (MOE) is a reusable Django/Python package for image optimization, responsive delivery, and 360-degree media processing.

The public package is intentionally application-agnostic. It does not depend on any consuming project's themes, tenants, brands, business models, or private infrastructure.

## Core capabilities

### Standard images

- automatic ImageField / FileField integration;
- immutable originals;
- AVIF, WebP and JPEG derivatives;
- responsive width sets;
- semantic profiles such as avatar, card, hero, and default;
- focal-point aware crops;
- dominant color, BlurHash and lightweight placeholders;
- SHA-256 deduplication;
- local, S3-compatible and Cloudflare R2 storage;
- Redis/Celery processing when enabled;
- CDN-ready derivative URLs;
- Django template tags for responsive rendering.

### 360 panoramas

- equirectangular panorama support;
- progressive preview;
- multiresolution pyramids;
- tiled AVIF/WebP delivery;
- generic manifests;
- Pannellum, Marzipano and Three.js adapters;
- optional cubemap generation.

## Install

~~~bash
pip install media-optimization-engine
~~~

Optional infrastructure extras:

~~~bash
pip install "media-optimization-engine[all]"
~~~

## Django setup

~~~python
# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "media_engine",
]

MEDIA_ENGINE_TASK_MODE = "auto"

MEDIA_ENGINE_AUTO_FIELDS = {
    "articles.Article": {
        "cover_image": {
            "profile": "hero",
            "role": "hero",
        },
    },
    "accounts.Profile": {
        "photo": {
            "profile": "avatar",
            "role": "content",
        },
    },
    "organizations.Organization": {
        "logo": {
            "profile": "default",
            "role": "content",
        },
    },
}
~~~

~~~python
# urls.py
from django.urls import include, path

urlpatterns = [
    path("api/v1/", include("media_engine.urls")),
]
~~~

Then:

~~~bash
python manage.py migrate
python manage.py media_engine_doctor
~~~

## Django template rendering

For normal model fields, use the high-level media_image tag:

~~~django
{% load responsive_media %}

{% media_image article "cover_image"
    alt=article.title
    css_class="article-hero"
    sizes="(max-width: 768px) 100vw, 1200px"
%}
~~~

MOE resolves the field's MediaBinding, generates a responsive picture with available AVIF/WebP sources, preserves the image's CSS classes, and falls back to the original field URL only when no processed binding is available.

### Logo or footer image

~~~django
{% load responsive_media %}

{% media_image organization "logo"
    alt=organization.name
    css_class="site-logo"
    sizes="240px"
%}
~~~

### Card grid

~~~django
{% load responsive_media %}

{% for article in articles %}
  <article class="article-card">
    {% media_image article "cover_image"
        alt=article.title
        css_class="article-card__image"
        sizes="(max-width: 640px) 92vw, (max-width: 1100px) 45vw, 360px"
    %}
    <h2>{{ article.title }}</h2>
  </article>
{% endfor %}
~~~

### Direct binding rendering

Advanced integrations can render a known asset directly:

~~~django
{% load responsive_media %}

{% responsive_image binding.asset
    profile=binding.profile
    role=binding.role
    alt=object.title
    css_class="media-object"
    picture_class="media-object-picture"
    sizes="100vw"
%}
~~~

### One optimized URL

For Open Graph metadata, CSS backgrounds, emails, or APIs where picture is not possible:

~~~django
{% load responsive_media %}

{% media_url organization "logo" preferred_width=512 preferred_format="webp" as optimized_logo %}

<meta property="og:image" content="{{ optimized_logo }}">
~~~

For normal page images, prefer media_image over media_url; the browser can make a better final choice from srcset and sizes.

## Responsive selection

MOE provides width descriptors and sizes. The browser chooses the final resource using layout width, viewport, DPR, supported formats, and its own network heuristics.

JavaScript is not required for normal responsive images.

Runtime measurement is appropriate only for highly dynamic components whose rendered width cannot be described reliably with sizes, such as resizable editors, canvas-like builders, or asynchronously mounted panels.

## Flutter / native clients

MOE also ships reference Dart adapters for native applications.

Standard Flutter clients should fetch the image manifest, measure the rendered widget width, multiply it by device pixel ratio, and select the first derivative at or above that physical width.

~~~dart
final variant = manifest.select(
  logicalWidth: constraints.maxWidth,
  devicePixelRatio: MediaQuery.devicePixelRatioOf(context),
  preferredFormat: 'webp',
);
~~~

Reference adapters are packaged under:

~~~text
media_engine/adapters/flutter/
~~~

This keeps optimization and derivative generation on the Django/Python backend while allowing Flutter to select and cache the most appropriate immutable URL. Panorama manifests use the same principle at tile/level granularity.

## Backfill

Historical media can be ingested with maintenance commands:

~~~bash
python manage.py backfill_registered_media
python manage.py audit_media_engine --fail-on-incomplete
~~~

New uploads registered in MEDIA_ENGINE_AUTO_FIELDS are handled automatically.

## Runtime independence

Embedded Django mode and standalone-node mode are autonomous. Optional control-plane synchronization must never be required for upload, processing, rendering, or derivative delivery.

## License

MIT License. Copyright (c) 2026 Achille Kabasele.
