Add Chapters in video timeline

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.

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

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:

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

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

For more information on adding AI-generated chapters for your videos refer to the blog post.