> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Add chapters to the video timeline

> FastPix enables you to add interactive chapters to your video timeline to boost navigation and user engagement.

FastPix enables you to add interactive chapters to your video timeline to boost navigation and user engagement.

You can add chapters to your video timeline to improve user navigation and enhance the viewing experience. By segmenting your video into chapters, viewers can easily jump to specific sections without needing to scrub through the entire video. This guide will show you how to add chapters to the `fastpix-player` video element using the `addChapters` method.

\


## Use auto generated chapters

FastPix provides a machine-learning-powered API to automatically generate chapter data for your videos. The service analyzes video content to create structured chapter information, including timestamps, titles, and summaries.

To learn how to use this service, refer to the following guide:
[Generate Video Chapters](/docs/in-video-ai/generate-video-chapters).

Once chapter data is generated, you can programmatically apply it to the fastpix-player using the `convertChaptersToPlayerFormat` method.

\


## Add video chapters manually

You can also define chapters manually. This is useful when:

* Chapter structure is known in advance.
* You want full control over chapter titles and timings.
* Automated chaptering is not required.

\


### Step 1: Set up the player element

Ensure your `fastpix-player` element is embedded properly in your HTML. The example below assumes that the player is already embedded in your page with a playback ID.

\


### Step 2: Wait for the player to load

To add chapters, the player must be fully loaded. Use the `DOMContentLoaded` event to run your script when the DOM is fully loaded. Check the `readyState` of the player to confirm it is prepared to accept chapters. If it is not ready, listen for the `loadedmetadata` event, which triggers when metadata like the video duration is available.

\


### Step 3: Add chapters dynamically

Define your chapters as an array of objects, each containing a `startTime` and a `value` (the chapter title). The `addChapters` method will handle the `endTime` automatically for each chapter, if it's not specified – using the `startTime` of the next chapter. If you do provide an `endTime`, the player will use that instead.

\


### Monitor chapter changes

Use the `chapterchange` event to monitor when chapters are updated or modified in the player. This is helpful for confirming changes or making further customizations.

\


**Code example**

```javascript
document.addEventListener('DOMContentLoaded', () => {
    const fpPlayerEl = document.querySelector('fastpix-player');

    const chapters = [
        { startTime: 0, endTime: 2, value: 'Introduction' },
        { startTime: 4, value: 'Chapter 2: Key Concepts' },
        { startTime: 5, endTime: 6, value: 'Chapter 3: Advanced Topics' },
    ];

    function addChaptersToPlayer() {
        if (fpPlayerEl && typeof fpPlayerEl.addChapters === 'function') {
            fpPlayerEl.addChapters(chapters);
        } else {
            console.error('addChapters method not found on fpPlayerEl');
        }
    }

    if (fpPlayerEl && fpPlayerEl.readyState >= 1) {
        addChaptersToPlayer();
    } else if (fpPlayerEl) {
        fpPlayerEl.addEventListener('loadedmetadata', addChaptersToPlayer, { once: true });
    } else {
        console.error('fpPlayerEl not found');
    }

    fpPlayerEl?.addEventListener('chapterchange', () => {
        console.log('Chapter change event detected');
        console.log('Active Chapter:', fpPlayerEl.activeChapter());
    });
}); 
```

\


### Explanation

`fpPlayerEl.readyState`: Checks if the player is ready. A readyState of 1 or higher means the player can accept metadata or chapters.

`loadedmetadata event`: Ensures that key metadata like video duration is loaded before adding chapters.

`addChapters method`: Adds chapters to the player. If endTime is omitted, it defaults to the startTime of the next chapter.

\


**Chapter structure:**

* **startTime**: The timestamp (in seconds) where the chapter begins.
* **value**: The chapter's title or label.

`chapterchange` event: Logs updates to chapters, useful for tracking changes or additional custom functionality.

\


## Convert OpenAI Chapters (Optional)

If you are using OpenAI to generate chapters for your videos, we also provide an option to directly integrate those chapters to FastPix Player.

For instance, if you have a JSON response with chapters generated by OpenAI, you can convert it to the required format with FastPix Player using the `convertOpenAIChapters` function.

\


**Example function**:

**`function`**

```javascript function
const openAIChapters = [ 
  { startTime: 0, text: 'Introduction' }, 
  { startTime: 4, text: 'Chapter 2: Key Concepts' }, 
  { startTime: 5, text: 'Chapter 3: Advanced Topics' }, 
]; 
  
const convertedChapters = convertOpenAIChapters(openAIChapters); 
fpPlayerEl?.addChapters(convertedChapters); 
```

\


> **PLEASE NOTE**
>
> This method is ideal when working with third-party tools or AI-based chapter generation services that do not return chapters in the FastPix format.

\


## Event handling for chapters

The `<fastpix-player>` element emits several useful events when working with chapters. You can attach listeners to handle user interactions and playback state changes.

* `loadedmetadata`: Fired when the video metadata is loaded and the player is ready to accept chapter data.
* `chapterchange`: Fired when the active chapter changes due to playback or user seeking.

\


Example

```javascript
fpPlayerEl.addEventListener('chapterchange', () => { 
const current = fpPlayerEl.activeChapter(); 
console.log('Now viewing chapter:', current?.title); 
});
```

* FastPix Player emits the chapterchange event when the active chapter changes.
* It also provides the activeChapter() method to get the current chapter object.

This lets you detect chapter changes and read the active chapter.

\
\


**Additional Resources**

Related guide: [Auto-generate video chapters with FastPix](/docs/in-video-ai/generate-video-chapters)

For more information on adding AI-generated chapters for your videos refer to the [blog post](https://www.fastpix.io/blog/ai-generated-chapters-for-your-videos-a-developers-guide).