Skip to content

Audio

Audio hosting (introduced in v0.12.0) gives you direct download / playback URLs without HLS overhead — audio files are typically small and don’t need adaptive streaming.

Audio hosting requires pro or pro_plus plan.

Quick upload via dashboard

  1. Open Library → Audio
  2. Drag a file or click Upload
  3. ID3 metadata is extracted automatically (cover art, title, artist, album, duration)
  4. After upload (typically <2 seconds), copy the playback URL

Supported formats

FormatExtensionNotes
MP3.mp3Most common
M4A / AAC.m4aApple ecosystem; smaller than MP3
FLAC.flacLossless
WAV.wavUncompressed; large files
OGG.oggWeb-native

Per-plan size limits are in plan comparison — audio shares the media_storage quota with video.

ID3 cover art extraction

Picora uses music-metadata to read ID3v2 / Vorbis / MP4 tags on upload. If the file embeds cover art, it’s extracted and saved as the audio’s thumbnail (thumbnail_url).

If extraction fails or no cover is embedded, Picora falls back to a format-specific default thumbnail:

  • MP3 → orange music icon
  • M4A → blue music icon
  • WAV → grey waveform icon
  • FLAC → green hi-fi icon
  • OGG → purple music icon

Extracted metadata also populates the title, duration_seconds, bitrate fields when available.

Upload via API

Terminal window
curl -X POST https://api.picora.me/v1/audio \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F file=@track.mp3 \
  -F title="My new song" \
  -F isPublic=true

Response:

{
  "success": true,
  "data": {
    "id": "aud_xK9mR2pQ7vB",
    "url": "https://media.picora.me/audio/aud_xK9mR2pQ7vB.mp3",
    "thumbnail_url": "https://media.picora.me/thumbnails/aud_xK9mR2pQ7vB.jpg",
    "title": "My new song",
    "filename": "track.mp3",
    "sizeBytes": 4194304,
    "durationSeconds": 245,
    "bitrate": 320,
    "isPublic": true,
    "createdAt": "2026-04-27T08:00:00Z"
  }
}

Direct streaming via <audio>:

<audio controls>
  <source src="https://media.picora.me/audio/aud_xK9mR2pQ7vB.mp3" type="audio/mpeg">
</audio>

Listing & filtering

Terminal window
GET /v1/media?type=audio&cursor=&limit=20

Audio shares the unified /v1/media endpoint with video. Filter with type=audio.

In the dashboard, the Library “Audio” tab handles pagination automatically.

Visibility, deletion, tags

Behave the same as images. Toggle isPublic, manage tags (max 10), delete via DELETE endpoint or dashboard.

Deletion removes the audio file, the thumbnail (if uploaded), and decrements media_storage quota.

Storage path

Audio files use a dedicated R2 / OSS prefix:

audio/{userId}/{YYYY-MM}/{nanoid}.{ext}
thumbnails/{audioId}.jpg

This separates audio from video for easier cost attribution and lifecycle management.

Common issues

“Cover art is the default icon, not my embedded one” — your file’s ID3 cover may be in an unsupported tag version, or the image inside is corrupted. Check with another tool (e.g., iD3 editor). Re-embed and re-upload.

“Bitrate shows 0” — music-metadata couldn’t parse the file. Doesn’t affect playback. Try re-encoding with ffmpeg.

“Duration shows 0” — same as above. Common with WAV files that lack header metadata; harmless.

“Audio plays but seeking doesn’t work” — your hosting CDN may not support range requests. Picora’s R2 / OSS does, so this usually means a browser / extension is blocking range requests.