morphosx 0.5.3

high-performance media processing engine for on-the-fly image transformations and storage.

morphosx 🧬

High performance, low footprint.
Self-hosted, open-source media engine for on-the-fly image processing and delivery.

morphosx is a high-speed, minimal cloud storage and media manipulation server. It converts almost any media type into an optimized, web-ready image derivative on-the-fly.

---

⚡ Core Features

• User-Bound Security: Protected assets and HMAC signatures tied to specific JWT-authenticated users.
• Private Folders: Secure per-user storage using the users/{user_id}/ path convention.
• Universal Rendering: Support for BIM (IFC), 3D (STL/OBJ/GLB), Office, Font Specimen, Archives, Video, Audio, and RAW.
• Modern Engines: Choice between Pillow and PyVips (ultra-fast).
• Cloud Ready: Pluggable storage system (Local & Amazon S3).
• Smart Caching: Automatic derivative caching for optimized delivery.

---

🚀 Installation & Deployment

1. Using Docker (Recommended)

The easiest way to run Morphosx with all features and system dependencies pre-installed.

docker run -p 6100:6100 --env-file .env ghcr.io/dcdavidev/morphosx:latest

2. Using pip (from PyPI)

You can install Morphosx as a library or a standalone CLI tool.

# Core installation (standard images only)
pip install morphosx

# Full installation (all media types support)
pip install "morphosx[full]"

# Selective installation
pip install "morphosx[video,pdf,3d]"

Note: Some extras require system libraries (e.g., ffmpeg for video, libvips for vips engine).

---

📖 Documentation

For detailed guides, check out the docs/ folder:

• Introduction: Overview, architecture, and quick start.
• Upload Guide: Managing public and private asset uploads.
• Processing & Presets: On-the-fly transformations and smart presets.
• Security & Signatures: HMAC validation and asset protection.
• Configuration: Environment variables and server settings.

---

🛠️ Usage Guide

1. Uploading Assets

Public Upload

curl -X POST "http://localhost:6100/v1/assets/upload?folder=news" -F "file=@img.jpg"

Private Upload

curl -X POST "http://localhost:6100/v1/assets/upload?private=true" \
     -H "Authorization: Bearer <TOKEN>" -F "file=@secret.pdf"

2. Retrieving & Processing

All GET requests must be signed using HMAC-SHA256.

GET /v1/assets/my-image.jpg?width=300&format=webp&signature=HASH

---

✨ Smart Presets

Use predefined aliases for cleaner URLs:

• preset=thumb: 150x150 WebP.
• preset=hero: 1920px WebP.
• preset=social: 1200x630 JPEG.
• preset=preview: 400px PNG.

---

🛡️ Advanced Security

Morphosx uses HMAC-SHA256 to prevent DoS attacks and unauthorized manipulation. The signature payload includes: asset_id | width | height | format | quality | preset | user_id.

---

🧪 Supported Media Table

Category	Extra	Extensions	Output Type
BIM	[bim]	ifc	Technical Project Card
3D	[3d]	stl, obj, glb, gltf	Technical Blueprint
Images	Core	jpg, png, webp	Processed Image
Modern Img	[modern]	heic, avif	Processed Image
RAW	[raw]	cr2, nef, dng, arw	Developed Image
Video	[video]	mp4, mov, webm, avi	Frame @ timestamp
Audio	[video]	mp3, wav, ogg, flac	Waveform Image
Docs	[pdf]	pdf	Page Render
Office	[office]	docx, pptx, xlsx	Summary Card
Text	Core	json, xml, md, txt	Syntax-highlighted
Typography	Core	ttf, otf	Font Specimen
Archives	Core	zip, tar	Content List

---

📜 License

MIT - Built for the Open Source community.