Implement double-buffering for smooth subtitle transitions
Eliminates flicker when captions appear in rapid succession by pre-loading next caption on secondary buffer while displaying current on primary. Transitions between buffers seamlessly. - Added secondary image element for double-buffering - Track which frames are loaded in primary and secondary buffers - New helper functions: renderSubtitleFrameOnBuffer(), showPrimaryBuffer(), swapBuffers() - Updated syncOverlayToPlaybackClock() to check pre-loaded frames and swap when ready - Improves user experience during rapid caption sequences All 276 tests pass.
timfa Tim Falken · pushed by timfa
Authored 2026-05-28 · 5 months ago
- Hash
89f7fd951a644cb9bce8f94a5bf6b8285c729822- Parent
7e31bef8
1 file changed
+91
−18
@@ -360,6 +360,10 @@
360
360
let activeObjectUrl = null;
361
361
let overlayEl = null;
362
362
let overlayImgEl = null;
363
let overlayImgElSecondary = null;
364
let primaryBufferIndex = 0;
365
let primaryFrameKey = null;
366
let secondaryFrameKey = null;
363
367
let menuEl = null;
364
368
let buttonEl = null;
365
369
let trackDisabled = false;
@@ -543,6 +547,8 @@
543
547
const closeObjectUrl = () =>
544
548
{
545
549
activeObjectUrl = null;
550
primaryFrameKey = null;
551
secondaryFrameKey = null;
546
552
};
547
553
548
554
const hideOverlay = () =>
@@ -703,34 +709,64 @@
703
709
return Math.round(prefetchRequestIntervalMs + (excessRatio * 250));
704
710
};
705
711
706
const renderSubtitleFrame = (frame) =>
712
const renderSubtitleFrameOnBuffer = (frame, bufferIndex) =>
707
713
{
708
if (!overlayEl || !overlayImgEl || !frame || !frame.objectUrl) return;
714
if (!frame || !frame.objectUrl) return false;
709
715
710
if (activeObjectUrl !== frame.objectUrl)
711
{
712
activeObjectUrl = frame.objectUrl;
713
overlayImgEl.src = frame.objectUrl;
714
}
716
const targetEl = bufferIndex === 0 ? overlayImgEl : overlayImgElSecondary;
717
if (!targetEl) return false;
718
719
targetEl.src = frame.objectUrl;
715
720
716
721
if (frame.frameWidth > 0 && frame.frameHeight > 0 && frame.canvasWidth > 0 && frame.canvasHeight > 0)
717
722
{
718
723
const widthPercent = (frame.frameWidth / frame.canvasWidth) * 100;
719
724
const heightPercent = (frame.frameHeight / frame.canvasHeight) * 100;
720
overlayImgEl.style.width = `${widthPercent}%`;
721
overlayImgEl.style.height = `${heightPercent}%`;
722
overlayImgEl.style.maxWidth = 'none';
723
overlayImgEl.style.maxHeight = 'none';
725
targetEl.style.width = `${widthPercent}%`;
726
targetEl.style.height = `${heightPercent}%`;
727
targetEl.style.maxWidth = 'none';
728
targetEl.style.maxHeight = 'none';
724
729
} else
725
730
{
726
overlayImgEl.style.width = 'auto';
727
overlayImgEl.style.height = 'auto';
728
overlayImgEl.style.maxWidth = '100%';
729
overlayImgEl.style.maxHeight = '100%';
731
targetEl.style.width = 'auto';
732
targetEl.style.height = 'auto';
733
targetEl.style.maxWidth = '100%';
734
targetEl.style.maxHeight = '100%';
730
735
}
731
736
737
if (bufferIndex === 0) primaryFrameKey = frame.key;
738
else secondaryFrameKey = frame.key;
739
740
return true;
741
};
742
743
const showPrimaryBuffer = () =>
744
{
745
if (!overlayEl) return;
746
const primaryEl = primaryBufferIndex === 0 ? overlayImgEl : overlayImgElSecondary;
747
const secondaryEl = primaryBufferIndex === 0 ? overlayImgElSecondary : overlayImgEl;
748
749
if (primaryEl) primaryEl.style.display = 'block';
750
if (secondaryEl) secondaryEl.style.display = 'none';
732
751
overlayEl.style.display = 'block';
733
overlayImgEl.style.display = 'block';
752
};
753
754
const swapBuffers = () =>
755
{
756
primaryBufferIndex = primaryBufferIndex === 0 ? 1 : 0;
757
};
758
759
const renderSubtitleFrame = (frame) =>
760
{
761
if (!overlayEl || !frame || !frame.objectUrl) return;
762
763
if (activeObjectUrl !== frame.objectUrl)
764
{
765
activeObjectUrl = frame.objectUrl;
766
renderSubtitleFrameOnBuffer(frame, primaryBufferIndex);
767
}
768
769
showPrimaryBuffer();
734
770
};
735
771
736
772
const syncOverlayToPlaybackClock = () =>
@@ -745,8 +781,35 @@
745
781
if (Number.isFinite(currentTime) && currentTime >= 0)
746
782
{
747
783
const cachedFrame = findCachedFrameForTime(selectedStreamIndex, currentTime);
748
if (cachedFrame) renderSubtitleFrame(cachedFrame);
749
else hideOverlay();
784
785
if (cachedFrame)
786
{
787
// Check if frame changed
788
const currentFrameKey = primaryBufferIndex === 0 ? primaryFrameKey : secondaryFrameKey;
789
if (cachedFrame.key !== currentFrameKey)
790
{
791
// Frame transition: check if it's pre-loaded on secondary buffer
792
const secondaryKey = primaryBufferIndex === 0 ? secondaryFrameKey : primaryFrameKey;
793
if (cachedFrame.key === secondaryKey)
794
{
795
// Swap to show pre-loaded secondary frame
796
swapBuffers();
797
showPrimaryBuffer();
798
activeObjectUrl = cachedFrame.objectUrl;
799
} else
800
{
801
// Not pre-loaded; render directly on secondary and swap
802
const secondaryIdx = primaryBufferIndex === 0 ? 1 : 0;
803
renderSubtitleFrameOnBuffer(cachedFrame, secondaryIdx);
804
swapBuffers();
805
showPrimaryBuffer();
806
activeObjectUrl = cachedFrame.objectUrl;
807
}
808
}
809
} else
810
{
811
hideOverlay();
812
}
750
813
}
751
814
752
815
playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);
@@ -1587,6 +1650,16 @@
1587
1650
overlayImgEl.style.height = 'auto';
1588
1651
overlayEl.appendChild(overlayImgEl);
1589
1652
1653
overlayImgElSecondary = document.createElement('img');
1654
overlayImgElSecondary.alt = 'Image subtitles (buffered)';
1655
overlayImgElSecondary.style.display = 'none';
1656
overlayImgElSecondary.style.margin = '0 auto';
1657
overlayImgElSecondary.style.objectFit = 'contain';
1658
overlayImgElSecondary.style.filter = 'drop-shadow(0 2px 2px rgba(0, 0, 0, 0.7))';
1659
overlayImgElSecondary.style.maxWidth = '100%';
1660
overlayImgElSecondary.style.height = 'auto';
1661
overlayEl.appendChild(overlayImgElSecondary);
1662
1590
1663
menuEl = document.createElement('div');
1591
1664
menuEl.className = 'video-subtitle-overlay-menu';
1592
1665
menuEl.style.position = 'absolute';
@@ -360,6 +360,10 @@360
let activeObjectUrl = null;360
let activeObjectUrl = null;361
let overlayEl = null;361
let overlayEl = null;362
let overlayImgEl = null;362
let overlayImgEl = null;363
let overlayImgElSecondary = null;364
let primaryBufferIndex = 0;365
let primaryFrameKey = null;366
let secondaryFrameKey = null;363
let menuEl = null;367
let menuEl = null;364
let buttonEl = null;368
let buttonEl = null;365
let trackDisabled = false;369
let trackDisabled = false;@@ -543,6 +547,8 @@543
const closeObjectUrl = () =>547
const closeObjectUrl = () =>544
{548
{545
activeObjectUrl = null;549
activeObjectUrl = null;550
primaryFrameKey = null;551
secondaryFrameKey = null;546
};552
};547
553
548
const hideOverlay = () =>554
const hideOverlay = () =>@@ -703,34 +709,64 @@703
return Math.round(prefetchRequestIntervalMs + (excessRatio * 250));709
return Math.round(prefetchRequestIntervalMs + (excessRatio * 250));704
};710
};705
711
706
const renderSubtitleFrame = (frame) =>712
const renderSubtitleFrameOnBuffer = (frame, bufferIndex) =>707
{713
{708
if (!overlayEl || !overlayImgEl || !frame || !frame.objectUrl) return;714
if (!frame || !frame.objectUrl) return false;709
715
710
if (activeObjectUrl !== frame.objectUrl)716
const targetEl = bufferIndex === 0 ? overlayImgEl : overlayImgElSecondary;711
{717
if (!targetEl) return false;712
activeObjectUrl = frame.objectUrl;718
713
overlayImgEl.src = frame.objectUrl;719
targetEl.src = frame.objectUrl;714
}715
720
716
if (frame.frameWidth > 0 && frame.frameHeight > 0 && frame.canvasWidth > 0 && frame.canvasHeight > 0)721
if (frame.frameWidth > 0 && frame.frameHeight > 0 && frame.canvasWidth > 0 && frame.canvasHeight > 0)717
{722
{718
const widthPercent = (frame.frameWidth / frame.canvasWidth) * 100;723
const widthPercent = (frame.frameWidth / frame.canvasWidth) * 100;719
const heightPercent = (frame.frameHeight / frame.canvasHeight) * 100;724
const heightPercent = (frame.frameHeight / frame.canvasHeight) * 100;720
overlayImgEl.style.width = `${widthPercent}%`;725
targetEl.style.width = `${widthPercent}%`;721
overlayImgEl.style.height = `${heightPercent}%`;726
targetEl.style.height = `${heightPercent}%`;722
overlayImgEl.style.maxWidth = 'none';727
targetEl.style.maxWidth = 'none';723
overlayImgEl.style.maxHeight = 'none';728
targetEl.style.maxHeight = 'none';724
} else729
} else725
{730
{726
overlayImgEl.style.width = 'auto';731
targetEl.style.width = 'auto';727
overlayImgEl.style.height = 'auto';732
targetEl.style.height = 'auto';728
overlayImgEl.style.maxWidth = '100%';733
targetEl.style.maxWidth = '100%';729
overlayImgEl.style.maxHeight = '100%';734
targetEl.style.maxHeight = '100%';730
}735
}731
736
737
if (bufferIndex === 0) primaryFrameKey = frame.key;738
else secondaryFrameKey = frame.key;739
740
return true;741
};742
743
const showPrimaryBuffer = () =>744
{745
if (!overlayEl) return;746
const primaryEl = primaryBufferIndex === 0 ? overlayImgEl : overlayImgElSecondary;747
const secondaryEl = primaryBufferIndex === 0 ? overlayImgElSecondary : overlayImgEl;748
749
if (primaryEl) primaryEl.style.display = 'block';750
if (secondaryEl) secondaryEl.style.display = 'none';732
overlayEl.style.display = 'block';751
overlayEl.style.display = 'block';733
overlayImgEl.style.display = 'block';752
};753
754
const swapBuffers = () =>755
{756
primaryBufferIndex = primaryBufferIndex === 0 ? 1 : 0;757
};758
759
const renderSubtitleFrame = (frame) =>760
{761
if (!overlayEl || !frame || !frame.objectUrl) return;762
763
if (activeObjectUrl !== frame.objectUrl)764
{765
activeObjectUrl = frame.objectUrl;766
renderSubtitleFrameOnBuffer(frame, primaryBufferIndex);767
}768
769
showPrimaryBuffer();734
};770
};735
771
736
const syncOverlayToPlaybackClock = () =>772
const syncOverlayToPlaybackClock = () =>@@ -745,8 +781,35 @@745
if (Number.isFinite(currentTime) && currentTime >= 0)781
if (Number.isFinite(currentTime) && currentTime >= 0)746
{782
{747
const cachedFrame = findCachedFrameForTime(selectedStreamIndex, currentTime);783
const cachedFrame = findCachedFrameForTime(selectedStreamIndex, currentTime);748
if (cachedFrame) renderSubtitleFrame(cachedFrame);784
749
else hideOverlay();785
if (cachedFrame)786
{787
// Check if frame changed788
const currentFrameKey = primaryBufferIndex === 0 ? primaryFrameKey : secondaryFrameKey;789
if (cachedFrame.key !== currentFrameKey)790
{791
// Frame transition: check if it's pre-loaded on secondary buffer792
const secondaryKey = primaryBufferIndex === 0 ? secondaryFrameKey : primaryFrameKey;793
if (cachedFrame.key === secondaryKey)794
{795
// Swap to show pre-loaded secondary frame796
swapBuffers();797
showPrimaryBuffer();798
activeObjectUrl = cachedFrame.objectUrl;799
} else800
{801
// Not pre-loaded; render directly on secondary and swap802
const secondaryIdx = primaryBufferIndex === 0 ? 1 : 0;803
renderSubtitleFrameOnBuffer(cachedFrame, secondaryIdx);804
swapBuffers();805
showPrimaryBuffer();806
activeObjectUrl = cachedFrame.objectUrl;807
}808
}809
} else810
{811
hideOverlay();812
}750
}813
}751
814
752
playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);815
playbackClockSyncHandle = requestFrame(syncOverlayToPlaybackClock);@@ -1587,6 +1650,16 @@1587
overlayImgEl.style.height = 'auto';1650
overlayImgEl.style.height = 'auto';1588
overlayEl.appendChild(overlayImgEl);1651
overlayEl.appendChild(overlayImgEl);1589
1652
1653
overlayImgElSecondary = document.createElement('img');1654
overlayImgElSecondary.alt = 'Image subtitles (buffered)';1655
overlayImgElSecondary.style.display = 'none';1656
overlayImgElSecondary.style.margin = '0 auto';1657
overlayImgElSecondary.style.objectFit = 'contain';1658
overlayImgElSecondary.style.filter = 'drop-shadow(0 2px 2px rgba(0, 0, 0, 0.7))';1659
overlayImgElSecondary.style.maxWidth = '100%';1660
overlayImgElSecondary.style.height = 'auto';1661
overlayEl.appendChild(overlayImgElSecondary);1662
1590
menuEl = document.createElement('div');1663
menuEl = document.createElement('div');1591
menuEl.className = 'video-subtitle-overlay-menu';1664
menuEl.className = 'video-subtitle-overlay-menu';1592
menuEl.style.position = 'absolute';1665
menuEl.style.position = 'absolute';