Image handling
Resize, crop, filter, and watermark artwork on the fly with the Tuned Global image engine
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]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 resize an image, add the required width and height to the request URL: [Thumbor URL]/unsafe/[WIDTH]x[HEIGHT]/[image path]
For example, to request a 200 × 200 image:
https://dxfve6m7pg0pq.cloudfront.net/unsafe/200x200/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
Important: By default, the image engine crops the image to match the requested dimensions. It does not perform a proportional resize. To resize the image without cropping, use fit-in (described below).
Advanced Options
Crop — default behaviour
When you specify dimensions without fit-in, the image is scaled to fill the target area. Any overflow is then cropped from the centre.
For example, the following request produces a tall 100 × 320 image:
https://dxfve6m7pg0pq.cloudfront.net/unsafe/100x320/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
The image fills the requested dimensions, and any content outside the 100 × 320 frame is removed.
Flip an image
Use a negative value for either dimension to flip the image:
- Negative width: flip horizontally
- Negative height: flip vertically
For example, this requests a 200 × 2000 image and flips it horizontally.: unsafe/-200x-200
https://dxfve6m7pg0pq.cloudfront.net/unsafe/-200x-200/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
Fit-in — proportional resize
Use fit-in to scale the image proportionally so that the complete image fits within the requested dimensions.
[Thumbor URL]/unsafe/fit-in/[WIDTH]x[HEIGHT]/[image path]
The image retains its original aspect ratio and is not cropped.
For example, to fit an image within 160 × 160:
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/160x160/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
To fit the same image within 200 × 1500:
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/200x1500/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
In this example, the image is constrained by the 200-pixel width. Its height is calculated automatically to preserve the original proportions.
Choosing between crop and fit-in
Crop — default | Grid layouts, thumbnails, avatars, and banners that require exact dimensions | Fills the requested area and crops any overflow |
fit-in | Detail views and full artwork displays | Shows the complete image and preserves its aspect ratio, but may not fill the entire container |
Filters
Filters let you control image quality, brightness, contrast, output format, and other visual properties.
Add filters after the size parameter using the filters: prefix: [Thumbor URL]/unsafe/[size]/filters:[filter1]:[filter2]/[image path]
Chain multiple filters together using colons.
Quality
Use quality(n) to control image compression, where n is a value from 1 to 100.
- Lower values produce smaller files but reduce visual quality.
- Higher values preserve more detail but increase file size.
For most applications, quality(70) provides a good balance between image quality and loading performance.
In the example below, the image is in quality(10)
/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg)
:https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/200x200/filters:quality(10)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
Brightness and Contrast
Use brightness(n) and contrast(n) to adjust the appearance of an image. Both filters accept values from -100 to 100.
| -100 to 100 | Negative values darken the image; positive values lighten it |
| -100 to 100 | Negative values reduce contrast; positive values increase it |
The following example reduces brightness and applies high contrast:
:brightness(-10):contrast(100)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg)
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/200x200/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
Output format
Use format(type) to force a specific output format.
| Recommended for most artwork and photographic images |
| Use when transparency must be preserved |
| Use for supported clients when smaller file sizes are required |
The engine returns JPEG by default, although the output may vary depending on the source image.
The following example forces PNG output:
:format(png)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg)
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/200x200/filters:quality(70):format(png)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
Watermarks
Use the watermark filter to overlay another image, such as a logo, on the source artwork.
watermark(imageUrl, x, y, alpha [, w_ratio [, h_ratio]])
| URL of the watermark image. Parentheses in the URL must be URL-encoded |
| Horizontal position. Positive values position from the left; negative values position from the right. Use |
| Vertical position. Positive values position from the top; negative values position from the bottom. Use |
| Transparency value from |
| Optional. Watermark width as a percentage of the source image width |
| Optional. Watermark height as a percentage of the source image height |
The following example adds the Tuned Global logo to the image with 50% transparency:
/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg){kind=logo}
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/400x400/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 options
Sizing, fit modes, and filters can be combined in a single request.
The following example:
- Fits the image within
300 × 300without cropping - Sets the image quality to
5 - Forces JPEG output
- Sets contrast to
100
:format(jpeg):contrast(100)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg)
https://dxfve6m7pg0pq.cloudfront.net/unsafe/fit-in/300x300/filters:quality(5):format(jpeg):contrast(100)/d16npyvi7pcxgr.cloudfront.net/images1004/100/4_0/060/252/790/910/3/104_1004_00602527909103_20220222_1307.jpg
The transformation portion of the URL is: /unsafe/fit-in/300x300/filters:quality(5):format(jpeg):contrast(100)/
Recommended presets
The following presets provide a useful starting point for common interface components.
Thumbnail grid |
| Crops images to create consistently sized square tiles |
Album detail artwork |
| Displays the complete artwork without cropping |
Artist hero banner |
| Crops the image to fill a wide banner |
Mobile list item |
| Produces a small, fast-loading image |
Blurred background |
| Produces a low-quality, blurred image for decorative backgrounds |
These presets are starting points. Adjust the dimensions and quality settings to suit your layouts, target devices, and network requirements.
Best practices
- Always specify dimensions: Do not serve the original full-size image directly to end users. Requesting an appropriately sized image reduces bandwidth usage, improves loading performance, and avoids unnecessary client-side resizing.
- Choose the appropriate resize mode: Use the default crop behaviour when a component must have exact dimensions, such as a thumbnail, avatar, or banner.mUse
fit-inwhen displaying the complete artwork is more important than filling the entire container. - Optimise image quality: Use
quality(70)as a general default. Lower values may be suitable for small thumbnails and decorative backgrounds. Higher values may be appropriate for large artwork displayed prominently in the interface. - Select the appropriate format: Use JPEG for most artwork unless transparency must be preserved. Use PNG for transparent images. Use WebP when it is supported by your target clients and smaller file sizes are required.
- Build URLs at render time: Store the raw image URL or image path returned by the metadata API, then construct the final image-engine URL when rendering the interface. This lets your application request different sizes, formats, and quality levels without retrieving the metadata again.
- Use responsive image sizes: Serve image dimensions appropriate to the device and layout. Avoid sending a large desktop image to every client. Where supported, use responsive image techniques such as
srcsetandsizesso the browser can select the most appropriate resource. - Cache transformed images: Requests that use the same source image and transformation parameters return the same result. Use long-lived client and CDN caching where appropriate. Changing the dimensions, fit mode, filters, or format creates a different image URL and therefore a separate cached resource.
On this page
- Image handling