# Luồng Tối ưu & Xử lý Hình ảnh/Video

Hệ thống Media Library tích hợp sẵn các công cụ mạnh mẽ như **Pillow** và **FFmpeg** để tự động xử lý tài nguyên mà không cần thông qua các API bên thứ 3.

## Logic Flow

Dưới đây là Sequence Diagram minh họa quá trình Upload và Resize hình ảnh / xử lý video theo nền tảng:

```mermaid
sequenceDiagram
    participant Client
    participant MediaRoute as /api/media
    participant ImageProcessor
    participant FFmpeg
    participant FileSystem
    
    Client->>MediaRoute: POST /upload (File: 50MB Max)
    MediaRoute->>MediaRoute: Validate MIME Type & Size
    MediaRoute->>ImageProcessor: save_uploaded_asset()
    ImageProcessor->>FileSystem: Lưu file gốc vào data/media/
    
    alt is_image
        ImageProcessor->>ImageProcessor: generate_image_thumbnail()
        Note over ImageProcessor: LANCZOS resize 400x400<br/>Convert RGBA/P to RGB
    else is_video
        ImageProcessor->>FFmpeg: generate_video_thumbnail()
        Note over FFmpeg: Extract frame at 1.0s<br/>(scale 400x400)
    end
    
    ImageProcessor->>FileSystem: Lưu thumbnail vào data/media/thumbs/
    ImageProcessor->>FileSystem: Cập nhật index.json metadata
    ImageProcessor-->>MediaRoute: Trả về đối tượng Asset
    MediaRoute-->>Client: 200 OK { asset }

    Client->>MediaRoute: POST /{id}/resize?platform=facebook
    MediaRoute->>ImageProcessor: resize_for_platform()
    Note over ImageProcessor: ImageOps.fit<br/>(Crop Center & Resize)
    ImageProcessor-->>MediaRoute: Trả về JPEG Bytes (1200x630)
    MediaRoute-->>Client: 200 OK Image Bytes
```

## Tối ưu Hình ảnh (Pillow)

1. **Sinh Thumbnail (`generate_image_thumbnail`):**
   - Đảm bảo tương thích hoàn toàn với JPEG bằng cách chuyển đổi các mode màu `RGBA`, `P`, `LA` sang `RGB` (thay thế kênh alpha bằng nền trắng).
   - Sử dụng thuật toán `Image.LANCZOS` để resize ảnh với chế độ antialiased, kích thước mặc định `400x400` để tối ưu tải danh sách.
   - Nén ảnh JPEG với `quality=85` và cờ `optimize=True`.

2. **Resize theo Nền tảng (`resize_for_platform`):**
   - Hỗ trợ cắt ảnh (crop) tự động tập trung vào chính giữa (`centering=(0.5, 0.5)`) kết hợp với resize (`ImageOps.fit`) nhằm đảm bảo không làm méo tỷ lệ (aspect ratio).
   - Cấu hình kích thước cố định cho Social Media:
     - `instagram_square`: 1080x1080
     - `instagram_portrait`: 1080x1350
     - `instagram_story` / `tiktok`: 1080x1920
     - `facebook`: 1200x630
     - `facebook_square`: 1080x1080

## Xử lý Video (FFmpeg / FFprobe)

1. **Trích xuất Thumbnail (`generate_video_thumbnail`):**
   - Triển khai lệnh `ffmpeg -ss 1.0 -i {video} -vframes 1` dùng để xuất 1 frame tại giây thứ 1.0 của video, tự động scale về `400x400`.
2. **Đọc Metadata (`get_video_metadata`):**
   - Sử dụng lệnh `ffprobe -print_format json -show_streams -show_format` để lấy nhanh các chỉ số: thời lượng video, độ phân giải thực, codec xử lý, và dung lượng tổng (size_bytes) để điền vào JSON index.
