com.brightcove.ssai.timeline

## Interface Timeline

-     public interface Timeline

  The Timeline interface is a representation of a single SSAI video, that is, a video with its Ads stitched in the video itself.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `Timeline.Type` The Timeline Type.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `MILLISECONDS_IN_MICROS`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getAbsolutePlayheadPosition(long contentPlayheadPosition)` Converts the relative content position to its absolute playhead position.
    `java.util.List<java.lang.Long>` | `getAdMarkerPositions()` It returns a list of Ad markers positions with respect to the relative content timeline.
    `AdPod` | `getAdPodAt(long absolutePlayheadPosition)` Returns the Ad pod at the position specified by the absolute playhead position, if the position belongs to an Ad, or null if it belongs to content.
    `java.util.List<AdPod>` | `getAdPods()` Searchs through the timeline and returns the list of Ad Pods that belongs to those Ad Timeline Blocks.
    `long` | `getContentLength()` It returns the content duration.
    `long` | `getContentPlayheadPosition(long absolutePlayheadPosition)` Calculates the corresponding content playhead position given the absolute playhead position, that is, the playhead position as if there were no Ads stitched to the content.
    `long` | `getRelativePlayheadPosition(long absolutePlayheadPosition)` Calculates the relative playhead position given the absolute playhead position.
    `TimelineBlock` | `getTimelineBlockAt(long absolutePlayheadPosition)` Returns the `TimelineBlock` at the specified absolutePlayheadPosition.
    `long` | `getTotalLength()` It returns the total duration of the video.
    `Timeline.Type` | `getType()` Gets the Timeline type.
    `boolean` | `isPlayingAd(long absolutePlayheadPosition)` Checks the playhead position and verifies whether we are inside an Ad block or not.
    `default void` | `notifyTimedAdPodFound(AdPod adPod)` Notifies this timeline that an `AdPod` has been found as timed metadata.
    `default void` | `reset()` Resets this timeline to its default initial value.
    `default void` | `updatePlayableWindow(long minimumPlayheadPosition, long maximumPlayheadPosition)` Updates the playable window within the Timeline.

- - ### Field Detail

    - #### MILLISECONDS_IN_MICROS

          static final long MILLISECONDS_IN_MICROS

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getType

          Timeline.Type getType()

      Gets the Timeline type.
      Returns:
        the type

    - #### getContentLength

          long getContentLength()

      It returns the content duration. Also known as relative duration. This is the duration of the original content without the duration of the stitched Ad videos.
      Returns:
        the duration in milliseconds

    - #### getTotalLength

          long getTotalLength()

      It returns the total duration of the video. It includes the duration of the content plus the duration of the stitched Ad videos.
      Returns:
        the duration in milliseconds

    - #### getContentPlayheadPosition

          long getContentPlayheadPosition(long absolutePlayheadPosition)

      Calculates the corresponding content playhead position given the absolute playhead position, that is, the playhead position as if there were no Ads stitched to the content.

      If the absolute playhead position corresponds to: - a pre-roll Ad, 0 will be returned. - a post-roll Ad, the content length will be returned. - a mid-roll Ad, the ad offset with respect to the content will be returned.

      If the absolute playhead position is outside the bounds of the total length, 0 will be returned.

      Parameters:
        `absolutePlayheadPosition` - the absolute playhead position in milliseconds.
      Returns:
        the corresponding content playhead position in milliseconds.
      See Also:
        `getRelativePlayheadPosition(long).`

    - #### getRelativePlayheadPosition

          long getRelativePlayheadPosition(long absolutePlayheadPosition)

      Calculates the relative playhead position given the absolute playhead position.

      If the absolute playhead position corresponds to: - a content block, it will return `getContentPlayheadPosition(long)`. - a single Ad block, the relative position of the Ad will be returned. - an Ad that belongs to an Ad pod (a sequenced group of ads), the position relative to the Ad pod will be returned.

      If the absolute playhead position is outside the bounds of the total length, 0 will be returned.

      Parameters:
        `absolutePlayheadPosition` - the absolute playhead position in milliseconds.
      Returns:
        the corresponding relative playhead position in milliseconds.
      See Also:
        `getContentPlayheadPosition(long).`

    - #### getAbsolutePlayheadPosition

          long getAbsolutePlayheadPosition(long contentPlayheadPosition)

      Converts the relative content position to its absolute playhead position.

      The content playhead position should be greater than 0 and lower or equals than `getContentLength()`, otherwise the value will be capped to the nearest limit, that is, negative values will be capped to 0 and values greater than `getContentLength()` will be capped to `getContentLength()`.

      Parameters:
        `contentPlayheadPosition` - the relative content playhead position in milliseconds.
      Returns:
        the the absolute playhead position in milliseconds.

    - #### getAdPodAt

          @Nullable
          AdPod getAdPodAt(long absolutePlayheadPosition)

      Returns the Ad pod at the position specified by the absolute playhead position, if the position belongs to an Ad, or null if it belongs to content.

      if the method `isPlayingAd(long)` returns true with the same playhead position, the AdPod must not be null.

      Parameters:
        `absolutePlayheadPosition` - the absolute playhead position in milliseconds.
      Returns:
        the Ad pod, if available.
      See Also:
        `isPlayingAd(long)`

    - #### getAdPods

          java.util.List<AdPod> getAdPods()

      Searchs through the timeline and returns the list of Ad Pods that belongs to those Ad Timeline Blocks.
      Returns:
        the list of Ad Pods available in the timeline.

    - #### isPlayingAd

          boolean isPlayingAd(long absolutePlayheadPosition)

      Checks the playhead position and verifies whether we are inside an Ad block or not.
      Parameters:
        `absolutePlayheadPosition` - the absolute playhead position in milliseconds
      Returns:
        true is we are in an Ad block.

    - #### getAdMarkerPositions

          @NonNull
          java.util.List<java.lang.Long> getAdMarkerPositions()

      It returns a list of Ad markers positions with respect to the relative content timeline.
      Returns:
        the list of Ad marker positions.

    - #### getTimelineBlockAt

          @Nullable
          TimelineBlock getTimelineBlockAt(long absolutePlayheadPosition)

      Returns the `TimelineBlock` at the specified absolutePlayheadPosition.
      Parameters:
        `absolutePlayheadPosition` - the absolute playhead position in milliseconds.
      Returns:
        the `TimelineBlock` at the specified absolutePlayheadPosition.

    - #### updatePlayableWindow

          default void updatePlayableWindow(long minimumPlayheadPosition,
                                            long maximumPlayheadPosition)

      Updates the playable window within the Timeline. This method only applies for Timelines of type `Timeline.Type.DYNAMIC`.

      Note: The default implementation does nothing. It can be overridden to provide the desired implementation.

      Parameters:
        `minimumPlayheadPosition` - the minimum playable position
        `maximumPlayheadPosition` - the maximum playable position

    - #### notifyTimedAdPodFound

          default void notifyTimedAdPodFound(AdPod adPod)

      Notifies this timeline that an `AdPod` has been found as timed metadata.

      Note: The default implementation does nothing. It can be overridden to provide the desired implementation.

      Parameters:
        `adPod` - the AdPod found

    - #### reset

          default void reset()

      Resets this timeline to its default initial value.

      Note: The default implementation does nothing. It can be overridden to provide the desired implementation.