didUpdatePlaybackProgressOfClip

Updates the playback progress of the currently playing clip.

Overview

Call this method periodically during clip playback to update the SDK with the current playback progress. The progress value should be a number between 0 and 1, representing the percentage of the clip that has been played.

Method Signature

didUpdatePlaybackProgressOfClip(index: number, to: number): void

Parameters

Parameter	Type	Description
index	number	The index of the clip being played, corresponding to its position in the flattened key plays array
to	number	The current playback progress as a value between 0 and 1

Return Value

This method does not return a value.

Example Usage

import SDK from '@maestro_io/maestro-web-sdk';

// Example of reporting progress at regular intervals
function startProgressReporting(clipIndex: number) {
  // Clear any existing progress reporting
  if (progressInterval) {
    clearInterval(progressInterval);
  }
  
  // Set up an interval to report progress
  progressInterval = setInterval(() => {
    // Get current progress from your video player
    const currentTime = videoPlayer.currentTime;
    const duration = videoPlayer.duration;
    
    // Calculate normalized progress (between 0 and 1)
    const progress = duration > 0 ? currentTime / duration : 0;
    
    // Report progress to the SDK
    const event = SDK.getMaestroEventViewModel();
    event.didUpdatePlaybackProgressOfClip(clipIndex, progress);
    
    // If playback is complete, clear the interval and notify completion
    if (progress >= 1) {
      clearInterval(progressInterval);
      progressInterval = null;
      event.didStopPlayingClip(clipIndex);
    }
  }, 250); // Report progress every 250ms
}

Integration with HTML5 Video

import SDK from '@maestro_io/maestro-web-sdk';

// Example with HTML5 video element
function setupHtml5VideoProgress() {
  const videoElement = document.getElementById('video-player') as HTMLVideoElement;
  const event = SDK.getMaestroEventViewModel();
  
  // Listen for timeupdate events (fired regularly during playback)
  videoElement.addEventListener('timeupdate', () => {
    const currentClipIndex = event.getCurrentlyPlayingClipIndex();
    
    if (currentClipIndex !== null) {
      // Calculate normalized progress (between 0 and 1)
      const progress = videoElement.duration > 0 
        ? videoElement.currentTime / videoElement.duration 
        : 0;
      
      // Report progress to the SDK
      event.didUpdatePlaybackProgressOfClip(currentClipIndex, progress);
    }
  });
}

Integration with Advanced Media Players

Shaka Player

import SDK from '@maestro_io/maestro-web-sdk';
import shaka from 'shaka-player';

// Example with Shaka Player
function setupShakaPlayerProgress() {
  const videoElement = document.getElementById('video-player') as HTMLVideoElement;
  const player = new shaka.Player(videoElement);
  const event = SDK.getMaestroEventViewModel();
  
  // Set up interval for progress reporting (Shaka doesn't have a specific event for this)
  let progressInterval: number | null = null;
  
  // When a clip starts playing
  function onPlayClip(clipIndex: number) {
    // Clear any existing interval
    if (progressInterval !== null) {
      clearInterval(progressInterval);
    }
    
    // Set up new interval
    progressInterval = window.setInterval(() => {
      const progress = videoElement.duration > 0 
        ? videoElement.currentTime / videoElement.duration 
        : 0;
      
      event.didUpdatePlaybackProgressOfClip(clipIndex, progress);
    }, 250);
  }
  
  // When a clip stops playing
  function onStopClip() {
    if (progressInterval !== null) {
      clearInterval(progressInterval);
      progressInterval = null;
    }
  }
  
  // Clean up on component unmount
  function cleanup() {
    if (progressInterval !== null) {
      clearInterval(progressInterval);
      progressInterval = null;
    }
  }
}

Internal Behavior

When didUpdatePlaybackProgressOfClip() is called, the SDK updates the progress state and clears any failure status for the clip:

didUpdatePlaybackProgressOfClip(index: number, to: number): void {
  this.keyPlaysViewModel.currentClipPlaybackProgress.value = to;
  this.keyPlaysViewModel.clearLoadFailureStatus(index);
}

These state updates trigger UI changes in the key plays panel, such as:

1. Updating the progress indicator for the clip
2. Clearing any error states associated with the clip

Progress Normalization

The progress value should be normalized between 0 and 1:

// Examples of proper normalization

// For a clip that is 30% complete
event.didUpdatePlaybackProgressOfClip(index, 0.3);

// For a clip that is at the beginning
event.didUpdatePlaybackProgressOfClip(index, 0);

// For a clip that is at the end
event.didUpdatePlaybackProgressOfClip(index, 1);

// For a clip with a known duration and current time
const progress = currentTime / duration;
event.didUpdatePlaybackProgressOfClip(index, progress);

Notes

• Call this method regularly during playback to provide smooth progress updates (typically every 250ms).
• The progress value must be a number between 0 and 1, where 0 represents the start of the clip and 1 represents the end.
• If the progress reaches 1, you should also call didStopPlayingClip() to indicate that playback has completed.
• This method also clears error states for the clip, which is useful if playback was retried after a failure.
• The index parameter should match the index that was passed to didStartPlayingClip().
• This method is synchronous and doesn't perform any network operations.