@mux/blurhash

A server-side package for node that uses woltapp/blurhash and sharp to make placeholders for Mux videos. Works nicely with Mux Player.

Note

Since we wrote this library, we've learned a lot about blurry image placeholders on the web. While we would still encourage the use of facade placeholders and lazy-loading, using blurhash in the way this library promotes may not be the most efficient technique.

Check out the new @mux/blurup library and Wes's blog post for the latest on this topic.

Installation

npm install @mux/blurhash

or

yarn add @mux/blurhash

Examples

• With NextJS and mux-player-react [Basic Usage] [Live Example]
• With SvelteKit and mux-player [Basic Usage] [Lazy Loading] [Live Example]

Usage

Run @mux/blurhash server-side. @mux/blurhash will not work in the browser.

import muxBlurHash from '@mux/blurhash';

const playbackId = '3fevCt00ntwf7WxwvBhRo1EZ01IoABwo2d';
const { blurHash, blurHashBase64, sourceWidth, sourceHeight } = await muxBlurHash(playbackId);

Using blurHashBase64 with Mux Player

mux-player element

<mux-player
	placeholder="{blurHashBase64}"
	style="aspect-ratio: {sourceWidth}/{sourceHeight}"
></mux-player>

mux-player-react and mux-player-react/lazy

<MuxPlayer placeholder={blurHashBase64} style={{ aspectRatio: sourceWidth / sourceHeight }} />

See the examples directory to learn more

Using blurHashBase64 with native elements

HTML

<img src="{blurHashBase64}" width="{sourceWidth}" height="{sourceHeight}" />

CSS

background-image: url({blurHashBase64});
aspect-ratio: {sourceWidth}/{sourceHeight};

Using blurHash with JavaScript

Canvas

See documentation for blurhash.decode

Options

@mux/blurhash will accept an optional second parameter that will allow configuration of the blurhash.

Parameter	Type	Description	Default
blurWidth	number	The image will be compressed to this width before blurring. Lower values load faster but have less detail.	32
blurHeight	number	The image will be compressed to this height before blurring. Lower values load faster but have less detail.	32
time	number	The video timestamp from which to grab the blurhash. (If you're using a thumbnailToken, then the time option will have no effect; encode time in your token according to the secure video playback guide linked below)
thumbnailToken	string	Videos with playback restrictions may require a thumbnail token. See https://docs.mux.com/guides/video/secure-video-playback for details

For example...

import muxBlurHash from '@mux/blurhash';

// a lower resolution blurHash that will load more quickly
const options = { blurWidth: 16, blurHeight: 16 };
const { blurHash } = await muxBlurHash(playbackId, options);