Thumbnailer Qt API
unity::thumbnailer::qt::Thumbnailer Class Referencefinal

Class to obtain thumbnail images for various media types. More...

#include <unity/thumbnailer/qt/thumbnailer-qt.h>

Public Member Functions

 Thumbnailer ()
 Constructs a thumbnailer instance. More...
 
 Thumbnailer (QDBusConnection const &connection)
 Constructs a thumbnailer instance, using the supplied DBus connection. More...
 
 ~Thumbnailer ()
 
QSharedPointer< RequestgetAlbumArt (QString const &artist, QString const &album, QSize const &requestedSize)
 Retrieves a thumbnail for an album cover from the remote image server. More...
 
QSharedPointer< RequestgetArtistArt (QString const &artist, QString const &album, QSize const &requestedSize)
 Retrieves a thumbnail for an artist from the remote image server. More...
 
QSharedPointer< RequestgetThumbnail (QString const &filePath, QSize const &requestedSize)
 Extracts a thumbnail from a media file. More...
 

Detailed Description

Class to obtain thumbnail images for various media types.

Class Thumbnailer provides thumbnail images for local media (image, audio, and video) files, as well as album covers and artist images for many musicians and bands.

Most common image formats, such as PNG, JPEG, BMP, and so on, are recognized. For streaming media, the recognized formats depend on the installed GStreamer codecs.

For local media files, thumbnails are extracted directly from the file. (For audio files, this requires the file to contain embedded artwork.) For album covers and artist images, artwork is downloaded from a remote image server (dash.ubuntu.com) that maintains a large database of albums and musicians.

The requested size for a thumbnail specifies a bounding box (in pixels) of type QSize to which the thumbnail will be scaled. (The aspect ratio of the original image is preserved.) Passing QSize(0,n) or QSize(n,0) defines a square bounding box of n pixels. Sizes with one or both dimensions < 0 return an error. Sizes with one or both dimensions ≥ max-thumbnail-size (usually 1920) are clamped to max-thumbnail-size pixels (see thumbnailer-settings(7)).

Original images are never scaled up, so the returned thumbnail may be smaller than its requested size.

All methods are asynchronous and are guaranteed not to block.

The return value is a shared pointer to a Request instance that provides access to the scaled thumbnail (or an error message).

Constructor & Destructor Documentation

unity::thumbnailer::qt::Thumbnailer::Thumbnailer ( )

Constructs a thumbnailer instance.

A default-constructed Thumbnailer instance communicates with the thumbnailer service via the session bus.

unity::thumbnailer::qt::Thumbnailer::Thumbnailer ( QDBusConnection const &  connection)
explicit

Constructs a thumbnailer instance, using the supplied DBus connection.

Instead of connecting to the session bus, this constructor uses the supplied DBus connection to contact the thumbnailer service.

Parameters
connectionThe DBus connection via which to send requests.
unity::thumbnailer::qt::Thumbnailer::~Thumbnailer ( )

Member Function Documentation

QSharedPointer<Request> unity::thumbnailer::qt::Thumbnailer::getAlbumArt ( QString const &  artist,
QString const &  album,
QSize const &  requestedSize 
)

Retrieves a thumbnail for an album cover from the remote image server.

Parameters
artistThe name of the artist.
albumThe name of the album.
requestedSizeThe bounding box for the thumbnail.
Returns
A QSharedPointer to a unity::thumbnailer::qt::Request holding the request state.
QSharedPointer<Request> unity::thumbnailer::qt::Thumbnailer::getArtistArt ( QString const &  artist,
QString const &  album,
QSize const &  requestedSize 
)

Retrieves a thumbnail for an artist from the remote image server.

Parameters
artistThe name of the artist.
albumThe name of the album.
requestedSizeThe bounding box for the thumbnail.
Returns
A QSharedPointer to a unity::thumbnailer::qt::Request holding the request state.
QSharedPointer<Request> unity::thumbnailer::qt::Thumbnailer::getThumbnail ( QString const &  filePath,
QSize const &  requestedSize 
)

Extracts a thumbnail from a media file.

Parameters
filePathThe path to the file to extract the thumbnail from.
requestedSizeThe bounding box for the thumbnail.
Returns
A QSharedPointer to a unity::thumbnailer::qt::Request holding the request state.

The documentation for this class was generated from the following file: