Skip to main content

​
Overview

Some videos may experience progressive audio/video desynchronization (drift) during playback, especially in longer sessions. Platzi Viewer includes adaptive A/V sync correction and a compatibility mode using FFmpeg to address these issues.

​
Understanding A/V Sync Problems

​
What Causes Desynchronization?

  1. Damaged timestamps in the video file - Incorrect or inconsistent PTS (Presentation Time Stamps)
  2. Network jitter - Unstable streaming causing buffering delays
  3. Container format issues - MP4 files with improper interleaving
  4. Browser decoding quirks - Different browsers handle malformed videos differently

​
Symptoms

  • Audio plays ahead of video (or vice versa)
  • Drift increases over time (e.g., 2 seconds off after 10 minutes)
  • Frequent automatic corrections or “jumps” in playback
  • Compatibility mode prompt appears

​
Adaptive Sync Correction

Platzi Viewer includes automatic drift detection and correction:

​
How It Works

  1. Frame-based monitoring - Continuously tracks A/V offset
  2. Soft corrections - Small adjustments (< 200ms) via playback rate changes
  3. Hard corrections - Large adjustments (≥ 200ms) via seeking
  4. Automatic mode switching - Offers compatibility mode if issues persist

​
Viewing Sync Statistics

Open browser console and check: 
window.__platziAvSyncLastStats
Output example: 
{
  "drift": 127,          // Current drift in ms
  "softCorrections": 3,  // Number of soft corrections
  "hardCorrections": 1,  // Number of hard corrections
  "totalChecks": 245
}

​
Compatibility Mode

When a video has persistent sync issues, the player may automatically suggest compatibility mode.

​
What Is Compatibility Mode?

Compatibility mode uses FFmpeg on the server to re-process the video stream in real-time:
  • Copy mode (default): Re-muxes the stream without re-encoding (fast, low CPU)
  • Reencode mode: Transcodes video to fix timestamp issues (slower, higher CPU)

​
Switching to Compatibility Mode

Manual switch:
  1. Open the video player
  2. Look for the compatibility mode prompt (appears if drift detected)
  3. Click “Switch to Compatibility Mode”
URL format: 
/api/video-compatible/{fileId}
vs normal mode: 
/drive/files/{fileId}

​
Checking Compatibility Mode Status

Query the health endpoint: 
curl http://localhost:8080/api/health
Response: 
{
  "compatStream": {
    "totalRequests": 10,
    "successfulStreams": 8,
    "failedStreams": 2,
    "totalBytes": 524288000,
    "lastFileId": "1OOJ5lrsLfFEnp6AKVKZKYZH5A-NasCjl",
    "lastMode": "copy",
    "lastError": null,
    "lastDurationSec": 45.2,
    "lastSpeedMBps": 12.4,
    "lastAt": "2026-03-07T14:32:10Z"
  }
}

​
FFmpeg Configuration

Error in /api/health:
"ffmpeg": {
  "available": false,
  "path": null
}
Impact: Compatibility mode will not work.Solution:1. Install FFmpeg:Windows:
  • Download from ffmpeg.org
  • Extract to C:\ffmpeg\bin\ffmpeg.exe or C:\Program Files\ffmpeg\bin\ffmpeg.exe
  • Or add to PATH
Linux (Ubuntu/Debian):
sudo apt update
sudo apt install ffmpeg
macOS:
brew install ffmpeg
2. Verify installation:
ffmpeg -version
3. Custom FFmpeg path:
# Windows
$env:FFMPEG_PATH="C:\custom\path\ffmpeg.exe"
python server.py

# Linux/Mac
FFMPEG_PATH=/custom/path/ffmpeg python server.py
When to use: Copy mode improves some videos but others remain out of sync.Enable reencode mode:
# Windows PowerShell
$env:PLATZI_COMPAT_FORCE_REENCODE="1"
python server.py

# Linux/Mac
PLATZI_COMPAT_FORCE_REENCODE=1 python server.py
Reencode mode increases CPU usage significantly. Only use if copy mode fails.
What it does:
  • Transcodes video with libx264 (CPU-based encoding)
  • Regenerates all timestamps (+genpts)
  • Fixes audio sample rate to 48kHz
  • Uses veryfast preset to balance speed and quality
Symptom: Video won’t load in compatibility mode.Check /api/health for lastError:
"lastError": "Input/output error"
Common errors:1. “Invalid data found when processing input”
  • File may be corrupted in Google Drive
  • Try downloading and re-uploading the file
2. “Connection reset by peer” / “Broken pipe”
  • Network issue between server and Drive
  • Retry the request
3. “ffmpeg_exit_1” (no stderr)
  • Generic FFmpeg error
  • Try reencode mode: PLATZI_COMPAT_FORCE_REENCODE=1
4. Timeout or slow processing:
  • Video file is too large for real-time processing
  • Check lastSpeedMBps - should be > 5 MB/s
  • Consider using VLC external player instead

​
GPU Acceleration (Windows)

​
Hardware Acceleration in Browser

Browsers use GPU acceleration by default for video decoding. Forcing dedicated GPU can improve performance: Windows Settings:
  1. Open Settings > System > Display > Graphics
  2. Click Browse and add:
    • Your browser executable (Chrome, Firefox, Edge)
    • Or PlatziViewerDesktop.exe for desktop app
  3. Select the app and click Options
  4. Choose High performance (uses dedicated GPU)
  5. Restart the application

​
Desktop App GPU Acceleration

The desktop app (PlatziViewerDesktop.exe) automatically requests hardware acceleration for Chromium-based rendering. Note: GPU acceleration helps with decoding performance but does not fix videos with damaged timestamps. Use compatibility mode for those.

​
Diagnostic Matrix

Use this reproducible test matrix to isolate desynchronization causes:

​
Test Procedure

For each problematic video, test all combinations:
#ModePlatformDurationNetwork
1NormalWeb Browser10-15 minStable (Ethernet/WiFi)
2NormalDesktop App10-15 minStable
3CompatibilityWeb Browser10-15 minStable
4CompatibilityDesktop App10-15 minStable
5NormalWeb Browser10-15 minUnstable (VPN/Mobile)
6CompatibilityWeb Browser10-15 minUnstable

​
Data to Record

For each test:
  1. Drift at checkpoints:
    • Minute 1: ___ ms
    • Minute 5: ___ ms
    • Minute 10: ___ ms
  2. Sync corrections:
    • Soft corrections: ___
    • Hard corrections: ___
  3. Mode switches:
    • Prompted to switch mode? Yes/No
    • Did automatic quality changes occur? Yes/No
  4. Health snapshot:
    • Check http://localhost:8080/api/health
    • Record: lastMode, lastError, lastSpeedMBps, failedStreams

​
Interpreting Results

Pattern 1: All modes fail → Video file is likely corrupted in Drive. Re-upload the file. Pattern 2: Normal mode fails, compatibility mode works → Video has timestamp issues. Use compatibility mode or VLC. Pattern 3: Only unstable network fails → Network jitter is the cause, not the video file. Improve network connection. Pattern 4: Desktop app works, web browser fails → Browser-specific decoding issue. Use desktop app or try a different browser. Pattern 5: Copy mode fails, reencode mode works → Enable PLATZI_COMPAT_FORCE_REENCODE=1 for this video type.

​
External Player (VLC)

If all else fails, open the video in VLC:

​
From the Player

  1. Click the “Open in VLC” button in the video player
  2. The video URL is sent to VLC automatically (Windows only)
Requirements:
  • VLC must be installed at:
    • C:\Program Files\VideoLAN\VLC\vlc.exe, or
    • C:\Program Files (x86)\VideoLAN\VLC\vlc.exe, or
    • Available in PATH as vlc

​
Manual VLC Playback

  1. Get the video file ID from browser DevTools Network tab
  2. Open VLC
  3. Media > Open Network Stream
  4. Enter URL: 
    http://localhost:8080/drive/files/{fileId}
  5. Click Play

​
Why VLC Works Better

VLC has more robust handling of:
  • Damaged timestamps
  • Incomplete/corrupted frames
  • Various codecs and container formats
It can also use hardware acceleration more aggressively than browsers.

​
Advanced: Server Streaming Metrics

The server logs streaming performance for diagnostics: Example log output: 
[STREAM] 1OOJ5lrsLfFEnp6AKVKZKYZH5A-NasCjl | Range: bytes=0-1048575 | 1.00 MB in 0.85s (1.18 MB/s)
[COMPAT] 1WWggG3NLugsK6dZ37wzbNeLAPqFdOVfj | 45.23 MB in 3.87s (11.69 MB/s)
What to look for:
  • Speed < 1 MB/s - Network bottleneck or Drive API throttling
  • Duration > 10s for small files - Server or Drive performance issue
  • Frequent errors - Check Drive API quota and authentication

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us