Title: New function: human_readable_duration Author: Adam Silverstein Published: January 15, 2019 --- [ ](https://profiles.wordpress.org/adamsilverstein/) [Adam Silverstein](https://profiles.wordpress.org/adamsilverstein/) 8:03 pm _on_ January 15, 2019 Tags: [5.1 ( 24 )](https://make.wordpress.org/core/tag/5-1/), [dev-notes ( 647 )](https://make.wordpress.org/core/tag/dev-notes/)    # New function: human_readable_duration In WordPress 5.1, the new `human_readable_duration` function will be introduced. This function accepts a duration in hours, minutes and seconds and returns a “human readable” string appropriate for screen readers. The function takes a string representing a _time duration_, with hours, minutes and seconds separated by a `:` (colon). For example, calling `human_readable_duration(' 3:10' );` will return `3 minutes, 10 seconds`. **Minutes and seconds are required**. For 10 seconds, the call would be `human_readable_duration( '0:10' );`. This new function was added as part of the work to _improve the display of media metadata_ in [#39667](https://core.trac.wordpress.org/ticket/39667) where, in addition to adding units, aria-labels with plain language descriptions were added to improve accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology( for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility): ![https://cldup.com/P8-Sq1n6Bv.png](https://lh5.googleusercontent.com/bi8aZyoZpIMzOsUwsYMks4UTKen35agGkGhr9B7OygotGD- HMxy8NB0cQgifZ-SLycXRAfWw8eg4AjPndC45RzEcJiDMsLABMBcibW4xYv9n_IRK68hXR5W7m2Zr45cWWju_O4Li) Improved time duration accessibility in the media library using the `human_readable_duration()` function. [#5-1](https://make.wordpress.org/core/tag/5-1/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/) ### Share this: * [ Threads ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=threads) * [ Mastodon ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=mastodon) * [ Bluesky ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=bluesky) * [ X ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=x) * [ Facebook ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=facebook) * [ LinkedIn ](https://make.wordpress.org/core/2019/01/15/new-function-human_readable_duration/?share=linkedin) 1. ![](https://secure.gravatar.com/avatar/f8b3e78da513af70d22b0a942297a300eef15e3ce8080e877c054ebb83e24d82? s=32&d=mm&r=g) 2. [JJJ](https://profiles.wordpress.org/johnjamesjacoby/) 8:18 pm _on_ January 15, 2019 3. The string “3:10” looks like a time stamp. 4. We should use “00:03:10” instead, which better communicates the hours:minutes: seconds format used the world over. 5. While I agree this function is neat and useful, I’m concerned about the format you’ve described for the same reasons I state above. 6. I would expect “3:10” to return “3 hours, 10 minutes” and not “3 minutes, 10 seconds.” 7. * ![](https://secure.gravatar.com/avatar/f8b3e78da513af70d22b0a942297a300eef15e3ce8080e877c054ebb83e24d82? s=32&d=mm&r=g) * [JJJ](https://profiles.wordpress.org/johnjamesjacoby/) 8:24 pm _on_ January 15, 2019 * Furthermore, does “10” alone (without a colon) return “10 seconds”? * Any other string formats considered valid or invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also _notabug_) that indicates the ticket is not a bug, is a support request, or is generally invalid.? * Was `human_diff_time()` updated to use this same formatting internally? * ![](https://secure.gravatar.com/avatar/64b51769e7b80312023eb6c3f766cb512cf79adf7265812b15442f9573a9a056? s=32&d=mm&r=g) * [Tran Ngoc Tuan Anh](https://profiles.wordpress.org/rilwis/) 1:37 am _on_ January 16, 2019 * Agree. Without the context, I also think “3:10” is more about “3 hours, 10 minutes”. - ![](https://secure.gravatar.com/avatar/82e095c8bc229017b128e53940ea534aa31f6624431bedee24c7e8756e42dd1c? s=32&d=mm&r=g) - [Adam Silverstein](https://profiles.wordpress.org/adamsilverstein/) 4: 10 am _on_ January 16, 2019 - Note that the screenshot above is from the ticketticket Created for both bug reports and feature development on the bug tracker. and a work in progress. The final string in the media modal includes ‘min’ more like this: [https://core.trac.wordpress.org/raw-attachment/ticket/39667/media-patched.jpg](https://core.trac.wordpress.org/raw-attachment/ticket/39667/media-patched.jpg)). - The function is explicitly designed to make a readable version of the strings the media modal contains and in regard to the input format, the doc blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. gives the context. - > Duration will be in string format (HH:ii:ss) OR (ii:ss), with a possible > prepended negative sign (-). 8. ![](https://secure.gravatar.com/avatar/82e095c8bc229017b128e53940ea534aa31f6624431bedee24c7e8756e42dd1c? s=32&d=mm&r=g) 9. [Adam Silverstein](https://profiles.wordpress.org/adamsilverstein/) 9:53 pm _on_ January 15, 2019 10. The format the function accepts was based on the fields we display in the media model for media duration. The function is used to add screen reader announcements for the durations when users use screen readers. 11. > We should use “00:03:10” instead, which better communicates the hours:minutes: > seconds format used the world over. 12. Are you suggesting we change the format of the media modal to ’00:03:00′ for a three minute item instead of 3:00? I’m not sure that makes sense, however feel free to open a tracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. to make that change. 13. > does “10” alone (without a colon) return “10 seconds”? 14. No. As stated in the post, “Minutes and seconds are required. For 10 seconds, the call would be human_readable_duration( ‘0:10’ );”. This might be worth changing to make the function more useful, however I believe the media modal always provides a minutes values. 15. > Was `human_diff_time()` updated to use this same formatting internally? 16. No this function is not really related to `human_diff_time`. 17. * ![](https://secure.gravatar.com/avatar/2705ec72762002e78c7aded24c0f5342a977a679a86abd8b1b3b2e09d5f6d715? s=32&d=mm&r=g) * [Michael Nelson](https://profiles.wordpress.org/mnelson4/) 6:16 am _on_ January 16, 2019 * This sounds like a nice addition for accessibilityAccessibility Accessibility( commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility). Does it translate to other languages well? - ![](https://secure.gravatar.com/avatar/82e095c8bc229017b128e53940ea534aa31f6624431bedee24c7e8756e42dd1c? s=32&d=mm&r=g) - [Adam Silverstein](https://profiles.wordpress.org/adamsilverstein/) 4: 23 pm _on_ January 16, 2019 - That was the goal! It does enable translations: the function’s internal strings like ‘hours’, ‘minutes’ and ‘seconds’ are all translatable. * ![](https://secure.gravatar.com/avatar/2705ec72762002e78c7aded24c0f5342a977a679a86abd8b1b3b2e09d5f6d715? s=32&d=mm&r=g) * [Michael Nelson](https://profiles.wordpress.org/mnelson4/) 9:54 pm _on_ January 24, 2019 * 🥇! * ![](https://secure.gravatar.com/avatar/7c9f1110d4461bea9644f874501cb1bc6e47a136a0d617bd8885708a67af79ee? s=32&d=mm&r=g) * [David Decker](https://profiles.wordpress.org/daveshine/) 7:46 am _on_ January 16, 2019 * > ’00:03:00′ * Yes, please change to this format as it is internationally used. Everyone would interpret 3:10 as three hours, 10 minutes - ![](https://secure.gravatar.com/avatar/cd8d0c2d1b5e4f91cca07de4b9e18fa26d88365c5573fceabe1eba68bdab5a38? s=32&d=mm&r=g) - [Arkadiusz Biczewski](https://profiles.wordpress.org/axinet/) 12:22 pm _on_ January 16, 2019 - If you see in Spotify 3:10 do you interpret it as 3 hours 10 minutes long song? 3 hours long media in a blogblog (versus network, site) media is so highly unexpectable that defaulting to minutes interpretation sounds really reasonable! * ![](https://secure.gravatar.com/avatar/7c9f1110d4461bea9644f874501cb1bc6e47a136a0d617bd8885708a67af79ee? s=32&d=mm&r=g) * [David Decker](https://profiles.wordpress.org/daveshine/) 2:59 pm _on_ January 17, 2019 * Ok, you are right about that – specifically for music, absolutely. * When using in that context I am ok with this format – however, I can imagine the community might be using this for lots of other things as well via plugins etc. then the general case would make more sense. 18. ![](https://secure.gravatar.com/avatar/edc9cda2015dbd467ad08b5447310f3fdcb322d166aecd352d4d70000e1de6d5? s=32&d=mm&r=g) 19. [Boldair Développement](https://profiles.wordpress.org/boldairdeveloppement/) 5:07 pm _on_ February 25, 2019 20. I tend to agree with the ’00:03:10′ format (OK the ‘min’ appended on display can make it more readable, but if not used in conjunction with media, it could lead to erroneous information (and even then, in media, a video for example could show’ 01:24′ and then would you read it as a 1 minute and 24 second video clip or a 1 hour 24 minutes featured film ?), better display it fully ‘hh:mm:ss’ to avoid possible confusion. (my approach is always to consider that if a possibility exists for a user to get it wrong, some users _will_ get it wrong,. Hence program as if chickens were gonna use your site, then humans will get it :)) 21. * ![](https://secure.gravatar.com/avatar/82e095c8bc229017b128e53940ea534aa31f6624431bedee24c7e8756e42dd1c? s=32&d=mm&r=g) * [Adam Silverstein](https://profiles.wordpress.org/adamsilverstein/) 5:33 pm _on_ February 25, 2019 * Thanks for the feedback. The confusion seems to stem from the difference what is expected from longer forms (eg videos where 1:30 would mean an hour and 30 min and audio where 1:30 would likely be one minute thirty seconds). Since this is a utility function we use for the media modal display, we can probably leave as is as long as the documentation is sufficient to describe the expected behavior. Comments are closed. # Post navigation [← JavaScript Chat Summary – January 15th](https://make.wordpress.org/core/2019/01/15/javascript-chat-summary-january-15th/) [Editor Chat Agenda: January 16th →](https://make.wordpress.org/core/2019/01/15/editor-chat-agenda-january-16th/)