Timeline API

[JayPanoz]

Timeline API

Introduction

The Timeline API provides a unified way for reading applications to understand where users are within a publication and provide meaningful context about their current location.

Purpose

Reading applications today struggle to answer basic questions like "What chapter/section am I currently reading?" or "Where does this chapter start?" across different publication formats. The Timeline API addresses this gap by providing consistent access to structural information and position context, regardless of whether the publication is an EPUB, audiobook, PDF, or web publication.

Use Cases

The Timeline API enables several key user experience features:

Navigation Features

• Progression Bars: Visual timelines with variants and contextualization, allowing users to see which chapter they'll navigate to when hovering or clicking
• Running Headers: Display current chapter/section information in application headers
• Navigation: Show next and previous chapter names in bottom navigation bars
• Table of Contents: Infer current TOC section and get position numbers/ranges for TOC items

Content Context Features

• Search Results: Group search results by chapters/sections for better context
• Bookmarks and Highlights: Provide context about which chapter/section contains user annotations

Content Types

The Timeline API works across all publication types supported by Readium:

Time-Based Publications

• Examples: Audiobooks, videos with synchronized text
• Position Model: Time-based (seconds, minutes)
• Use Case: Chapter boundaries defined by time markers

Page-Based Publications

• Examples: PDFs, fixed-layout EPUBs, comic books
• Position Model: Page numbers and coordinates
• Use Case: Direct mapping between page numbers and content sections

Reflowable Publications

• Examples: Reflowable EPUBs, web publications
• Position Model: Dynamic positioning based on content flow
• Use Case: Adapting to different screen sizes and user preferences

Readium Architecture Context

The Timeline API integrates with existing Readium components:

Readium Web Publication Manifest (RWPM)

• Reading Order: Defines the sequence of content resources
• Table of Contents: Provides structural hierarchy for navigation – we may not always have this available

Positions List

• Pre-computed position information for publications
• We may not always have this available

Guided Navigation

• Additional navigation structures beyond basic TOC

Locator

• Standardized References: Consistent way to reference any location in any publication
• Media Support: Handles text, audio, video, and image content

Technical Implementation

Data Integration

The Timeline API requires consolidating data from multiple sources:

• Reading Order: Defines sequence of content resources
• Table of Contents: Provides structural hierarchy – we may not always have this available
• Position Lists: Pre-computed position information – we may not always have this available
• Guided Navigation: Additional navigation structures beyond basic TOC

Performance Considerations

• In-Memory Representation: Timeline data kept in memory for reuse
• Caching: Time-consuming operations (like ID resolution) require caching
• Resource Access: Web publications may lack direct access to resources

Possible Approaches

• EPUB/Web: Intersection observers on IDs for viewport detection
• Audiobooks: Track metadata and time markers for timeline positioning
• PDFs/Prepaginated: Page-based positioning

Related Work

• OPDS Progression: Shares concepts with timeline API for progression tracking