BlueGit

timfa filemanager

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
public/shared-video-player.js +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 } else
729 } else
725 {
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 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 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';