🎥 Video v2 - HLS Video Streaming Repository

The central asset repository for high-performance HLS (HTTP Live Streaming) and MP4 video delivery across the Franc Vila and Badreya web platforms.

---

📖 Table of Contents

• 🔍 Overview
• ⚡ Why HLS (HTTP Live Streaming)?
• 📂 Repository Structure
• ⚙️ Prerequisites
• 🚀 How to Convert Videos
• 🛠️ How the Conversion Script Works
• 🔗 URL Structure & Hosting
• 💻 React & Next.js Integration
• 📋 Developer Workflow

---

🔍 Overview

This repository acts as the media hosting and processing backend for Badreya and Franc Vila web platforms. Instead of serving massive static .mp4 files directly—which delays page rendering, causes buffering, and consumes excessive mobile data—videos are processed into HLS (HTTP Live Streaming) directories. This allows the websites to serve fast, modern, and adaptive video streams tailored directly to each user's network connection.

---

⚡ Why HLS (HTTP Live Streaming)?

1. Adaptive Bitrate Streaming: The player automatically shifts between 1080p (high fidelity) and 750p (lighter weight) depending on the user's internet speed, ensuring zero buffer lags.
2. Instant Playback (Fast Start): The video is split into small chunks (8 seconds each). The browser only needs to download the first segment to start playing, resulting in an instant-on user experience.
3. Broad Native Compatibility: Works natively on Safari and iOS devices, and seamlessly on Chrome, Firefox, and Edge via standard integration libraries (such as hls.js).

---

📂 Repository Structure

video-v2/
├── Reloj-azul-y-negro-FVGB.mp4  # Original high-res MP4 source files
├── fin3.mp4                    
├── frnkvll.mp4                 
└── hls/                         # HLS-converted streaming bundles
    ├── convert_hls.sh           # 🛠️ Smart HLS Bash conversion script
    │
    ├── Reloj-azul-y-negro-FVGB/ # Converted HLS output directory
    │   ├── master.m3u8          # 📜 Master Playlist file (Adaptive index)
    │   ├── v0/                  # Stream 0: 1080p (High Quality)
    │   │   ├── index.m3u8       # Playlist for the 1080p stream
    │   │   └── seg000.ts...     # Segmented 1080p video files (TS chunks)
    │   └── v1/                  # Stream 1: 750p (Medium Quality)
    │       ├── index.m3u8       # Playlist for the 750p stream
    │       └── seg000.ts...     # Segmented 750p video files (TS chunks)
    │
    ├── fin3/                    # HLS files for fin3
    ├── frnkvll/                 # HLS files for frnkvll
    └── ...

---

⚙️ Prerequisites

To run the local conversion script on your machine, you need FFmpeg and FFprobe installed:

# Install FFmpeg using Homebrew on macOS
brew install ffmpeg

Verify that the utilities are installed correctly by running:

ffmpeg -version
ffprobe -version

---

🚀 How to Convert Videos

Follow these steps to convert any standard .mp4 video file into an HLS adaptive streaming bundle:

1️⃣ Navigate to the script directory

Open your terminal and change directory to the hls folder:

cd hls

2️⃣ Run the conversion script

Run the script by providing the path to your source .mp4 file and the desired output folder name:

./convert_hls.sh <input_file_path> <output_directory_name>

💡 Commands & Examples:

• To convert the fin3.mp4 video located in the root folder:

  ./convert_hls.sh ../fin3.mp4 fin3

• To convert the frnkvll.mp4 video:

  ./convert_hls.sh ../frnkvll.mp4 frnkvll

• To convert an external video on your desktop:

  ./convert_hls.sh ~/Desktop/my-new-watch.mp4 my-new-watch

---

🛠️ How the Conversion Script Works

The convert_hls.sh script automates a premium transcoding pipeline:

1. Resolution & Compression Tiers:
   • v0 (1080p - High Quality): Uses a high-fidelity Constant Rate Factor CRF 18 (visually near-lossless), high-efficiency slow preset compression, and crystal-clear 256k AAC stereo audio.
   • v1 (750p - Medium Quality): Uses a balanced CRF 21 for optimized mobile viewing and 4G streaming, and compact 128k AAC stereo audio.
2. Chunk Segmentation:
   • Cuts the video streams into small, independent 8-second segments (.ts files).
3. Dynamic Master Playlist Generation (master.m3u8):
   • Uses ffprobe to query the precise output resolutions dynamically, and writes a standard-compliant multi-variant playlist.

---

🔗 URL Structure & Hosting

This repository is hosted on GitHub Pages, serving files directly as a static content delivery network (CDN):

• GitHub Repository: https://github.com/simaa99/video-v2
• Static Content Base URL: https://simaa99.github.io/video-v2/

📌 Live Stream URL Pattern:

To play or stream any converted video in your code, target the folder's master.m3u8 playlist using this structure:

https://simaa99.github.io/video-v2/hls/<folder_name>/master.m3u8

🔗 Live Production Streams:

• Blue/Black Watch Video (watch-v1):
  https://simaa99.github.io/video-v2/hls/watch-v1/master.m3u8
• Jewelry Show Video (jewely-v1):
  https://simaa99.github.io/video-v2/hls/jewely-v1/master.m3u8
• Jihad Show Video (jihad-v1):
  https://simaa99.github.io/video-v2/hls/jihad-v1/master.m3u8

---

💻 React & Next.js Integration

To play adaptive HLS streams smoothly in your web apps, we recommend implementing a custom video component utilizing hls.js for non-native browsers, and native fallback for Apple devices.

Here is a ready-to-use, optimized React component:

"use client";

import { useEffect, useRef } from "react";
import Hls from "hls.js";

interface HlsVideoPlayerProps {
  src: string;        // Path to the master.m3u8 file
  poster?: string;    // Image shown before the video starts
  className?: string;
  autoPlay?: boolean;
  muted?: boolean;
  loop?: boolean;
}

export default function HlsVideoPlayer({
  src,
  poster,
  className = "",
  autoPlay = true,
  muted = true,
  loop = true,
}: HlsVideoPlayerProps) {
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    let hls: Hls | null = null;

    if (Hls.isSupported()) {
      // For browsers without native HLS support (Chrome, Firefox, Edge, etc.)
      hls = new Hls({
        maxMaxBufferLength: 30, // Buffers up to 30 seconds ahead for fluid playback
      });
      hls.loadSource(src);
      hls.attachMedia(video);
      
      hls.on(Hls.Events.MANIFEST_PARSED, () => {
        if (autoPlay) {
          video.play().catch((err) => console.log("Autoplay was blocked:", err));
        }
      });
    } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
      // For browsers with native HLS support (Safari on macOS, iOS devices)
      video.src = src;
      video.addEventListener("loadedmetadata", () => {
        if (autoPlay) {
          video.play().catch((err) => console.log("Autoplay was blocked:", err));
        }
      });
    }

    return () => {
      // Prevent memory leaks by destroying the HLS instance on component unmount
      if (hls) {
        hls.destroy();
      }
    };
  }, [src, autoPlay]);

  return (
    <video
      ref={videoRef}
      poster={poster}
      className={`w-full h-full object-cover ${className}`}
      muted={muted}
      loop={loop}
      playsInline
      controls
    />
  );
}

---

📋 Developer Workflow

Use this checklist when introducing a new video asset to the system:

• 1. Transfer Video: Place the original .mp4 file in the root video-v2/ directory.
• 2. Convert Video: Change directory to hls/ in your terminal and run the converter script:

  ./convert_hls.sh ../my-video.mp4 my-video-folder

• 3. Inspect Outputs: Open the new directory and verify that master.m3u8, v0/, and v1/ were created successfully.
• 4. Push to Git: Add, commit, and push the newly generated folders:

  git add .
  git commit -m "feat: add HLS stream for my-video"
  git push origin main

• 5. Wait & Verify: Give GitHub Pages about a minute to complete deployment, then check the livestream URL directly in a player or browser:

  https://simaa99.github.io/video-v2/hls/my-video-folder/master.m3u8
  

• 6. Integrate: Embed the new HLS URL into your target codebase using the VideoPlayer component.

---

_{Designed with precision to provide the ultimate media streaming experience.}