9.8 KiB

Raw Blame History

Complete Video Player Replacement Plan

Executive Summary

This document outlines a comprehensive plan to completely replace the current custom video player implementation with ArtPlayer + hls.js, eliminating the FFmpeg transcoding system unless absolutely necessary.

Current State Analysis

Existing Architecture

Custom HTML5 video player with advanced transcoding pipeline
FFmpeg-based process management with anti-jitter technology
Complex format support through real-time transcoding
Process deduplication and heartbeat mechanisms
Anti-jitter progress tracking and protected duration handling

Pain Points Identified

Transcoding system complexity and maintenance overhead
FFmpeg process management reliability issues
High resource consumption for video processing
Complex deployment requirements
Browser compatibility limitations for certain formats

Proposed Solution: ArtPlayer + hls.js Integration

Core Technology Stack

ArtPlayer.js: Modern, lightweight video player (18-25kB gzipped)
hls.js: HLS streaming support with adaptive bitrate
Native browser capabilities: Leverage built-in format support

Architecture Changes

Before (Current)

Video File → FFmpeg Transcoding → Process Management → HTML5 Player → User

After (Proposed)

Video File → Format Detection → [Direct Streaming | HLS Streaming | Fallback] → ArtPlayer → User

Implementation Strategy

Phase 1: Foundation Setup (Week 1-2)

Dependencies Installation

npm install artplayer hls.js artplayer-plugin-hls

Core Component Development

Create unified ArtPlayerWrapper component
Implement format detection logic
Set up basic HLS integration
Maintain existing bookmark/rating APIs

Phase 2: Feature Parity (Week 2-3)

Essential Features Migration

Keyboard shortcuts (Space, arrows, F, M)
Fullscreen support with proper exit handling
Progress tracking and resume functionality
Bookmark integration with real-time updates
Star rating system compatibility

UI/UX Enhancements

Modern player controls with ArtPlayer theming
Picture-in-picture mode support
Playback speed controls (0.5x - 2.0x)
Advanced subtitle support (VTT, SRT, ASS/SSA)
Mini-player functionality for multitasking

Phase 3: Streaming Architecture (Week 3-4)

Format Support Strategy

Tier 1: Direct Streaming (Native Browser Support)

MP4 (H.264, H.265)
WebM (VP8, VP9)
OGG (Theora)
Direct file serving with HTTP range requests

Tier 2: HLS Streaming (ArtPlayer + hls.js)

Adaptive bitrate for network optimization
Live streaming support
Advanced error recovery
Multi-audio track support

Tier 3: Fallback Mode

Simple file serving for unsupported formats
Basic playback without advanced features
User notification for limited functionality

API Endpoint Modifications

New Endpoints:

// Direct file streaming
GET /api/stream/direct/:id

// HLS playlist generation (when needed)
GET /api/stream/hls/:id/playlist.m3u8
GET /api/stream/hls/:id/segment/:segment

// Format detection
GET /api/video/:id/format

Deprecated Endpoints:

// Remove transcoding endpoints
DELETE /api/stream/:id/transcode
DELETE /api/ffmpeg/*

Phase 4: Transcoding System Removal (Week 4-5)

Code Cleanup

Remove FFmpeg dependencies and configurations
Delete process management system
Clean up anti-jitter hooks and utilities
Remove video analysis utilities
Update database schema (remove codec_info dependency)

Dependency Reduction

# Remove FFmpeg-related packages
npm uninstall fluent-ffmpeg
# Remove process management utilities
# Remove video analysis dependencies

Technical Implementation Details

New Player Component Architecture

// src/components/artplayer-wrapper.tsx
import Artplayer from 'artplayer';
import Hls from 'hls.js';

interface ArtPlayerWrapperProps {
  video: VideoFile;
  onProgress: (time: number) => void;
  onBookmark: () => void;
  onRate: (rating: number) => void;
}

export const ArtPlayerWrapper: React.FC<ArtPlayerWrapperProps> = ({
  video,
  onProgress,
  onBookmark,
  onRate
}) => {
  const playerRef = useRef<Artplayer>(null);
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const player = new Artplayer({
      container: containerRef.current,
      url: getVideoUrl(video),
      type: getVideoType(video),
      plugins: getPlugins(video),
      // Maintain existing features
      subtitle: {
        url: video.subtitleUrl,
        type: 'vtt',
        style: {
          color: '#fff',
          fontSize: '20px',
        }
      },
      // Feature parity configuration
      fullscreen: true,
      fullscreenWeb: true,
      pip: true,
      playbackRate: true,
      aspectRatio: true,
      screenshot: true,
      hotkey: true,
    });

    // Integrate with existing systems
    player.on('video:timeupdate', () => {
      onProgress(player.currentTime);
    });

    playerRef.current = player;

    return () => {
      player.destroy();
    };
  }, [video]);

  return <div ref={containerRef} className="artplayer-container" />;
};

Format Detection Logic

// src/lib/video-format-detector.ts
export const detectVideoFormat = (video: VideoFile): VideoFormat => {
  const extension = getFileExtension(video.path).toLowerCase();
  
  // Tier 1: Direct streaming support
  const directStreamingFormats = ['mp4', 'webm', 'ogg'];
  if (directStreamingFormats.includes(extension)) {
    return {
      type: 'direct',
      url: `/api/stream/direct/${video.id}`,
      mimeType: getMimeType(extension)
    };
  }
  
  // Tier 2: HLS streaming for optimal experience
  const hlsSupportedFormats = ['m3u8', 'mp4', 'ts'];
  if (hlsSupportedFormats.includes(extension)) {
    return {
      type: 'hls',
      url: `/api/stream/hls/${video.id}/playlist.m3u8`
    };
  }
  
  // Tier 3: Fallback to direct file serving
  return {
    type: 'fallback',
    url: `/api/files/content/${video.id}`,
    warning: 'Limited playback features for this format'
  };
};

HLS Integration with ArtPlayer

// src/lib/artplayer-hls-plugin.ts
export const artplayerHlsPlugin = (option) => {
  return (art) => {
    const hls = new Hls();
    
    hls.loadSource(option.url);
    hls.attachMedia(art.video);
    
    hls.on(Hls.Events.MANIFEST_PARSED, () => {
      // Auto-select optimal quality level
      const levels = hls.levels;
      const autoLevel = hls.autoLevelEnabled;
      
      if (levels.length > 1 && autoLevel) {
        art.controls.updateQualitySelector(levels);
      }
    });
    
    hls.on(Hls.Events.ERROR, (event, data) => {
      handleHlsError(art, hls, data);
    });
    
    return {
      name: 'hls',
      hls: hls
    };
  };
};

Migration Timeline

Week 1: Foundation

Install dependencies
Create core ArtPlayer wrapper component
Implement basic format detection
Set up development environment

Week 2: Feature Implementation

Migrate keyboard shortcuts
Implement progress tracking
Add bookmark/rating integration
Create subtitle support system

Week 3: Streaming Architecture

Implement HLS streaming with hls.js
Add quality selection controls
Create fallback mechanisms
Optimize performance

Week 4: Testing & Cleanup

Comprehensive testing across formats
Remove transcoding system
Update API endpoints
Performance optimization

Week 5: Deployment

Production deployment
Monitoring setup
User feedback collection
Bug fixes and refinements

Risk Assessment & Mitigation

High-Risk Areas

1. Format Compatibility Issues

Risk: Some video formats may not play properly without transcoding Mitigation: Comprehensive format testing, robust fallback system Impact: Medium | Probability: High

2. Feature Regression

Risk: Existing features may not work identically Mitigation: Thorough feature parity testing, user acceptance testing Impact: High | Probability: Medium

3. Performance Degradation

Risk: New player may perform worse than optimized current system Mitigation: Performance benchmarking, optimization iterations Impact: Medium | Probability: Low

Mitigation Strategies

Staged Rollout: Deploy to subset of users first
Rollback Plan: Maintain ability to revert to current system
Feature Flags: Enable/disable new features dynamically
Monitoring: Comprehensive analytics and error tracking
User Feedback: Collect and act on user reports quickly

Success Metrics

Performance Metrics

Load Time: < 1.5s for first frame (vs current 2.8s on 4G)
Buffering Ratio: < 1% (vs current 4.1%)
Seek Performance: < 1s (vs current 3+ seconds)
Memory Usage: Reduce by 30-50%

User Experience Metrics

Playback Success Rate: > 99.5%
User Satisfaction: Maintain or improve current ratings
Feature Usage: Track adoption of new features
Error Rate: < 0.1% of total playbacks

Technical Metrics

Bundle Size: Target < 100kB for video player code
API Response Time: < 200ms for video metadata
CDN Performance: < 500ms for video start
Mobile Performance: Maintain current mobile experience

Conclusion

This replacement plan offers a path to modernize the video playback system while significantly reducing complexity and maintenance overhead. The combination of ArtPlayer's modern UI capabilities and hls.js's streaming expertise will provide a superior user experience while eliminating the resource-intensive transcoding pipeline.

The key to success lies in maintaining feature parity during the transition and implementing robust fallback mechanisms for format compatibility. With proper testing and staged deployment, this migration will result in a more maintainable, performant, and feature-rich video platform.

9.8 KiB Raw Blame History