# Media Coding Web - Configuration & Run Guide

Media Coding Web is a high-performance video transcoding and streaming web application. It retrieves source media files from AWS S3 or MinIO, transcodes them on the fly utilizing hardware-accelerated video encoders, and streams them efficiently to the browser using HLS (m3u8).

## Features

- **High-Performance HLS Streaming:** Streams video using HLS for fast startup, localized buffering, native browser video controls, and frame-accurate seeking.
- **Hardware-Accelerated Encoding:** Detects and seamlessly supports Intel QSV, NVIDIA NVENC, and VAAPI hardware encoders natively via FFmpeg.
- **AWS S3 / MinIO Integration:** Securely downloads media from S3-compatible endpoints to a dedicated local cache directory before processing.
- **Persistent Sessions:** Utilizes Valkey (Redis) for stateful session management, eliminating repetitive login actions.
- **Real-Time Progress:** Displays live feedback for both background S3 downloading and FFmpeg transcoding, communicated to the web application via WebSockets.
- **Modern User Interface:** Features a sleek and highly responsive user interface complete with built-in light and dark mode switching.
- **Centralized Log Storage:** Persists application activity and debugging events safely within the project's `/logs/` directory utilizing Winston loggers.
- **Unified Configuration:** A single `.env` file powers the entire web application settings.

## Prerequisites

To properly run and deploy this project, your environment should contain:

1. **Node.js**: Version 18.x or newer is required to natively support all APIs.
2. **FFmpeg with Hardware Support**: 
   - Ensure you configure an FFmpeg instance on your system. 
   - For maximal performance, the application defaults to searching for `jellyfin-ffmpeg` located at `/usr/lib/jellyfin-ffmpeg/ffmpeg`. Feel free to point it at any other binary containing QSV or NVENC support by modifying the `JELLYFIN_FFMPEG_PATH` path inside `.env`.
3. **Valkey (or Redis)**: An active Redis-compatible cache server string is required for user sessions.
4. **AWS S3 / MinIO Account**: An object storage endpoint containing your encoded `.mp4` media catalog.

## Configuration & Installation

1. **Install Dependencies**:
   Navigate into the project root directory and execute:
   ```bash
   npm install
   ```

2. **Establish Environment Variables**:
   Create a pristine copy of the `.env.example` structure:
   ```bash
   cp .env.example .env
   ```
   Open `.env` using your preferred editor to tailor your environment:
   - **Valkey/Redis Settings**: Configure `VALKEY_URL`.
   - **S3 Connectivity**: Insert your `S3_BUCKET_ADDRESS` and `AWS_REGION`. For MinIO specifically, fill the `S3_ENDPOINT` key (e.g. `http://127.0.0.1:9000`) and verify `S3_FORCE_PATH_STYLE=true`.

## Running the Application

To launch the web interface and application server, simply run:
```bash
npm start
```
*(You may also run `npm run dev` to execute the local environment.)*

## Verifying Setup

1. Open a browser and load `http://localhost:3000` (or your defined `PORT`).
2. Log into the system using your relevant S3 authorization if using local user mode.
3. The server will communicate directly to your S3 bucket and load the application's root dashboard.
4. Upon clicking any available video media, the server will rapidly download the required chunks to the local cache, start compiling HLS indexing data using native hardware encoding, and pipe an advanced native video stream back into your browser.
