didFailToPlayClip

Indicates that a clip failed to play.

Overview

Call this method when your video player fails to play a clip. This allows the SDK to update its UI to reflect the error state and potentially retry or handle the error appropriately.

Method Signature

didFailToPlayClip(index: number): void

Parameters

Parameter	Type	Description
index	number	The index of the clip that failed to play, corresponding to its position in the flattened key plays array

Return Value

This method does not return a value.

Example Usage

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

// Example of handling clip playback failure
function handleClipPlaybackError(clipIndex: number, error: Error) {
  console.error(`Failed to play clip at index ${clipIndex}:`, error);
  
  // Get the event view model
  const event = SDK.getMaestroEventViewModel();
  
  // Notify the SDK about the failure
  event.didFailToPlayClip(clipIndex);
  
  // Clean up any resources
  cleanupPlayback();
  
  // Optionally show a custom error UI
  showErrorUI(`Failed to play clip: ${error.message}`);
  
  // Optionally try to play the next clip
  const totalClips = event.getKeyPlaysCount();
  if (clipIndex + 1 < totalClips) {
    playClip(clipIndex + 1);
  }
}

// Integration with a video player
function playClip(clipIndex: number) {
  try {
    // Get clip URL or ID
    const clipUrl = getClipUrl(clipIndex);
    
    // Set up video player
    videoPlayer.src = clipUrl;
    
    // Set up error handling
    videoPlayer.onerror = (error) => {
      handleClipPlaybackError(clipIndex, error);
    };
    
    // Start playback
    videoPlayer.play()
      .then(() => {
        // Get the event view model
        const event = SDK.getMaestroEventViewModel();
        
        // Notify the SDK that playback has started
        event.didStartPlayingClip(clipIndex);
      })
      .catch((error) => {
        handleClipPlaybackError(clipIndex, error);
      });
  } catch (error) {
    handleClipPlaybackError(clipIndex, error);
  }
}

Integration with HTML5 Video

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

// Example with HTML5 video element
function setupHtml5VideoErrorHandling() {
  const videoElement = document.getElementById('video-player') as HTMLVideoElement;
  const event = SDK.getMaestroEventViewModel();
  
  // Listen for error events
  videoElement.addEventListener('error', () => {
    const currentClipIndex = event.getCurrentlyPlayingClipIndex();
    
    if (currentClipIndex !== null) {
      // Get error details
      const error = videoElement.error;
      const errorMessage = error ? `Code: ${error.code}, Message: ${error.message}` : 'Unknown error';
      console.error(`Video playback error: ${errorMessage}`);
      
      // Notify the SDK about the failure
      event.didFailToPlayClip(currentClipIndex);
    }
  });
}

Error Handling Strategy

When a clip fails to play, you have several options for handling the error:

1. Skip to next clip: Automatically move on to the next clip
2. Retry playback: Attempt to play the same clip again (possibly with a different quality or source)
3. Display error: Show an error message to the user
4. Combined approach: Retry a certain number of times, then skip or show an error

Here's an example of a retry strategy:

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

// Example of a retry strategy
function playClipWithRetry(clipIndex: number, maxRetries = 2) {
  let retryCount = 0;
  
  function attemptPlayback() {
    try {
      // Get clip URL or ID
      const clipUrl = getClipUrl(clipIndex);
      
      // Set up video player
      videoPlayer.src = clipUrl;
      
      // Set up error handling
      videoPlayer.onerror = () => {
        retryCount++;
        
        if (retryCount <= maxRetries) {
          console.warn(`Retrying playback (attempt ${retryCount} of ${maxRetries})`);
          attemptPlayback();
        } else {
          console.error(`Failed to play clip after ${maxRetries} attempts`);
          
          // Notify the SDK about the failure
          const event = SDK.getMaestroEventViewModel();
          event.didFailToPlayClip(clipIndex);
          
          // Try the next clip or show error UI
          handleFailureAfterRetries(clipIndex);
        }
      };
      
      // Start playback
      videoPlayer.play()
        .then(() => {
          // Get the event view model
          const event = SDK.getMaestroEventViewModel();
          
          // Notify the SDK that playback has started
          event.didStartPlayingClip(clipIndex);
        })
        .catch((error) => {
          videoPlayer.onerror(error);
        });
    } catch (error) {
      videoPlayer.onerror(error);
    }
  }
  
  // Start the first attempt
  attemptPlayback();
}

Internal Behavior

When didFailToPlayClip() is called, the SDK updates the error state for the clip:

didFailToPlayClip(index: number): void {
  this.keyPlaysViewModel.handleKeyPlayLoadFailure(index);
}

// In KeyPlaysViewModel
handleKeyPlayLoadFailure(forKeyPlayAtIndex: number): void {
  const clipID = this.clipID(forKeyPlayAtIndex);
  if (clipID) {
    const newFailedClips = this.failedClips.value;
    newFailedClips[clipID] = 'recentFailure';
    
    this.failedClips.value = newFailedClips;
    
    // After 5 seconds, change the status from 'recentFailure' to 'nonRecentFailure'
    setTimeout(() => {
      if (this.loadFailureStatus(forKeyPlayAtIndex) === 'recentFailure') {
        const newFailedClips = this.failedClips.value;
        newFailedClips[clipID] = 'nonRecentFailure';
        this.failedClips.value = newFailedClips;
      }
    }, 5000);
  }
}

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

1. Displaying an error indicator for the clip
2. Possibly adjusting the UI to indicate that the clip is in an error state
3. After 5 seconds, transitioning from a "recent failure" state to a "non-recent failure" state, which may affect the UI

Notes

• Call this method as soon as you determine that a clip cannot be played, whether due to network errors, format issues, or other problems.
• The error state goes through two phases: "recent failure" (first 5 seconds) and "non-recent failure" (after 5 seconds). This allows the UI to show different visual feedback based on how recently the error occurred.
• After calling this method, you can attempt to play a different clip, retry the same clip, or allow the user to choose what to do next.
• This method is synchronous and doesn't perform any network operations.
• If you retry playback successfully, the successful didStartPlayingClip() call will clear the error state.