Skip to main content

benecaster_duration_display

Filter Free

Filters an episode duration as the website shows it. It fires in benecaster_format_duration(), the one website duration formatter, so a callback reaches Benecaster’s episode cards, the [benecaster_latest_episode] shortcode’s duration, and any theme template that calls the function. Use it to show 1 hour 2 minutes, 1hr 2mins, or the seconds again (1:02:03).

The default is hours and minutes, H:MM, rounded to the nearest minute: 00:47:23 shows as 0:47 and 01:02:03 as 1:02. 0:47 is forty-seven minutes. Anything above zero is at least 0:01.

Display only. The feed, REST’s duration and the episode editor keep HH:MM:SS, which podcast apps require, and nothing stored changes. The admin Episodes list has its own filter, benecaster_admin_duration_display.

Return '' to hide the figure on the website: the episode card then prints no duration element, and leaves out its whole meta row when the duration was the only thing in it; [benecaster_latest_episode] prints no duration paragraph.

Parameters

Name Type Default Description
$formatted string — The default: `H:MM`, rounded to the nearest minute. For a value that is not a duration, that value as stored, trimmed
$seconds int|null — Total whole seconds, or null when the value is not a duration
$duration string — The value as stored or passed in

Returns: string

Example

add_filter( 'benecaster_duration_display', function ( string $formatted, ?int $seconds ): string {
    if ( null === $seconds ) {
        return $formatted; // Free text the podcaster typed: leave it alone.
    }
    $minutes = $seconds > 0 ? max( 1, (int) round( $seconds / 60 ) ) : 0;
    $hours   = intdiv( $minutes, 60 );
    $minutes = $minutes % 60;

    if ( 0 === $hours ) {
        return sprintf( '%dmins', $minutes );          // 47mins
    }
    return sprintf( '%dhr %dmins', $hours, $minutes ); // 1hr 2mins
}, 10, 2 );

Notes

It is not called for an empty duration. Return $formatted when $seconds is null, so free text a podcaster typed survives. A callback that returns words translates them itself, with _n() and sprintf(). See Show durations in words on the website, Show short-form durations and Bring the seconds back on the website.

Affects

Need this built rather than just documented? See our services →