Skip to main content

Thumbnail Manipulation

Overview​

The Stingray Music API offers a versatile service for manipulating thumbnails of images associated with music tracks, albums, artists, and other related media. This service is hosted through the img.stingray.com domain and allows users to transform images by applying various query parameters directly within the image URL. This feature is particularly useful for developers who need to display images at different resolutions or formats on their applications to enhance user experience and optimize loading times.

Accessing the Service​

To use the thumbnail manipulation service, you will need to fetch images from the Stingray domain using the following base URL: https://img.stingray.com/v3/{token}.

The image can then be modified by appending the desired query parameters to the URL.

Supported Query Parameters​

The service supports the following query parameters, which can be used to transform the thumbnail images:

  • height: The desired height of the image in pixels.
  • width: The desired width of the image in pixels.
  • format: The desired image format. Supported formats are png (default), jpeg, and webp.
  • quality: The image compression quality. This parameter is only applicable when the format parameter is also set. The quality range for png is from 0 (lowest quality, highest compression) to 9 (highest quality, lowest compression), and for jpeg from 1 (lowest quality, highest compression) to 100 (highest quality, lowest compression).
Default

The default dimension for station thumbnails is 540 pixels by 540 pixels. For song thumbnails, the default dimension is 574 pixels by 574 pixels.

Usage Examples​

Below are some examples of how to use the query parameters to manipulate image thumbnails:

Note that if the format parameter is not present, the quality parameter will have no effect.

Best Practices​

  • Always specify both width and height to maintain the aspect ratio of the image unless a specific distortion is required for your design.
  • Use the format parameter to serve the most appropriate image format supported by the client's browser to optimize performance.
  • Adjust the quality parameter carefully to find the right balance between image clarity and file size, particularly important for web applications to ensure fast loading times.

Conclusion​

The thumbnail manipulation service provided by the Stingray Music API is a powerful tool for developers to dynamically adjust images to suit the needs of their applications. By utilizing the supported query parameters, developers can ensure that their applications serve optimized images without the need for additional image processing tools.