Skip to main content

Assign episode numbers based on a custom sequence

Free Beginner

Benecaster assigns max + 1 across all published episodes by default. Use this filter to suppress auto-numbering for trailers and bonus episodes, restart numbering per season, or skip reserved numbers. Returning 0 suppresses auto-numbering for the episode.

When to Use This

By default Benecaster assigns max(existing numbers) + 1 across all published episodes in a show. Use benecaster_episode_auto_number when:

  • You want to suppress numbering for trailers, bonus, or sponsored episodes

  • Your show uses per-season numbering (S1E1, S1E2, S2E1…) and you want episode numbers to restart with each season

  • You reserve certain numbers (e.g. 100, 200) and need to skip them

  • You manage episode numbers in an external system and want to pull the next value from there

How It Works

The filter receives the number Benecaster was about to assign, plus the episode and show IDs. Return whatever number you want instead. The recipe covers the two common shapes:

  • Suppressing numbering for some episode types — read _benecaster_episode_type and return 0 for anything that isn’t full, which skips assignment entirely.

  • Restarting numbering per season — read _benecaster_season_number, count the published full episodes already in that season, and return that count plus one.

Notes

Return 0 to suppress auto-numbering. A return value of 0 tells Benecaster to skip the auto-number assignment entirely. The episode is published without a number. The podcaster can still set a number manually in the episode editor.

The filter fires only when there is no existing number. It does not override numbers the podcaster has manually set. It fires on first publish of episodes that have no _benecaster_episode_number meta value.

The incoming value is the default calculation. It is max(existing episode numbers for this show) + 1, or 1 if no numbered episodes exist. Return it unchanged to accept the default.

Season numbering requires the Seasons feature. The season meta field (_benecaster_season_number) is only set when the Seasons toggle is on in Settings → Show → Advanced.

Related

Code

<?php
// Suppress auto-numbering for non-full episodes (trailers, bonus).
add_filter( 'benecaster_episode_auto_number', function ( int $next, int $episode_id, int $show_id ): int {
    $type = get_post_meta( $episode_id, '_benecaster_episode_type', true );
    if ( 'full' !== $type ) {
        return 0; // 0 = skip auto-numbering.
    }
    return $next;
}, 10, 3 );

View on GitHub →

Hooks Used

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

Powered by