Video Playback

​

Overview

​

Video Player Features

​

YouTube-Style Custom Controls

• Play/Pause Button - Toggle video playback
• Progress Bar - Seek to any point in the video
• Volume Control - Slider and mute button
• Playback Speed - Cycle through speeds (0.5x, 0.75x, 1x, 1.25x, 1.5x, 2x)
• Quality Selector - Choose video quality (if available)
• Subtitles (CC) - Toggle Spanish subtitles when available
• Fullscreen Toggle - Enter/exit fullscreen mode
• External Player - Open video in VLC or another external player

​

Player Controls Bar

[Play/Pause] [Volume] [Time: 0:00 / 12:34] ... [CC] [Quality] [VLC] [Speed] [Fullscreen]

​

Video Overlay

• Open External Player - Launch VLC or default video player
• Download Video - Download video file directly
• Previous Class - Navigate to previous video
• Next Class - Navigate to next video

​

Streaming from Google Drive

​

How It Works

Browser → server.py (Proxy) → Google Drive API → Video Stream

• No videos stored locally on the server
• Streams on-demand using Google Drive file IDs
• Supports HTTP Range Requests for seeking and buffering
• Transparent proxy with automatic authentication

​

HTTP Range Requests

• Partial Content: Browser requests specific byte ranges (HTTP 206)
• Efficient Seeking: Jump to any point without downloading entire file
• Buffer Control: Download only what’s needed for smooth playback
• Bandwidth Optimization: Reduces data transfer for seeking/skipping

​

Streaming URLs

// Internal API format
http://localhost:8080/drive/files/{googleDriveFileId}

• File metadata retrieval from Drive
• MIME type detection (fallback by extension)
• Range request processing
• Chunked streaming (1MB chunks)

​

Adaptive A/V Synchronization

​

Sync Monitoring

• Uses requestVideoFrameCallback API when available
• Monitors drift between currentTime and mediaTime
• Samples every 700ms to detect desynchronization

• Tracks dropped video frames via getVideoPlaybackQuality()
• Monitors frame drop ratio every 3 seconds
• Triggers corrective actions on sustained drops

​

Automatic Corrections

• Triggered on moderate drift (≥0.28s for 4+ samples)
• Seeks back 0.03 seconds to realign
• Cooldown: 9 seconds between corrections

• Triggered on severe drift (≥0.42s for 6+ samples)
• Seeks back 0.08 seconds for stronger correction
• Cooldown: 12 seconds between corrections
• Recorded for diagnostics

• Triggered on severe frame drops (≥20% drop ratio)
• Automatically lowers video quality if in auto mode
• Prevents further A/V desynchronization
• Cooldown: 7 seconds between quality changes

​

Sync Statistics

window.__platziAvSyncLastStats = {
  elapsedSec: 1200,
  hardResyncEvents: 3,
  softResyncEvents: 12,
  frameDriftSoftHits: 45,
  frameDriftHardHits: 8,
  autoQualityDownshifts: 1,
  qualitySwitches: 2,
  compatibilityActivations: 0
}

​

Compatibility Mode

​

When to Use Compatibility Mode

​

How It Works

# Backend compatibility endpoint
/api/video-compatible/{fileId}

1. Copy mode - Fast remuxing to fix container issues
2. Transcode mode - Full re-encode for severe corruption (if PLATZI_COMPAT_FORCE_REENCODE=1)

• Streams while processing (no pre-download wait)
• Automatically selects best codec profile
• Preserves original quality when possible
• Falls back to normal mode on error

​

Compatibility Prompt

┌──────────────────────────────────────────────────────┐
│ Este video parece tener timestamps inestables.       │
│ [Modo compat.] [Abrir VLC] [Siempre] [×]            │
└──────────────────────────────────────────────────────┘

• Modo compat. - Enable FFmpeg compatibility mode
• Abrir VLC - Open video in VLC media player
• Siempre - Always open VLC for future sync issues
• × - Dismiss for this class

​

Quality Selection

​

Auto Quality

• Network Speed: Connection type (2G, 3G, 4G, etc.)
• Viewport Size: Screen resolution (480p, 720p, 1080p)
• Data Saver: Honors browser/OS data saving preferences

• 2G/Slow-2G: 360p
• 3G: 480p
• Viewport ≤800px: 480p
• Viewport ≥1200px: 1080p
• Default: 720p

​

Manual Quality Selection

1. Click the Quality button in player controls
2. Select from available qualities:
   • Auto (recommended)
   • 1080p
   • 720p
   • 480p
   • 360p
   • Original
3. Player switches quality while maintaining playback position

​

Quality Switching

• Remembers current playback position
• Pauses briefly to load new quality
• Resumes automatically at same timestamp
• Minimum 7-second interval between switches

​

Playback Speed Control

​

Available Speeds

• 0.5x (half speed)
• 0.75x (slow)
• 1x (normal) - default
• 1.25x (fast)
• 1.5x (faster)
• 2x (double speed)

​

Speed Override Detection

• Disables automatic A/V sync corrections
• Prevents auto-quality adjustments
• Allows you to watch at custom speeds without interference

​

Subtitles

​

Subtitle Support

• Format: .vtt files served from Google Drive
• Language: Spanish (es)
• Default: Off (toggle manually)

​

Enabling Subtitles

1. Click the CC button in player controls
2. Subtitles toggle on/off
3. Button highlights when active: CC

​

Buffering and Seek

​

Buffer Visualization

• Gray bar - Unbuffered portion
• White segments - Buffered ranges
• Red bar - Played portion
• Circular thumb - Current position

​

Seeking

1. Click or drag on the progress bar
2. Preview position updates while dragging
3. Release to seek to new position

• ← - Seek backward 5 seconds
• → - Seek forward 5 seconds

• Pauses video during seek
• Resumes automatically if playing
• Uses optimized sync-aware seeking

​

Buffer Management

• Minimum 0.25s buffer before starting playback
• Soft resync requires 0.3s buffer ahead
• Auto-downshift requires 0.35s buffer
• Adaptive buffering based on network speed

​

External Player Integration

​

Opening in VLC

1. Click External Player button in overlay or controls
2. Video URL is copied to clipboard automatically
3. VLC (or system default) opens with the stream

• Desktop: vlc:// protocol handler
• Android: Intent-based VLC launch
• iOS: vlc-x-callback:// URL scheme
• Fallback: Opens URL in new tab

​

Download Video

​

Fullscreen Mode

​

Entering Fullscreen

• Click the Fullscreen button
• Press F key
• Double-click the video

​

Exiting Fullscreen

• Click the Exit Fullscreen button
• Press Escape key
• Press F key again

• Controls auto-hide after 2.5 seconds
• Mouse movement shows controls temporarily
• Works on video wrapper (includes controls)

​

Advanced Features

​

Touch Device Optimization

• Larger tap targets for buttons
• Touch-friendly controls layout
• Optimized sidebar behavior
• Prevents accidental interactions

​

Mouse UI Auto-Hide

• Controls appear on mouse movement
• Auto-hide after 2.5 seconds during playback
• Always visible when paused
• Overlay fades independently

​

Clean Navigation

• Video stops automatically
• Source is removed to prevent background audio
• Fullscreen exits cleanly
• Resources are freed properly

​

Diagnostics and Troubleshooting

​

Health Check

GET /api/health

• Drive API availability
• FFmpeg availability
• Compatibility mode statistics
• Recent streaming performance

​

Console Diagnostics

// A/V sync statistics
window.__platziAvSyncLastStats

// Current player instance
window.__playerView

​

Common Issues

• Check /api/health endpoint
• Verify Google Drive access
• Check browser console for errors

• Enable compatibility mode manually
• Try opening in VLC
• Check compatibility health snapshot

• Lower video quality manually
• Check network connection
• Verify buffer ahead time

• Ensure CC button is clicked (highlighted)
• Check that .vtt file exists for the class
• Check browser console for subtitle loading errors

​

Best Practices

1. Let Auto-Sync Work: Avoid manual seeking during initial buffer
2. Use Compatibility Mode: For videos with repeated sync issues
3. Quality Selection: Use auto mode for best experience
4. Network Issues: Lower quality manually if buffering persists
5. Long Sessions: Sync corrections may increase over time (normal behavior)
6. External Players: Use VLC for maximum compatibility with problematic files