Skip to content

Commit 4d3779f

Browse files
dylanjhadylanjha
committed
docs/readme-for-mux-video: document how to use this
1 parent ccedec6 commit 4d3779f

File tree

2 files changed

+176
-0
lines changed

2 files changed

+176
-0
lines changed

Diff for: ‎images/env-key.png

54.7 KB
Loading

Diff for: ‎packages/mux-video/README.md

+176
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Introduction
2+
3+
`<mux-video></mux-video>` is a Mux-flavored HTML5 video element.
4+
5+
If you are familiar with using `<video />` + [Hls.js](https://github.com/video-dev/hls.js) in your application, then you'll feel right at home with this web component.
6+
7+
# Installation
8+
9+
If you're using `npm` or `yarn`, install that way:
10+
11+
## Package manager
12+
13+
14+
```
15+
yarn add @mux-elements/mux-video
16+
```
17+
18+
or
19+
20+
```
21+
npm i @mux-elements/mux-video
22+
```
23+
24+
Then, import the library into your application with either `import` or `require`:
25+
26+
```js
27+
import '@mux-elements/mux-video'
28+
```
29+
30+
or
31+
32+
```js
33+
require('@mux-elements/mux-video')
34+
```
35+
36+
## CDN option
37+
38+
Alternatively, use the CDN hosted version of this package:
39+
40+
```html
41+
<script src="https://unpkg.com/@mux-elements/[email protected]/index.js"></script>
42+
```
43+
44+
## Features and benefits
45+
46+
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](https://github.com/video-dev/hls.js) and [Mux Data](https://docs.mux.com/guides/data/monitor-hls-js) yourself.
47+
48+
`<mux-video>` will automatically handle recoverable errors that happen during video playback. This is particularly handy for live streams that may experience disconnects.
49+
50+
`<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.
51+
52+
## Usage
53+
54+
Loading this library in the browser will register a [custom web component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) for `<mux-video>`.
55+
56+
Now you are free to use this web component in your HTML, just as you would with the HTML5 `<video>` element.
57+
58+
```html
59+
<body>
60+
<p></p>
61+
62+
<mux-video
63+
playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe?foo=bar&biz=baz"
64+
env-key="mux-data-env-key"
65+
metadata-video-title="Big Buck Bunny"
66+
metadata-viewer-user-id="user-id-1234"
67+
controls
68+
></mux-video>
69+
</body>
70+
```
71+
72+
Attributes:
73+
74+
* `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`
75+
* `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
76+
77+
<img src="../../images/env-key.png" alt="Mux Data dashboard env key"></img>
78+
79+
* `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)
80+
* `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)
81+
* `metadata-video-id`: This is an arbitrary ID that should map back to a record of this video in your database. If not provided then the `playback-id` will be used for this value.
82+
83+
This is the bare bones of metadata that you should provide to the `<mux-video>` element.
84+
85+
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](https://docs.mux.com/guides/video/web-autoplay-your-videos).
86+
87+
### Advanced: more metadata
88+
89+
To go above and beyond `metadata-*` attributes
90+
91+
To set other available metadata fields use the `metadata` property on the `<mux-video>` element like so:
92+
93+
```html
94+
<mux-video
95+
playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
96+
env-key="mux-data-env-key"
97+
metadata-video-title="Big Buck Bunny"
98+
metadata-viewer-user-id="user-id-1234"
99+
controls
100+
>
101+
</mux-video>
102+
103+
<script>
104+
const muxVideo = document.querySelector('mux-video');
105+
muxVideo.metadata = {
106+
experiment_name: 'landing_page_v3',
107+
video_content_type: 'clip',
108+
video_series: 'season 1',
109+
};
110+
</script>
111+
112+
```
113+
114+
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:
115+
116+
```json
117+
{
118+
"experiment_name": 'landing_page_v3',
119+
"video_content_type": 'clip',
120+
"video_series": 'season 1',
121+
}
122+
```
123+
124+
When `metadata-url` is specified then `<mux-video>` will asychronously fetch the extra metadata without blocking the initial startup time.
125+
126+
```html
127+
<mux-video
128+
playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
129+
env-key="mux-data-env-key"
130+
metadata-video-title="Big Buck Bunny"
131+
metadata-viewer-user-id="user-id-1234"
132+
metadata-url="https://api.myapp.com/v1/metadata-endpoint.json"
133+
controls
134+
>
135+
</mux-video>
136+
```
137+
138+
Take a look at the [metadata guide](https://docs.mux.com/guides/data/make-your-data-actionable-with-metadata) to view an exhaustive list of available values.
139+
140+
### Advanced: prefer-native
141+
142+
By default `<mux-video>` will use Hls.js if the browser supports [Media Source Extension](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API). This includes using Hls.js in Mac OS Safari.
143+
144+
If you prefer to use the browser-native Hljs engine whenever possible then pass in the `prefer-native` attribute.
145+
146+
```html
147+
<mux-video
148+
playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
149+
env-key="mux-data-env-key"
150+
metadata-video-title="Big Buck Bunny"
151+
metadata-viewer-user-id="user-id-1234"
152+
prefer-native
153+
controls
154+
>
155+
</mux-video>
156+
```
157+
158+
### Advanced: Signed URLs and other playback query params
159+
160+
Mux supports a number of query parameters on HLS playback URLs. Most commonly is the `token=` param [used for signed URLs](https://docs.mux.com/guides/video/secure-video-playback).
161+
162+
In order to use `token=` -- or any other query params, pass them through with the `playback-id` attribute:
163+
164+
```
165+
playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe?token=jwt-signed-token"
166+
```
167+
168+
# FAQ
169+
170+
### If I'm using Mux, do I have to use this library?
171+
172+
No, not at all! The way Mux delivers HLS video is compliant with the HLS spec. Any video player that supports HLS will work with Mux Video.
173+
174+
### If I'm not use Mux Video, can I still use this library?
175+
176+
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.

0 commit comments

Comments
 (0)