Stream and artwork

Stream a track as 128kbps MP3 with metadata headers, and fetch cover art.

Stream and artwork#

Stream a track inline for playback, with track metadata returned in response headers, and fetch its cover art. Both routes are keyed by ISRC (exactly 12 characters).

Stream a track#

Streaming is 128kbps only. The audio is returned inline (Content-Disposition: inline) so it plays in a browser or audio element rather than downloading. On the first request for an ISRC, Hep.gg fetches and caches the file, so subsequent streams are served from cache.

Response#

200 with an audio/mpeg stream and these metadata response headers. A HEAD /stream/:isrc is also supported, but it returns only Content-Type and Accept-Ranges. The X-Track-* metadata headers, including the artwork URL, are sent on GET responses only.

The stream advertises Accept-Ranges: bytes and honors HTTP range requests, so players and audio bots can seek. Send a Range header (for example Range: bytes=0-) and you get a 206 Partial Content response with Content-Range and the metadata headers; omit it and you get the full 200.

Errors#

• 400 { "error": "Invalid ISRC" } when the ISRC is not exactly 12 characters.
• 404 { "error": "Track not found" } when no track matches the ISRC.
• 500 on a server-side failure.

Examples#

# Read just the metadata headers
curl -I "https://music.jakeypri.me/stream/USRC17607839?key=YOUR_KEY"
 
# Stream the audio to a file
curl -L "https://music.jakeypri.me/stream/USRC17607839?key=YOUR_KEY" -o stream.mp3

const res = await fetch("https://music.jakeypri.me/stream/USRC17607839", {
  headers: { "X-API-Key": "YOUR_KEY" },
});
 
const meta = {
  title: decodeURIComponent(res.headers.get("x-track-title") ?? ""),
  artist: decodeURIComponent(res.headers.get("x-track-artist") ?? ""),
  album: decodeURIComponent(res.headers.get("x-track-album") ?? ""),
  durationSec: Number(res.headers.get("x-track-duration") ?? 0),
  artwork: res.headers.get("x-track-artwork"),
};
// res.body is the 128kbps audio stream

Cover artwork#

The cover art proxy returns a 250x250 JPEG for an ISRC. Unlike every download and stream route, this endpoint requires no API key, so you can embed the URL directly in an <img> tag. The image is cached server-side and served with a one-year client cache.

Response#

200 with Content-Type: image/jpeg and Cache-Control: public, max-age=31536000 (one year). Errors: 400 { "error": "Invalid ISRC" }, 404 { "error": "Artwork not found" }, 500 { "error": "Failed to fetch artwork" }.

curl -L "https://music.jakeypri.me/artwork/USRC17607839" -o cover.jpg

<img
  src="https://music.jakeypri.me/artwork/USRC17607839"
  alt="cover art"
  width="250"
  height="250"
/>