@mux/mux-video
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.4 • Public • Published

    <mux-video/>

    Downloads Version License

    Introduction

    <mux-video></mux-video> is a Mux-flavored HTML5 video element.

    If you are familiar with using <video /> + Hls.js in your application, then you'll feel right at home with this web component.

    Installation

    If you're using npm or yarn, install that way:

    Package manager

    yarn add @mux/mux-video
    

    or

    npm i @mux/mux-video
    

    Then, import the library into your application with either import or require:

    import '@mux/mux-video';

    or

    require('@mux/mux-video');

    CDN option

    Alternatively, use the CDN hosted version of this package:

    <script src="https://unpkg.com/@mux/mux-video@0.4"></script>

    If you are using ECMAScript modules, you can also load the mux-video.mjs file with type=module:

    <script type="module" src="https://unpkg.com/@mux/mux-video@0.4/dist/mux-video.mjs"></script>

    Features and benefits

    Without <mux-video> if you want to use the browser built-in HTML5 video element for playback you would have to wire up Hls.js and Mux Data yourself.

    <mux-video> will automatically handle recoverable errors that happen during video playback. This is particularly handy for live streams that may experience disconnects.

    <mux-video> will use the optimial Hls.js settings for Mux Video so you don't have to worry about that. <mux-video> will also periodically test new versions of Hls.js and upgrade to known stable versions so you don't have to worry about upgrading to a new version of Hls.js yourself.

    Usage

    Loading this library in the browser will register a custom web component for <mux-video>.

    Now you are free to use this web component in your HTML, just as you would with the HTML5 <video> element.

    <body>
      <mux-video
        playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
        metadata-video-title="Big Buck Bunny"
        metadata-viewer-user-id="user-id-1234"
        stream-type="on-demand"
        controls
      ></mux-video>
    </body>

    Attributes:

    • playback-id: This is the playback ID for your Mux Asset or Mux Live Stream. The playback-id is the variable you may have used before to construct a .m3u8 hls url like this:https://stream.mux.com/{PLAYBACK_ID}.m3u8. Mux Docs
    • env-key: This is the environment key for Mux Data. Note that this is different than your API Key. Get your env key from the "Mux Data" part of the Mux Dashboard. If undefined and you are playing a Mux Video asset, the environment will be inferred.

    Mux Data dashboard env key

    • metadata-video-title: This is an arbitrary title for your video that will be passed in as metadata into Mux Data. Adding a title will give you useful context in your Mux Data dashboard. (optional, but encouraged)
    • metadata-viewer-user-id: If you have a logged-in user this should be an anonymized ID value that maps back to the user in your database. Take care to not expose personal identifiable information like names, usernames or email addresses. (optional, but encouraged)
    • metadata-video-id: This is an arbitrary ID that should map back to a record of this video in your database.
    • stream-type: Enum value: one of "on-demand", "live" (HLS live stream), "ll-live" (low latency live). Not strictly required, but preferred so that <mux-video /> can make optimizations based on the type of stream.
    • start-time: number (seconds): Set this to start playback of your media at some time other than 0.

    This is the bare bones of metadata that you should provide to the <mux-video> element.

    All the other attributes that you would use on a <video> element like poster, controls, muted and autoplay are available and will work the same as they do with the HTML5 video element. One sidenote about autoplay though -- read this to understand why that might not always work as expected.

    Advanced: more metadata

    To go above and beyond metadata-* attributes

    To set other available metadata fields use the metadata property on the <mux-video> element like so:

    <mux-video
      playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      controls
    >
    </mux-video>
    
    <script>
      const muxVideo = document.querySelector('mux-video');
      muxVideo.metadata = {
        experiment_name: 'landing_page_v3',
        video_content_type: 'clip',
        video_series: 'season 1',
      };
    </script>

    Instead of using the metadata property, you also have the option to specify a remote URL for fetching metadata asynchronously. In the example below you would have an API server running at https://api.myapp.com/ and the specified endpoint should respond with JSON in the form of something like this:

    {
      "experiment_name": "landing_page_v3",
      "video_content_type": "clip",
      "video_series": "season 1"
    }

    When metadata-url is specified then <mux-video> will asychronously fetch the extra metadata without blocking the initial startup time.

    <mux-video
      playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      metadata-url="https://api.myapp.com/v1/metadata-endpoint.json"
      controls
    >
    </mux-video>

    Take a look at the metadata guide to view an exhaustive list of available values.

    Advanced: prefer-mse

    Pass the prefer-mse attribute to prioritze the in-code Media Source Extensions based engine (currently hls.js) when MSE are supported by the browser. (Without prefer-mse, the default behaviour for <mux-video> is to try the native playback via the underlying <video/> tag )

    <mux-video
      playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      prefer-mse
      controls
    >
    </mux-video>

    Advanced: type

    By default <mux-video> will try to figure out the type of media you're trying to play (for example, an HLS/m3u8 media source, an mp4, etc.) based the extension of the file from the src attribute's url. This allows <mux-video> to determine whether it can/should use an in-code player or native playback. By way of example, the code below has an identifiable "mp4" extension, so <mux-video> will rely on native plyaback via the underlying <video/> tag.

    <mux-video
      src="https://stream.mux.com/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/high.mp4"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      prefer-mse
      controls
    >
    </mux-video>

    Sometimes, however, your src URL may not have an identifiable extension. In these cases, we recommend relying on the type attribute, similar to the <source/> tag's type attribute. Below is an example of explicitly declaring the MIME type for an HLS/m3u8 media source:

    <mux-video
      src="https://stream.notmux.com/path/to/an/hls/source/playlist"
      type="application/vnd.apple.mpegurl"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      prefer-mse
      controls
    >
    </mux-video>

    Or, for convenience, we also support the shorthand type="hls:

    <mux-video
      src="https://stream.notmux.com/path/to/an/hls/source/playlist"
      type="hls"
      metadata-video-title="Big Buck Bunny"
      metadata-viewer-user-id="user-id-1234"
      prefer-mse
      controls
    >
    </mux-video>

    Advanced: Signed URLs and other playback query params

    Mux supports a number of query parameters on HLS playback URLs. Most commonly is the token= param used for signed URLs.

    In order to use token= -- or any other query params, pass them through with the playback-id attribute:

    playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe?token=jwt-signed-token"
    

    Advanced: Use with React+TypeScript

    Even though we don't (yet!) have our own React version of <mux-video>, you can still use it in your React app. However, if you're also using TypeScript, make sure you add the following TypeScript definitions, since custom elements (like as <mux-video>) will not be recognized as Intrinsic Elements:

    interface MuxVideoHTMLAttributes<T> extends React.VideoHTMLAttributes<T> {
      debug?: boolean;
      autoplay?: boolean;
    }
    
    declare global {
      namespace JSX {
        interface IntrinsicElements {
          'mux-video': React.DetailedHTMLProps<MuxVideoHTMLAttributes<HTMLVideoElement>, HTMLVideoElement>;
        }
      }
    }

    FAQ

    If I'm using Mux, do I have to use this library?

    No, you do not. The way Mux delivers HLS video is compliant with the HLS spec. Any video player that supports HLS will work with Mux Video.

    If I'm not using Mux Video, can I still use this library?

    You sure can! Instead of passing in playback-id="" attribute, pass in src="" with an HLS url. You can still use env-key="" to get all the features of Mux Data with your non-Mux video.

    Keywords

    none

    Install

    npm i @mux/mux-video

    DownloadsWeekly Downloads

    2,119

    Version

    0.8.4

    License

    MIT

    Unpacked Size

    4.49 MB

    Total Files

    38

    Last publish

    Collaborators

    • mux-npmjs
    • akemner