Video player

useMediaStream plays an HLS or DASH stream in your <video>. It renders nothing: no markup, no controls, no styling. The video element is yours, and so are the controls. The hook attaches the right engine and hands back the state to build on.

import { useMediaStream, type MediaStreamData } from '@adonis-agora/media-react'
import { useRef } from 'react'

export default function Lesson({ video }: { video: MediaStreamData }) {
  const ref = useRef<HTMLVideoElement>(null)
  const stream = useMediaStream(ref, video, {
    hls: () => import('hls.js'),
    dash: () => import('dashjs'),
  })

  return (
    <>
      <video ref={ref} controls playsInline className="aspect-video w-full" />
      {stream.levels.length > 1 && (
        <select
          value={stream.autoLevel ? -1 : stream.currentLevel}
          onChange={(e) => stream.setLevel(Number(e.target.value))}
        >
          <option value={-1}>Auto</option>
          {stream.levels.map((l) => (
            <option key={l.index} value={l.index}>{l.height}p</option>
          ))}
        </select>
      )}
      {stream.error && <p role="alert">This video can't be played.</p>}
    </>
  )
}

video comes from the server: media.access.stream(ctx, id) or media.library.stream(id). See Video streaming.

How it picks an engineCopy Anchor Link

The sources are tried in the order the server lists them, HLS first. The first one this browser can play wins:

• preferNative: true: native HLS wins whenever the browser has it, and hls.js isn't even downloaded there. The browser then picks the quality itself, so levels stays empty.
• No source playable: error explains why, and names the loader that's missing.

Why loaders and not dependenciesCopy Anchor Link

hls.js and dash.js are big, and an app usually needs one of them at most. So the hook imports nothing: you pass () => import('hls.js') and () => import('dashjs'). Your bundler then splits them into chunks that are downloaded only when a video needs them. Install the ones you use:

npm i hls.js          # HLS outside Safari/iOS
npm i dashjs          # DASH (hls.js alone plays the HLS side of a CMAF package)

With the default transformers.video() package (CMAF, both manifests), hls.js alone is enough: every browser gets HLS. Load dash.js only if you serve DASH-only packages or want DASH by preference: order the sources conversions server-side, or pass a sources list of your own.

OptionsCopy Anchor Link

The stream can also be a single source ({ src, format }) or a bare manifest URL. A bare URL's format comes from its extension (.mpd means DASH). null detaches.

What it returnsCopy Anchor Link

Changing the stream tears the old player down before attaching the new one, and so does unmounting.