From 9cead74fb34a66962bb7c81726152087cd1c2630 Mon Sep 17 00:00:00 2001 From: buenosairesam Date: Thu, 12 Feb 2026 19:46:12 -0300 Subject: [PATCH] updated docs --- .../04-media-storage.md} | 0 docs/architecture/index.html | 211 ++++++++++------ docs/index.html | 232 ++++++++++++++++++ docs/media-storage.html | 125 ++++++++++ 4 files changed, 491 insertions(+), 77 deletions(-) rename docs/{media-storage.md => architecture/04-media-storage.md} (100%) create mode 100644 docs/index.html create mode 100644 docs/media-storage.html diff --git a/docs/media-storage.md b/docs/architecture/04-media-storage.md similarity index 100% rename from docs/media-storage.md rename to docs/architecture/04-media-storage.md diff --git a/docs/architecture/index.html b/docs/architecture/index.html index 5ed7e13..b913f2d 100644 --- a/docs/architecture/index.html +++ b/docs/architecture/index.html @@ -1,87 +1,144 @@ - + - - - - MPR - Architecture - - - -

MPR - Media Processor

-

A web-based media transcoding tool with professional architecture.

+ + + + MPR - Architecture + + + +

MPR - Media Processor

+

+ A web-based media transcoding tool with professional architecture. +

- + -

System Overview

-
-
-

Architecture

- - System Overview - - Open full size +

System Overview

+
+
+

Architecture

+ + System Overview + + Open full size +
-
-
-

Components

-
    -
  • Reverse Proxy (nginx)
    • -
  • Application Layer (Django, FastAPI, UI)
    • -
  • Worker Layer (Celery, Lambda)
    • -
  • Data Layer (PostgreSQL, Redis, SQS)
    • -
  • Storage (Local FS, S3)
    • -
-
- -

Data Model

-
-
-

Entity Relationships

- - Data Model - - Open full size +
+

Components

+
    +
  • + + Reverse Proxy (nginx) +
    • +
  • + + Application Layer (Django, FastAPI, UI) +
    • +
  • + + Worker Layer (Celery, Lambda) +
    • +
  • + + Data Layer (PostgreSQL, Redis, SQS) +
    • +
  • + + Storage (Local FS, S3) +
    • +
-
-
-

Entities

-
    -
  • MediaAsset - Video/audio files with metadata
    • -
  • TranscodePreset - Encoding configurations
    • -
  • TranscodeJob - Processing queue items
    • -
-
- -

Job Flow

-
-
-

Job Lifecycle

- - Job Flow - - Open full size +

Data Model

+
+
+

Entity Relationships

+ + Data Model + + Open full size +
-
-
-

Job States

-
    -
  • PENDING - Waiting in queue
    • -
  • PROCESSING - Worker executing
    • -
  • COMPLETED - Success
    • -
  • FAILED - Error occurred
    • -
  • CANCELLED - User cancelled
    • -
-
+
+

Entities

+
    +
  • + + MediaAsset - Video/audio files with metadata +
    • +
  • + + TranscodePreset - Encoding configurations +
    • +
  • + + TranscodeJob - Processing queue items +
    • +
+
-

Quick Reference

- 
# Generate SVGs from DOT files
+        
Job Flow

+        

+            

+                
Job Lifecycle

+                
+                    Job Flow
+                
+                Open full size
+            

+        

+
+        

+            
Job States

+            
    
+                
  • 
+                    
+                    PENDING - Waiting in queue
+                
    • 
+                
  • 
+                    
+                    PROCESSING - Worker executing
+                
    • 
+                
  • 
+                    
+                    COMPLETED - Success
+                
    • 
+                
  • 
+                    
+                    FAILED - Error occurred
+                
    • 
+                
  • 
+                    
+                    CANCELLED - User cancelled
+                
    • 
+            

+        

+
+        
Media Storage

+        

+            

+                MPR separates media into input and output paths for flexible
+                storage configuration.
+            

+            

+                View Media Storage Documentation →
+            

+        

+
+        
Quick Reference

+        
# Generate SVGs from DOT files
 dot -Tsvg 01-system-overview.dot -o 01-system-overview.svg
 dot -Tsvg 02-data-model.dot -o 02-data-model.svg
 dot -Tsvg 03-job-flow.dot -o 03-job-flow.svg
@@ -89,13 +146,13 @@ dot -Tsvg 03-job-flow.dot -o 03-job-flow.svg
 # Or generate all at once
 for f in *.dot; do dot -Tsvg "$f" -o "${f%.dot}.svg"; done

 
-    
Access Points

-    
# Add to /etc/hosts
+        
Access Points

+        
# Add to /etc/hosts
 127.0.0.1 mpr.local.ar
 
 # URLs
 http://mpr.local.ar/admin  - Django Admin
 http://mpr.local.ar/api    - FastAPI (docs at /api/docs)
 http://mpr.local.ar/ui     - Timeline UI

-
+    
 
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..b4450b7
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,232 @@
+
+
+    
+        
+        
+        MPR - Architecture
+        
+    
+    
+        
MPR - Media Processor

+        

+            A web-based media transcoding tool with professional architecture.
+        

+
+        
+
+        
System Overview

+        

+            

+                
Architecture

+                
+                    System Overview
+                
+                Open full size
+            

+        

+
+        

+            
Components

+            
    
+                
  • 
+                    
+                    Reverse Proxy (nginx)
+                
    • 
+                
  • 
+                    
+                    Application Layer (Django, FastAPI, UI)
+                
    • 
+                
  • 
+                    
+                    Worker Layer (Celery, Lambda)
+                
    • 
+                
  • 
+                    
+                    Data Layer (PostgreSQL, Redis, SQS)
+                
    • 
+                
  • 
+                    
+                    Storage (Local FS, S3)
+                
    • 
+            

+        

+
+        
Data Model

+        

+            

+                
Entity Relationships

+                
+                    Data Model
+                
+                Open full size
+            

+        

+
+        

+            
Entities

+            
    
+                
  • 
+                    
+                    MediaAsset - Video/audio files with metadata
+                
    • 
+                
  • 
+                    
+                    TranscodePreset - Encoding configurations
+                
    • 
+                
  • 
+                    
+                    TranscodeJob - Processing queue items
+                
    • 
+            

+        

+
+        
Job Flow

+        

+            

+                
Job Lifecycle

+                
+                    Job Flow
+                
+                Open full size
+            

+        

+
+        

+            
Job States

+            
    
+                
  • 
+                    
+                    PENDING - Waiting in queue
+                
    • 
+                
  • 
+                    
+                    PROCESSING - Worker executing
+                
    • 
+                
  • 
+                    
+                    COMPLETED - Success
+                
    • 
+                
  • 
+                    
+                    FAILED - Error occurred
+                
    • 
+                
  • 
+                    
+                    CANCELLED - User cancelled
+                
    • 
+            

+        

+
+        
Media Storage

+        

+            

+                MPR separates media into input and
+                output paths, each independently configurable.
+                File paths are stored
+                relative to their respective root to ensure
+                portability between local development and cloud deployments (AWS
+                S3, etc.).
+            

+        

+
+        

+            
Input / Output Separation

+            
    
+                
  • 
+                    
+                    MEDIA_IN - Source media files to process
+                
    • 
+                
  • 
+                    
+                    MEDIA_OUT - Transcoded/trimmed output files
+                
    • 
+            

+            
Why Relative Paths?

+            
    
+                
  • Portability: Same database works locally and in cloud
    • 
+                
  • Flexibility: Easy to switch between storage backends
    • 
+                
  • Simplicity: No need to update paths when migrating
    • 
+            

+        

+
+        

+            
Local Development

+            
MEDIA_IN=/app/media/in
+MEDIA_OUT=/app/media/out
+
+/app/media/
+├── in/                    # Source files
+│   ├── video1.mp4
+│   └── subfolder/video3.mp4
+└── out/                   # Transcoded output
+    └── video1_h264.mp4

+        

+
+        

+            
AWS/Cloud Deployment

+            
MEDIA_IN=s3://source-bucket/media/
+MEDIA_OUT=s3://output-bucket/transcoded/
+MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/

+            

+                Database paths remain unchanged (already relative). Just upload
+                files to S3 and update environment variables.
+            

+        

+
+        

+            
API Endpoints

+            
    
+                
  • 
+                    POST /api/assets/scan - Recursively scans
+                    MEDIA_IN and registers video/audio files
+                
    • 
+                
  • 
+                    POST /api/jobs/ - Creates transcoding job with
+                    source asset, preset, and optional trim times
+                
    • 
+            

+            
Supported File Types:

+            

+                Video: mp4, mkv, avi, mov, webm, flv, wmv, m4v

+                Audio: mp3, wav, flac, aac, ogg, m4a
+            

+        

+
+        
Quick Reference

+
+        
Access Points

+        
# Add to /etc/hosts
+127.0.0.1 mpr.local.ar
+
+# URLs
+http://mpr.local.ar/admin  - Django Admin
+http://mpr.local.ar/api    - FastAPI (docs at /api/docs)
+http://mpr.local.ar/ui     - Timeline UI

+    
+
diff --git a/docs/media-storage.html b/docs/media-storage.html
new file mode 100644
index 0000000..4d30a51
--- /dev/null
+++ b/docs/media-storage.html
@@ -0,0 +1,125 @@
+
Media Storage Architecture

+
Overview

+
MPR separates media into input and output paths, each independently configurable. File paths are stored relative to their respective root to ensure portability between local development and cloud deployments (AWS S3, etc.).

+
Storage Strategy

+
Input / Output Separation

+
| Path | Env Var | Purpose |
+|------|---------|---------|
+| MEDIA_IN | /app/media/in | Source media files to process |
+| MEDIA_OUT | /app/media/out | Transcoded/trimmed output files |

+
These can point to different locations or even different servers/buckets in production.

+
File Path Storage

+
    
+
  • Database: Stores only the relative path (e.g., videos/sample.mp4)
    • 
+
  • Input Root: Configurable via MEDIA_IN env var
    • 
+
  • Output Root: Configurable via MEDIA_OUT env var
    • 
+
  • Serving: Base URL configurable via MEDIA_BASE_URL env var
    • 
+

+
Why Relative Paths?

+
    
+
  1. Portability: Same database works locally and in cloud
    2. 
+
  2. Flexibility: Easy to switch between storage backends
    3. 
+
  3. Simplicity: No need to update paths when migrating
    4. 
+

+
Local Development

+
Configuration

+
bash
+MEDIA_IN=/app/media/in
+MEDIA_OUT=/app/media/out

+
File Structure

+
/app/media/
+├── in/                    # Source files
+│   ├── video1.mp4
+│   ├── video2.mp4
+│   └── subfolder/
+│       └── video3.mp4
+└── out/                   # Transcoded output
+    ├── video1_h264.mp4
+    └── video2_trimmed.mp4

+
Database Storage

+
```

+
Source assets (scanned from media/in)

+
filename: video1.mp4
+file_path: video1.mp4

+
filename: video3.mp4
+file_path: subfolder/video3.mp4
+```

+
URL Serving

+
    
+
  • Nginx serves input via location /media/in { alias /app/media/in; }
    • 
+
  • Nginx serves output via location /media/out { alias /app/media/out; }
    • 
+
  • Frontend accesses: http://mpr.local.ar/media/in/video1.mp4
    • 
+
  • Video player: <video src="/media/in/video1.mp4" />
    • 
+

+
AWS/Cloud Deployment

+
S3 Configuration

+
```bash

+
Input and output can be different buckets/paths

+
MEDIA_IN=s3://source-bucket/media/
+MEDIA_OUT=s3://output-bucket/transcoded/
+MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/
+```

+
S3 Structure

+
```
+s3://source-bucket/media/
+├── video1.mp4
+└── subfolder/
+    └── video3.mp4

+
s3://output-bucket/transcoded/
+├── video1_h264.mp4
+└── video2_trimmed.mp4
+```

+
Database Storage (Same!)

+
```
+filename: video1.mp4
+file_path: video1.mp4

+
filename: video3.mp4
+file_path: subfolder/video3.mp4
+```

+
API Endpoints

+
Scan Media Folder

+
http
+POST /api/assets/scan

+
Behavior:
+1. Recursively scans MEDIA_IN directory
+2. Finds all video/audio files (mp4, mkv, avi, mov, mp3, wav, etc.)
+3. Stores paths relative to MEDIA_IN
+4. Skips already-registered files (by filename)
+5. Returns summary: { found, registered, skipped, files }

+
Create Job

+
```http
+POST /api/jobs/
+Content-Type: application/json

+
{
+  "source_asset_id": "uuid",
+  "preset_id": "uuid",
+  "trim_start": 10.0,
+  "trim_end": 30.0
+}
+```

+
Behavior:
+- Server sets output_path using MEDIA_OUT + generated filename
+- Output goes to the output directory, not alongside source files

+
Migration Guide

+
Moving from Local to S3

+
    
+
  1. 
+
    Upload source files to S3:
+   bash
+   aws s3 sync /app/media/in/ s3://source-bucket/media/
+   aws s3 sync /app/media/out/ s3://output-bucket/transcoded/
    
+
    2. 
+
  2. 
+
    Update environment variables:
+   bash
+   MEDIA_IN=s3://source-bucket/media/
+   MEDIA_OUT=s3://output-bucket/transcoded/
+   MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/
    
+
    3. 
+
  3. 
+
    Database paths remain unchanged (already relative)
    
+
    4. 
+

+
Supported File Types

+
Video: .mp4, .mkv, .avi, .mov, .webm, .flv, .wmv, .m4v
+Audio: .mp3, .wav, .flac, .aac, .ogg, .m4a

\ No newline at end of file