Maestro Event Interface

Introduction

The Maestro Event Interface (IMaestroEvent) defines a set of methods for interacting with the current event. These methods allow you to control panel visibility, manage playback, and access state information. The interface is implemented by the MaestroEventViewModel and is available after calling userDidStartWatchingEvent().

Interface

interface IMaestroEvent {
  /**
   * @description Tells the SDK that the user just started playing a new key play clip at the given index.
   */
  didStartPlayingClip(index: number): void;

  /**
   * @description Tells the SDK that the user just stopped playing a key play clip at the given index.
   */
  didStopPlayingClip(index: number): void;

  /**
   * @description Tells the SDK that the user tried to play the clip but it failed to play back.
   */
  didFailToPlayClip(index: number): void;

  /**
   * @description Updates the SDK with the latest progress in the playback of the currently-played key play clip, from 0 to 1.
   */
  didUpdatePlaybackProgressOfClip(index: number, to: number): void;

  /**
   * @description Tells the SDK that the app displayed the MaestroPanel.
   */
  didShowPanel(): Promise<void>;

  /**
   * @description Tells the SDK that the app hid the MaestroPanel.
   */
  didHidePanel(): Promise<void>;

  /**
   * @description Alerts the SDK that the current event does not support key plays.
   */
  currentEventDoesNotSupportKeyPlays(): void;

  /**
   * @description Retrieves the event ID for the currently loaded event.
   */
  getCurrentEventID(): string | null;

  /**
   * @description Retrieves the array index of the key play clip that is currently being played.
   */
  getCurrentlyPlayingClipIndex(): number | null;

  /**
   * @description Retrieves the array index of the key plays clip that was most recently played.
   */
  getLastPlayedClipIndex(): number | null;

  /**
   * @description Retrieves the progress (between 0 and 1) of the currently-played key play clip.
   */
  getCurrentClipPlaybackProgress(): number | null;

  /**
   * @description Retrieves the number of key plays.
   */
  getKeyPlaysCount(): number | null;

  /**
   * @description Tells the SDK to start managing focus.
   */
  startFocusManagement(): Promise<void>;

  /**
   * @description Feeds the SDK new key plays data. A null value indicates a failure to retrieve the data.
   */
  updateKeyPlaysData(data: IMaestroKeyPlaysResponse | null): Promise<void>;
}

Table of Contents

Panel Management

• Panel Management
  • didShowPanel()
  • didHidePanel()
  • currentEventDoesNotSupportKeyPlays()

Playback Controls

• Playback Controls
  • didStartPlayingClip()
  • didStopPlayingClip()
  • didFailToPlayClip()
  • didUpdatePlaybackProgressOfClip()

State Access

• State
  • getCurrentEventID()
  • getCurrentlyPlayingClipIndex()
  • getLastPlayedClipIndex()
  • getCurrentClipPlaybackProgress()
  • getKeyPlaysCount()
  • updateKeyPlaysData()

Focus Management

• Focus Management

Key Responsibilities

• Panel Management:
  Methods like didShowPanel() and didHidePanel() allow you to notify the SDK when the panel's visibility changes, enabling proper state management and analytics tracking.

• Playback Control:
  Methods like didStartPlayingClip(), didStopPlayingClip(), and didUpdatePlaybackProgressOfClip() enable you to inform the SDK about the state of clip playback, allowing the UI to update accordingly.

• State Access:
  Methods like getCurrentEventID(), getCurrentlyPlayingClipIndex(), and getKeyPlaysCount() provide access to the current state of the event, allowing your application to make informed decisions.

• Data Updates:
  The updateKeyPlaysData() method allows you to update the key plays data displayed in the panel, either when new data becomes available or when the user explicitly requests a refresh.

• Focus Management:
  The startFocusManagement() method helps manage focus transitions between the SDK UI and your application, ensuring a seamless navigation experience.

The Maestro Event Interface creates a clear contract between your application and the SDK, enabling bidirectional communication for panel management, playback control, and state access. This interface is core to the SDK's functionality and is designed to work seamlessly with the Event Delegate implementation in your application.