`benecaster_chapter_autosuggest`

Filter Free Since v1.0.0

Powers the “Auto-suggest chapters” button in the episode editor’s More tab → Chapters section. The button is visible only when an add-on registers its slug via benecaster_installed_addons. Clicking it POSTs to POST /benecaster/v1/episodes/{id}/chapters/auto-suggest (admin-only, requires edit_posts + wp_rest nonce), which calls this filter and returns the results for the editor to pre-fill.

Return an array of chapter rows. Each row must include a valid HH:MM:SS timestamp and a title. Rows with malformed timestamps are dropped silently before the response is returned. If the filter returns an empty array or every row has a bad timestamp, the endpoint responds with 501 and the editor shows “No chapter suggestions were returned.”

Suggestions pre-fill the chapter editor only — nothing is persisted automatically. The podcaster must review and save.

Parameters

Name	Type	Default	Description
`$chapters`	`array`	—	Default value is an empty array. Add rows to it or replace it entirely.
`$episode_id`	`int`	—	WordPress post ID of the episode the auto-suggest was requested for
`$post`	`WP_Post`	—	The episode post object

Returns: array

Examples

Provide chapter suggestions from a stored transcript

add_filter( 'benecaster_chapter_autosuggest', function( array $chapters, int $episode_id, WP_Post $post ): array {
    $transcript = get_post_meta( $episode_id, '_my_transcript_text', true );
    if ( '' === $transcript ) {
        return $chapters; // empty array → 501 response
    }

    $segments = my_segment_transcript( $transcript );

    return array_map(
        fn( array $s ): array => [
            'timestamp' => $s['hms'],
            'title'     => $s['title'],
            'url'       => $s['deep_link'] ?? null,
            'image_id'  => $s['image_id']  ?? null,
        ],
        $segments
    );
}, 10, 3 );

Notes

This filter runs on admin requests only (permission_callback_editor gate). It is safe to make relatively expensive calls (LLM, external HTTP) inside the callback without a fragment-cache wrapper. The benecaster_installed_addons filter controls whether the Auto-suggest button appears in the UI — register your add-on slug there if you want the button to show. See the suggest-chapter-markers-from-transcript recipe for a complete working example.

Affects

Chapter editor Auto-suggest button