> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Video clipping

> Locate an event as a moment or an interval with temporal annotations.

Video clipping identifies **when** an event occurs. Ask for a moment when you need one event boundary, or an interval when you need the duration of an action. Visual events use the video frames; audible events require [soundtrack analysis](#locate-an-audible-cue). The response contains temporal annotations; it does not create a new video file.

## Find a basketball event

This example asks two different questions about the same shot: when the ball passes through the hoop, and the interval covering the shot attempt. Each request defines what to include so the model can distinguish the event from the surrounding play.

Install the `perceptron>=0.4.0` Python package and set `PERCEPTRON_API_KEY` before running:

```python theme={null}
import os

from perceptron import Client, video

client = Client(api_key=os.environ["PERCEPTRON_API_KEY"])
video_url = (
    "https://raw.githubusercontent.com/perceptron-ai-inc/perceptron/"
    "main/cookbook/_shared/assets/capabilities/video-clipping/mj_shot_short.mp4"
)


def locate_event(question, include_soundtrack=False):
    response = client.chat.completions.create(
        model="perceptron-mk1.5",
        messages=[{
            "role": "user",
            "content": [
                video(video_url),
                {"type": "text", "text": (
                    question + " Use clip annotations with asset_idx=0 and "
                    "timestamps in explicit seconds. If the requested event "
                    "is absent or uncertain, say so instead of inventing a timestamp."
                )},
            ],
        }],
        reasoning_effort="high",
        max_completion_tokens=2048,
        vision_config={
            "annotation_format": "clip",
            "enable_audio_in_video": include_soundtrack,
        },
    )
    choice = response.choices[0]
    if choice.finish_reason != "stop":
        raise RuntimeError(f"Incomplete clipping answer: {choice.finish_reason}")
    return choice.message.content or ""


print("Moment:")
print(locate_event(
    "Find the moment the ball passes through the hoop. "
    "Return a single timestamp for that event."
))

print("Interval:")
print(locate_event(
    "Find the shot-attempt interval, from the player's shooting motion "
    "through the ball passing through the hoop. Return a start and end time."
))
```

## Locate an audible cue

The basketball sample also contains audio. Reuse `locate_event` with `include_soundtrack=True` to locate an audible event on the same video timeline:

```python theme={null}
print(locate_event(
    "Find any clear increase in crowd reaction around the shot. "
    "Use the audio to identify its start and end, and describe separately "
    "what is visible during that interval. If no clear change is audible, say so.",
    include_soundtrack=True,
))
```

This sets `vision_config.enable_audio_in_video` alongside `annotation_format: "clip"`; the default remains frames only. Define the cue you want, such as an audible phrase, an alarm, or a change in background sound. Do not treat a visible action as proof that its expected sound occurred. Returned times are estimates, so review the source audio before making a precise cut.

Both the frames and soundtrack belong to video asset `0`. [Timestamped frames](/perceptron-mk1.5/capabilities/video-understanding#send-timestamped-frames) alone cannot supply audio evidence. Use the original video or an excerpt that retains its soundtrack when refining an audible boundary, and preserve any offset to the original timeline. See [video soundtracks](/perceptron-mk1.5/capabilities/video-understanding#analyze-video-soundtracks) for input handling and limits.

## Interpret moments and intervals

These examples illustrate the markup; the times are not measured predictions for the sample video:

```html theme={null}
<clip mention="ball passes through hoop" asset_idx="0" t="3.2 seconds" />
<clip mention="shot attempt" asset_idx="0" t="1.0 seconds 3.2 seconds" />
```

The first annotation is a moment. The second is an interval with a start and end. Both refer to the video at asset `0`. A moment is an approximate location in time; it does not establish a playable duration. To create a highlight, your application can add a chosen amount of time before and after it, clamped to the video boundaries.

For repeated events, request a separate clip for each occurrence. A collection can describe the group with `mention` and supply an inherited asset selector:

```html theme={null}
<collection mention="shot attempts" asset_idx="0">
  <clip t="1.0 seconds 3.2 seconds" />
  <clip t="7.0 seconds 9.4 seconds" />
</collection>
```

This is also an illustrative format example. See [annotation format](/perceptron-mk1.5/concepts/annotations#clips) for timestamp parsing and asset selector inheritance.

## Use temporal evidence

Before seeking, cutting, or displaying a returned clip, validate its asset selector and timestamps. Check that times are finite, within the chosen video's timeline, and ordered for an interval. A response ending with `finish_reason: "length"` may contain unfinished annotations; do not treat it as a complete result.

Frame sampling can miss a short event or leave its boundary uncertain. Avoid promising frame-exact cuts from an estimated timestamp. For a closer look, provide frames around the candidate interval using [timestamped video frames](/perceptron-mk1.5/capabilities/video-understanding#send-timestamped-frames), preserving the timeline or recording any excerpt offset.

Use [video Q\&A](/perceptron-mk1.5/capabilities/video-qa) when you need an explanation of the event. Use [video tracking](/perceptron-mk1.5/capabilities/video-tracking) when you also need an object's location over time.