@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="https://github.com/muxinc/blurhash/raw/main/{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.

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);