Filter Hooks Reference

All filter hooks provided by Benecaster. Each hook name links to its reference page with full parameter docs, return type, usage notes, and code examples.

Unless noted otherwise, every filter here fires on any install. Filters marked Premium sit on code paths that only run on a licensed install — not because the filter itself costs anything, but because without a license there is nothing for it to filter.

About the Since column. Each filter’s own reference page records the plugin version it was introduced in, once one exists. It is blank on every entry here because nothing has shipped yet — it gets filled in at the 1.0.0 launch.

Feed

Filter what goes into a feed’s compiled RSS XML — the episode list, per-episode data, enclosure
URLs, Podcasting 2.0 tags, and the final XML string itself.

Filter	Description
`benecaster_feed_episodes`	Filters the array of episode objects for a feed tier before XML serialization
`benecaster_feed_episode_data`	Filters the data array for a single episode before XML rendering, `itunes:` tags and `<content:encoded>` included, plus a trailing `$tier_slug` — most granular per-episode customization point
`benecaster_feed_enclosure_url`	Filters the audio/video URL placed in the RSS `<enclosure>` tag
`benecaster_feed_item_xml`	Filters the compiled XML string for a single episode item after serialization
`benecaster_feed_episode_limit`	Filters the maximum number of episodes included per feed tier
`benecaster_feed_channel_data`	Filters the channel-level RSS data array before XML compilation, `itunes:` tags included, plus a trailing `$tier_slug`; includes `new_feed_url` key for controlling the `<itunes:new-feed-url>` tag
`benecaster_rss_extra_channel_tags`	Filters an array of extra tags appended to the RSS channel block, which core escapes and renders — not a raw XML string
`benecaster_rss_extra_item_tags`	Filters an array of extra tags appended to each episode item, which core escapes and renders — not a raw XML string
`benecaster_feed_xml`	Filters the complete compiled RSS XML string; two call sites — per-tier (`string` third arg) and assembled multi-tier (`string[]` third arg)
`benecaster_podcast_chapters`	Filters `podcast:chapters` data for an episode item; Chapter Markers add-on populates automatically
`benecaster_podcast_transcripts`	Filters `podcast:transcript` entries for an episode item; Transcription add-on populates automatically
`benecaster_feed_podcast_channel_tags`	Filters the channel-level Podcasting 2.0 tag array before XML output; array pre-populated from show meta (guid, locked, funding, block, txt, license)
`benecaster_feed_podcast_episode_tags`	Filters the per-episode Podcasting 2.0 tag array before XML output; integration point for Transcription Service (`podcast:transcript`), Guest Manager (`podcast:person`), and Chapter Markers (`podcast:chapters`) add-ons
`benecaster_feed_podcast_funding_label`	Filters the `<podcast:funding>` element label text; defaults to “{show title} Listener Support”
`benecaster_episode_references`	Filters the references array for an episode before it is returned in REST responses

Subscriber Engagement

Controls the inactivity threshold used to decide when a subscriber’s feed is considered stopped.

Filter	Description
`benecaster_subscriber_engagement_threshold`	Filters the inactivity threshold (days) used by the engagement cron before it marks a subscriber as inactive; override per show

RSS Output Filters — Premium

Reserved for premium-only feed output filters. All filters in this section require an active
paid Benecaster license; none are currently published here.

Filter	Description

SSP / PowerPress Import

Filters the arguments used to insert a draft episode while importing from Seriously Simple
Podcasting.

Filter	Description
`benecaster_ssp_import_post_data`	Filters the `wp_insert_post()` argument array before each SSP draft episode is inserted; override title, status, content, or date

Episodes

Filter an episode’s resolved data — its iTunes type, description, audio/video URLs and players,
share links, and whether it’s accessible to the current user.

Filter	Description
`benecaster_episode_auto_number`	Filters the auto-assigned episode number when an episode is first published
`benecaster_episode_itunes_type`	Filters the resolved iTunes canonical type for an episode during feed compilation
`benecaster_episode_description`	Filters the episode description HTML rendered on the front-end episode page (distinct from `benecaster_episode_description_rss` which filters the RSS feed description)
`benecaster_episode_audio_url`	Filters the audio file URL used in the front-end player and episode page
`benecaster_episode_embed_audio`	Filters the rendered HTML for the embedded audio player on the episode page
`benecaster_episode_video_url`	Filters the video file URL used in the front-end player and episode page
`benecaster_episode_embed_video`	Filters the rendered HTML for the embedded video player on the episode page
`benecaster_episode_share_links`	Filters the share links array for an episode; each entry is `{label, url, class}`; used in the `episode/share.php` template part
`benecaster_show_episode_player`	Filters whether the episode player is rendered on the episode page; return `false` to suppress the player entirely (locked-state template still renders)
`benecaster_show_episode_content`	Filters whether the episode page shows the full show notes or the teaser; args `(bool $show_content, int $episode_id, ?int $user_id, ?string $user_tier)`
`benecaster_show_episode_download`	Filters whether the “Download episode” link is shown on the episode page; args `(bool $show, int $episode_id, ?int $user_id, ?string $user_tier)`. The filter can only hide the link: returning `true` for a visitor without access has no effect.
`benecaster_show_episode_transcript`	Filters whether the “Read the transcript” link is shown on the episode page; same arguments as the download filter, and it can likewise only hide the link
`benecaster_episode_is_accessible`	Overrides episode access for custom rules; args `(bool $can_access, int $episode_id, int $user_id, string $tier_slug)` where `$tier_slug` is the subscriber’s active token tier or `''` when no token; return `false` to lock, `true` to grant access regardless of tier; fires inside `benecaster_user_can_access_episode()`

Templates — Episode Page

Filter the custom fields shown on an episode page and the previous/next navigation links and
subscribe fallback text.

Filter	Description
`benecaster_episode_custom_fields`	Filters the custom fields renderable groups array before output in `episode/custom-fields.php`; each group is `{heading, fields[]}`
`benecaster_episode_nav_prev`	Filters the `WP_Post` object for the previous episode in `episode/navigation.php`; return `null` to suppress the previous link
`benecaster_episode_nav_next`	Filters the `WP_Post` object for the next episode in `episode/navigation.php`; return `null` to suppress the next link
`benecaster_episode_subscribe_fallback_message`	Filters the subscribe CTA fallback text shown in `episode/subscribe.php` when no subscribe URL is configured

Episode Page Blocks

Register, reorder, or replace the rendered HTML of the blocks that make up an episode page —
related episodes, navigation, share buttons, social links, and platform links — and the
shortcodes that mirror several of them.

Filter	Description
`benecaster_episode_page_block_types`	Registers or modifies block type definitions for the Episode Page settings panel
`benecaster_episode_page_blocks`	Filters the ordered block list before an episode page renders; each block: `{slug, enabled, config}`
`benecaster_episode_page_block_{slug}`	Filters the rendered HTML for one specific Episode Page block (dynamic filter name — `{slug}` matches the block type slug); return `''` to suppress
`benecaster_related_episodes_query_types`	Registers or modifies query type strategies for the Related Episodes block
`benecaster_related_episodes`	Filters the related episodes array before rendering in the Related Episodes block
`benecaster_related_episodes_output`	Filters the rendered HTML output of the Related Episodes block
`benecaster_episode_nav_output`	Filters the rendered HTML of the Episode Navigation block and `[benecaster_episode_nav]` shortcode
`benecaster_episode_share_text`	Filters the share text for a specific platform in the Share Buttons block
`benecaster_episode_share_output`	Filters the rendered HTML output of the Share Buttons block and `[benecaster_episode_share]` shortcode
`benecaster_show_social_links`	Filters the show social links array for the Social Links block and `[benecaster_social_links]` shortcode
`benecaster_social_links_output`	Filters the rendered HTML output of the Social Links block and `[benecaster_social_links]` shortcode
`benecaster_rss_link_output`	Filters the rendered HTML of the RSS Subscribe button and `[benecaster_rss_link]` shortcode
`benecaster_platform_links_output`	Filters the rendered HTML of the Platform Links block and `[benecaster_platform_links]` shortcode

Templates — Episode Archive

Filter the text, HTML, and per-card data rendered on the episode archive listing.

Filter	Description
`benecaster_archive_header_title`	Filters the archive heading text rendered in `archive/header.php`
`benecaster_archive_header_description`	Filters the archive subheading/description text rendered in `archive/header.php`
`benecaster_archive_show_filters`	Filters whether the episode filter bar is rendered; return `false` to suppress it
`benecaster_archive_no_results_message`	Filters the empty-state message shown in `archive/no-results.php` when no episodes match the current filters
`benecaster_archive_pagination_html`	Filters the pagination HTML rendered in `archive/pagination.php`
`benecaster_episode_card_classes`	Filters the CSS class string on each episode card in `archive/episode-card.php`
`benecaster_episode_card_meta`	Filters the meta array for each episode card; keys: `episode_number`, `season_number`, `duration`, `pub_date`
`benecaster_episode_card_title`	Filters the episode title string rendered in each archive card
`benecaster_episode_card_excerpt`	Filters the episode excerpt string rendered in each archive card
`benecaster_episode_card_artwork`	Filters the artwork URL used in each archive card
`benecaster_episode_card_locked_message`	Filters the locked state message shown on archive cards for episodes the current user cannot access

Episode Search

Filter the episode search query, its results, and what’s eligible to be indexed — including a
short-circuit for replacing Benecaster’s own search entirely.

Filter	Description
`benecaster_search_query_args`	Filters the query arguments before the episode search runs
`benecaster_search_pre_results`	Short-circuit the episode search; return a non-null array to skip Benecaster’s own query and return custom results
`benecaster_search_results`	Filters the final episode search result set and pagination metadata
`benecaster_search_result_excerpt`	Filters the search result excerpt string; `<mark>` wrapping around matched terms is already applied
`benecaster_search_indexable`	Controls whether a specific episode is included in search results; return `false` to exclude
`benecaster_search_output`	Filters the rendered HTML output of `[benecaster_search]`
`benecaster_search_supplemental_episode_ids`	Adds supplemental episode IDs to merge into search results via `OR p.ID IN (...)` (e.g. transcript matches from the Transcription add-on)

Data Export

Filter	Description
`benecaster_export_sheets`	Registers and filters available sheets for the “Your Data” XLSX export
`benecaster_export_sheet_rows_sheet_id_{sheet_id}`	Provides or filters row data for one XLSX export sheet (dynamic filter name — `{sheet_id}` is replaced with the sheet ID string)

Member Thanks

Filter	Description
`benecaster_member_thanks_query_types`	Registers or modifies query type strategies for the `[benecaster_member_thanks]` shortcode and the Episode Workbench tile
`benecaster_member_thanks_output`	Filters the rendered HTML output of `[benecaster_member_thanks]`

Custom Fields

Filter custom field group definitions before they render, and individual field values before
they’re returned to the caller.

Filter	Description
`benecaster_field_groups`	Filters the array of field group definitions before they are rendered for a CPT
`benecaster_field_value`	Filters a custom field value before it is returned to the caller

References

Filters the reference group list for a show before it’s returned in REST responses.

Filter	Description
`benecaster_reference_groups`	Filters the reference group list for a show before it is returned in REST responses

Admin UI

Register or modify what appears in the Benecaster admin — dashboard cards, episode editor tabs,
and show settings pages and sections.

Filter	Description
`benecaster_dashboard_cards`	Filters the dashboard card declarations rendered after the built-in stat cards
`benecaster_episode_editor_tabs`	Filters the tab configuration array used by the episode editor sidebar
`benecaster_settings_pages`	Filters the settings page declarations shown in the show settings left navigation
`benecaster_settings_sections`	Filters field section declarations injected into existing settings pages

Email

Filter any part of an outgoing Benecaster email — whether it sends, its subject and body, its
headers, its merge tags, its header/footer branding, and which types are exempt from broadcast
opt-out suppression.

Filter	Description
`benecaster_email_should_send`	Controls whether a specific email is dispatched; type-specific variant: `benecaster_email_should_send_{type}`
`benecaster_email_subject`	Filters the subject line for any Benecaster email; type-specific variant: `benecaster_email_subject_{type}`
`benecaster_email_body_html`	Filters the HTML body for any Benecaster email; type-specific variant: `benecaster_email_body_html_{type}`
`benecaster_email_body_text`	Filters the plain text body for any Benecaster email; type-specific variant: `benecaster_email_body_text_{type}`
`benecaster_email_headers`	Filters the headers array passed to `wp_mail()`; type-specific variant: `benecaster_email_headers_{type}`
`benecaster_email_merge_tags`	The primary hook for registering custom merge tags; type-specific variant: `benecaster_email_merge_tags_{type}`
`benecaster_email_wrapper_args`	Filters the header/footer template context: logo URL, show name, accent color, footer text
`benecaster_email_template_locale`	Filters the locale used for email template file resolution before template loading
`benecaster_email_unsubscribe_allowed`	Controls whether an unsubscribe request should be processed; only use for rate limiting, never to block legitimate opt-outs
`benecaster_transactional_email_types`	Filters the email types that bypass broadcast opt-out suppression (welcome, token_reset, etc.)
`benecaster_managed_email_types`	Filters the array of registered email types; types returned here appear as editable templates in the Email Editor

Shortcode Output

Filter the final rendered HTML of most Benecaster shortcodes, one filter per shortcode.

Filter	Description
`benecaster_player_output`	Filters the full rendered HTML output of `[benecaster_player]`
`benecaster_subscribe_output`	Filters the full rendered HTML output of `[benecaster_subscribe]`
`benecaster_episode_description_output`	Filters the rendered HTML output of `[benecaster_episode_description]`
`benecaster_latest_episode_output`	Filters the rendered HTML output of `[benecaster_latest_episode]`
`benecaster_episode_link_output`	Filters the rendered HTML of an episode link inserted via the TipTap `@` inline picker (`[benecaster_episode_link]`)
`benecaster_timestamp_output`	Filters the rendered HTML of a timestamp link inserted via the TipTap `#` trigger (`[benecaster_timestamp]`)
`benecaster_feed_url_output`	Filters the full rendered HTML output of `[benecaster_feed_url]`
`benecaster_qr_code_output`	Filters the full rendered HTML output of `[benecaster_qr_code]`
`benecaster_episodes_output`	Filters the full rendered HTML output of `[benecaster_episodes]`
`benecaster_locked_content_message`	Filters the locked state HTML for a locked episode; parameters: `($html, $episode_id, $required_tier, $user_tier)` — `$required_tier` is `''` when undetermined; `$user_tier` is `''` when not subscribed; fires in `episode/player-locked.php` and the player shortcode
`benecaster_upgrade_prompt_html`	Filters the upgrade prompt HTML shown to logged-in subscribers at the wrong tier; parameters: `($html, $episode_id, $show_id, $required_tier, $user_tier)`
`benecaster_subscriber_count_output`	Filters the rendered output of `[benecaster_subscriber_count]`
`benecaster_episode_count_output`	Filters the rendered output of `[benecaster_episode_count]`
`benecaster_tier_price_output`	Filters the rendered output of `[benecaster_tier_price]`
`benecaster_tier_name_output`	Filters the rendered output of `[benecaster_tier_name]`
`benecaster_pricing_table_output`	Filters the rendered output of `[benecaster_pricing_table]`

Account Page

Filter the subscriber account page’s URL and the labels Benecaster adds to other membership
plugins’ own account screens.

Filter	Description
`benecaster_account_page_url`	Filters the subscriber account page URL returned by `benecaster_account_page_url()`
`benecaster_wc_account_tab_label`	Filters the label of the Podcast Subscriptions tab in WooCommerce My Account
`benecaster_pmpro_account_link_label`	Filters the label of the Manage Podcast Subscriptions link in the PMPro account page
`benecaster_memberpress_account_label`	Filters the section heading in the MemberPress account page
`benecaster_rcp_account_label`	Filters the section heading in the Restrict Content Pro account page

Templates — Show Page

Filter the text, HTML, and query arguments rendered on the public show page — header, subscribe
links, tiers, embedded episode list, and public stats.

Filter	Description
`benecaster_show_description`	Filters the show description text returned by `benecaster_get_show_description()`
`benecaster_show_header_title`	Filters the show title rendered in `show/header.php`
`benecaster_show_header_description`	Filters the show description rendered in `show/header.php`
`benecaster_show_header_artwork_url`	Filters the show artwork URL used in `show/header.php`
`benecaster_show_subscribe_links`	Filters the platform links array rendered in `show/subscribe-links.php`; each entry: `{platform, url}`
`benecaster_show_tiers`	Filters the tiers array rendered in `show/tiers.php`; each entry from the active bridge’s `get_all_tiers()`
`benecaster_show_episode_list_args`	Filters the `WP_Query` arguments for the embedded episode list in `show/episode-list.php`; defaults: `posts_per_page=10`, `orderby=date`, `order=DESC`
`benecaster_show_stats_visible`	Controls whether `show/stats.php` renders; returns `false` by default — return `true` to show public stats
`benecaster_show_stats_episode_count`	Filters the episode count displayed in the public stats block

Token and Access

Filter the tier a user resolves to for a show, and the teaser content shown to someone who
can’t access a locked episode.

Filter	Description
`benecaster_user_tier_for_show`	Filters the resolved tier slug for the current user on a given show; used by `benecaster_get_user_tier_for_show()` and by `PreviewTierManager` for Preview as Tier mode; return a tier slug string or empty string
`benecaster_teaser_content`	Filters the teaser content shown to users who cannot access a locked episode; fires in `TeaserResolver::resolve()` called from `episode/content.php`; Free

Setup and Configuration

Filter the setup wizard’s step list and bridge options, and register runtime setup-guidance
notices for add-ons.

Filter	Description
`benecaster_setup_wizard_steps`	Filters the ordered array of step definitions passed to the setup wizard
`benecaster_setup_wizard_bridge_options`	Filters the bridge card options displayed in the wizard’s Subscription step
`benecaster_addon_setup_checks`	Registers runtime setup guidance notices for add-ons; each callable returns `null` (condition met) or a notice array (condition failing); `SetupNoticeManager` evaluates on every admin load

Maintenance

Filter retention windows used by Benecaster’s own cleanup jobs — imported shadow records and
the email log.

Filter	Description
`benecaster_shadow_record_expiry_days`	Filters the shadow import record expiry threshold in days (default 90); controls when completed Patreon/Supercast migration records are purged
`benecaster_email_log_retention_days`	Filters the email log retention period in days (default 180); controls what the orphaned data scanner surfaces as cleanable in Tools → Maintenance