updated docs

docs/media-storage.html

@@ -0,0 +1,125 @@
+<h1>Media Storage Architecture</h1>
+<h2>Overview</h2>
+<p>MPR separates media into <strong>input</strong> and <strong>output</strong> paths, each independently configurable. File paths are stored <strong>relative to their respective root</strong> to ensure portability between local development and cloud deployments (AWS S3, etc.).</p>
+<h2>Storage Strategy</h2>
+<h3>Input / Output Separation</h3>
+<p>| Path | Env Var | Purpose |
+|------|---------|---------|
+| <code>MEDIA_IN</code> | <code>/app/media/in</code> | Source media files to process |
+| <code>MEDIA_OUT</code> | <code>/app/media/out</code> | Transcoded/trimmed output files |</p>
+<p>These can point to different locations or even different servers/buckets in production.</p>
+<h3>File Path Storage</h3>
+<ul>
+<li><strong>Database</strong>: Stores only the relative path (e.g., <code>videos/sample.mp4</code>)</li>
+<li><strong>Input Root</strong>: Configurable via <code>MEDIA_IN</code> env var</li>
+<li><strong>Output Root</strong>: Configurable via <code>MEDIA_OUT</code> env var</li>
+<li><strong>Serving</strong>: Base URL configurable via <code>MEDIA_BASE_URL</code> env var</li>
+</ul>
+<h3>Why Relative Paths?</h3>
+<ol>
+<li><strong>Portability</strong>: Same database works locally and in cloud</li>
+<li><strong>Flexibility</strong>: Easy to switch between storage backends</li>
+<li><strong>Simplicity</strong>: No need to update paths when migrating</li>
+</ol>
+<h2>Local Development</h2>
+<h3>Configuration</h3>
+<p><code>bash
+MEDIA_IN=/app/media/in
+MEDIA_OUT=/app/media/out</code></p>
+<h3>File Structure</h3>
+<p><code>/app/media/
+├── in/                    # Source files
+│   ├── video1.mp4
+│   ├── video2.mp4
+│   └── subfolder/
+│       └── video3.mp4
+└── out/                   # Transcoded output
+    ├── video1_h264.mp4
+    └── video2_trimmed.mp4</code></p>
+<h3>Database Storage</h3>
+<p>```</p>
+<h1>Source assets (scanned from media/in)</h1>
+<p>filename: video1.mp4
+file_path: video1.mp4</p>
+<p>filename: video3.mp4
+file_path: subfolder/video3.mp4
+```</p>
+<h3>URL Serving</h3>
+<ul>
+<li>Nginx serves input via <code>location /media/in { alias /app/media/in; }</code></li>
+<li>Nginx serves output via <code>location /media/out { alias /app/media/out; }</code></li>
+<li>Frontend accesses: <code>http://mpr.local.ar/media/in/video1.mp4</code></li>
+<li>Video player: <code>&lt;video src="/media/in/video1.mp4" /&gt;</code></li>
+</ul>
+<h2>AWS/Cloud Deployment</h2>
+<h3>S3 Configuration</h3>
+<p>```bash</p>
+<h1>Input and output can be different buckets/paths</h1>
+<p>MEDIA_IN=s3://source-bucket/media/
+MEDIA_OUT=s3://output-bucket/transcoded/
+MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/
+```</p>
+<h3>S3 Structure</h3>
+<p>```
+s3://source-bucket/media/
+├── video1.mp4
+└── subfolder/
+    └── video3.mp4</p>
+<p>s3://output-bucket/transcoded/
+├── video1_h264.mp4
+└── video2_trimmed.mp4
+```</p>
+<h3>Database Storage (Same!)</h3>
+<p>```
+filename: video1.mp4
+file_path: video1.mp4</p>
+<p>filename: video3.mp4
+file_path: subfolder/video3.mp4
+```</p>
+<h2>API Endpoints</h2>
+<h3>Scan Media Folder</h3>
+<p><code>http
+POST /api/assets/scan</code></p>
+<p><strong>Behavior:</strong>
+1. Recursively scans <code>MEDIA_IN</code> directory
+2. Finds all video/audio files (mp4, mkv, avi, mov, mp3, wav, etc.)
+3. Stores paths <strong>relative to MEDIA_IN</strong>
+4. Skips already-registered files (by filename)
+5. Returns summary: <code>{ found, registered, skipped, files }</code></p>
+<h3>Create Job</h3>
+<p>```http
+POST /api/jobs/
+Content-Type: application/json</p>
+<p>{
+  "source_asset_id": "uuid",
+  "preset_id": "uuid",
+  "trim_start": 10.0,
+  "trim_end": 30.0
+}
+```</p>
+<p><strong>Behavior:</strong>
+- Server sets <code>output_path</code> using <code>MEDIA_OUT</code> + generated filename
+- Output goes to the output directory, not alongside source files</p>
+<h2>Migration Guide</h2>
+<h3>Moving from Local to S3</h3>
+<ol>
+<li>
+<p><strong>Upload source files to S3:</strong>
+   <code>bash
+   aws s3 sync /app/media/in/ s3://source-bucket/media/
+   aws s3 sync /app/media/out/ s3://output-bucket/transcoded/</code></p>
+</li>
+<li>
+<p><strong>Update environment variables:</strong>
+   <code>bash
+   MEDIA_IN=s3://source-bucket/media/
+   MEDIA_OUT=s3://output-bucket/transcoded/
+   MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/</code></p>
+</li>
+<li>
+<p><strong>Database paths remain unchanged</strong> (already relative)</p>
+</li>
+</ol>
+<h2>Supported File Types</h2>
+<p><strong>Video:</strong> <code>.mp4</code>, <code>.mkv</code>, <code>.avi</code>, <code>.mov</code>, <code>.webm</code>, <code>.flv</code>, <code>.wmv</code>, <code>.m4v</code>
+<strong>Audio:</strong> <code>.mp3</code>, <code>.wav</code>, <code>.flac</code>, <code>.aac</code>, <code>.ogg</code>, <code>.m4a</code></p>