Taleem Player Engine

The Taleem Player Engine is a time-based playback engine.

It renders Taleem decks by computing visibility as a function of absolute time.

The player does not infer, guess, or correct timing. It enforces the timing contract exactly as written.

What the Player Engine Does

• accepts a valid deck-v1 Taleem deck
• tracks a playback clock provided by the application
• computes slide visibility from start / end
• computes item visibility from showAt
• renders progressive, time-synced presentations

What the Player Engine Does Not Do

• edit or mutate deck data
• guess missing or invalid timings
• manage audio or narration playback
• own the system clock
• repair malformed decks

These responsibilities belong to the application layer.

Public API

The player engine exposes a single factory function.

import { createTaleemPlayer } from "taleem-player";

const player = createTaleemPlayer({
  mount: "#app",
  deck
});

This creates a time-driven playback controller over a validated deck.

Player Instance API

{
  play(): void,
  pause(): void,
  stop(): void,

  seek(time: number): void,
  setRate(rate: number): void,

  getCurrentTime(): number,
  getVisibleSlides(): Slide[],
  getVisibleItems(slideIndex: number): Item[]
}

Timing Model

All visibility decisions are computed from:

• slide start and end times
• item showAt timestamps

There is no concept of:

• relative time
• slide-local time
• implicit sequencing

Time is absolute and global across the entire deck.

Mental Model

What should be visible at time T?

At any given moment, the player answers this question deterministically.

Given the same deck and the same time input, the output is always the same.

Relationship to Browser Engine

The two engines serve different, non-overlapping purposes.

Player Engine moves by time, not by slide index.

• Browser Engine selects slides explicitly
• Player Engine reveals content progressively

Neither engine is a fallback for the other.

Failure Mode (By Design)

If timing data is invalid:

• items may never appear
• slides may collapse to zero duration
• playback may appear incorrect

These failures are intentional.

The player does not correct authoring mistakes, because silent correction breaks determinism.

Stability

The Player Engine API is stable and frozen.

Internal optimizations may continue, but public behavior will not change without a schema version bump.