woltapp / blurhash

BlurHash BlurHash is a compact representation of a placeholder for an image. Why would you want this? Does your designer cry every time you load their beautifully designed screen, and it is full of empty boxes because all the images have not loaded yet? Does your database engineer cry when you want to solve this by trying to cram little thumbnail images into your data to show as placeholders? BlurHash will solve your problems! How? Like this: You can also see nice examples and try it out yourself at blurha.sh! How does it work? In short, BlurHash takes an image, and gives you a short string (only 20-30 characters!) that represents the placeholder for this image. You do this on the backend of your service, and store the string along with the image. When you send data to your client, you send both the URL to the image, and the BlurHash string. Your client then takes the string, and decodes it into an image that it shows while the real image is loading over the network. The string is short enough that it comfortably fits into whatever data format you use. For instance, it can easily be added as a field in a JSON object. In summary:     Want to know all the gory technical details? Read the algorithm description. Implementing the algorithm is actually quite easy! Implementations are short and easily ported to your favourite language or platform. Implementations So far, we have created these implementations: • C - An encoder implementation in portable C code. • Swift - Encoder and decoder implementations, and a larger library offering advanced features. There is also an example app to play around with the algorithm. • Kotlin - A decoder implementation for Android. • TypeScript - Encoder and decoder implementations, and an example page to test. • Python - Integration of the C encoder code into Python. These cover our use cases, but could probably use polishing, extending and improving. There are also these third party implementations that we know of: • Pure Python - Implementation of both the encoder and decoder in pure Python. • One version in Go, and another version in Go. • PHP - Encoder and decoder implementations in pure PHP. • Java - Encoder implementation in Java. • Clojure - Encoder and decoder implementations in Clojure. • Nim - Encoder and decoder implementation in pure Nim. • Rust and WebAssembly - Encoder and decoder implementations in Rust. Distributed as both native Rust and WebAssembly packages. • Ruby - Encoder implementation in Ruby. • Crystal - Encoder implementation in pure Crystal. • Elm - Encoder and decoder in Elm. • Dart - Encoder and decoder implementation in C into Dart using dart-ffi. • Pure Dart - Encoder and decoder implementation in pure Dart. • .NET - Encoder and decoder in C#. • JavaScript - Encoder and decoder implementation in pure JavaScript. • .NET - Encoder implementation in C#. • Haskell - Encoder and decoder in pure Haskell. • Scala - Encoder and decoder in Scala. • Elixir - Encoder implementation in pure Elixir. • ReScript - Encoder and decoder implementation in ReScript (BuckleScript). • JavaScript - Tiny optimized decoder implementation JS. • Xojo - Encoder and decoder implementation in pure Xojo. • React Native - UI Component for React Native. (Decoder in Swift and Kotlin) • Zig - Encoder implementation in Zig. • Titanium SDK - Decoder for Titanium SDK (Android) • BQN - Encoder, decoder and terminal viewer in pure BQN. • Jetpack Compose - Decoder Jetpack Compose implementation • C++ - Encoder and decoder in C++. • Kotlin Multiplatform - Encoding & decoding for Android, iOS & JVM • OCaml - Encoder implementation in OCaml. Can't find the language you're looking for? Try your luck with the GitHub search. For example, here are the search results for repos which have "blurhash" in their name. Perhaps you'd like to help extend this list? Which brings us to... Contributing We'd love contributions! The algorithm is very simple - less than two hundred lines of code - and can easily be ported to your platform of choice. And having support for more platforms would be wonderful! So, Java decoder? Golang encoder? Haskell? Rust? We want them all! We will also try to tag any issues on our issue tracker that we'd love help with, so if you just want to dip in, go have a look. You can file a pull request with us, or you can start your own repo and project if you want to run everything yourself, we don't mind. If you do want to contribute to this project, we have a code of conduct. Users Who uses BlurHash? Here are some projects we know about: • Wolt - We are of course using it ourselves. BlurHashes are used in the mobile clients on iOS and Android, as well as on the web, as placeholders during image loading. • Mastodon - The Mastodon decentralised social media network uses BlurHashes both as loading placeholders, as well as for hiding media marked as sensitive. • Signal - Signal Private Messenger uses Blurhashes as placeholders before photo & video messages are downloaded in chat conversations. • Jellyfin - Jellyfin the free software media system uses Blurhashes as placeholders for images of movies and TV shows when they are being downloaded. Good Questions How fast is encoding? Decoding? These implementations are not very optimised. Running them on very large images can be a bit slow. The performance of the encoder and decoder are about the same for the same input or output size, so decoding very large placeholders, especially on your UI thread, can also be a bit slow. However! The trick to using the algorithm efficiently is to not run it on full-sized data. The fine detail of an image is all thrown away, so you should scale your images down before running BlurHash on them. If you are creating thumbnails, run BlurHash on those instead of the full images. Similarly, when displaying the placeholders, very small images work very well when scaled up. We usually decode placeholders that are 32 or even 20 pixels wide, and then let…