woltapp/blurhash

A very compact representation of a placeholder for an image.

Summary

BlurHash is an algorithm and reference library, written in portable C, that encodes a small blurred preview of an image as a short string (typically 20-30 characters). The string travels with the image metadata, and clients decode it into a low-resolution preview to display while the full image loads over the network. The repository also ships implementations in Swift, Kotlin, TypeScript, and a Python wrapper, with many third-party ports for Go, PHP, Java, Rust, C#, and others.

What it is useful for

The primary use case is showing image placeholders during load. Instead of an empty box while a network fetch is in flight, the client renders a soft, color-accurate preview derived from the original image. This avoids storing separate thumbnail files just to populate empty UI areas.

Beyond placeholders, the README documents a few secondary uses. Mastodon uses BlurHash to mask images marked as such, sidestepping expensive blur filters. Because the data representation exposes frequency components, engineers can extract approximate color averages for specific regions (for example, the top edge of an image) without doing full pixel work. The README also notes that the average color of the entire image is encoded in just the DC component and can be retrieved without implementing the rest of the DCT pipeline.

How engineers can use it

The repo does not document a single installation command. It is structured as a reference C encoder in a C/ directory, with separate directories for Swift, Kotlin, and TypeScript ports. Engineers integrating BlurHash will typically pick the implementation for their stack (for example, the Swift port for iOS, Kotlin for Android, TypeScript for browsers) and link or vendor the relevant sources.

In a typical workflow, the backend encodes an image into a BlurHash string and stores it alongside the image record. When sending data to a client (as a field in JSON, for instance), both the image URL and the BlurHash string are included. The client decodes the string into a small image (the README suggests 20-32 pixels wide, then scaled up by the UI layer) and shows it until the real image arrives.

Two tuning knobs are documented: the number of X and Y components (4x3 is suggested as a balance, adjusted for aspect ratio), and an optional punch parameter that scales contrast. A documented limitation is performance: encoding or decoding very large inputs is not optimized and can be slow, especially on a UI thread. The recommended mitigation is to scale source images down before encoding and keep decoded placeholders small.