WSI Streamer

A modern, cloud-native tile server for Whole Slide Images. One command to start serving tiles directly from S3.

# Installation (requires Rust, see alternatives below)
cargo install wsi-streamer

# On your local machine
wsi-streamer s3://my-slides-bucket --s3-region eu-west-3

That's it. No configuration files, no local storage, no complex setup. Open http://localhost:3000/view/sample.svs in your browser to view a slide.

Why WSI Streamer?

Whole Slide Images are large (1-3GB+) and typically live in object storage. Traditional viewers require downloading entire files before serving a single tile. WSIStreamer takes a different approach: it understands slide formats natively, fetches only the bytes needed via HTTP range requests, and returns JPEG tiles immediately.

• Range-based streaming — fetches only the bytes needed for each tile, no local files
• Built-in viewer — OpenSeadragon-based web viewer with pan, zoom, and dark theme
• Native format support — Rust parsers for Aperio SVS and pyramidal TIFF
• Production-ready — HMAC-SHA256 signed URL authentication
• Multi-level caching — slides, blocks, and encoded tiles

Installation

Install from crates.io:

cargo install wsi-streamer

Or build from source:

git clone https://github.com/PABannier/WSIStreamer.git
cd WSIStreamer
cargo build --release

Or run with Docker:

# Pull from GitHub Container Registry
docker run -p 3000:3000 -e WSI_S3_BUCKET=my-bucket ghcr.io/pabannier/wsistreamer:latest

# Or use Docker Compose for local development with MinIO
docker compose up --build

Usage

Basic

# Serve slides from S3
wsi-streamer s3://my-slides

# Custom port
wsi-streamer s3://my-slides --port 8080

# S3-compatible storage (MinIO, etc.)
wsi-streamer s3://slides --s3-endpoint http://localhost:9000

API

# List slides
curl http://localhost:3000/slides

# Get slide metadata
curl http://localhost:3000/slides/sample.svs

# Fetch a tile (level 0, position 0,0)
curl http://localhost:3000/tiles/sample.svs/0/0/0.jpg -o tile.jpg

# Get thumbnail
curl "http://localhost:3000/slides/sample.svs/thumbnail?max_size=256" -o thumb.jpg

Authentication

# Enable HMAC-SHA256 authentication
wsi-streamer s3://my-slides --auth-enabled --auth-secret "$SECRET"

# Generate signed URLs
wsi-streamer sign --path /tiles/slide.svs/0/0/0.jpg --secret "$SECRET" --base-url http://localhost:3000

The web viewer handles authentication automatically when enabled.

Validation

# Check S3 connectivity
wsi-streamer check s3://my-slides

# List available slides
wsi-streamer check s3://my-slides --list-slides

# Test a specific slide
wsi-streamer check s3://my-slides --test-slide sample.svs

Configuration

All options can be set via CLI flags or environment variables:

Option	Env Var	Default	Description
--host	WSI_HOST	0.0.0.0	Bind address
--port	WSI_PORT	3000	HTTP port
--s3-bucket	WSI_S3_BUCKET	—	S3 bucket name
--s3-endpoint	WSI_S3_ENDPOINT	—	Custom S3 endpoint
--s3-region	WSI_S3_REGION	us-east-1	AWS region
--auth-enabled	WSI_AUTH_ENABLED	false	Enable authentication
--auth-secret	WSI_AUTH_SECRET	—	HMAC secret key
--cache-slides	WSI_CACHE_SLIDES	100	Max slides in cache
--cache-tiles	WSI_CACHE_TILES	100MB	Tile cache size
--jpeg-quality	WSI_JPEG_QUALITY	80	JPEG quality (1-100)
--cors-origins	WSI_CORS_ORIGINS	any	Allowed CORS origins

Run wsi-streamer --help for full details.

API Reference

Endpoint	Description
GET /health	Health check
GET /view/{slide_id}	Web viewer
GET /tiles/{slide_id}/{level}/{x}/{y}.jpg	Fetch tile
GET /slides	List slides
GET /slides/{slide_id}	Slide metadata
GET /slides/{slide_id}/thumbnail	Thumbnail
GET /slides/{slide_id}/dzi	DZI descriptor

See API_SPECIFICATIONS.md for complete documentation.

Supported Formats

Format	Extensions	Compression
Aperio SVS	.svs	JPEG, JPEG 2000
Pyramidal TIFF	.tif, .tiff	JPEG, JPEG 2000

Files must be tiled (not stripped) and pyramidal.

In the media

• January 17th, 2026: front page of Hacker News and Rust subreddit

License

MIT. See LICENSE.

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md.