09 July 2025 - (in calibre 8.6.0)
- format_duration(value, template, [largest_unit])
Format the value, a number of seconds, into a string showing weeks, days, hours, minutes, and seconds. If the value is a float then it is rounded to the nearest integer. You choose how to format the value using a template consisting of value selectors surrounded by [ and ] characters. The selectors are:
Code:
[w]: weeks
[d]: days
[h]: hours
[m]: minutes
[s]: seconds
You can put arbitrary text between selectors.
The optional largest_unit parameter specifies the largest of weeks, days, hours, minutes, and seconds that will be produced by the template. If provided it must be one of the
value selectors.
The following examples use a duration of 2 days (172,800 seconds) 1 hour (3,600 seconds) and 20 seconds, which totals to 176,420 seconds. - format_duration(176420, '[d][h][m][s]') will return the value 2d 1h 0m 20s.
- format_duration(176420, '[h][m][s]') will return the value 49h 0m 20s.
- format_duration(176420, 'Your reading time is [d][h][m][s]', 'h') returns the value Your reading time is 49h 0m 20s.
- format_duration(176420, '[w][d][h][m][s]') returns the value 2d 1h 0m 20s. Note that the zero weeks value is not returned.
More functionality is documented in calibre.