Date transformation function requested

General Discussion
1

Feature Request: Generic $dateformat() Scripting Function

Mp3tag already provides several date/time properties, including locale-dependent values like %_file_mod_datetime% and locale-independent raw values like %_file_mod_datetime_raw%.

However, there is currently no scripting function that allows formatting these values into a user-defined date/time format.

As a result, users cannot easily create locale-independent filenames, tag values or export data without relying on string manipulation or the Windows regional settings.

I would therefore like to propose a generic date formatting function:

$dateformat(<date>, <format>)

For example:

$dateformat(%_file_mod_datetime_raw%,yyyyMMdd)
→ 20260702

$dateformat(%_file_mod_datetime_raw%,yyMMdd)
→ 260702

$dateformat(%_file_mod_datetime_raw%,yyyy-MM-dd)
→ 2026-07-02

$dateformat(%_file_mod_datetime_raw%,dd.MM.yyyy)
→ 02.07.2026

$dateformat(%_file_mod_datetime_raw%,M/d/yyyy)
→ 7/2/2026

$dateformat(%_file_mod_datetime_raw%,yyyy-MM-dd HH:mm:ss)
→ 2026-07-02 14:35:18

A formatting syntax based on the familiar date format specifiers used by many programming languages would probably be the most intuitive:

yyyy
yy
MM
M
MMM
dd
d
ddd
hh
mm
ss

One of the main advantages of a generic $dateformat() function is that it would not be limited to a single placeholder. It could be used consistently with all existing and future date/time properties that provide a well-defined date/time value.

For example:

$dateformat(%_file_create_datetime_raw%,yyyyMMdd)

$dateformat(%_file_mod_datetime_raw%,yyyy-MM-dd hh:mm:ss)

This would provide a simple, locale-independent and reusable solution for all scripting scenarios involving dates and times.

The proposed function name was chosen deliberately because similar concepts already exist in many programming languages and APIs (e.g. Java's DateFormat, PHP's date_format() / DateTime::format()), making its purpose immediately recognizable to many users.

2

I've added a scripting function $fmtDate(fmt,x) to format raw timestamps into human-readable dates using a user-defined format string with Mp3tag v3.36-beta.2.

For example, the date 2001-02-03 04:05:06 can be created using yyyy-MM-dd HH:mm:ss where

Format Output
yyyy 2001 (year)
MM 02 (month)
dd 03 (day)
HH 04 (24-hour)
mm 05 (minute)
ss 06 (second)

If the second parameter (timestamp) is omitted, the current timestamp is used.

3

Thank you.
I tested it and it works with the probably most commonly used date source: the current time and date, the creation and modification date of a file as retrieved with %_file_create_datetime_raw% and %_file_mod_datetime_raw%.
Great stuff.

4

Great!

Which date-time fields are actually supported, e.g. (ISO) calendar weeks (for weekly charts)? Which convention for placeholders do you adopt, i.e. what exactly do M, MM, MMM, MMMM, MMMMM resolve to (e.g. 7, 07, Jul or JUL, July, J)?

5

There is little built-in support for that in Win32 and the only API that's available are GetDateFormat and GetTimeFormat, which treat dates and times separately. As a result, they don't support free-form format strings that mix date and time placeholders.

Because of that, I've implemented a custom parser for a basic set of placeholders. I only want to expose what's actually needed, although I may already have crossed that line.

Extending the table above, the following format specifiers are currently supported:

Format Output Field
yyyy 2001 year
yy 01 year, short
MMMM February month name, long
MMM Feb month name, short
MM 02 month, zero-padded
M 2 month
dddd Saturday weekday, long
ddd Sat weekday, short
dd 03 day, zero-padded
d 3 day
HH 04 24-hour, zero-padded
H 4 24-hour
hh 04 12-hour, zero-padded
h 4 12-hour
mm 05 minute, zero-padded
m 5 minute
ss 06 second, zero-padded
s 6 second

For possible compatibility with a future macOS implementation, I also added the following aliases:
EEEE Saturday weekday, long
EE Sat weekday, short

I haven't looked into week numbers yet. IIRC, there are some funny edge cases like January 1st being in the last week of the previous year in some cases.

Looking at the list above, this should serve as a practical solution for users who previously had to extract individual segments from localized date strings via regular expressions.

6

USA have different week numbering (because of course they do) than the ISO. Main differences are that US weeks starts on Sundays, and week 1 is where January 1st is. ISO weeks starts on Mondays and week 1 is the week containing the first Thursday in January.

7

This is not unique to the USA. In terms of the global population, the prevailing custom is actually that Monday is not traditionally the first day of the week.
However, there is a growing discrepancy (even within the USA) between traditional usage and the digital or business world, where the ISO 8601 standard is increasingly applied. This discrepancy manifests differently depending on whether one is considering the first day of the week or the first calendar week of the year. It is all quite confusing, really.

8

I assumed that Microsoft made ICU (using CLDR data) available to Win32 applications, because formatting dates and times has some unexpected pitfalls indeed. Relying on well-tested APIs almost always makes sense here.

For instance, ordinal week numbers fortunately almost always comply with ISO 8601 rules, which means that Dec 29, 30 and 31 as well as Jan 01, 02 and 03 may belong to adjacent year, so your yyyy and yy would probably fail for them, and also the last week of the year may be the 53rd instead of the 52nd.

Furthermore, some users or locales may choose a different primary calendar, but more often they will use a secondary alternate calendar. Some of them will just have a different year number (e.g. Thailand) or era name and year number (e.g. Japan), others will additionally start the year on a different date and organise months differently (e.g. India, Iran) and possibly use the old Julian leap day algorithm (e.g. Ethiopia) or a lunar one with leap months (e.g. Israel, China) or without (e.g. Middle East). The important bit there is – assuming you, as the sane person you are, do not want to implement support for all of them yourself – that the date calculation functions you are using will always use the Gregorian calendar, not a local one. Most date formatting functions, on the other hand, should respect the system locale and user settings.

CLDR includes “narrow”, single-letter versions of stuff like month and day names, which should be used as table column headers, for instance, where the presences of others will remove ambiguity (e.g. for J, M and A in JFMAMJJASOND or T and S in MTWTFSS). It also records standalone variants for some languages where they differ from use within full dates. Part of day designators like “a.m.” or “PM” and “noon” are another can of worms handled there.