Skip to content

Download Structure and Metadata

Jump to bottom
V1ck3s edited this page Mar 7, 2026 · 2 revisions

Download Structure & Metadata

This page documents how octo-fiesta organizes downloaded music and what metadata is embedded in files.

Folder Structure

Downloaded music is organized using a configurable folder template. The default template produces a clean Artist/Album/Track hierarchy:

downloads/
├── Artist Name/
│   ├── Album Title/
│   │   ├── 01 - Track One.flac
│   │   ├── 02 - Track Two.flac
│   │   └── ...
│   └── Another Album/
│       └── ...
└── playlists/
    ├── My Favorite Songs.m3u
    └── ...

Custom Templates

You can customize the folder structure using the FOLDER_TEMPLATE setting. See Configuration - Folder Template for all available placeholders and examples.

A few examples:

# Default
FOLDER_TEMPLATE={artist}/{album}/{track} - {title}
# → Radiohead/OK Computer/06 - Karma Police.mp3

# With year and quality
FOLDER_TEMPLATE={artist}/[{year}] {album} ({quality})/{track} - {title}
# → Radiohead/[1997] OK Computer (MP3_128)/06 - Karma Police.mp3

# Genre-based
FOLDER_TEMPLATE={genre}/{artist} - {year} - {album}/{disc}-{track} - {title}
# → Alternative/Radiohead - 1997 - OK Computer/1-06 - Karma Police.mp3

File Naming

Tracks

With the default template, track files are named:

{track_number} - {title}.{extension}

Examples:

  • 01 - Enter Sandman.flac
  • 02 - Sad but True.mp3
  • 10 - The Unforgiven.flac

The file name is determined by the last segment of the folder template. With a custom template, the naming follows whatever pattern you define.

Special Characters

File and folder names are sanitized to be filesystem-safe:

  • Invalid characters (/, \, :, *, ?, ", <, >, |) are replaced or removed
  • Leading/trailing spaces and dots are trimmed
  • Very long names are truncated

Playlist Files

Playlists are stored as M3U files in the playlists/ subdirectory:

#EXTM3U
#PLAYLIST:My Favorite Songs
#EXTINF:325,Metallica - Enter Sandman
../Metallica/Metallica (1991)/01 - Enter Sandman.flac
#EXTINF:289,Nirvana - Smells Like Teen Spirit
../Nirvana/Nevermind (1991)/01 - Smells Like Teen Spirit.flac

Features:

  • Extended M3U format with metadata
  • Relative paths for portability
  • Compatible with most music players
  • Automatically updated as tracks are downloaded

Embedded Metadata

octo-fiesta embeds comprehensive metadata in downloaded files using ID3v2 (MP3) or Vorbis comments (FLAC).

Basic Information

Tag Description Example
Title Track title Enter Sandman
Artist Track artist(s) Metallica
Album Album name Metallica
Album Artist Primary album artist Metallica
Genre Music genre Metal

Track Information

Tag Description Example
Track Number Track position 1
Total Tracks Total tracks on album 12
Disc Number Disc number 1
Total Discs Total discs 1

Date Information

Tag Description Example
Year Release year 1991
Release Date Full release date 1991-08-12

Audio Information

Tag Description Example
BPM Beats per minute 120
Duration Track length 331 (seconds)

Identifiers

Tag Description Example
ISRC International Standard Recording Code USEE10100057
Comment Additional info (may include ISRC) ISRC: USEE10100057

Credits

Tag Description Example
Composer Song composer(s) James Hetfield, Lars Ulrich
Contributors Additional contributors Bob Rock

Rights Information

Tag Description Example
Copyright Copyright notice © 1991 Elektra Records
Label Record label Elektra

Cover Art

High-resolution cover art is embedded directly in audio files:

  • Format: JPEG or PNG
  • Resolution: Highest available from provider (typically 1000x1000 or higher)
  • Type: Front cover

The same cover art is used for all tracks in an album.

Quality & Format

Downloaded files match your configured quality settings:

Setting Format Typical Bitrate File Size (4 min track)
FLAC FLAC ~1000 kbps ~30 MB
FLAC_24_HIGH FLAC 24-bit ~3000 kbps ~90 MB
MP3_320 MP3 320 kbps ~10 MB
MP3_128 MP3 128 kbps ~4 MB

Navidrome Integration

For seamless integration with Navidrome:

  1. Set download path to a directory Navidrome scans:

    DOWNLOAD_PATH=/path/to/navidrome/music/octo-fiesta

  2. Trigger a library scan in Navidrome after downloads:

    • Automatic: Navidrome's scheduled scan will pick up new files
    • Manual: Use Navidrome's "Scan" button

  3. Playlist import:

    • Configure Navidrome to scan the playlists/ directory
    • M3U files will be imported as playlists

Storage Considerations

Disk Space

Estimate storage needs based on quality:

Quality Per Track Per Album (12 tracks) Per 1000 tracks
MP3 128 ~4 MB ~48 MB ~4 GB
MP3 320 ~10 MB ~120 MB ~10 GB
FLAC 16-bit ~30 MB ~360 MB ~30 GB
FLAC 24-bit ~90 MB ~1 GB ~90 GB

Cache Management

octo-fiesta includes a cache cleanup service that can be configured to manage disk space. Downloaded tracks remain permanently unless manually deleted.

Troubleshooting

Missing Metadata

Some tracks may have incomplete metadata from the provider. octo-fiesta embeds all available metadata but cannot add what the provider doesn't supply.

Cover Art Issues

If cover art is missing:

  • The provider may not have cover art for that release
  • The cover art URL may have been temporarily unavailable

File Permission Issues

Ensure the download directory is writable by the user running octo-fiesta:

chmod 755 /path/to/downloads

For Docker:

volumes:
  - ./downloads:/app/downloads

Clone this wiki locally