# Spotify Saver Folder Structure Convention for Organizing Downloaded Music > Discover Spotify Saver's folder structure convention for organizing downloaded music. Learn the Artist → Album (Year) → Track hierarchy for efficient file management on gabrielbaute/spotify-saver. - Repository: [Gabriel Baute/spotify-saver](https://github.com/gabrielbaute/spotify-saver) - Tags: best-practices - Published: 2026-03-02 --- **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: ``` // ()/ - - . ``` ### 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 ` ()`. 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 ` - - .`. 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`](https://github.com/gabrielbaute/spotify-saver/blob/main/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 `/` 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 `/` 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 ` - - .` 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: ```python 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: ```python 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: ```python 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: ```python 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`](https://github.com/gabrielbaute/spotify-saver/blob/main/spotifysaver/downloader/youtube_downloader.py), which sanitizes metadata for cross-platform compatibility. - **Track files are named** using the pattern ` - - .` 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// ()/ - - .`. 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 ` - - .`. 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 `/` directory. Playlist downloads similarly receive `cover.jpg` and `playlist.nfo` files in the playlist's root folder.