Skip to main content

benecaster_chapter_autosuggest

Filter Free

Powers the “Auto-suggest chapters” button in the episode editor’s More tab → Chapters section. The button is visible only when the Transcription Service add-on is installed and switched on for the episode’s show (Settings → Add-ons → Active on); another add-on hooking this filter does not make it appear. Clicking it POSTs to POST /benecaster/v1/episodes/{id}/chapters/auto-suggest (requires a wp_rest nonce and permission to edit that episode), 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, which may use one to three hour digits, 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.

Transcription Service answers this filter itself, at priority 10, with chapters cut from the episode’s transcript at pauses and speaker changes, and keeps rows an earlier callback returned: hook below 10 to offer yours first, or above 10 to replace its list.

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

Related Recipes

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