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:

   npm install
   

2. Establish Environment Variables: Create a pristine copy of the .env.example structure:

   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:

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.