Fast thumbnails for
online media.

The Javascript client provides additional functionality to integrate into web browsers.

• Defines custom <tbr-thumb> HTML element
• Zero runtime dependencies, only needs fetch
• Automatic lazy streaming and batch requests through viewport visibility
• Caching takes full advantage of HTTP header directives
• No build imports, works directly in simple web pages
• Placeholders for failures, even when disconnected or misconfigured
• Thumbrella supports over one hundred formats

The custom element <tbr-thumb> element is defined under the optional export /element. Use the setup function as the easiest way to register everything.

<script type="module">
  import { tbrSetup } from "https://cdn.jsdelivr.net/npm/@thumbrella/client@1/browser.js";
  tbrSetup("http://localhost:3114");
</script>

<h1>Hello, Thumbrella</h1>
<tbr-thumb src="https://demo.thumbrella.dev/media/pocket-game.webp"></tbr-thumb>
<tbr-thumb src="https://demo.thumbrella.dev/media/padres-stereo.exr"></tbr-thumb>

A separate export at /browser provides a lightwer weight set of functions to help integrate Thumbrella client results with dom nodes.

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

• examples/element.html Using the custom <tbr-thumb> element.
• examples/browser.html Track multiple thumbnails as they stream.

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

• Caching takes full advantage of HTTP header directives
• Binary thumbnails load easily into PIL, Qt, Pygame, and others
• Placeholders for failures, even when disconnected or misconfigured
• Bundled CLI for thumbnailing local files
• Thumbrella supports over one hundred 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
• In-memory LRU cache takes full advantage of HTTP header directives
• 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 -OG "http://localhost:3114/thumb.jpeg" \
  --data-urlencode "url=https://demo.thumbrella.dev/media/harbor-trucks.mp4"

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

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

See the client API documentation for more details how these calls can be used.