--- title: "Timeline" description: "Clover's player for IIIF Presentation 4 Timelines: sound, played as a music app plays it, with its artwork, Canvas's transport, captions as lyrics and chapters as tracks, on its own or in a Root." url: https://clover.iiif.library.northwestern.edu/docs/timeline version: "4" --- # Timeline \ (web components: \)44 kB loaded by a page with it alone to first view, gzipped (web components: 92 kB loaded by a page with it alone to first view, styles included, gzipped) Sound, as Presentation 4 shapes it: a Timeline, played as a music app plays it, its artwork beside its title, its captions as lyrics and its chapters as tracks. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx
``` **Web components** ```html
``` ## API reference Plays the Presentation 4 Timeline you hand it, or loads one itself (`iiifContent` (web components: `iiif-content`): a Manifest gives its first Timeline). Inside a `Root` (web components: ``), given nothing, it plays the Root’s view when that is a Timeline; [`Body` (web components: ``)](https://clover.iiif.library.northwestern.edu/docs/body) draws a Timeline view with it. A Presentation 3 Canvas of sound alone is a Timeline once upgraded, so the Viewer plays one with it too. It fills its parent, so give the parent a height. It plays through [Canvas](https://clover.iiif.library.northwestern.edu/docs/canvas), with its transport, captions, chapters and annotations on the recording’s time, as a player: the Timeline’s label is its title and its Manifest’s is under it; its captions and annotations show as lyrics; and where it has room, its chapters are listed as tracks under it. Its artwork is the Timeline’s placeholder Canvas until it first plays, then its accompanying Canvas, each standing in for the other, else its thumbnail, at its own shape. The player’s ground takes the artwork’s colors. **React** | Prop | Type | Default | Description | | ----------------- | ---------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeline` | `object` | The Root’s view | A Presentation 4 Timeline to play; `toPresentation4()` upgrades older ones. | | `iiifContent` | `string \| object` | — | A Timeline to load and play, or a Manifest’s first: URL or JSON. | | `label` | language map or `string` | The Timeline’s label | The view’s accessible name, and the player’s title. | | `partOf` | language map or `string` | The Manifest’s label | What it is part of, under its title. | | `language` | `string` | The reader’s, or the Root’s | The language to read labels, captions’ names and annotations in. | | `highContrast` | `boolean` | `false` | Clover’s higher-contrast mode: the accent kept to rings, outlines and marks, never under words or a glyph. Inside a `Root`, the Root’s too; on wherever the reader’s system asks for more contrast. | | `controls` | `boolean \| { annotations, information }` | `true` | The round controls over the Body; the transport stays. | | `placeholder` | `boolean` | `true` | Show the Timeline’s `placeholderContainer` as its artwork until it plays. | | `annotations` | `{ annotation, targetIndex, pageLabel?, pageId? }[]` | The Root’s | Annotations on its time, each a cue while its stretch plays. | | `chapters` | `{ id?, label, lang?, start, end? }[]` | The Ranges, in a `Root` | Chapters, on its seek bar, in a menu, and as tracks where there is room. | | `caption` | `string \| null` | — | The caption file (`id`) to show while captions are on. | | `onCaptionChange` | `(caption: { id, language? } \| null) => void` | — | The reader chose a caption file, or Off (`null`). | | `onMediaElement` | `(element: HTMLVideoElement \| null) => void` | — | The recording’s element, for a transcript of your own. | | `onEnded` | `() => void` | — | Playback reached the end: a cue to move on. | | `options` | `object` | — | Canvas’s: `request` and `hideDelay` among them. | | `className` | `string` | — | Added to `clover-canvas clover-timeline`, on its `figure`. | | `children` | `ReactNode` | — | Your own controls, kept over the Body. | **Web components** ### `` A IIIF Presentation 4 Timeline (sound), played through Canvas, with its transport, captions, chapters and annotations on its time, and its accompanying or placeholder Canvas while it plays. Alone, it plays what it is given; inside a clover-root, given nothing, the root's view when that is a Timeline. As tall as --clover-body-height (60vh) or its own style. | Name | Type | Default | Description | | ----------------------- | ------------------------------------------------------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iiif-content` | `string` | — | A Timeline, or a Manifest (its first Timeline), by URL, in any Presentation version. | | `label` | `string` | — | The Body's name. A Timeline names it by its own label. | | `language` | `string` | — | The language to read IIIF text in. | | `high-contrast` | `boolean` | `false` | Clover's higher-contrast mode, for what is inside: the accent kept to rings, outlines and marks, never under words or a glyph, where the controls' dark fill takes its place, edged in the accent. On wherever the reader's system asks for more contrast, too. | | `controls` | `boolean` | `true` | "false" leaves out the controls over the Body; the transport stays. | | `placeholder` | `boolean` | `true` | "false" opens a Timeline straight away, past its placeholderContainer. | | `.iiifContent` | `string \| Record \| null` | — | As a property: What to load and play, as a URL or a IIIF resource. | | `.timeline` | `Record \| null` | — | A Presentation 4 Timeline to play. | | `.annotations` | `Record[] \| null` | — | Annotations on its time, each shown as a cue while its stretch plays, as Canvas's annotations property takes them. | | `.options` | `Record \| null` | — | As Canvas's options: request (credentials, headers) and hideDelay among them. | | `.controls` | `boolean \| { information?: boolean; annotations?: boolean; [option: string]: unknown } \| null` | — | As a property: Which of the Body's controls it shows, as Canvas's controls takes it, in place of the attribute. | | `clover-caption-change` | `{ caption: { id: string; language?: string } \| null }` | — | An event. The reader chose a caption file in the Body's Captions menu, or Off (null). | | `clover-ended` | `Record` | — | An event. Playback reached the end. | ## Examples ### In a Viewer The Viewer plays a Manifest’s Timelines with it, as it shows its Canvases with Canvas. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ### Its artwork A Timeline’s `accompanyingContainer` is its artwork while it plays, here the box the broadcast’s reel came in, at its own shape; its ground takes the artwork’s colors. > **Example**: a live example on the page, showing sample IIIF data. What it shows is demonstration content, not about Clover; its code, where the page gives it, follows. **React** ```jsx ``` **Web components** ```html ``` ## Formats Timeline plays what a browser’s audio and video elements play: MP4 (AAC), MP3, Ogg and WebM, and HLS streams through hls.js, which loads only for one. The `format` a recording declares is passed to the browser as it is. A body of Presentation 4’s type `Audio` plays, and so does Presentation 3’s `Sound`. A recording in several files, painted one after another on its time, plays as one, its time, seek bar and chapters across them all, as [0064](https://iiif.io/api/cookbook/recipe/0064-opera-one-canvas/)’s opera in two acts does. The IIIF Cookbook’s recipes for sound play with it: [0002](https://iiif.io/api/cookbook/recipe/0002-mvm-audio/) in either version, 0014’s accompanying image, 0103’s annotations and 0434’s choice of formats. ## Accessibility Timeline’s transport is the one Canvas plays video with. Every button and slider is named and has its key in its popover, and the controls stay on screen while keyboard focus is in them. With the view focused, Space or K plays and pauses, J and L skip ten seconds back or forward, and M mutes. Captions come from the Timeline’s WebVTT files, each in its own language, and show in the player as lyrics; its plain-text transcript shows in the Panel’s Transcript. Each file is taken for what its annotation `provides`, as a publisher says in Presentation 4: captions, subtitles, or a transcript, which shows in the Transcript and is never offered as captions, since it may leave out the sounds captions describe. The artwork is described by its Canvas’s label, and every word and control on the player’s ground keeps its contrast whatever the artwork’s colors. The chapters listed as tracks say which is playing in words and weight, not color alone. A recording never starts by itself: it plays when the reader presses Play, or follows a link or the Manifest’s `auto-advance`. ## Size A page with a Timeline alone loads the figure beside the title to its first view, playing MP4 audio; hls.js, for a stream, loads only when one plays. In a Viewer it adds nothing up front: `Body` (web components: ``) loads Timeline the first time a Timeline shows, and the Default template stays 95 kB to first view. ## What’s next - The player made without Canvas’s 2D renderer at all, which it no longer draws with. - Timelines painted into Scenes, and Presentation 4’s `timeMode`.