Fast thumbnails for
online media.

The Python client uses requests for blocking and optionally aiohttp for async streaming results.

• Client defaults to synchronous requests with requests
• Async support via thumbrella-client[async] using aiohttp
• Caching takes full advantage of HTTP cache headers
• Binary thumbnails load easily into PIL, Qt, `Pygame, and other image libraries
• Always provides placeholder, even when disconnected or misconfigured
• Typed results with media classification and metadata
• Thumbrella server supports hundreds of formats

##  Install with,  `uv add thumbrella-client`  ##

import thumbrella

# Connect to server and generate a thumbnail.
tbr = thumbrella.Client()
result = tbr.thumb("https://demo.thumbrella.dev/media/blue-scooter.fbx")
print(result.status, len(result.media.thumbnail), "bytes")

# Pillow can decode from a zero-copy buffer.
from PIL import Image
img = Image.open(result.media.thumbnail.io)

The source comes with several starting point examples. See the client documentation for more details and examples.

• examples/basic.py Download a thumbnail from a single url.
• examples/stream.py Stream multiple thumbnails as they render.
• examples/collage.py Assemble thumbnails from multiple sources into a single grid image.

The Rust client provides easy, high level functionality for caching, error control, and other conveniences. By default it provides async calls using reqwests and tokio. Using the blocking feature provides a blocking interface for simpler environments.

• Async-first with reqwest (rustls TLS)
• Minimal dependencies, reqwest, serde, base64, thiserror
• Stream results as the server renders thumbnails (coming soon)
• In-memory LRU cache takes full advantage of HTTP cache headers
• The client and server always provide placeholder images, even when disconnected
• Typed results with media classification and metadata
• Thumbrella server supports hundreds of formats

//  Install with, `cargo add thumbrella-client`  //

use thumbrella_client as thumbrella;

#[tokio::main]
async fn main() -> Result<(), thumbrella::Error> {
    let tbr = thumbrella::Client::new(None);
    tbr.verify().await?;

    // Get result and write thumbnail to jpeg file
    let result = tbr.thumb("https://demo.thumbrella.dev/media/game-level.png").await?;
    if let Some(media) = &result.media {
        println!("{} bytes  {}", media.thumbnail.len(), media.kind);
        std::fs::write("thumb.jpg", media.thumbnail.bytes())?;
    }

    Ok(())
}

The source comes with several starting point examples. See the client documentation for more details and examples.

• examples/basic.rs Download a thumbnail from a single url.
• examples/stream.rs Stream multiple thumbnails as they render.

The direct HTTP requests are designed to be usable without rich clients. This can work from any language with any HTTP library. Also from command line tools like curl or wget.

• Batch requests process in parallel
• Streamable batch results with ndjson or sse
• Every request results in a valid image or placeholder
• Server provides advanced http caching support
• Thumbrella server supports hundreds of formats

curl -G "http://localhost:3114/thumb" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/harbor-trucks.mp4" \
  --output thumb.jpeg

To interact with Thumbrella Cloud, register online for a quick and free account. Then add the token into the Authoriation header.

curl -G "https://cloud.thumbrella.dev/thumb" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/golden-gate.exr" \
  --header "Authorization: Bearer tbr_e_HVZgIwSOUwhJZscXQ2sN7eO" \
  --output thumb.jpeg

See the client api documentation for more details on the calls available.

The Astro components provide a higher level component for thumbnails. These components are still a work in progress and not ready yet for immediate use.

Get started with npm install @thumbrella/astro.

The thumbnail components work together to handle streaming, batching, and caching automatically.

---
import { Client, Thumbnail } from '@thumbrella/client';

const tbr = new Client(import.meta.env.THUMBRELLA_KEY);
---
<Thumbnail src="https://demo.thumbrella.dev/media/harbor-trucks.mp4" />

Each page is expected to have a global <Thumbrella> component to define the server and configuration details. The page then uses multiple <Thumbnail> components.

The thumbnails are intended to be handled by browsers as the page is viewed. They are not downloaded and applied to the site as static content.