[players] Pre-seek next decoder to handle-in to avoid slate flash

With handles set on a playlist, the hidden decoder preloading the next
entity sat at t=0 until playNext seeked it at switch time, so the first
frame (the slate) was painted for an instant before the seek completed.
Park the preloaded decoder on the next entity's handle-in frame as soon
as it is preloaded (loadEntity, switchPlayers, and on nextHandleIn prop
updates), fed by a new nextEntityHandleIn computed in PlaylistPlayer.

Fixes #1019

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: frankrousseau

src/components/players/players/PlaylistPlayer.vue

@@ -135,6 +135,7 @@
           :is-hd="isHd"
           :is-repeating="isRepeating"
           :muted="true"
+          :next-handle-in="nextEntityHandleIn"
           :panzoom="true"
           :handle-in="
             ['shot', 'edit', 'episode'].includes(playlist.for_entity)
@@ -258,6 +259,7 @@
           :is-repeating="isRepeating"
           :current-preview-index="currentPreviewIndex"
           :muted="isMuted"
+          :next-handle-in="nextEntityHandleIn"
           :panzoom="true"
           @entity-change="onPlayerPlayingEntityChange"
           @frame-update="onRawPlayerFrameUpdate"
@@ -1304,6 +1306,12 @@ const nextEntityIndex = computed(() => {
   return index
 })
 
+// Next entity's handle-in, so the viewers can park their preloaded decoder
+// past the slate before the players switch (#1019).
+const nextEntityHandleIn = computed(
+  () => getEntityHandles(entityList.value[nextEntityIndex.value]).handleIn
+)
+
 const picturePreviews = computed(() =>
   entityList.value.flatMap(e => [
     {

src/components/players/viewers/MultiVideoViewer.vue

@@ -106,6 +106,11 @@ const props = defineProps({
     type: String,
     default: 'main'
   },
+  nextHandleIn: {
+    // Handle-in frame of the next entity, used to pre-seek its decoder
+    type: Number,
+    default: 0
+  },
   panzoom: {
     type: Boolean,
     default: false
@@ -401,6 +406,19 @@ const reloadCurrentEntity = (silentReload = false) => {
   loadEntity(currentIndex.value, currentPlayer.value.currentTime, silentReload)
 }
 
+// Park the preloaded decoder on the next entity's handle-in frame so its
+// first frame (slate) is never the one painted when players switch.
+const preseekNextPlayer = () => {
+  const player = nextPlayer.value
+  if (!player || !player.getAttribute('src') || props.nextHandleIn <= 0) return
+  const nextEntity = props.entities[getNextIndex(currentIndex.value)]
+  const nextFps =
+    parseFloat(nextEntity?.fps) ||
+    parseFloat(currentProduction.value?.fps) ||
+    DEFAULT_FPS
+  player.currentTime = props.nextHandleIn / nextFps
+}
+
 const loadEntity = (index = 0, currentTime = 0, silentLoad = false) => {
   if (index < props.entities.length) {
     const nextIndex = getNextIndex(index)
@@ -436,6 +454,7 @@ const loadEntity = (index = 0, currentTime = 0, silentLoad = false) => {
       if (!nextPlayer.value.src.endsWith(nextMoviePath)) {
         nextPlayer.value.src = nextMoviePath
       }
+      preseekNextPlayer()
     } else if (nextPlayer.value) {
       nextPlayer.value.src = ''
     }
@@ -596,6 +615,7 @@ const switchPlayers = () => {
   nextPlayer.value = tmpPlayer
   if (nextEntity) {
     nextPlayer.value.src = getMoviePath(nextEntity)
+    preseekNextPlayer()
   }
   resetHeight()
   setSpeed(rate)
@@ -710,6 +730,15 @@ watch(
   }
 )
 
+// At switch time the prop still holds the previous "next" value: re-apply
+// the pre-seek once the parent pushes the new next entity's handle-in.
+watch(
+  () => props.nextHandleIn,
+  () => {
+    preseekNextPlayer()
+  }
+)
+
 watch(
   () => props.entities,
   () => {

tests/unit/players/multivideoviewer.spec.js

@@ -27,7 +27,7 @@ const removeRvfcMock = () => {
   delete HTMLVideoElement.prototype.cancelVideoFrameCallback
 }
 
-const mountViewer = () => {
+const mountViewer = (props = {}) => {
   const store = createStore({
     getters: { currentProduction: () => ({ fps: '25' }) }
   })
@@ -37,7 +37,8 @@ const mountViewer = () => {
         { id: 'e1', preview_file_id: 'p1', preview_file_extension: 'mp4', fps: 25 },
         { id: 'e2', preview_file_id: 'p2', preview_file_extension: 'mp4', fps: 25 }
       ],
-      name: 'main'
+      name: 'main',
+      ...props
     },
     global: {
       mocks: { $t: key => key },
@@ -185,6 +186,30 @@ describe('players/MultiVideoViewer (canvas pipeline)', () => {
     wrapper.unmount()
   })
 
+  it('pre-seeks the preloaded decoder to the next entity handle-in (#1019)', async () => {
+    const wrapper = mountViewer({ nextHandleIn: 100 })
+
+    wrapper.vm.loadEntity(0)
+    await wrapper.vm.$nextTick()
+
+    const current = wrapper.vm.currentPlayer
+    const next = wrapper
+      .findAll('video.playlist-movie-decoder')
+      .map(w => w.element)
+      .find(el => el !== current)
+
+    // The decoder preloading e2 must already be parked on its handle-in
+    // frame so the slate at frame 0 never flashes when players switch
+    expect(next.src).toContain('/movies/low/preview-files/p2.mp4')
+    expect(next.currentTime).toBeCloseTo(100 / 25)
+
+    // A handle change on the next entity re-parks the decoder
+    await wrapper.setProps({ nextHandleIn: 50 })
+    expect(next.currentTime).toBeCloseTo(50 / 25)
+
+    wrapper.unmount()
+  })
+
   it('does not emit frame-update from ticks while paused', async () => {
     const wrapper = mountViewer()
     wrapper.vm.loadEntity(0)