Skip to main content

Create a Custom Clip

This guide walks through the complete flow for letting a user audition a full track and create their own custom clip within your app.

Prerequisites​

Overview of the flow​

  1. Fetch the full track so the user can audition it.
  2. Present a clip-selection UI (maximum 60 seconds).
  3. Report track plays that occur during auditioning.
  4. Create the custom clip via POST /v2/clips.
  5. Use the returned clip ID for subsequent fetch, play, add, share, and download operations.

Step 1: Fetch the full track​

Send a GET /v2/tracks/{id} request with the trackId to retrieve a signed URL for the full-length source audio. See the Fetch Track reference.

The response includes standard metadata (title, artist, artwork) plus a curatedClip object when Feed has designated a best section for the track. The curatedClip object contains:

  • startMs — the start offset in milliseconds from the beginning of the track where the curated clip begins.
  • stopMs — the stop offset in milliseconds where the curated clip ends.
  • id — the unique identifier of the curated clip.

Recommendation: default your clip-selection UI to the startMs/stopMs values from curatedClip when they are present. The user then begins hearing the same section of the track that plays during a Collection browse — a natural starting point they can refine rather than starting from scratch. This is considered better UX and is strongly encouraged.

Step 2: Present a clip-selection UI​

Allow the user to listen to the full track and drag or adjust start and end points to select their preferred section. The maximum clip length is 60 seconds. Enforce this limit in your UI, preventing preview playback beyond 60s sections of the song at any time.

Track the start and end times in seconds (not milliseconds) — you will need them in the next step.

Step 3: Report track plays during auditioning​

Each time the user plays the track during the auditioning process, send a POST /v2/tracks/{id}/play event. See the Report Track Play reference.

Reporting these plays is required for accurate royalty attribution and for the engagement analytics visible in Clips Studio.

Step 4: Create the custom clip​

Once the user confirms their selection, create the clip by sending POST v2/clips with:

  • clientId: the user's stable client identifier.
  • trackId: the track the clip is drawn from.
  • start: clip start time in seconds.
  • end: clip end time in seconds.

See the Create Custom Clip reference for the full request and response contract.

The response includes a clipId for the newly created clip. This is the ID you will use for all subsequent operations.

Step 5: Use the returned clip ID​

After the clip is created, use the clipId returned in the response as you would any other clip ID from a Collection:

  • Fetch the signed URL — call GET /v2/clips/{id} or include the ID in a GET /v2/clips batch request.
  • Report playback and engagement events — use the clip ID in play, add, share, and download event calls.

The clip is stored in Feed's system and can be referenced by this ID in future sessions.

v1 vs v2

  • /track-fetch: In v1, full tracks were retrieved using POST /track-fetch with a JSON body. In v2, the equivalent endpoint is GET /v2/tracks/{id}.

  • /clip: in v1, custom clipping was done via POST /clip. in v2 the equivalent endpint is POST /v2/clips.

Next steps​