Media Event Filter

A dependecy free, tiny package for producing a sane default interpretation of playback events from a HTMLMediaElement.

Why

The HTML5 video element does not produce a consistent set of events that correspond to the updates required by trackers and user interfaces, like loaded, buffering or seeking.

Different player engines built on top of the Media Source Extension all have their own implementations for listening to events.

This filter aims to provide a single source of truth that can be used across player engines and browser native playback.

Adheres to the Eyevinn Player Analytics Specification.

Overview

``typescript
/* Loading of stream is complete, playback is ready to start /
/* It is now safe to let the user press a play button /
"loaded";
/* A seek has started /
"seeking";
/* A seek has ended /
"seeked";
/* Buffering has started /
/* Does not trigger during seek, cancelled by a seek /
"buffering";
/* Buffering has ended /
/* Does not trigger during seek /
"buffered";
/* A request to start playing again has been made /
"play";
/** The stream has started playing after loading completed
OR the stream has started playing after the stream was previously paused /
"playing";
/* The stream has been paused /
"pause";
/* The end of the stream was reached /
"ended";
/* A timeupdate event /
"timeupdate";
`

Limitations

Does not support native HTML5 MSE controls (

Usage

npm install @eyevinn/media-event-filter

yarn add @eyevinn/media-event-filter

Example of creating and listening to the event filter.

`typescript
import {
getMediaEventFilter,
FilteredMediaEvent,
} from "@eyevinn/media-event-filter";

const videoElement = document.createElement("video");

// Using a switch statement

const mediaEventFilter = getMediaEventFilter({
mediaElement: videoElement,
callback: (event: FilteredMediaEvent) => {
switch (event) {
case FilteredMediaEvent.LOADED:
// handle loaded
break;
case FilteredMediaEvent.BUFFERING:
// handle buffering
break;
case FilteredMediaEvent.BUFFERED:
// handle buffered
// ...
default:
break;
}
},
});

// Call when done
mediaEventFilter.teardown();
`

`typescript
// Object notation can also be used

const handlers = {
[FilteredMediaEvent.LOADED]: () => {
/ handle loaded /
},
[FilteredMediaEvent.BUFFERING]: () => {
/ handle buffering /
},
[FilteredMediaEvent.BUFFERED]: () => {
/ handle buffered /
},
// ...
};

const mediaEventFilter = getMediaEventFilter({
mediaElement: videoElement,
callback: (event: FilteredMediaEvent) => handlers[event]?.(),
});
`

`typescript
// It is safe to use destructuring

const { teardown } = getMediaEventFilter({
/ ... /
});

teardown();
`

$3

The filter can be used to easily build a React UI on top of Shaka.

A barebones sample integration (see it on codepen):

`javascript
import { useCallback, useEffect, useMemo, useRef, useState } from "React";
import shaka from "shaka-player";
import {
FilteredMediaEvent,
getMediaEventFilter,
} from "@eyevinn/media-event-filter";

const PlayerComponent = ({ videoUrl }) => {
const videoRef = useRef(null);
const [playing, setPlaying] = useState(false);
const [loading, setLoading] = useState(true);
const [blocked, setBlocked] = useState(false);

useEffect(() => {
if (!videoUrl || !videoRef.current) return () => {};

const eventFilter = getMediaEventFilter({
mediaElement: videoRef.current,
// add your state handlers here
callback: (event) => {
switch (event) {
case FilteredMediaEvent.LOADED:
setLoading(false);

// attempt autoplay
videoRef.current.play().catch((e) => {
// catch autoplay block
if (e.name.indexOf("NotAllowedError") > -1) {
setBlocked(true);
}
});
break;
case FilteredMediaEvent.PLAYING:
// reset autplay blocked
setBlocked(false);
// we're playing!
setPlaying(true);
break;
case FilteredMediaEvent.ENDED:
case FilteredMediaEvent.PAUSE:
setPlaying(false);
break;
default:
break;
}
},
});

const player = new shaka.Player(videoRef.current);

// Add configuration if needed
// player.configure()

player
// start loading the stream
.load(videoUrl)
// catch errors during load
.catch(console.error);

// Kill player when unmounted
return () => {
player.destroy();
eventFilter.teardown();
};
}, [videoUrl, videoRef]);

const play = useCallback(() => {
if (!videoRef.current) return;

videoRef.current.play();
}, [videoRef]);

const pause = useCallback(() => {
if (!videoRef.current) return;

videoRef.current.pause();
}, [videoRef]);

return (



);
};
`

`javascript
// Use it:

`

Benefits

Get a single source of truth for playback events regardless of engine (Shaka, Hls.js, DashJS, native) or browser (Chrome, Firefox, Safari).

Pipe the events directly into your UI state management for a reliable source of truth of playback state updates.

The event sequence map directly to popular tracking providers and playback SDKs without further filtering, like Youbora, Comscore, Yospace, or Nielsen. _If yours is also supported we welcome PRs to update this list!_

Compatible with EPAS.

Events

A description of events and their sequencing.

$3

`typescript
LOADED; // playback is ready to start
PLAYING; // playback started
SEEKING; // seek requested
PAUSED; // manual pause
PLAY; // manual play
SEEKED; // seek finished
PLAYING; // video is rolling again
BUFFERING; // unable to continue playing due to missing buffer
BUFFERED; // buffer ended by incoming seek request
SEEKING; // seek requested
SEEKED; // seek finished
PAUSED; // manual pause
PLAY; // manual play
PLAYING; // video is rolling again
ENDED; // video reached the end
`

$3

The initial load of the video has completed, and it is ready to start playing.

No other event can trigger before loaded.

$3

Seeking has started.

If buffering is ongoing buffered will be triggered prior to seeking.

Buffer events can not trigger during a seek.

Can not trigger before loaded.

$3

Seeking has ended.

Can not trigger before loaded.

Can not trigger without a preceding seeking event.

$3

Buffering has started.

Can not trigger during a seek.

Can not trigger before loaded.

$3

Buffering has ended, or was interrupted by a seek.

Can not trigger during a seek.

Can not trigger without a preceding buffering event.

$3

Playback has been requested.

Can not trigger before loaded.

Can not trigger if video was not previously paused.

$3

Playback has started.

Can not trigger before loaded.

Can not trigger during seeking.

Can not trigger during buffering.

Can not trigger if video was not previously paused.

A play requested during seeking or buffering will trigger playing after the seek or buffer has finished.

$3

Playback has been paused.

Seeking or buffering do not count as pausing.

Can not trigger before loaded.

$3

A timeupdate event

Can not trigger before loaded.

$3

The player has reached the end of a stream.

To allow restarting the stream after the end of stream has been reached set allowResumeAfterEnded to true.

Contributing

Contributions to improve compatibility with or add support for different engines, tracking solutions, and browsers are welcome.

$3

The project uses feature branches, and a rebase merge strategy.

Make sure you have git pull set to rebase mode:

git config pull.rebase true

Optionally, you can add the --global flag to the above command.

To start working on a new feature: git checkout .

As the project uses semantic-release to automatically generate release notes based on commits, it is important to follow some rules when committing.

This project uses conventional commits.

Read Using Git with Discipline.

Read How to Write a Commit Message.

A commit should:

- contain a single change set (smaller commits are better)
- pass tests, linting, and typescript checks
- not be broken

Along with enabling time saving automation, it enables extremely powerful debug workflows via git bisect, making bug hunting a matter of minutes instead of days. There are a number of articles out there on the magic of bisecting.

Basic structure of a commit message:

`
[optional scope]: