Skip to content
Arc XP

Creating an Audio Clip

This tutorial walks through the process of creating and publishing an audio clip by using the Arc XP Audio API.

1. Create an Empty Record

First, create a metadata record for your audio clip. This establishes the clip in the system before you upload the actual audio file.

Terminal window
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/clips/ \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tutorial Audio Clip",
    "description": "A sample audio clip created via API",
    "tags": ["tutorial"]
  }'

The API returns a 201 Created response, which includes the new clip’s content_id. The Location header in the response has the URL of the new resource. Use the content_id value anywhere the following URLs show {audio_id}.

2. Upload Audio

We recommend the two-step presigned-URL flow for attaching audio. First, request a presigned upload URL. Supported formats include WAV, MP3, FLAC, M4A, and MP4 (see the developer guide for details).

Terminal window
curl -X POST "https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/clips/{audio_id}/upload/presigned?file_name=audio.mp3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The response includes an upload_url for the direct upload and a notification_url for processing updates. Upload the file bytes to the returned URL as a second step:

Terminal window
curl -X PUT "PRESIGNED_UPLOAD_URL" \
  -H "Content-Type: audio/mp3" \
  --upload-file /path/to/your/file.mp3

The presigned URL’s signature covers Content-Type: audio/{extension}, where extension denotes the file extension you passed as file_name (for example, audio/wav, audio/flac, audio/m4a, or audio/mp4 for a video file uploaded for audio extraction). This value must match the Content-Type header on your PUT request exactly, or the upload fails with a signature error.

Track progress with Server-Sent Events (SSE)

Audio processing happens asynchronously. To track progress in real time, subscribe to the notification_url returned with the presigned response. It streams Server-Sent Events (SSE) with progress notifications while the audio processes:

  • encoding_started: File received, encoding has begun.
  • encoding_analyzing: Audio analysis in progress.
  • encoding_complete: Encoding finished; you can publish the clip.
  • encoding_failed: An error occurred during processing.

3. Publish the Clip

To make the audio clip available on the public internet, you need to publish it. After the processing state reaches ready, you can publish the clip to make it available for delivery.

Terminal window
curl -X POST https://api.[org].arcpublishing.com/audiocenter/api/editorial/v1/clips/{audio_id}/publish \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Once published, the clip’s publishing_status will change to published.

4. Use with the Audio Player

Give the audio player the audio_id, config, and arc-token to play the clip. For more information about how to get a delivery key for the arc-token, visit Managing Headless API Tokens, but assign the token to the audio collection rather than the view collection.

<script
  type="module"
  src="https://[org]-[environment].audio.arc-cdn.net/player/arc/v0.3.3/arc-player.min.js"
></script>


<h1>Hello Audio!</h1>
<arc-audio-player media-id="{AUDIO_ID}" config='{"orgId":"{org}","env":"{environment}"}' arc-token="{arcToken}"></arc-audio-player>