Adaptive Bitrate HLS Delivery With Cloudinary and Next.js

Your video buffers. Netflix doesn’t. Here’s the difference, and how to close it with one URL parameter.

• Live demo: stream-video-like-a-pro-hls-cloudin.vercel.app
• Source code: github.com/musebe/stream-video-like-a-pro-hls-cloudinary-nextjs

Every tutorial ships a <video src="my-video.mp4" /> and calls it done. That works fine until your user is on a train with two bars of signal. Then it buffers. Then they leave.

The uncomfortable truth:

Progressive MP4 is a single file at a fixed bitrate. The player either downloads it fast enough to keep up, or it doesn’t. There’s no middle ground.

Netflix, YouTube, Twitch, and every other major streaming platform use adaptive bitrate (ABR) streaming. The player measures your bandwidth every few seconds and switches quality seamlessly. You never notice the switch. You just never buffer.

Setting this up used to mean FFmpeg pipelines, manifest generators, CDN configuration, and a headache. With Cloudinary, it’s a simple URL change.

ABR streaming works by pre-encoding the same video at multiple quality levels (the quality ladder) and packaging them into a manifest file the player reads.

Every few seconds the player measures bandwidth, picks the highest quality tier it can sustain without buffering, and fetches the next segment from that tier. The switch is invisible.

HTTP Live Streaming (HLS), originally from Apple and now an IETF standard (RFC 8216), is the most widely supported ABR format on the web. It delivers content as short .ts segments (typically two to six seconds each), indexed by an .m3u8 playlist file.

# A simplified HLS master manifest
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=400000,RESOLUTION=640x360
360p/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2000000,RESOLUTION=1280x720
720p/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=4500000,RESOLUTION=1920x1080
1080p/index.m3u8

The player fetches this manifest, reads the available variants, picks one, and starts loading segments. When bandwidth changes, it switches variant. No interruption.

Here’s the entire Cloudinary HLS setup:

# Before — fixed quality MP4
https://res.cloudinary.com/<cloud>/video/upload/my-video.mp4

# After — full adaptive HLS
https://res.cloudinary.com/<cloud>/video/upload/sp_auto/my-video.m3u8

sp = streaming profile. auto = let Cloudinary choose the optimal quality ladder for the source video.

No FFmpeg, pipeline, or manifest generator. One URL change.

View the Cloudinary docs: Adaptive Bitrate Streaming

Instead of a boring embed, you built StreamLab, a gamified comparison arena where readers can feel the difference between HLS and MP4, not just read about it.

• Try it live: stream-video-like-a-pro-hls-cloudin.vercel.app
• Full source: github.com/musebe/stream-video-like-a-pro-hls-cloudinary-nextjs

Server (page.tsx)
└── Builds Cloudinary URLs from env vars
└── Passes hlsSrc, mp4Src, poster to VideoArena

Client (video-arena.tsx → hls-player.tsx)
└── useHls() attaches HLS.js to <video>
└── Safari detected → native HLS instead
└── Stats, scores, achievements update in real time

The URL construction happens server-side; no env vars leak to the client, and the heavy HLS.js library is dynamically imported only when the component mounts.

npx create-next-app@latest . --typescript --tailwind --app --src-dir
npx shadcn@latest init --defaults
npx shadcn@latest add badge card progress separator tabs tooltip
npm install hls.js web-vitals
Code language: CSS (css)

If you have a package-lock.json anywhere up your directory tree (common on developer machines), Turbopack may adopt the wrong workspace root and throw a React Client Manifest 500 error.

Fix it in next.config.ts:

const nextConfig: NextConfig = {
  turbopack: {
    root: process.cwd(), // anchor to the project, not the filesystem root
  },
};
Code language: JavaScript (javascript)

Then delete .next/ and restart. One-time fix.

All URL construction lives in src/lib/cloudinary.ts. Pure functions, no SDK dependency.

hlsUrl({ cloudName, publicId })
// → https://res.cloudinary.com/<cloud>/video/upload/sp_auto/<id>.m3u8

mp4Url({ cloudName, publicId })
// → https://res.cloudinary.com/<cloud>/video/upload/<id>.mp4

posterUrl({ cloudName, publicId }, offsetSeconds = 2)
// → https://res.cloudinary.com/<cloud>/video/upload/so_2.0,pg_1/<id>.jpg
Code language: HTML, XML (xml)

The poster URL is worth highlighting. so_2.0 seeks 2 seconds in; pg_1 extracts that frame as an image. No separate upload. No pre-processing step. Cloudinary generates it on the first request and caches it.

URLs are built in page.tsx (a React Server Component) and passed down as props. This means:

• Env vars never reach the browser bundle.
• URL computation has zero client-side cost.
• The HTML already contains the correct poster src on first paint, improving LCP.

// src/app/page.tsx
const config = { cloudName, publicId };

<VideoArena
  hlsSrc={hlsUrl(config)}
  mp4Src={mp4Url(config)}
  poster={posterUrl(config, 2)}
/>
Code language: JavaScript (javascript)

See the full helpers: src/lib/cloudinary.ts

The entire HLS lifecycle lives in src/hooks/use-hls.ts. Three design decisions made this nontrivial.

Chrome on macOS passes video.canPlayType("application/vnd.apple.mpegurl"), but stalls on Cloudinary’s HLS segments and emits no quality-level events. Using native HLS for Chrome produces a broken experience.

The fix: a user-agent regex that detects actual Safari:

function isActualSafari(): boolean {
  return /^((?!chrome|android|crios|fxios).)*safari/i.test(navigator.userAgent);
}
Code language: JavaScript (javascript)

HLS.js loads via an asynchronous dynamic import. If the component unmounts before the import resolves, the callback fires on a dead component and calls setState into the void (React warning) or, worse, into a freshly mounted replacement (wrong data).

useEffect(() => {
  let cancelled = false;

  import("hls.js").then(({ default: Hls }) => {
    if (cancelled) return; // component already gone

    hls.on(Hls.Events.MANIFEST_PARSED, (_, data) => {
      if (cancelled) return; // guard every async callback
      setLevels(data.levels.map(/* ... */));
      setIsLoaded(true);
    });
  });

  return () => {
    cancelled = true; // all callbacks check this before setState
    hlsRef.current?.destroy();
  };
}, [src, autoPlay]);
Code language: JavaScript (javascript)

onLevelSwitch and onEnded are callbacks from the parent. If they’re in the useEffect dep array, any time the parent re-renders with a new inline function reference, HLS tears down and re-initialises. Infinite loop.

// Store latest version in a ref — always current, never a dep
const onLevelSwitchRef = useRef(onLevelSwitch);
onLevelSwitchRef.current = onLevelSwitch;

// Inside the effect, call via ref — zero dep-array impact
hls.on(Hls.Events.LEVEL_SWITCHED, (_, data) => {
  onLevelSwitchRef.current?.(data.level);
});
Code language: PHP (php)

Dep array stays [src, autoPlay]. HLS only restarts when the source actually changes.

Full hook implementation: src/hooks/use-hls.ts

Three things the native <video> element can’t do on its own:

1. Quality badge overlay. Reads stats.qualityLabel from useHls and renders a QualityBadge that animates through tiers
2. Score accumulation. A setInterval ticks every second and awards points based on the current quality level
3. Quality level pills. Shows every available HLS variant below the player, highlights the active one

<video
  ref={videoRef}
  poster={poster}
  controls
  playsInline
  preload="auto"   // start buffering immediately on mount
  className="w-full rounded-lg aspect-video bg-zinc-900"
/>
Code language: HTML, XML (xml)

preload="auto" is the often-forgotten attribute that tells the browser to start filling the buffer without waiting for the user to hit play. Critical for LCP.

A standard <video> element with a stats panel that shows buffer depth, dropped frames, and load time, using the same metrics as the HLS player so the comparison is honest.

The key difference the stats reveal: MP4 shows no quality label because there’s only one. HLS shows the current tier and how many times it switched.

src/components/stats-panel.tsx surfaces six numbers that tell the real story:

One honest caveat: webkitDroppedFrameCount is a Chromium-only API. On Firefox and Safari it returns undefined and shows 0. The stats panel handles this gracefully with a nullish fallback.

Stats are updated two ways:

• Event-driven: On FRAG_LOADED (every segment fetch).
• Polled: setInterval every 1 second for buffer depth (the video element doesn’t fire events for this).

The gamification lives in src/components/video-arena.tsx and src/types/video.ts.

Higher quality = more points per second. This makes the advantage of HLS immediately visible: a smooth 1080p stream scores 4x more than a buffering 360p one.

The achievement unlock function needs to check whether a badge is already unlocked. The naive approach (closing over unlockedIds state) creates a new function identity every time an achievement unlocks, cascading new identities into every callback and triggering an infinite HLS re-init loop.

The fix: track unlocked IDs in a ref, not state, for the deduplication check.

const unlockedRef = useRef(new Set<string>());

const unlock = useCallback((id: string) => {
  if (unlockedRef.current.has(id)) return; // ref check, not state
  unlockedRef.current = new Set([...unlockedRef.current, id]);
  setUnlockedIds(unlockedRef.current); // update state for the UI
  setPendingAchievement(achievement);
}, []); // [] — permanently stable, no cascade
Code language: JavaScript (javascript)

Full implementation: src/components/video-arena.tsx

The most effective way to teach a URL parameter is to make it clickable.

src/components/url-anatomy.tsx renders the full HLS URL as a row of interactive segments. Click any segment and a panel below explains exactly what it does.

https://res.cloudinary.com/<cloud>/video/upload/sp_auto/<id>.m3u8
│                           │       │             │       │     │
CDN base                    Cloud   Resource      KEY     ID    Manifest
                            name    type          ↑
                                             Click to learn

Each segment is a <button> with a colour, a label, and a description. No third-party library. Zero dependencies. Pure useState with a lookup table.

The sp_auto segment starts highlighted by default, as that’s the one thing readers need to remember.

Building this demo surfaced three nonobvious React hook bugs worth documenting.

// ❌ Calls parent setState inside a child setState updater
setScore((prev) => {
  const next = prev + rate;
  onScoreUpdate?.(next); // triggers parent's setScore → renders during render
  return next;
});

// ✅ Call them sequentially, not nested
scoreRef.current += rate;
setScore(scoreRef.current);
onScoreUpdate?.(scoreRef.current);
Code language: JavaScript (javascript)

React’s state updater function must be pure. Calling another component’s setState inside it violates that contract and logs “Cannot update a component while rendering a different component.”

The original unlock closed over unlockedIds state to check for duplicates:

// ❌ unlock closes over state — new identity on every unlock
const unlock = useCallback((id: string) => {
  if (unlockedIds.has(id)) return;           // state in dep array
  setUnlockedIds(prev => new Set([...prev, id]));
}, [unlockedIds]);                            // ← triggers the loop
Code language: JavaScript (javascript)

Calling unlock updates unlockedIds. That creates a new unlock. A new unlock creates a new handleScoreUpdate. A new handleScoreUpdate changes the onScoreUpdate prop. That prop change restarts the score useEffect, resets the interval, and fires onScoreUpdate again. Full circle.

The fix: move the duplicate check into a ref so unlock never needs state in its dep array.

// ✅ unlock reads a ref — identity never changes
const unlockedRef = useRef(new Set<string>());

const unlock = useCallback((id: string) => {
  if (unlockedRef.current.has(id)) return;  // ref, not state
  unlockedRef.current = new Set([...unlockedRef.current, id]);
  setUnlockedIds(unlockedRef.current);       // state only for the UI
}, []);                                       // ← permanently stable
Code language: JavaScript (javascript)

Rule: if a useCallback dep is state that changes as a result of calling that callback, you have a self-reinforcing loop. Move the check to a ref.

// ❌ The async callback ignores whether the effect was cleaned up
import("hls.js").then(({ default: Hls }) => {
  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    setIsLoaded(true); // fires on the old (cleaned-up) effect's HLS instance
  });
});

// ✅ Cancelled flag blocks all post-cleanup setState calls
let cancelled = false;
import("hls.js").then(({ default: Hls }) => {
  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    if (cancelled) return;
    setIsLoaded(true);
  });
});
return () => { cancelled = true; hls.destroy(); };
Code language: JavaScript (javascript)

In React 18 Strict Mode, effects intentionally mount → cleanup → remount. Without the cancelled flag, the first effect’s async callback sets state on the second mount’s component, producing the “Maximum update depth exceeded” loop.

Largest Contentful Paint (LCP) is the Core Web Vitals metric most affected by video delivery. A video with a slow-loading poster, or one that blocks the main thread, tanks LCP.

Install web-vitals to instrument LCP in your own pages: web.dev/vitals Cloudinary’s Video Optimization guide covers additional LCP wins like format selection and codec settings.

# Local
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your-cloud
NEXT_PUBLIC_CLOUDINARY_VIDEO_PUBLIC_ID=your-video-id

# Vercel dashboard → Settings → Environment Variables → same keys
Code language: PHP (php)

Both variables are NEXT_PUBLIC_, inlined at build time into the client bundle. Safe because they’re already public (they appear in every video URL your browser loads).

sp_auto is a lazy transformation. The first request to your-video.m3u8 triggers Cloudinary to transcode the source into HLS variants. The manifest returns quickly; the first segments may buffer for 10–30 seconds while transcoding completes.

A pre-warm strategy would be to make an HTTP request to the .m3u8 URL from your CI/CD pipeline or a serverless function after each deploy. Subsequent loads hit the CDN edge cache instantly.

# Simple pre-warm in your deploy script
curl -s "https://res.cloudinary.com/<cloud>/video/upload/sp_auto/<id>.m3u8" > /dev/null
Code language: PHP (php)

Alternatively, use Cloudinary’s eager transformations at upload time to pregenerate HLS segments before any user requests them.

The StreamLab demo is live at stream-video-like-a-pro-hls-cloudin.vercel.app, deployed on Vercel’s Edge Network backed by Cloudinary’s CDN for the media assets.

Before: https://res.cloudinary.com/<cloud>/video/upload/<id>.mp4
After:  https://res.cloudinary.com/<cloud>/video/upload/sp_auto/<id>.m3u8

That’s it. With one parameter, you get full adaptive streaming.

Ready to start building with Cloudinary? Sign up for a free account today.

• Cloudinary Adaptive Bitrate Streaming
• Cloudinary Video Optimization Guide
• Cloudinary Eager Transformations
• HLS.js Documentation
• IETF RFC 8216 — HTTP Live Streaming
• Core Web Vitals — LCP
• Next.js App Router

Built with Next.js 16.2, Cloudinary, HLS.js, Tailwind CSS, and Shadcn UI. Full source at github.com/musebe/stream-video-like-a-pro-hls-cloudinary-nextjs.