colibrio-reader-framework/com.colibrio.readingsystem.base/EpubReaderPublication/createMediaOverlaySyncMediaTimeline

createMediaOverlaySyncMediaTimeline

abstract fun createMediaOverlaySyncMediaTimeline(readerDocuments: List<ReaderDocument>, config: MediaOverlaySyncMediaTimelineConfiguration, onSuccess: (SyncMediaTimeline) -> Unit, onError: (ColibrioException) -> Unit, progressCallback: (Double) -> Unit = {})

Creates a new EPUB Media Overlay SyncMediaTimeline if available in the publication.

You can check if this publication contains Media Overlays by checking if availableSyncMediaFormats contains SyncMediaFormat.EPUB_MEDIA_OVERLAY.

For more information about EPUB Media Overlays, see: https://www.w3.org/publishing/epub3/epub-mediaoverlays.html

Parameters

readerDocuments

  • The reader documents that should be part of the timeline.

config

  • Configuration of the timeline.

onSuccess
onError

  • Called if there was an error creating the timeline.

progressCallback

  • A function called several times indicating the create progress as a value between 0 and 1.

abstract suspend fun createMediaOverlaySyncMediaTimeline(readerDocuments: List<ReaderDocument>, config: MediaOverlaySyncMediaTimelineConfiguration, progressCallback: (Double) -> Unit = {}): ColibrioResult<SyncMediaTimeline>

Creates a new EPUB Media Overlay SyncMediaTimeline if available in the publication.

You can check if this publication contains Media Overlays by checking if availableSyncMediaFormats contains SyncMediaFormat.EPUB_MEDIA_OVERLAY.

For more information about EPUB Media Overlays, see: https://www.w3.org/publishing/epub3/epub-mediaoverlays.html

Threading

Call this from the main dispatcher. Called from another dispatcher, the cleanup that runs when the calling coroutine is cancelled may not reach the reading system, leaving the timeline behind.

Cancelled calls

Cancelling does not abort a timeline the reading system has already started building. Such a timeline may still be created, and because you never receive its handle it cannot be destroyed afterwards - unlike a TTS or content position timeline, it is not released when the publication is unloaded either. Prefer letting the call finish and then calling destroySyncMediaTimeline.

Return

Either ColibrioResult.Success when the SyncMediaTimeline has been created successfully, or ColibrioResult.Error if an error occurred while creating the timeline.

Parameters

readerDocuments

  • The reader documents that should be part of the timeline.

config

  • Configuration of the timeline.

progressCallback

  • A function called several times indicating the create progress as a value between 0 and 1.

abstract fun createMediaOverlaySyncMediaTimeline(readerDocuments: List<ReaderDocument>, onSuccess: (SyncMediaTimeline) -> Unit, onError: (ColibrioException) -> Unit, progressCallback: (Double) -> Unit = {})

Creates a new EPUB Media Overlay SyncMediaTimeline if available in the publication.

You can check if this publication contains Media Overlays by checking if availableSyncMediaFormats contains SyncMediaFormat.EPUB_MEDIA_OVERLAY.

This method will use default MediaOverlaySyncMediaTimelineConfiguration

For more information about EPUB Media Overlays, see: https://www.w3.org/publishing/epub3/epub-mediaoverlays.html

Parameters

readerDocuments

  • The reader documents that should be part of the timeline.

onSuccess
onError

  • Called if there was an error creating the timeline.

progressCallback

  • A function called several times indicating the create progress as a value between 0 and 1.

abstract suspend fun createMediaOverlaySyncMediaTimeline(readerDocuments: List<ReaderDocument>, progressCallback: (Double) -> Unit = {}): ColibrioResult<SyncMediaTimeline>

Creates a new EPUB Media Overlay SyncMediaTimeline if available in the publication.

You can check if this publication contains Media Overlays by checking if availableSyncMediaFormats contains SyncMediaFormat.EPUB_MEDIA_OVERLAY.

This method will use default MediaOverlaySyncMediaTimelineConfiguration

For more information about EPUB Media Overlays, see: https://www.w3.org/publishing/epub3/epub-mediaoverlays.html

Threading

Call this from the main dispatcher. Called from another dispatcher, the cleanup that runs when the calling coroutine is cancelled may not reach the reading system, leaving the timeline behind.

Cancelled calls

Cancelling does not abort a timeline the reading system has already started building. Such a timeline may still be created, and because you never receive its handle it cannot be destroyed afterwards - unlike a TTS or content position timeline, it is not released when the publication is unloaded either. Prefer letting the call finish and then calling destroySyncMediaTimeline.

Return

Either ColibrioResult.Success when the SyncMediaTimeline has been created successfully, or ColibrioResult.Error if an error occurred while creating the timeline.

Parameters

readerDocuments

  • The reader documents that should be part of the timeline.

progressCallback

  • A function called several times indicating the create progress as a value between 0 and 1.