Media

The simplest way to download cover art and preview audio is through the client methods download_cover() and download_preview() (shown below). They wrap the transport-driven helpers in spotify_scraper.media, which the sync and async facades share. Cover embedding needs the media extra (mutagen); install it with pip install "spotifyscraper[media]". See the Media downloads guide for examples.

Client methods

spotify_scraper.SpotifyClient.download_cover

download_cover(
    entity: HasImagesAndName,
    dest: str | Path = ".",
    *,
    size: ImageSize = "largest",
    filename: str | None = None,
) -> Path

Download an entity's cover art to dest and return its path.

Parameters:

Name	Type	Description	Default
entity	HasImagesAndName	Any fetched model carrying name and images (a :class:Track falls back to its album's images when empty).	required
dest	str | Path	Destination directory; created if it does not exist.	'.'
size	ImageSize	"largest" or "smallest" of the available images.	'largest'
filename	str | None	Explicit filename; defaults to a sanitized <name>.<ext> (extension from the response content type).	None

Returns:

Type	Description
Path	The path of the written image.

Raises:

Type	Description
MediaError	If the entity has no images.
SpotifyScraperError	If the client is closed.

spotify_scraper.SpotifyClient.download_preview

download_preview(
    entity: Track | Episode,
    dest: str | Path = ".",
    *,
    filename: str | None = None,
    embed_cover: bool = False,
) -> Path

Download a track or episode preview MP3 and return its path.

Parameters:

Name	Type	Description	Default
entity	Track | Episode	A :class:Track or :class:Episode with a preview_url.	required
dest	str | Path	Destination directory; created if it does not exist.	'.'
filename	str | None	Explicit filename; defaults to a sanitized <name>.mp3.	None
embed_cover	bool	When True, embed the entity's cover art and basic tags via mutagen (the media extra).	False

Returns:

Type	Description
Path	The path of the written MP3.

Raises:

Type	Description
MediaError	If no preview exists, or embed_cover is requested without mutagen installed.
SpotifyScraperError	If the client is closed.

Async client methods

spotify_scraper.AsyncSpotifyClient.download_cover async

download_cover(
    entity: HasImagesAndName,
    dest: str | Path = ".",
    *,
    size: ImageSize = "largest",
    filename: str | None = None,
) -> Path

Download an entity's cover art to dest and return its path.

Parameters:

Name	Type	Description	Default
entity	HasImagesAndName	Any fetched model carrying name and images (a :class:Track falls back to its album's images when empty).	required
dest	str | Path	Destination directory; created if it does not exist.	'.'
size	ImageSize	"largest" or "smallest" of the available images.	'largest'
filename	str | None	Explicit filename; defaults to a sanitized <name>.<ext> (extension from the response content type).	None

Returns:

Type	Description
Path	The path of the written image.

Raises:

Type	Description
MediaError	If the entity has no images.
SpotifyScraperError	If the client is closed.

spotify_scraper.AsyncSpotifyClient.download_preview async

download_preview(
    entity: Track | Episode,
    dest: str | Path = ".",
    *,
    filename: str | None = None,
    embed_cover: bool = False,
) -> Path

Download a track or episode preview MP3 and return its path.

Parameters:

Name	Type	Description	Default
entity	Track | Episode	A :class:Track or :class:Episode with a preview_url.	required
dest	str | Path	Destination directory; created if it does not exist.	'.'
filename	str | None	Explicit filename; defaults to a sanitized <name>.mp3.	None
embed_cover	bool	When True, embed the entity's cover art and basic tags via mutagen (the media extra).	False

Returns:

Type	Description
Path	The path of the written MP3.

Raises:

Type	Description
MediaError	If no preview exists, or embed_cover is requested without mutagen installed.
SpotifyScraperError	If the client is closed.

Helper functions

These are the lower-level functions the client methods delegate to; reach for them only if you are driving a transport yourself.

spotify_scraper.media.download_cover_sync

download_cover_sync(
    transport: Transport,
    entity: HasImagesAndName,
    dest: Path,
    *,
    size: ImageSize = "largest",
    filename: str | None = None,
) -> Path

Download an entity's cover art and return the written path.

Parameters:

Name	Type	Description	Default
transport	Transport	HTTP transport to fetch the image with.	required
entity	HasImagesAndName	Any entity carrying name and images.	required
dest	Path	Destination directory (created if missing).	required
size	ImageSize	"largest" or "smallest".	'largest'
filename	str | None	Explicit filename; defaults to <name>.<ext>.	None

Returns:

Type	Description
Path	The path of the written image.

Raises:

Type	Description
MediaError	If the entity has no images.

spotify_scraper.media.download_cover_async async

download_cover_async(
    transport: AsyncTransport,
    entity: HasImagesAndName,
    dest: Path,
    *,
    size: ImageSize = "largest",
    filename: str | None = None,
) -> Path

Async mirror of :func:download_cover_sync.

spotify_scraper.media.download_preview_sync

download_preview_sync(
    transport: Transport,
    entity: Previewable,
    dest: Path,
    *,
    filename: str | None = None,
    embed_cover: bool = False,
) -> Path

Download a track or episode preview MP3 and return the written path.

Parameters:

Name	Type	Description	Default
transport	Transport	HTTP transport to fetch with.	required
entity	Previewable	A :class:Track or :class:Episode with a preview_url.	required
dest	Path	Destination directory (created if missing).	required
filename	str | None	Explicit filename; defaults to <name>.mp3.	None
embed_cover	bool	When True, embed the entity's cover art and basic tags via mutagen (the media extra).	False

Returns:

Type	Description
Path	The path of the written MP3.

Raises:

Type	Description
MediaError	If no preview exists, or embed_cover is requested without mutagen installed.

spotify_scraper.media.download_preview_async async

download_preview_async(
    transport: AsyncTransport,
    entity: Previewable,
    dest: Path,
    *,
    filename: str | None = None,
    embed_cover: bool = False,
) -> Path

Async mirror of :func:download_preview_sync.

spotify_scraper.media.pick_image

pick_image(
    images: Sequence[Image], size: ImageSize
) -> Image

Return the largest or smallest image by pixel area.

Parameters:

Name	Type	Description	Default
images	Sequence[Image]	Candidate images; must be non-empty.	required
size	ImageSize	"largest" or "smallest".	required

Returns:

Type	Description
Image	The selected :class:Image.

Raises:

Type	Description
MediaError	If images is empty.

spotify_scraper.media.safe_filename

safe_filename(name: str, max_length: int = 150) -> str

Sanitize name into a single safe path component.

Strips control characters and path separators, collapses whitespace, preserves Unicode word characters, and caps the result length.

Parameters:

Name	Type	Description	Default
name	str	Raw entity name.	required
max_length	int	Maximum length of the returned stem.	150

Returns:

Type	Description
str	A non-empty, separator-free filename stem.

spotify_scraper.media.extension_from_content_type

extension_from_content_type(
    content_type: str | None,
) -> str

Map a response content type to a bare file extension (default jpg).