Skip to content

Proposal: Add configurable download subdirectory templating#125

Open
paubineau wants to merge 1 commit into
LumePart:devfrom
paubineau:custom-download-subdirectory-support
Open

Proposal: Add configurable download subdirectory templating#125
paubineau wants to merge 1 commit into
LumePart:devfrom
paubineau:custom-download-subdirectory-support

Conversation

@paubineau
Copy link
Copy Markdown
Contributor

@paubineau paubineau commented May 1, 2026

My goal is to allow Explo downloads to use a media-server-friendly folder layout, such as {artist}/{album}, so the Explo collection displays correctly in Jellyfin while still supporting non-persistent playlists.

  • Add DOWNLOAD_SUBDIRECTORY_FORMAT to customize download subfolders when USE_SUBDIRECTORY=true
  • Support {playlist}, {artist}, and {album} tokens, with {playlist} preserving the existing default behavior
  • Keep flat downloads unchanged when USE_SUBDIRECTORY=false
  • Expose the new subdirectory format option in the web settings and setup wizard
  • Add file based (called playlist-manifest) tracking/cleanup for non-persistent runs using formats without a {playlist} root
  • Remove empty artist/album folders when playlist-manifest cleanup deletes unreferenced files
  • Refresh Jellyfin images during library scans
  • Write album_artist metadata for YouTube downloads to improve media server grouping

Notes:

DOWNLOAD_SUBDIRECTORY_FORMAT is ignored unless USE_SUBDIRECTORY=true.

Formats rooted by {playlist} keep the existing cleanup behavior: non-persistent runs delete that playlist's download folder.

For formats that do not start with {playlist}, Explo cannot safely delete an entire playlist folder anymore because files from different playlists may share the same artist/album folders. In that case, Explo stores a per-playlist cleanup record under playlist-manifests and only removes files that are no longer referenced by another Explo playlist.

The cleanup implementation is split into path/template helpers (paths.go) and playlist-manifest helpers (manifest.go): path helpers resolve the configured subdirectory format safely, while playlist manifests track which downloaded files belong to each playlist when multiple playlists share the same artist/album folders.

Playlist cleanup only tracks files created by Explo during a run, or files already known from another Explo playlist manifest. Existing user-library files are not claimed for cleanup.

Possible split:

If this PR is not something you want to merge because of the added complexity, the Jellyfin-related changes may still be worth considering separately:

  • Refresh Jellyfin images during library scans
  • Write album_artist metadata for YouTube downloads to improve media server grouping

These changes are independent from the configurable subdirectory feature and improve how Explo-downloaded tracks are grouped and displayed with artwork in Jellyfin.

Disclosure:

I used AI assistance (Codex) to speed up implementation while preparing this PR. I reviewed and tested all changes before submitting.

@paubineau paubineau force-pushed the custom-download-subdirectory-support branch from 04b527a to 082e04d Compare May 9, 2026 11:07
@paubineau paubineau force-pushed the custom-download-subdirectory-support branch from f56ae50 to df1f630 Compare May 9, 2026 11:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant