thumbp

⚡ Thumbp: A Lightweight & Fast WebP Thumbnail Image Generator
==============================================================

[![Hex.pm](https://img.shields.io/hexpm/v/thumbp.svg)](https://hex.pm/packages/thumbp)
[![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/thumbp/)
[![Hex.pm](https://img.shields.io/hexpm/dt/thumbp.svg)](https://hex.pm/packages/thumbp)
[![License](https://img.shields.io/hexpm/l/thumbp.svg)](https://github.com/ryochin/thumbp/blob/main/LICENSE)

Thumbp is a highly efficient thumbnail creation library for Elixir, producing [WebP](https://developers.google.com/speed/webp) output for optimal speed and performance.

No need for ImageMagick, FFmpeg, libvips, or any other external libraries.

Usage
-----

Read an image file and create a thumbnail:

```elixir
iex> content = File.read!("./test/assets/images/sample.jpg")
iex> Thumbp.create(content, 320, 240)
{:ok, <<82, 73, 70, 70, 195, 152, 14, 0, 0, 87, 69, ...>>}
```

The `width` and `height` parameters specify maximum bounds rather than exact dimensions; the aspect ratio is preserved.

Adjust the quality with an optional parameter ranging from 0 to 100 (default is 60):

```elixir
iex> Thumbp.create(content, 160, 120, quality: 50)
```

You can also specify a target size, though this may increase processing time by approximately 20-80%.

```elixir
iex> Thumbp.create(content, 160, 120, target_size: 4_096)    # set to 4KB
```

> [!Tip]
> The `quality` and `target_size` options are mutually exclusive.

Adjust the encoding effort from 0 (fastest) to 6 (smallest file size). The default is 3.

```elixir
iex> Thumbp.create(content, 160, 120, effort: 5)
```

Installation
------------

The package can be installed by adding `thumbp` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:thumbp, "~> 0.2.0"}
  ]
end
```

Then, run `mix deps.get`.

Benchmark
---------

* Input: [1280x960 JPEG](https://github.com/ryochin/thumbp/blob/main/test/assets/images/sample.jpg) (85% quality), 171.5KB
* Output: 320x240 WebP (60% quality), ~2.4KB

```sh
mix run benchmark/benchmark.exs
```

```text
Name                      ips        average  deviation         median         99th %
thumbp                 174.05        5.75 ms     ±3.17%        5.73 ms        6.23 ms
image (libvips)        130.71        7.65 ms     ±3.13%        7.62 ms        8.43 ms

Comparison:
thumbp                 174.05
image (libvips)        130.71 - 1.33x slower +1.91 ms
```

Measured on macOS Sequoia 15.7.3 arm64, Apple M4 (10) @ 4.46 GHz.

Development
-----------

### Prerequisites

> [!NOTE]
> This library requires the [Rust](https://www.rust-lang.org/) toolchain, version 1.85 or later, for compilation. The crate uses edition 2024, which earlier toolchains cannot build.

Follow the instructions at [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) to install Rust.

Verify the installation by checking the `cargo` command version:

```sh
cargo --version
# Should output something like: cargo 1.92.0 (344c4567c 2025-10-21)
```

Then, set the `RUSTLER_PRECOMPILATION_EXAMPLE_BUILD` environment variable to ensure that local sources are compiled instead of downloading a precompiled library file.

```sh
RUSTLER_PRECOMPILATION_EXAMPLE_BUILD=1 mix compile
```

License
-------

The MIT License