didStartPlayingClip

Indicates that a clip has started playing.

Overview

Call this method when your video player starts playing a clip. This allows the SDK to update its UI to reflect the current playback state.

Method Signature

didStartPlayingClip(index: number): void

Parameters

Parameter	Type	Description
index	number	The index of the clip that has started playing, 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 playing a clip and notifying the SDK
function playClip(clipIndex: number) {
  // Get the clip ID or URL from your data source
  const clipId = getClipId(clipIndex);
  
  // Start playing the clip in your video player
  videoPlayer.load(clipId);
  videoPlayer.play();
  
  // Notify the SDK that the clip has started playing
  const event = SDK.getMaestroEventViewModel();
  event.didStartPlayingClip(clipIndex);
  
  // Set up progress reporting
  startProgressReporting(clipIndex);
  
  // Set up completion detection
  videoPlayer.onEnded(() => {
    event.didStopPlayingClip(clipIndex);
  });
}

// Helper function to report progress to the SDK
function startProgressReporting(clipIndex: number) {
  // Clear any existing progress reporting
  if (progressInterval) {
    clearInterval(progressInterval);
  }
  
  // Set up an interval to report progress
  progressInterval = setInterval(() => {
    const progress = videoPlayer.currentTime / videoPlayer.duration;
    
    // Report progress to the SDK (value between 0 and 1)
    const event = SDK.getMaestroEventViewModel();
    event.didUpdatePlaybackProgressOfClip(clipIndex, progress);
    
    // If we've reached the end, stop reporting and notify completion
    if (progress >= 1) {
      clearInterval(progressInterval);
      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 playClipWithHtml5Video(clipIndex: number, clipUrl: string) {
  const videoElement = document.getElementById('video-player') as HTMLVideoElement;
  
  // Set up the video source
  videoElement.src = clipUrl;
  
  // Get the event view model
  const event = SDK.getMaestroEventViewModel();
  
  // Set up event listeners for the video element
  videoElement.onplay = () => {
    // Notify the SDK that the clip has started playing
    event.didStartPlayingClip(clipIndex);
  };
  
  videoElement.ontimeupdate = () => {
    // Report progress to the SDK
    const progress = videoElement.currentTime / videoElement.duration;
    if (!isNaN(progress)) {
      event.didUpdatePlaybackProgressOfClip(clipIndex, progress);
    }
  };
  
  videoElement.onended = () => {
    // Notify the SDK that the clip has completed
    event.didStopPlayingClip(clipIndex);
  };
  
  videoElement.onerror = () => {
    // Notify the SDK that the clip failed to play
    event.didFailToPlayClip(clipIndex);
  };
  
  // Start playing
  videoElement.load();
  videoElement.play().catch(error => {
    console.error('Error playing video:', error);
    event.didFailToPlayClip(clipIndex);
  });
}

Internal Behavior

When didStartPlayingClip() is called, the SDK updates several state properties in the KeyPlaysViewModel:

didStartPlayingClip(index: number) {
  this.keyPlaysViewModel.lastPlayedClipIndex.value = index;
  this.keyPlaysViewModel.currentClipPlaybackProgress.value = 0;
  this.keyPlaysViewModel.currentlyPlayingClipIndex.value = index;
  this.keyPlaysViewModel.clearLoadFailureStatus(index);
}

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

1. Highlighting the currently playing clip
2. Showing a progress indicator
3. Possibly scrolling the panel to make the playing clip visible
4. Clearing any previous error states for this clip

Notes

• Call this method as soon as the clip actually starts playing, not when it starts loading.
• The index parameter corresponds to the position in the flattened array of all key plays, regardless of their sections.
• This method is part of a series of methods for tracking clip playback:
  • didStartPlayingClip() - Called when playback starts
  • didUpdatePlaybackProgressOfClip() - Called periodically during playback
  • didStopPlayingClip() - Called when playback completes
  • didFailToPlayClip() - Called if playback fails
• This method is synchronous and doesn't perform any network operations.
• After calling this method, you should regularly call didUpdatePlaybackProgressOfClip() to update the progress indicator.