Spotify Saver Folder Structure Convention for Organizing Downloaded Music

Spotify-Saver stores every downloaded audio file under a configurable base directory using a strict three-tier hierarchy of Artist → Album (Year) → Track, implemented in the YouTubeDownloader._get_output_path method.

Spotify-Saver is an open-source tool that downloads Spotify tracks from YouTube sources. According to the gabrielbaute/spotify-saver source code, the application follows a predictable folder structure convention that organizes music by artist and album metadata, making collections easy to browse with any file manager.

The Three-Tier Directory Hierarchy

The convention creates a logical tree that mirrors physical music library standards. Every track is placed according to its metadata following this exact pattern:

<base_dir>/<Artist>/<Album Name> (<Release Year>)/<Track Number> - <Artist> - <Track Title>.<ext>

Artist Level

The first directory level is named after the primary artist (or the album-artist supplied during download). This groups all albums by the same creator under a single folder, preventing a flat list of thousands of files.

Album Level with Release Year

Inside the artist folder, Spotify-Saver creates a sub-folder named <Album Name> (<Release Year>). The year is extracted from the track's release_date field and formatted to four digits. This distinguishes between re-releases, remasters, and different editions of the same album.

Track File Naming

The final audio file follows the pattern <Track Number> - <Artist Name> - <Track Title>.<ext>. Leading zeros ensure proper sorting in file managers. The extension matches the chosen audio format (m4a, mp3, or opus).

How the Folder Structure Is Built in Code

The logic that assembles this layout lives in spotifysaver/downloader/youtube_downloader.py. The YouTubeDownloader class contains two key helpers that construct these paths:

1. _get_output_path (lines 71-95): This method assembles the artist name, album name, and year from the Track object. It sanitizes each component to be Windows-compatible (removing illegal characters), creates the directory tree recursively, and returns the full file path.

2. _get_album_dir (lines 38-48): Used for album-wide operations, this helper returns the same <Artist>/<Album (Year)> folder path that the track writer uses, ensuring consistency between single-track and full-album downloads.

Both methods ensure that special characters in artist or album names are cleaned before directory creation, preventing filesystem errors on Windows, macOS, and Linux.

Special Cases: Albums vs. Playlists

The folder structure convention adapts slightly depending on whether you download a single album or an entire playlist.

Album Downloads

When downloading an entire album, Spotify-Saver applies the standard hierarchy to each track. Additionally, the album folder receives optional metadata files:

• cover.jpg: The album artwork at full resolution
• album.nfo: An XML metadata file containing track listings, dates, and Spotify IDs

These files are written to the same <Artist>/<Album (Year)> directory alongside the audio files.

Playlist Downloads

For playlists, the behavior changes in YouTubeDownloader.download_playlist (lines 42-44). Instead of scattering tracks across individual artist folders, Spotify-Saver creates a top-level folder named after the playlist directly under the base directory. Inside this folder, each track follows the standard <Track Number> - <Artist> - <Track Title>.<ext> naming convention, but without the intermediate Artist/Album subfolders.

Customizing the Base Directory

While the default root folder is Music, you can override this when instantiating the downloader. The YouTubeDownloader class accepts a base_dir parameter that relocates the entire tree:

from spotifysaver.downloader.youtube_downloader import YouTubeDownloader

# Custom base directory

dl = YouTubeDownloader(base_dir="MyMusic")

All subsequent downloads—whether single tracks, albums, or playlists—will be rooted under your specified directory instead of the default Music folder.

Practical Code Examples

Here is how the path construction works with a real Track object:

from spotifysaver.downloader.youtube_downloader import YouTubeDownloader
from spotifysaver.models import Track

# Example Track (normally obtained from Spotify API)

track = Track(
    name="One More Time",
    number=1,
    artists=["Daft Punk"],
    album_name="Discovery",
    release_date="2001-03-12",
    cover_url=None,
)

# Initialise downloader (default base_dir = "Music")

dl = YouTubeDownloader()

# Compute where the file will be saved

output_path = dl._get_output_path(track)   # internal helper, used by the library

print(output_path)

# → Music/Daft Punk/Discovery (2001)/01 - Daft Punk - One More Time.m4a

Downloading an entire album automatically creates the same structure for every track and adds the optional cover image and NFO file:

album = dl.spotify_api.get_album("some_spotify_album_id")  # returns Album object

dl.download_album(album, download_lyrics=True, nfo=True, cover=True)

# Files will appear under:

# Music/Daft Punk/Discovery (2001)/...

# and a "cover.jpg" + "album.nfo" inside the album folder.

Downloading a playlist creates a flat structure within a named folder:

playlist = dl.spotify_api.get_playlist("some_spotify_playlist_id")
dl.download_playlist(
    playlist,
    output_format=AudioFormat.MP3,
    bitrate=Bitrate.B256,
    cover=True,
    nfo=True,
)

# Resulting folder:

# Music/My Awesome Playlist/

# ├─ 01 - Artist - Track1.mp3

# ├─ …

# ├─ cover.jpg

# └─ playlist.nfo

Summary

• Spotify-Saver uses a three-tier hierarchy: Base Directory → Artist → Album (Year) → Track File.
• File paths are constructed by YouTubeDownloader._get_output_path in spotifysaver/downloader/youtube_downloader.py, which sanitizes metadata for cross-platform compatibility.
• Track files are named using the pattern <Track Number> - <Artist> - <Track Title>.<ext> to ensure proper sorting.
• Album downloads include optional cover.jpg and NFO metadata files inside the album folder.
• Playlist downloads create a dedicated top-level folder and store tracks flatly using the standard naming convention.
• The base directory is configurable via the base_dir parameter when initializing YouTubeDownloader, defaulting to Music.

Frequently Asked Questions

What is the default folder structure for Spotify Saver downloads?

By default, Spotify-Saver stores files under a Music directory using the hierarchy Music/<Artist>/<Album Name> (<Year>)/<Track Number> - <Artist> - <Track Title>.<ext>. This structure is applied to every track downloaded from Spotify, whether individually or as part of an album.

How does Spotify Saver handle file names for downloaded tracks?

The application generates file names from the Track object metadata, specifically using the pattern <Track Number> - <Artist Name> - <Track Title>.<ext>. The extension matches the selected audio format (m4a, mp3, or opus). This naming scheme ensures that files sort chronologically by track number in any file manager.

Can I change the base directory where Spotify Saver saves music?

Yes. When instantiating the YouTubeDownloader class, pass a custom base_dir parameter (e.g., YouTubeDownloader(base_dir="MyMusic")). The entire directory tree—artists, albums, and playlists—will be rooted under your specified path instead of the default Music folder.

Does Spotify Saver add metadata files to the album folders?

Yes. When downloading complete albums with the nfo=True and cover=True flags, Spotify-Saver writes a cover.jpg containing the album artwork and an album.nfo file with XML metadata to the same <Artist>/<Album (Year)> directory. Playlist downloads similarly receive cover.jpg and playlist.nfo files in the playlist's root folder.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}