HLS Video Player - Administrator Guide

Table of Contents

• Overview
• Installation
• Configuration
• Managing Videos
• Monitoring & Maintenance
• Troubleshooting
• Advanced Configuration

Overview

This guide is intended for administrators who need to install, configure, and maintain the HLS Video Player feature in the Sponzy platform. HLS (HTTP Live Streaming) provides adaptive bitrate streaming, which automatically adjusts video quality based on the viewer's network conditions.

Installation

System Requirements

• Web server with PHP 7.4+
• FFmpeg 4.0+ with libx264 support
• Laravel FFmpeg package
• Sufficient disk space for multiple video quality versions

Installation Steps

1. Verify FFmpeg Installation

   Ensure FFmpeg is installed with HLS support:

   ffmpeg -version
   ffmpeg -encoders | grep libx264

2. Create Storage Directory

   Create a directory for HLS files:

   mkdir -p public/uploads/hls
   chmod 775 public/uploads/hls

3. Update Configuration

   Add HLS path to your config/path.php:

   'hls' => 'uploads/hls/',

4. Add Required Libraries

   Add the following to your main layout file:

   <!-- Video.js CSS -->
   <link href="https://vjs.zencdn.net/7.20.3/video-js.css" rel="stylesheet" />
   
   <!-- Video.js -->
   <script src="https://vjs.zencdn.net/7.20.3/video.min.js"></script>
   <!-- HLS.js -->
   <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>

5. Update Database Schema

   Run the migration to add the HLS column:

   php artisan migrate

Configuration

Admin Panel Settings

Navigate to Admin Panel → Settings → Video Settings to configure HLS options:

• Enable HLS Encoding - Turn on/off HLS encoding for new uploads
• HLS Quality Levels - Configure quality tiers (Low, Medium, High)
• Segment Length - Duration of each HLS segment (default: 10 seconds)
• Key Frame Interval - Interval between keyframes (default: 48)

Quality Settings

Configure the quality levels based on your audience's needs:

Storage Configuration

HLS requires more storage than standard MP4 files. Configure your storage settings accordingly:

• Local Storage - Ensure sufficient disk space (2-3x more than MP4 only)
• Cloud Storage - Configure S3, Wasabi, or other providers with proper CORS settings

Managing Videos

Batch Converting Existing Videos

To convert your existing video library to HLS format:

1. Go to Admin Panel → Videos → Manage Videos
2. Use the filter options to select videos to convert
3. Select the videos you want to convert
4. Click "Convert to HLS" from the batch actions dropdown
5. Confirm the action to start the conversion process

Monitoring Conversion Progress

Track the progress of video conversions:

1. Navigate to Admin Panel → System → Queue Monitor
2. Look for jobs with the type "ConvertVideoToHLS"
3. Check the status column for progress information

Managing HLS Files

HLS creates multiple files for each video:

• Master Playlist - Main .m3u8 file that references all quality levels
• Quality Playlists - Individual .m3u8 files for each quality level
• Segments - Multiple .ts files containing video chunks

You can manage these files through the file manager:

1. Go to Admin Panel → Files → File Manager
2. Navigate to the HLS directory
3. Files are organized by video ID and quality level

Monitoring & Maintenance

Performance Monitoring

Monitor the performance of your HLS implementation:

• Server Load - Check CPU and memory usage during encoding
• Storage Usage - Monitor disk space consumption
• Bandwidth Usage - Track CDN or server bandwidth for HLS segments

Regular Maintenance

Perform these maintenance tasks regularly:

• Clean Failed Conversions - Remove incomplete or failed HLS conversions
• Update FFmpeg - Keep FFmpeg updated for better performance and security
• Check for Orphaned Files - Remove HLS files that are no longer referenced in the database

Backup Considerations

When backing up your system, consider these HLS-specific points:

• HLS files significantly increase backup size
• Consider separate backup schedules for HLS content
• You can regenerate HLS files from MP4 sources if needed

Troubleshooting

Common Issues

Encoding Failures

Symptoms: Videos fail to convert to HLS format

Possible Causes:

• Insufficient server resources
• FFmpeg configuration issues
• Corrupted source video

Solutions:

• Check FFmpeg error logs: storage/logs/laravel.log
• Increase PHP memory limit and execution time
• Verify FFmpeg installation and codecs

Playback Issues

Symptoms: Videos don't play or frequently buffer

Possible Causes:

• CORS configuration issues
• Missing or corrupted HLS segments
• JavaScript errors

Solutions:

• Check browser console for errors
• Verify CORS headers are properly set
• Ensure all HLS segments are accessible

Diagnostic Tools

Use these tools to diagnose HLS issues:

• HLS Validator - https://hlsbook.net/hls-validator/
• FFmpeg HLS Info - ffprobe -v quiet -print_format json -show_format -show_streams video.m3u8
• Browser Developer Tools - Network tab to monitor segment loading

Advanced Configuration

Custom FFmpeg Parameters

You can customize the FFmpeg encoding parameters for better quality or efficiency:

// In EncodeVideo.php
$format->addAdditionalParameter('-preset', 'slow'); // Better quality, slower encoding
$format->addAdditionalParameter('-crf', '23'); // Constant Rate Factor (quality)

CDN Integration

For high-traffic sites, configure a CDN for HLS delivery:

1. Set up your CDN to serve files from your HLS directory
2. Configure proper CORS headers on your CDN
3. Update your config to use the CDN URL for HLS files

Encryption

To secure your HLS content with encryption:

// In EncodeVideo.php
$hlsExporter->withEncryptionKey(
    $encryptionKey,      // Your encryption key
    $encryptionKeyUrl,   // URL where the key can be accessed
    $encryptionIV        // Initialization vector
);