starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[Enhancement]: Add episode number and date to file name #1644

New Issue
Open
opened 2026-04-24 23:53:06 +02:00 by adam · 10 comments
adam commented 2026-04-24 23:53:06 +02:00
Owner
Copy Link
Copy Source

Originally created by @peterpepo on GitHub (Jan 4, 2024).

Describe the feature/enhancement

Adding the episode number and (or - configurable) date to downloaded file name.
After downloading (archiving) my favourite podcast, its folder looks like a huge mess inside without indicating date or number of the episode.

I've seen alternative podcast app, where you can configure to prepend episode number and date to downloaded file name.
Adding this would be a huge improvement. Optionally renaming all previous files (without redownloading from scratch).

Implementing this would greatly improve organization inside podcast folder, which currently can be only alphabetically ordered, and really makes no sense when accessed from outside of audiobookshelf gui (for example windows explorer, when I play in my mp3 player)

Example of such file names:

<episode_num>_<YYYY-MM-DD>_<Episode_name>.<ext>
004_2024-01-03_Hello.mp3
003_2024-01-01_World.mp3
002_2023-10-17_Lorem.mp3
001_2022-11-15_Ipsum.mp3

My favourite podcast folder currently looks like this:
abs_folder_inside

Originally created by @peterpepo on GitHub (Jan 4, 2024). ### Describe the feature/enhancement Adding the episode number and (or - configurable) date to downloaded file name. After downloading (archiving) my favourite podcast, its folder looks like a huge mess inside without indicating date or number of the episode. I've seen alternative podcast app, where you can configure to prepend episode number and date to downloaded file name. Adding this would be a huge improvement. Optionally renaming all previous files (without redownloading from scratch). Implementing this would greatly improve organization inside podcast folder, which currently can be only alphabetically ordered, and really makes no sense when accessed from outside of audiobookshelf gui (for example windows explorer, when I play in my mp3 player) Example of such file names: ``` <episode_num>_<YYYY-MM-DD>_<Episode_name>.<ext> 004_2024-01-03_Hello.mp3 003_2024-01-01_World.mp3 002_2023-10-17_Lorem.mp3 001_2022-11-15_Ipsum.mp3 ``` My favourite podcast folder currently looks like this: ![abs_folder_inside](https://github.com/advplyr/audiobookshelf/assets/2683131/f2ebb363-2196-4567-8493-8160281b5ccd)
adam added the enhancement label 2026-04-24 23:53:06 +02:00
adam commented 2026-04-24 23:53:07 +02:00
Author
Owner
Copy Link
Copy Source

@kxseven commented on GitHub (Aug 13, 2024):

I would like to suggest a revision to this enhancement that on the basis that the episode number won't always be known for podcasts unless it is already part of RSS feed data.

Example podcast RSS
image

Suggested revision:

  • Allow the user to configure the podcast filename based on tokens similar to that used in other media management software
  • Allow tokens for
    • Episode title (%E)
    • Podcast title (%P)
    • Published date (%D) - raw value from the RSS Feed
    • Published date (%YMD) - simple date in YYYY-MM-DD format that allows for normal file sorting to work as expected
  • Set the default value for this configuration to "%E" to prevent breaking existing deployments
@kxseven commented on GitHub (Aug 13, 2024): I would like to suggest a revision to this enhancement that on the basis that the episode number won't always be known for podcasts unless it is already part of RSS feed data. **Example podcast RSS** ![image](https://github.com/user-attachments/assets/307710d5-7790-422d-b030-aee1b9e661f0) Suggested revision: - Allow the user to configure the podcast filename based on tokens similar to that used in other media management software - Allow tokens for - Episode title (%E) - Podcast title (%P) - Published date (%D) - raw value from the RSS Feed - Published date (%YMD) - simple date in YYYY-MM-DD format that allows for normal file sorting to work as expected - Set the default value for this configuration to "%E" to prevent breaking existing deployments
adam commented 2026-04-24 23:53:08 +02:00
Author
Owner
Copy Link
Copy Source

@imalmo commented on GitHub (Mar 12, 2025):

I see this as a crucial feature and it's the one omission that is holding me back from using Audiobookshelf. It doesn't make much difference when streaming from Audiobookshelf at home, but it makes a huge difference to the organisation of a folder when manually transferring to another audio app when out and about.

Being able to prepend 'YYYY-MM-DD' to the start of a file makes organisation simple.

@imalmo commented on GitHub (Mar 12, 2025): I see this as a crucial feature and it's the one omission that is holding me back from using Audiobookshelf. It doesn't make much difference when streaming from Audiobookshelf at home, but it makes a huge difference to the organisation of a folder when manually transferring to another audio app when out and about. Being able to prepend 'YYYY-MM-DD' to the start of a file makes organisation simple.
adam commented 2026-04-24 23:53:09 +02:00
Author
Owner
Copy Link
Copy Source

@MagiX13 commented on GitHub (May 17, 2025):

I wrote a few lines that allow to replace placeholders for Season (%S), Episode (%E), Episode title (%T), published Year (%Y), Month (%M) and Day (%D) with the respective information for the individual episode. For now, this is done via a env variable that can be set - otherwise the episode title is used as is currently the case.
Question is: would this be sufficient for now to get such functionality merged? Do I need to implement FE functionality to set this up? Customisation options per podcast etc?

For sure, documenting (but where?) such a feature is needed, but I think an env variable might be sufficient to address the requirements here and in #1869

@MagiX13 commented on GitHub (May 17, 2025): I wrote a few lines that allow to replace placeholders for Season (%S), Episode (%E), Episode title (%T), published Year (%Y), Month (%M) and Day (%D) with the respective information for the individual episode. For now, this is done via a env variable that can be set - otherwise the episode title is used as is currently the case. Question is: would this be sufficient for now to get such functionality merged? Do I need to implement FE functionality to set this up? Customisation options per podcast etc? For sure, documenting (but where?) such a feature is needed, but I think an env variable might be sufficient to address the requirements here and in #1869
adam commented 2026-04-24 23:53:09 +02:00
Author
Owner
Copy Link
Copy Source

@MagiX13 commented on GitHub (May 22, 2025):

Pinging @advplyr for potential input on the above

@MagiX13 commented on GitHub (May 22, 2025): Pinging @advplyr for potential input on the above
adam commented 2026-04-24 23:53:10 +02:00
Author
Owner
Copy Link
Copy Source

@advplyr commented on GitHub (May 22, 2025):

I don't think it should be an ENV variable. It probably belongs in the podcast library settings.
How are you handling when there is no episode or season?

@advplyr commented on GitHub (May 22, 2025): I don't think it should be an ENV variable. It probably belongs in the podcast library settings. How are you handling when there is no episode or season?
adam commented 2026-04-24 23:53:10 +02:00
Author
Owner
Copy Link
Copy Source

@MagiX13 commented on GitHub (May 22, 2025):

Then I need to play a bit around with the FE as well

I was wondering if this should be a podcast library setting or a podcast specific setting (taking the default from the library). Also because of %S and %E as you rightly point out.

For now it just doesn't replace the %S or %E tag if the season/episode is null. However, I'm more than happy to hear of any ideas on how to better handle that. removing the tags might be an option but this might leave weird artifacts for "S%SE%E-%T like "SE-Title"

@MagiX13 commented on GitHub (May 22, 2025): Then I need to play a bit around with the FE as well I was wondering if this should be a podcast library setting or a podcast specific setting (taking the default from the library). Also because of %S and %E as you rightly point out. For now it just doesn't replace the %S or %E tag if the season/episode is null. However, I'm more than happy to hear of any ideas on how to better handle that. removing the tags might be an option but this might leave weird artifacts for "S%SE%E-%T like "SE-Title"
adam commented 2026-04-24 23:53:10 +02:00
Author
Owner
Copy Link
Copy Source

@katbyte commented on GitHub (Sep 22, 2025):

Great to see this issue already exists and there is a PR for it already! thanks @MagiX13 for a PR - using a format string + allowing it to be set per podcast i think solves the problem fairly completely addressing most edge cases i can think of

This is stopping me from fully using audiobookshelf for podcasts and retiring podgrab (which is abandoned) as filenames are really important to me

and now that my current podcast app has added ads 😒 looking to switch over

@advplyr any timeline for when the PR could be looked at / is there anything holding it up?

@katbyte commented on GitHub (Sep 22, 2025): Great to see this issue already exists and there is a PR for it already! thanks @MagiX13 for a PR - using a format string + allowing it to be set per podcast i think solves the problem fairly completely addressing most edge cases i can think of This is stopping me from fully using audiobookshelf for podcasts and retiring podgrab (which is abandoned) as filenames are really important to me and now that my current podcast app has added ads 😒 looking to switch over @advplyr any timeline for when the PR could be looked at / is there anything holding it up?
adam commented 2026-04-24 23:53:10 +02:00
Author
Owner
Copy Link
Copy Source

@JoeKarlsson commented on GitHub (Sep 23, 2025):

+1 for implementation of this feature. This filename customization capability has become a critical blocker for practical podcast management and playability.

@JoeKarlsson commented on GitHub (Sep 23, 2025): +1 for implementation of this feature. This filename customization capability has become a critical blocker for practical podcast management and playability.
adam commented 2026-04-24 23:53:10 +02:00
Author
Owner
Copy Link
Copy Source

@1lL1l1 commented on GitHub (Mar 21, 2026):

Just adding that I'd also love to see this feature, hoping to see it implemented at some point.

@1lL1l1 commented on GitHub (Mar 21, 2026): Just adding that I'd also love to see this feature, hoping to see it implemented at some point.
adam commented 2026-04-24 23:53:11 +02:00
Author
Owner
Copy Link
Copy Source

@svenjacobs commented on GitHub (Apr 12, 2026):

I just started using Audiobookshelf. Being able to specify file name patterns with episode numbers and/or timestamps would be really helpful for keeping podcast folders organized. It would be even better if it could also process existing files.

@svenjacobs commented on GitHub (Apr 12, 2026): I just started using Audiobookshelf. Being able to specify file name patterns with episode numbers and/or timestamps would be really helpful for keeping podcast folders organized. It would be even better if it could also process existing files.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#1644
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?