nextav/docs/archive/transcoding-legacy/VIDEO-PLAYER-REPLACEMENT-PLAN.md

# 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
```bash
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:**
```typescript
// 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:**
```typescript
// 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
```bash
# Remove FFmpeg-related packages
npm uninstall fluent-ffmpeg
# Remove process management utilities
# Remove video analysis dependencies
```

## Technical Implementation Details

### New Player Component Architecture

```typescript
// 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

```typescript
// 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

```typescript
// 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

1. **Staged Rollout**: Deploy to subset of users first
2. **Rollback Plan**: Maintain ability to revert to current system
3. **Feature Flags**: Enable/disable new features dynamically
4. **Monitoring**: Comprehensive analytics and error tracking
5. **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.