MediaStore React Hooks

If you would rather write your own react components, Media Chrome has a React <Context.Provider> and corresponding hooks to directly integrate with its MediaStore state management API. These are included in our standard npm package.

To use, simply import these from "media-chrome/react/media-store".

Media Chrome has a MediaStore “under the hood” that manages all media state and media state change requests.

If you’re familiar with React Redux and its useSelector() and useDispatch() hooks, working with Media Chrome’s MediaStore React integration should feel familiar. Here’s a basic example of using the provider and hooks:

import {
  MediaProvider,
  useMediaDispatch,
  useMediaSelector,
  useMediaRef,
  useMediaFullscreenRef,
  MediaActionTypes,
} from 'media-chrome/react/media-store';

const Video = () => {
  // "Wire up" the <video/> element to the MediaStore using useMediaRef()
  const mediaRef = useMediaRef();
  return (
    <video
      ref={mediaRef}
      style={{ width: '100vw' }}
      src="https://stream.mux.com/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/high.mp4"
      preload="auto"
      muted
      crossOrigin=""
    />
  );
};

const PlayerContainer = ({ children }) => {
  // "Wire up" the element you want the MediaStore to target for fullscreen using useMediaFullscreenRef()
  const mediaFullscreenRef = useMediaFullscreenRef();
  return (<div ref={mediaFullscreenRef}>{children }</div>);
};

const PlayButton = () => {
  // Dispatch media state change requests using useMediaDispatch()
  const dispatch = useMediaDispatch();
  // Get the latest media state you care about in your component using useMediaSelector()
  const mediaPaused = useMediaSelector(state => state.mediaPaused);
  return (
    <button
      onClick={() => {
        // Select from a set of well-defined actions for state change requests
        // using MediaActionTypes
        const type = mediaPaused
          ? MediaActionTypes.MEDIA_PLAY_REQUEST
          : MediaActionTypes.MEDIA_PAUSE_REQUEST;
        dispatch({ type });
      }}
    >
      {mediaPaused ? 'Play' : 'Pause'}
    </button>
  );
};

const FullscreenButton = () => {
  // Dispatch media state change requests using useMediaDispatch()
  const dispatch = useMediaDispatch();
  // Get the latest media state you care about in your component using useMediaSelector()
  const mediaIsFullscreen = useMediaSelector(state => state.mediaIsFullscreen);
  return (
    <button
      onClick={() => {
        // Select from a set of well-defined actions for state change requests
        // using MediaActionTypes
        const type = mediaIsFullscreen
          ? MediaActionTypes.MEDIA_EXIT_FULLSCREEN_REQUEST
          : MediaActionTypes.MEDIA_ENTER_FULLSCREEN_REQUEST;
        dispatch({ type });
      }}
    >
      {mediaIsFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
    </button>
  );
};

const Player = () => {
  // Get access to Media Chrome's state management in your components using <MediaProvider/>
  // NOTE: Unlike many other providers (including react-redux's Provider), you'll likely want to keep
  // your <MediaProvider/> in or close to your <Player/> component)
  return (
    <MediaProvider>
      <PlayerContainer>
        <Video />
        <div>
          <PlayButton />
          <FullscreenButton />
        </div>
      </PlayerContainer>
    </MediaProvider>
  );
};

export default Player;

For a full simple example of working with MediaStore in React, check out our NextJS example page (source).

For a slightly more advanced example that uses Material UI and the <mux-video> custom media element, you can check out this other NextJS Example page (source).

This is the context provider for media state and media state change requests. Use it like you would other react context providers, i.e.:

return (
  <MediaProvider>
    {/* descendant components that
      - use media state,
      - make media state change requests, or
      - are the source of media state, e.g. a <video> component
    */}
  </MediaProvider>
);

This is the primary way to wire up a media element to both get the latest media state using useMediaSelector() and make state change requests using useMediaDispatch(). For most use cases, it’s as simple as:

const mediaRef = useMediaRef();
// ... additional code
return (
  <video
    ref={mediaRef}
    // ... additional props
  />
);

Note that the MediaStore also supports extended state like video renditions and audio tracks that are not available “out of the box” with e.g. a <video> element. To take advantage of these, you can rely on a web-component based custom media element like the <mux-video> custom media element, where you’d wire it up in exactly the same way, e.g.:

// import the custom element
import '@mux/mux-video';

// ...

const mediaRef = useMediaRef();
// ... additional code
return (
  <mux-video
    ref={mediaRef}
    // ... additional props
  />
);

You can find a slightly advanced example of this usage here.

In order to make sure your custom controls show up while the video is in fullscreen, you’ll need to wrap your UI up in a component that will serve as your root fullscreen element. To wire this up to the MediaStore, use useMediaFullscreenRef(). For most use cases, it’s as simple as:

const fullscreenRef = useMediaFullscreenRef();
// ... additional code
return (
  <div
    ref={fullscreenRef}
    // ... additional props
  >
  {/* UI controls, video element, etc. should be descendent components in here */}
  </div>
);

You can find a simple example of using useMediaFullscreenRef() here, or a slightly more advanced example here.

This is the primary way to get the latest media state from the MediaStore. To use it, you simply pass in a “selector function” to grab the state you need for a particular component, like this:

const mediaMuted = useMediaSelector(state => state.mediaMuted);

Below is a list of all available MediaState properties with descriptions.

Availability states describe whether or not a particular feature or state is usable in the current context. By convention, the availability media state property’s name corresponds to the other, related media state(s) and state change request types it describes. So e.g. mediaVolumeUnavailable corresponds to the mediaVolume state and the "mediavolumerequest" state change request type; "mediaCastUnavailable" corresponds to the mediaIsCasting state and the "mediaentercastrequest" and "mediaexitcastrequest" state change request types; and so on.

Also by convention, these state properties will all describe different kinds of unavailability. This allows users to ignore availability states for simple UI implementations. It also allows users to treat availability states as “truthy” values when they don’t need to distinguish between different types of (un)availability. For example:

const airplayAvailable = useSelector(state => !state.mediaAirplayUnavailable);

Below are the different categories of unavailability. As mentioned above, undefined means the feature is available in the current playback context. For convenience, we provide the AvailabilityStates constants object as one of our exports in the media-chrome/react/media-store module, with the following key/value pairs:

Volume levels, provided via the mediaVolumeLevel state, are a convenience state based on the mediaVolume and mediaMuted states which indicate how loud the “effective volume” currently. For convenience, we provide the VolumeLevels constants object as one of our exports in the media-chrome/react/media-store module, with the following key/value pairs:

Stream types describe whether the currently loaded media is a live stream or on demand. This can be helpful if your UI will potentially be used for both live and on demand content, and you want to be able to show different controls for each (e.g. hiding your seek bar for live). For full functionality, this relies on custom media elements like <mux-video>, though the MediaStore will fall back to checking if the media element has a duration of Infinity just in case you’re just using e.g. a <video> element with hls.js. Since this is determined based on the loaded media, which is an asynchronous process, there is also an "unknown" value for initial load cases. For convenience, we provide the StreamTypes constants object as one of our exports in the media-chrome/react/media-store module, with the following key/value pairs:

For more on stream types, check out the docs.

Subtitles objects are the sorts of values provided by captions/subtitles state modeled by the MediaStore (e.g. mediaSubtitlesList). They’re intentionally “shaped” like a TextTrack object, specifically the kind, label, and language properties.

Cue objects are the sorts of values provided by state modeled by the MediaStore provided by a text track’s cues (e.g. mediaChaptersCues). They’re intentionally “shaped” like a VTTCue object, specifically the text, startTime, and endTime properties.

Rendition objects are the sorts of values provided to represent different video renditions, or “qualities” for a media stream for MediaStore state like mediaRenditionList. This information isn’t natively supported by an HTMLMediaElement, so it will require a custom media element like <mux-video>. The object looks like this:

type Rendition = {
  src?: string;
  id?: string;
  width?: number;
  height?: number;
  bitrate?: number;
  frameRate?: number;
  codec?: string;
  readonly selected: boolean;
};

For more information and a “mixin” implementation, see the media-tracks project.

Audio Track objects are the sorts of values provided to represent different audio tracks such as alternative languages or descriptive audio for visually impaired folks. This information isn’t natively supported by an HTMLMediaElement, so it will require a custom media element like <mux-video>. The object looks like this:

type AudioTrack = {
  id?: string;
  kind?: string;
  label: string;
  language: string;
  enabled: boolean;
};

For more information and a “mixin” implementation, see the media-tracks project.

This is the primary way to make media state change requests to the MediaStore. To use it, you simply invoke the dispatch function returned from useMediaDispatch() with the action type (and detail, where relevant), like this:

const dispatch = useMediaDispatch();
// ... additional code
return (
  <button onClick={() => {
    const type = MediaActionTypes.MEDIA_TOGGLE_SUBTITLES_REQUEST;
    dispatch({ type });
  }}>Toggle Subtitles</button>
);

Below is a list of all available MediaActionTypes for media state change requests with descriptions.

For convience, we provide a MediaActionTypes constants object for all well defined media state change request types. Our naming convention is to use “CONSTANT_CASE” (aka UPPERCASE_SNAKE_CASE) for the keys, so e.g. 'mediaplayrequest' would be MediaActionTypes.MEDIA_PLAY_REQUEST.