ThumbnailsApi

@objcMembers
@objc(BMPThumbnailsApi)
public class ThumbnailsApi : NSObject

Provides the means to interact and manage thumbnails. Accessible through Player.thumbnails.

This API is not supported during casting.

  • Registers a container view for the thumbnails to be rendered in.

    All subviews of the registered container will be managed by the SDK. If the view parameter has value nil, the SDK will stop rendering the thumbnails in the previously provided container. Only one container can be registered at a time.

    Important

    Visibility of the container has to be managed by the application.

    Note

    To trigger the rendering of a thumbnail for a specific time, use renderThumbnail(forTime:) or renderThumbnail(for:time:).

    Declaration

    Swift

    public func registerContainer(_ view: UIView?)

    Parameters

    view

    The view to render the thumbnails in. Pass nil to unregister the current container.

  • Returns the thumbnail image for the active Source at a certain time. Requires a configured ThumbnailTrack in the corresponding SourceConfig.

    This function returns nil in the following cases:

    • If there is no active source.
    • If the thumbnails were not loaded yet.
    • If there are no ThumbnailTracks provided in the corresponding SourceConfigs.

    • If there is no thumbnail available at the provided time.

    Declaration

    Swift

    public func thumbnail(forTime time: TimeInterval) -> Thumbnail?

    Parameters

    time

    The time for which the thumbnail should be returned.

    Return Value

    An instance of Thumbnail for the given time, or nil.

  • Renders a thumbnail for a specific time in the registered thumbnail container utilizing the media data instead of an optionally configured ThumbnailTrack. For the best performance, it is recommended to be used with HLS streams, that have EXT-X-I-FRAME-STREAM-INF tags with I-Frame playlists.

    Important

    A container must be registered using registerContainer(_:) before calling this method. If no container is registered, this method will always return false.

    When called:

    • The thumbnail for the specified time will be rendered and displayed in the registered container.
    • If the rendering succeeds, the method will return true.
    • If rendering fails, the method will return false.

    Behavior on Multiple Calls:

    • If this method is called again while a previous thumbnail rendering is still in progress, the pending rendering will be canceled.

    • The previously pending call will return false once canceled.

    Declaration

    Swift

    public func renderThumbnail(
    forTime time: TimeInterval,
    toleranceBefore: TimeInterval = DefaultValues.toleranceBefore,
    toleranceAfter: TimeInterval = DefaultValues.toleranceAfter
) async -> Bool

    Parameters

    time

    The time for which the thumbnail should be rendered.
    toleranceBefore

    The allowed time tolerance before the specified time. Passing 0 will request frame accurate seeking, which may incur additional decoding delay. Default value is 10 seconds.
    toleranceAfter

    The allowed time tolerance after the specified time. Passing 0 will request frame accurate seeking, which may incur additional decoding delay. Default value is 10 seconds.

    Return Value

    true if the thumbnail is successfully rendered and displayed in the container. false if rendering failed, canceled or no container is registered.

  • Renders a thumbnail for a specific time and source in the registered thumbnail container utilizing the media data instead of an optionally configured ThumbnailTrack. For the best performance, it is recommended to be used with HLS streams, that have EXT-X-I-FRAME-STREAM-INF tags with I-Frame playlists. If no container is registered, this function will return false.

    Important

    A container must be registered using registerContainer(_:) before calling this method. If no container is registered, this method will always return false.

    When called:

    • The thumbnail for the specified time will be rendered and displayed in the registered container.
    • If the rendering succeeds, the method will return true.
    • If rendering fails, the method will return false.

    Behavior on Multiple Calls:

    • If this method is called again while a previous thumbnail rendering is still in progress, the pending rendering will be canceled.

    • The previously pending call will return false once canceled.

    Declaration

    Swift

    public func renderThumbnail(
    for source: Source,
    time: TimeInterval,
    toleranceBefore: TimeInterval = DefaultValues.toleranceBefore,
    toleranceAfter: TimeInterval = DefaultValues.toleranceAfter
) async -> Bool

    Parameters

    source

    The source for which the thumbnail should be rendered from. This source has to be part of the playlist already.
    time

    The time for which the thumbnail should be rendered.
    toleranceBefore

    The allowed time tolerance before the specified time. Passing 0 will request frame accurate seeking, which may incur additional decoding delay. Default value is 10 seconds.
    toleranceAfter

    The allowed time tolerance after the specified time. Passing 0 will request frame accurate seeking, which may incur additional decoding delay. Default value is 10 seconds.

    Return Value

    true if the thumbnail is successfully rendered and displayed in the container. false if rendering failed, canceled or no container is registered.