go-blurhash

go-blurhash is a pure Go implementation of the BlurHash algorithm, which is used by Mastodon an other Fediverse software to implement a swift way of preloading placeholder images as well as hiding sensitive media. Read more about it here.

tl;dr: BlurHash is a compact representation of a placeholder for an image.

This library allows generating the BlurHash of a given image, as well as reconstructing a blurred version with specified dimensions from a given BlurHash.

This library is based on the following reference implementations: - Encoder: https://github.com/woltapp/blurhash/blob/master/C (C) - Deocder: https://github.com/woltapp/blurhash/blob/master/TypeScript (TypeScript)

BlurHash is written by Dag Ågren / Wolt.

	Before	After
Image		"LFE.@D9F01_2%L%MIVD*9Goe-;WB"
Hash	"LFE.@D9F01_2%L%MIVD*9Goe-;WB"

Installation

From source

go get -u github.com/buckket/go-blurhash

Usage

go-blurhash exports three functions:

func blurhash.Encode(xComponents, yComponents int, rgba image.Image) (string, error)
func blurhash.Decode(hash string, width, height, punch int) (image.Image, error)
func blurhash.Components(hash string) (xComponents, yComponents int, err error)

Here’s a simple demonstration. Check pkg.go.dev for the full documentation.

package main

import (
    "fmt"
    "github.com/buckket/go-blurhash"
    "image/png"
    "os"
)

func main() {
    // Generate the BlurHash for a given image
    imageFile, _ := os.Open("test.png")
    loadedImage, err := png.Decode(imageFile)
    str, _ := blurhash.Encode(4, 3, loadedImage)
    if err != nil {
        // Handle errors
    }
    fmt.Printf("Hash: %s\n", str)

    // Generate an image for a given BlurHash
    // Width will be 300px and Height will be 500px
    // Punch specifies the contrasts and defaults to 1
    img, err := blurhash.Decode(str, 300, 500, 1)
    if err != nil {
        // Handle errors
    }
    f, _ := os.Create("test_blur.png")
    _ = png.Encode(f, img)

    // Get the x and y components used for encoding a given BlurHash
    x, y, err := blurhash.Components("LFE.@D9F01_2%L%MIVD*9Goe-;WB")
    if err != nil {
        // Handle errors
    }
    fmt.Printf("xComponents: %d, yComponents: %d", x, y)
}

Limitations

• Presumably a bit slower than the C implementation (TODO: Benchmarks)

Notes

• As mentioned here, it’s best to generate very small images (~32x32px) via BlurHash and scale them up to the desired dimensions afterwards for optimal performance.
• Since #2 we diverted from the reference implementation by memorizing sRGBtoLinear values, thus increasing encoding speed at the cost of higher memory usage.
• Starting with v1.1.0 the signature of blurhash.Encode() has changed slightly (see #3).

License

GNU GPLv3+