> ## 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.

# Audio clipping

> Locate audible events and speech as moments or intervals in a recording.

Audio clipping identifies **when** something can be heard. Ask for the onset of a sound, the duration of an audible event, or the interval containing a spoken phrase. The response contains `<clip>` annotations in text. Use their timestamps for playback or editing in your application; the API does not return a cut audio file.

## Locate an audible event

Install `perceptron>=0.4.0`, set `PERCEPTRON_API_KEY`, and place a short WAV recording at `./recording.wav`. This example asks for the first alarm in your recording. If there is no clear alarm, the prompt asks the model to report that instead of inventing an interval.

```python theme={null}
import os

from perceptron import Client, audio

client = Client(
    provider="perceptron",
    api_key=os.environ["PERCEPTRON_API_KEY"],
)
audio_part = audio("recording.wav")


def locate_event(question):
    response = client.chat.completions.create(
        model="perceptron-mk1.5",
        messages=[{
            "role": "user",
            "content": [
                audio_part,
                {"type": "text", "text": (
                    question + " Use clip annotations with asset_idx=0 and "
                    "timestamps in explicit seconds from the start of this recording. "
                    "If the event is absent or unclear, say so without inventing timestamps."
                )},
            ],
        }],
        reasoning_effort="high",
        max_completion_tokens=2048,
        vision_config={"annotation_format": "clip"},
    )
    choice = response.choices[0]
    if choice.finish_reason != "stop" or choice.message.tool_calls:
        raise RuntimeError(f"Incomplete audio clipping answer: {choice.finish_reason}")
    return choice.message.content or ""


print(locate_event(
    "Find the first audible alarm. Return an interval from when the alarm "
    "begins until that occurrence stops."
))
```

`vision_config.annotation_format: "clip"` requests temporal annotations for audio as well as video. Standalone audio does not require `enable_audio_in_video`. For MP3, FLAC, remote URLs, or uploaded files, use the corresponding [audio input form](/perceptron-mk1.5/capabilities/audio#choose-an-audio-input).

## Ask for a moment or an interval

Reuse `locate_event` to ask for a single boundary instead of a duration:

```python theme={null}
print(locate_event(
    "Find the moment the first alarm begins. Return one timestamp for its onset."
))
```

These annotations illustrate the two formats; they are not measured predictions for your recording:

```html theme={null}
<clip mention="alarm begins" asset_idx="0" t="2.4 seconds" />
<clip mention="first alarm" asset_idx="0" t="2.4 seconds 5.8 seconds" />
```

A single timestamp is a moment. Two timestamps give the start and end of an interval. For repeated events, ask for a separate interval for each occurrence. A collection can group those intervals under a shared description and asset selector; see [annotation format](/perceptron-mk1.5/concepts/annotations#clips).

Define the boundary you need in the prompt:

| Task                 | Example instruction                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| Find a spoken phrase | “Locate the interval containing the words ‘the meeting is postponed.’ If they are not audible, say so.” |
| Find repeated sounds | “Return a separate interval for each audible burst of applause.”                                        |
| Mark a transition    | “Return the moment when the background music stops.”                                                    |

Use [audio transcription](/perceptron-mk1.5/capabilities/audio-transcription) when you need the spoken words, or [audio Q\&A](/perceptron-mk1.5/capabilities/audio-qa) when you need an explanation of their meaning.

## Keep timestamps attached to the recording

Times are measured in seconds from the start of the supplied recording. If you create an excerpt starting 120 seconds into a longer recording, a returned time of 2.4 seconds maps to 122.4 seconds in the original. Keep that offset with the excerpt when combining results.

`asset_idx="0"` selects the recording in this example. The attribute is optional, even when requested: without an explicit or inherited selector, use the last asset available when the annotation was produced. With several recordings or other media, resolve the [asset selector](/perceptron-mk1.5/guides/multiple-assets#resolve-selectors-before-drawing) before interpreting times.

## Validate before seeking or cutting

* Require a completed response. A `length` finish reason or interrupted stream can leave an unfinished annotation.
* Check that times are finite, nonnegative, within the selected recording, and ordered for an interval. A moment needs an application-chosen interval before it can become a playable excerpt.
* Listen around the proposed boundary before making a precise cut. Requested tags and timestamps are model output to validate, not a guarantee of sample-accurate alignment.

Long recordings share the model's input and output budget. See [audio limits](/perceptron-mk1.5/capabilities/audio#understand-usage-and-limits) before sending a recording. For audible events in a video, use [video clipping with sound](/perceptron-mk1.5/capabilities/video-clipping#locate-an-audible-cue) and explicitly enable soundtrack processing.