Add optimized media delivery and HLS support

docs/FRONTEND_INTEGRATION.md

@@ -18,7 +18,7 @@ CORS_ORIGINS=http://192.168.1.12:3000,http://192.168.1.12:5173
 GOOGLE_CALLBACK_URL=http://192.168.1.12:4000/api/v1/auth/google/callback
 ```
 
-With `PUBLIC_BASE_URL` configured, file fields such as `avatar`, `coverImage`, `imageUrls`, `videoUrl`, `audioUrl`, `thumbnailUrl`, `mediaUrl`, and marketplace images are returned as absolute URLs.
+With `PUBLIC_BASE_URL` configured, file fields such as `avatar`, `coverImage`, `imageUrls`, `videoUrl`, `hlsUrl`, `audioUrl`, `thumbnailUrl`, `mediaUrl`, and marketplace images are returned as absolute URLs.
 
 ## Pagination contract
 
@@ -211,11 +211,30 @@ When `VIDEO_PROCESSING_ENABLED=true` and `ffmpeg` is available on the server:
 
 - uploaded post/reel videos are converted to optimized `mp4`
 - `+faststart` is applied so playback begins faster on mobile/web
+- uploaded post/reel videos also produce an HLS playlist at `hlsUrl` when `VIDEO_PROCESSING_GENERATE_HLS=true`
+- local storage responses serve `mp4`, `m3u8`, `m4s`, and `ts` files with explicit media `Content-Type` headers and `Accept-Ranges: bytes`
 - a thumbnail image is generated automatically if the client does not send `thumbnailUrl`
 
 If `ffmpeg` is not installed or video processing is disabled, uploads still work and the original
 video file is stored as-is.
 
+Recommended client behavior:
+
+- use `hlsUrl` first when present for adaptive/streaming playback
+- fall back to `videoUrl` for progressive `mp4` playback
+
+## Audio and image delivery
+
+Managed uploads are stored under stable UUID-based paths, so local storage responses now send cache-friendly headers:
+
+- images (`jpg`, `jpeg`, `png`, `webp`, `gif`) are served with explicit `Content-Type` and long-lived immutable `Cache-Control`
+- audio (`mp3`, `wav`, `m4a`, `aac`, `ogg`) is served with explicit `Content-Type`, long-lived immutable `Cache-Control`, and `Accept-Ranges: bytes`
+
+Recommended client behavior:
+
+- for audio, stream `audioUrl` directly and allow byte-range playback/resume
+- for images, render `imageUrls` directly and rely on URL-based caching for repeat views
+
 ## Marketplace split
 
 Marketplace is now separated from musical instruments at the API contract level: