Image Handling

Overview

Tuned Global provides an image engine (powered by Thumbor) that lets you resize, crop, filter, and watermark artwork on the fly. Instead of requesting pre-sized images, you construct a URL that tells the engine exactly what dimensions, quality, and effects you need — it processes the original image and returns the result via CDN.

This means your application only needs to know the base image URL (returned by the metadata API) and the Thumbor endpoint (provided by Tuned Global). You build the final URL at render time, tailored to each device and layout.

Prerequisites

A Thumbor base URL provided by Tuned Global (e.g. https://dxfve6m7pg0pq.cloudfront.net/)
Image URLs returned from the metadata API (artist artwork, album covers, playlist images, etc.)
Understanding of the pixel dimensions your application needs for each UI component

How It Works

Every image request follows this URL pattern:

[Thumbor URL]/unsafe/[parameters]/[image path]

Segment	Description	Example
Thumbor URL	Fixed base URL provided by Tuned Global	`https://dxfve6m7pg0pq.cloudfront.net/`
unsafe/	Required path prefix for all requests	`unsafe/`
Parameters	Size, fit mode, and filters (detailed below)	`fit-in/420x420/filters:quality(70)`
Image path	The image URL from the API, without `https://`	`d16npyvi7pcxgr.cloudfront.net/images1004/...`

Getting the Image Path

The metadata API returns full image URLs for tracks, albums, artists, and playlists. For example:

https://d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

To use this with the image engine, strip the https:// prefix and append the remainder to your Thumbor request:

d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Note: The raw API URL returns the full-size original image as delivered by the label (format may be converted). Always use the image engine to serve appropriately sized images to your users.

Basic Usage

To request a resized image, specify the target dimensions in pixels as WIDTHxHEIGHT:

[Thumbor URL]/unsafe/[WIDTH]x[HEIGHT]/[image path]

Example — 420x420 image:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/420x420/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Important: By default, specifying dimensions will crop the image (not proportionally resize it). The image is scaled to fill the largest dimension, then cropped to the smallest. If you need proportional resizing without cropping, use the fit-in mode described below.

Advanced Options

Crop (Default Behaviour)

When you specify dimensions without fit-in, the engine scales the image to fill the target area and crops the overflow from the centre.

Example — 420x1420 (tall crop):

https://dxfve6m7pg0pq.cloudfront.net/unsafe/420x1420/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

The image becomes 1420px tall and is cropped to 420px wide from the centre.

Flip: Use a negative value for either dimension to flip the image horizontally (negative width) or vertically (negative height).

Fit-In (Proportional Resize)

Use fit-in to scale the image proportionally so it fits entirely within the specified dimensions, with no cropping. The image is scaled to the smallest dimension.

[Thumbor URL]/unsafe/fit-in/[WIDTH]x[HEIGHT]/[image path]

Example — fit within 420x420:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x420/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Example — fit within 420x1420:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x1420/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

The image retains its original proportions and is not cropped — it scales down to fit the constraining dimension (420px in this case).

Choosing Between Crop and Fit-In

Mode	Best For	Behaviour
Crop (default)	Grid layouts, thumbnails, avatars — where you need exact dimensions	Fills the area, trims overflow
Fit-in	Detail views, full artwork display — where you need the complete image	Scales to fit, may leave whitespace

Filters

Filters let you adjust quality, brightness, contrast, format, and more. Add them after the size parameter using the filters: prefix. Chain multiple filters with colons.

[Thumbor URL]/unsafe/[size]/filters:[filter1]:[filter2]/[image path]

Quality

Control JPEG compression quality from 1 (lowest) to 100 (highest). Lower values reduce file size and improve load times.

Recommended: quality(70) — a good balance between visual quality and file size for most applications.

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x420/filters:quality(70)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Brightness and Contrast

Adjust brightness and contrast for specific visual effects. Both accept values from -100 to 100.

Filter	Range	Effect
`brightness(n)`	-100 to 100	Negative = darker, positive = lighter
`contrast(n)`	-100 to 100	Negative = flatter, positive = punchier

Example — reduced brightness with high contrast:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x420/filters:quality(70):brightness(-10):contrast(100)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Format

Force a specific output format. The engine defaults to JPEG but may return PNG depending on the source image.

Format	Use Case
`format(jpeg)`	Smallest file size — recommended for most artwork
`format(png)`	When transparency is required
`format(webp)`	Modern browsers — smaller than JPEG at equivalent quality

Example — force JPEG output:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x420/filters:quality(70):format(jpeg)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Watermark

Overlay a watermark image with full control over positioning, transparency, and sizing.

Syntax:

watermark(imageUrl, x, y, alpha [, w_ratio [, h_ratio]])

Parameter	Description
`imageUrl`	URL of the watermark image. If the URL contains parentheses, they must be URL-encoded
`x`	Horizontal position. Positive = from left, negative = from right. Use `center` to centre horizontally, `repeat` to tile. Append `p` for percentage (e.g. `20p`)
`y`	Vertical position. Positive = from top, negative = from bottom. Use `center` to centre vertically, `repeat` to tile. Append `p` for percentage (e.g. `20p`)
`alpha`	Transparency from 0 (fully opaque) to 100 (fully transparent)
`w_ratio`	Optional. Percentage of image width the watermark should fit. Defaults to `none`
`h_ratio`	Optional. Percentage of image height the watermark should fit. Defaults to `none`

Example — logo watermark at bottom-right with 50% transparency:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/420x420/filters:watermark(https://d2byqs7e78w6a1.cloudfront.net/DEMO/video/test_meta2/tg-logo-web-1.png,-10,-70p,50)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Note: Additional filters are available including blur and saturation. Contact Tuned Global for the full filter reference.

Combining Everything

Filters, sizing, and fit mode all compose into a single URL. Here's a production-ready example that resizes to 300x300, fits proportionally, sets quality to 70, and forces JPEG output:

https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/300x300/filters:quality(70):format(jpeg)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg

Recommended Presets

Use Case	URL Parameters	Notes
Thumbnail grid (square)	`unsafe/150x150/filters:quality(60):format(jpeg)`	Crop mode for exact grid alignment
Album detail artwork	`unsafe/fit-in/600x600/filters:quality(80):format(jpeg)`	Fit-in to show full artwork
Artist hero banner	`unsafe/1200x400/filters:quality(70):format(jpeg)`	Crop for wide banner layout
Mobile list item	`unsafe/fit-in/80x80/filters:quality(60):format(jpeg)`	Small, fast-loading
Background blur overlay	`unsafe/fit-in/400x400/filters:quality(40):blur(20):format(jpeg)`	Low quality + blur for background effect

Best Practices

Always specify dimensions. Never serve the original full-size image to end users — it wastes bandwidth and slows rendering.
Use fit-in for variable layouts. If your container size isn't guaranteed to match the image aspect ratio, fit-in prevents unexpected cropping.
Set quality to 70 for general use. This reduces file size significantly with minimal visible quality loss on artwork.
Force JPEG format unless you specifically need transparency (PNG) or are targeting modern browsers only (WebP).
Cache aggressively on the client. Image URLs with the same parameters always return the same result — set long cache headers in your application.
Build URLs at render time. Store only the raw image path from the API. Construct the full Thumbor URL when rendering, so you can adjust dimensions per device without re-fetching metadata.
Use responsive sizing. Serve different dimensions for mobile, tablet, and desktop rather than one large image for all devices.

Image Handling

Image Handling

Overview

Prerequisites

How It Works

Getting the Image Path

Basic Usage

Advanced Options

Crop (Default Behaviour)

Fit-In (Proportional Resize)

Choosing Between Crop and Fit-In

Filters

Quality

Brightness and Contrast

Format

Watermark

Combining Everything

Recommended Presets

Best Practices

On this page