diff --git a/data/media.db b/data/media.db index 38afa93..374aa07 100644 Binary files a/data/media.db and b/data/media.db differ diff --git a/docs/ANTI-JITTER-IMPLEMENTATION.md b/docs/ANTI-JITTER-IMPLEMENTATION.md new file mode 100644 index 0000000..2922237 --- /dev/null +++ b/docs/ANTI-JITTER-IMPLEMENTATION.md @@ -0,0 +1,358 @@ +# Anti-Jitter Progress System Implementation + +## Overview + +This document describes the implementation of Stash's anti-jitter mechanisms in NextAV to solve the streaming buffer jitter problem where progress bars jump backward as new data arrives. + +## Problem Solved + +**Before**: The progress bar would jump backward when: +- Buffer underruns occurred +- Network delays caused time to "catch up" +- Raw video time updates were directly reflected in the UI + +**After**: Smooth, consistent progress that: +- Prevents backward jumps beyond a threshold +- Throttles updates to prevent excessive re-renders +- Allows small backward adjustments for smooth playback +- Provides visual buffer state feedback + +## Implementation Details + +### 1. Custom Hook: `useAntiJitterProgress` + +**Location**: `src/lib/use-anti-jitter-progress.ts` + +**Key Features**: +- **Jitter Threshold**: 0.5 seconds - maximum allowed backward jump +- **Update Throttling**: 100ms minimum between updates +- **Progress Reference**: Maintains stable progress state +- **Buffer Monitoring**: Tracks actual buffer state + +**Core Logic**: +```typescript +const handleTimeUpdate = () => { + if (videoRef.current) { + const now = Date.now(); + const video = videoRef.current; + const rawTime = video.currentTime; + const currentProgress = progressRef.current; + + // Prevent backward jumps beyond threshold + if (rawTime < currentProgress - jitterThreshold) { + console.log(`[ANTI-JITTER] Blocked backward jump: ${rawTime}s -> ${currentProgress}s`); + return; // Block this update + } + + // Throttle updates to prevent excessive re-renders + if (now - lastUpdateRef.current < updateThrottle) { + return; + } + + // Validate and update progress + if (rawTime >= 0 && rawTime <= (duration || Infinity)) { + if (rawTime >= currentProgress - 0.1) { + // Forward progress or small adjustment + progressRef.current = rawTime; + setCurrentTime(rawTime); + lastUpdateRef.current = now; + } + } + } +}; +``` + +### 2. Enhanced Progress Bar + +**Features**: +- **Buffer Visualization**: Blue overlay shows buffered content +- **Smooth Progress**: Blue bar shows current playback position +- **Seek Overlay**: Invisible range input for seeking +- **Buffer Status**: Text display of buffered duration + +**Visual Elements**: +```tsx +