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

# Segment videos

> Use the Playground to transform raw video into structured, timestamped data by defining the segments and fields that matter to your application.

The platform partitions videos into labeled, timestamped segments. Define the types of segments you want to detect and the fields you want to extract. The platform identifies segment boundaries and returns custom metadata for each segment in JSON format. For details on segment definitions, fields, and best practices, see the [Segment videos](/docs/guides/segment-videos) guide.

The page uses a two-panel layout. Select a video, define your segments, and configure parameters in the left panel. Results appear in the right panel.

# Get started

When you open the Segment page, you can start in one of the following ways:

* **Segment your own video**: In the left panel, select a video, choose a template, and run segmentation. See the [Procedure](#procedure) section below for the full steps.
* **Resume a previous task**: In the right panel, select the **History** tab and choose a past task to load its results.
* **Try an example**: In the right panel, select the **Examples** tab and choose a pre-built example. The example populates a video and segment definition for you and runs segmentation automatically. After the results appear, you can edit the definition and rerun segmentation.

# Procedure

1. In the left panel, select the video preview area to choose a video that you've already uploaded, or upload a new video directly from the dialog.

2. Define your segments. Under **segment\_definitions**, select a template or choose **Write My Own** to start from scratch with an empty segment definition.

3. *(Optional)* To customize the definition, select the **Edit in Builder** button.

   ![](/_fern-img/48c5c0e1a1a37542c665612461c1198d282bdc127b93f0c2f68768234d47a9d4.webp)

The **Segment Definition Builder** modal opens with two panels. Define your segment in the **Builder** panel (visual interface) or the **Editor** panel (raw JSON). Changes in either panel are reflected immediately in the other.

In the **Segment Definition Builder**, you can:

* Edit the segment description.
* Add, rename, or remove fields.
* Specify time ranges to limit segmentation to specific parts of the video.
* Add more segment definitions.

![](/_fern-img/cac4151beafb4432c83c41115891779d9ca805f942ce46b878717a0754949a1b.webp)

4. *(Optional)* Adjust the parameters under **Advanced Settings**. To reset all parameters to their default values, select the **Reset** button.

5. Select the **Segment** button. The platform displays progress messages while processing. You can leave the page and return later to see the results.

# View results

Results appear in the right panel. Select the **Visual** or **JSON** tab to switch between views.

## Visual tab

The **Visual** tab shows a video player, a segment timeline, and a metadata panel.

![](/_fern-img/7ea6fa9c09d6aca192b6db7c91e3d6b7be607b22ff0d0a950214c735c988e4fa.webp)

* **Video player**: Plays the selected video. Navigates to the corresponding segment when you select a segment on the timeline.
* **Segment timeline**: Displays segments as labeled blocks on a horizontal bar. Hover over a segment to see its time range. Select a segment to play it and view its metadata.
* **Metadata panel**: Shows the extracted fields for the selected segment, including the segment definition name, a timestamp badge, and a segment counter (Example: "7/12").

## JSON tab

The **JSON** tab shows the raw JSON response. This includes the segment definition schema, all detected segments with timestamps, and the extracted metadata for each segment.

![](/_fern-img/7dac2a49c348e5e927dbaf6c17a3eeef3d50ba7b845843bfb56ca4c5ee0a75e2.webp)

# Work with results

## Play a specific segment

Select a segment on the timeline to play that portion of the video. The metadata panel updates to show the fields for the selected segment.

![](/_fern-img/3a0eab0b7fcf5da3420fe5443a9a3e684d90b4dfba47a238636e7f6c16318f39.webp)

## View the code snippet

Select the **View Code** button to see the request as cURL, Python, or JavaScript. Copy and paste the snippet into your application.

![](/_fern-img/f25a315c0b9dfe44b4173a3f2c0ac7c8467fa3d62e21d7ede05e025fc3ce7ee4.webp)

## Adjust your segment definitions

To change your segment definitions, select a different template from the **segment\_definitions** dropdown or select the **Edit in Builder** button to modify the definition directly. Then select the **Segment** button to rerun the segmentation.