Obtained formats: principles & usage

When analyzing a URL, the API returns a formats list: these are the obtained formats for that source (e.g., progressive MP4, M4A audio, HLS .m3u8 streams, DASH .mpd streams, separate tracks). This page explains how to use them depending on the environment (browser, app, server).

view_stream

Progressive vs Adaptive

Progressive: a single file (video+audio) — ideal for downloading and direct playback.
Adaptive (HLS/DASH): segmented streams/manifests, sometimes separate audio/video — ideal for streaming.

high_quality

Useful fields

ext (mp4/m4a/webm…), height, fps, vcodec/acodec, filesize, url, audio_only/video_only, protocol (https/m3u8/dash), note (progressive/hls/dash…).

tune

Format selection

Choose depending on the use case: single MP4 file for fast download, HLS/DASH for adaptive streaming, or M4A for audio only.

Obtained format: sample structure

{
  "format_id": "720p",
  "ext": "mp4",
  "vcodec": "h264",
  "acodec": "aac",
  "tbr": 2500,         // total bitrate (kbps) if progressive
  "vbr": 2300,         // video bitrate (kbps) if known
  "abr": 192,          // audio bitrate (kbps) if known
  "width": 1280,
  "height": 720,
  "fps": 30,
  "filesize": 104857600,  // in bytes, if available
  "protocol": "https|m3u8|dash",
  "url": "https://cdn.example.com/video-720p.mp4",
  "audio_only": false,
  "video_only": false,
  "note": "progressive | hls | dash | audio-only | video-only",
  "manifest_url": "https://cdn.example.com/manifest.m3u8" // if HLS/DASH
}

Not all fields are guaranteed for each platform; the API returns what is available.

Compatibility & players (browser / app)

Obtained format	Browser playback	Notes
Progressive MP4 (`ext: mp4`, `note: progressive`)	Yes, via HTML5 `<video>`	Simplest for direct play/download.
M4A Audio (`ext: m4a`, `audio_only: true`)	Yes, via HTML5 `<audio>`	Perfect for podcasts/audio extraction.
HLS (`protocol: m3u8`, `note: hls`)	Safari (native), other browsers with `hls.js`	Adaptive streaming; requires a compatible player.
DASH (`protocol: dash`, `note: dash`)	JS players (e.g., `dash.js` or Shaka)	Separate tracks, `.mpd` manifest.
Video only (`video_only: true`)	No (silent file)	Must be paired with an audio track.
Audio only (`audio_only: true`)	Yes (`<audio>`)	Can be combined with a video-only format.

Usage in the browser

1) Progressive MP4 (simple)

<video controls width="640" height="360" src="https://cdn.example.com/video-720p.mp4"></video>

2) M4A Audio

<audio controls src="https://cdn.example.com/audio-best.m4a"></audio>

3) HLS (`.m3u8`) with `hls.js`

<video id="v" controls width="640" height="360"></video>
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<script>
  const url = "https://cdn.example.com/manifest.m3u8"; // obtained HLS link
  const video = document.getElementById("v");
  if (video.canPlayType("application/vnd.apple.mpegURL")) {
    // Safari (native HLS)
    video.src = url;
  } else if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(url);
    hls.attachMedia(video);
  } else {
    console.error("HLS not supported");
  }
</script>

4) DASH (`.mpd`) with `dash.js`

<video id="v2" controls width="640" height="360"></video>
<script src="https://cdn.jsdelivr.net/npm/dashjs/dist/dash.all.min.js"></script>
<script>
  const url = "https://cdn.example.com/manifest.mpd"; // obtained DASH link
  const player = dashjs.MediaPlayer().create();
  player.initialize(document.getElementById("v2"), url, true);
</script>

lightbulb

To play URLs directly from a browser, the source server must allow loading (CORS) and serve the correct MIME type.

“video-only” + “audio-only” formats

When the API returns separate tracks (obtained formats with video_only=true and audio_only=true), you have two approaches:

Adaptive playback: use an HLS/DASH player that combines tracks on the fly.
Final file: merge server-side to produce a single MP4 (e.g., via transmux/mux tools).

function pickAdaptivePair(formats, maxHeight = 1080){
  const v = formats
    .filter(f => f.video_only && (f.height||0) <= maxHeight)
    .sort((a,b) => (b.height||0) - (a.height||0))[0];
  const a = formats
    .filter(f => f.audio_only)
    .sort((a,b) => (b.abr||0) - (a.abr||0))[0];
  return v && a ? { video:v, audio:a } : null;
}

Tip: Keep URLs and metadata to log and diagnose playback issues.

Selecting a format (heuristics)

thumb_up Best progressive MP4 ≤ 1080p

function pickBestProgressiveMp4(formats){
  return formats
    .filter(f => !f.video_only && !f.audio_only && f.ext === "mp4" && (f.height || 0) <= 1080)
    .sort((a,b) => (b.height||0) - (a.height||0) || (b.tbr||0) - (a.tbr||0))
    [0] || null;
}

Sorted by resolution then bitrate; ignores separate formats.

graphic_eq Audio only (M4A preferred)

function pickAudioOnly(formats){
  const audio = formats.filter(f => f.audio_only || (!f.video_only && f.ext === "m4a"));
  return audio.sort((a,b) => (b.abr||0) - (a.abr||0))[0] || null;
}

Useful for podcasts/audio extraction.

Downloading an obtained format

Download a progressive MP4

curl -L "https://cdn.example.com/video-720p.mp4" -o "video-720p.mp4"

Download an M4A audio

curl -L "https://cdn.example.com/audio-best.m4a" -o "audio.m4a"

shield

In production, avoid downloading on the client side. Use your server (proxy) to secure keys and manage bandwidth.

Notes & troubleshooting

CORS & MIME: to play a format URL directly in a webpage, the source server must allow the domain (CORS) and return the correct Content-Type.
Players: HLS = native Safari or hls.js; DASH = dash.js or Shaka.
Temporary failures: try again later; some sources restrict access.
Separate tracks: prefer an adaptive player, or merge server-side into a final file.

Navigation