Ittybit

Overview

The Chapters Task divides video or audio content into time-coded segments with titles or summaries for each part.

It helps structure long-form content — such as podcasts, talks, or tutorials — into easily navigable chapters that can be displayed in players or apps.

When complete, the task creates a Track file with "kind": "chapters"

and a .json or .vtt file containing the chapter list.

Example Output

{
  "id": "file_789xyz",
  "object": "track",
  "kind": "chapters",
  "language": "en",
  "format": "json",
  "filename": "video-chapters.json",
  "duration": 600.0,
  "filesize": 1450,
  "url": "https://live.ittybit.net/video-chapters.json",
  "chapters": [
    {
      "index": 0,
      "start": 0.0,
      "end": 60.2,
      "title": "Introduction"
    },
    {
      "index": 1,
      "start": 60.2,
      "end": 180.5,
      "title": "Product Demo"
    },
    {
      "index": 2,
      "start": 180.5,
      "end": 600.0,
      "title": "Conclusion and Q&A"
    }
  ],
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}

Creating a Chapters Task

You can create a Chapters task directly from a file or URL,

or include it as part of a workflow.

import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "chapters",
  url: "https://example.com/video.mp4",
  description: "Generate structured chapters for a video",
  webhook_url: "https://your-app.com/chapters-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);

Webhook Example

When processing completes, the results will be sent to your webhook endpoint.

app.post("/chapters-webhook", async (req, res) => {
  const { kind, status, results } = req.body || {};

  if (kind !== "chapters" || status !== "completed") {
    return res.status(200).send("Not a completed Chapters task");
  }

  console.log("Chapter file URL:", results.url);
  console.log("Detected chapters:", results.chapters?.length);

  res.status(200).send("Chapters processed");
});

File Structure

Property	Type	Description
id	string	Unique file ID for the chapter track.
object	string	Always "track".
kind	string	Always "chapters".
language	string	Detected or target language code (ISO 639-1).
format	string	Output format ("json" or "vtt").
filename	string	Chapter file name.
duration	number	Duration of the associated media file in seconds.
filesize	number	Size of the output file in bytes.
url	string	Public URL of the chapters file.
chapters	array	List of chapter segments with index, start, end, and title.
created / updated	string (ISO 8601)	Creation and update timestamps.

Supported Inputs

Chapters tasks can be generated from:

Video files: .mp4, .mov, .webm
Audio files: .mp3, .m4a, .wav

Example Workflow Integration

Chapters are often created as part of an automation workflow,

alongside other track types such as subtitles and thumbnails.

{
  "name": "Auto-generate video tracks",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "video", "format": "mp4" },
    { "kind": "subtitles", "ref": "video-subtitles" },
    { "kind": "thumbnails", "count": 3 },
    { "kind": "chapters", "ref": "video-chapters" }
  ],
  "status": "active"
}

This automation converts uploaded videos to MP4 and generates

subtitles, thumbnails, and chapters automatically.

Example Chapter File (VTT Format)

WEBVTT

00:00:00.000 --> 00:01:00.200
Introduction

00:01:00.200 --> 00:03:00.500
Product Demo

00:03:00.500 --> 00:10:00.000
Conclusion and Q&A

Common Use Cases

Creating chapter markers for podcasts and long-form videos
Adding timeline navigation in media players
Segmenting content for search or summarization
Auto-generating “table of contents” for educational videos

Summary

The Chapters task divides a video or audio file into structured, time-coded segments.

It’s ideal for long-form content and can be automatically triggered via workflows or webhooks.

Chapters

On this page