Skip to main content

Read a transcript’s passages by speaker, with each speaker’s guest

Premium Intermediate Transcription Service

For an add-on that needs who said what: AI Search answers “what has [guest] said about [topic]?” by indexing each passage under the guest its speaker is mapped to under Speaker names in the episode editor’s Transcript tab. Read it with benecaster_get_episode_transcript_passages(), never from the Transcription Service add-on’s own storage.

It returns one passage per speaker turn, each [ 'start' => float, 'end' => float, 'speaker' => ?int, 'speaker_label' => string, 'guest_id' => ?int, 'text' => string ]:

  • Consecutive lines by the same speaker (or by no speaker) are joined with single spaces. start is the turn’s first line’s start and end its last line’s end, in seconds.
  • speaker is the 1-based speaker number, null for a transcript without speaker labels. speaker_label is how the transcript shows that speaker now: the mapped guest’s current name from Guest Manager, else the name saved when they were chosen, else the translated Speaker N; '' with no speaker.
  • guest_id is the Guest Manager guest the speaker is mapped to, as stored, or null (unmapped, or a typed name). It is returned whether or not Guest Manager is active: read the guest with benecaster_guest_manager_get_guest(), which returns null for one that is gone.
  • null exactly when benecaster_get_episode_transcript_text() is: no finished transcript, not an episode, empty, or Hidden. An empty array for a transcript without timestamps (a plain-text import), which has no lines: read its text with the text reader.
  • One audio source per call: the base audio unless $audio_variant_key names a tier’s audio variant, as the text reader.
  • It does not decide who may see the text. Before showing a viewer anything built from it, check benecaster_user_can_see_transcript().
  • It is defined on every request, whether or not the show’s license is current, so a show keeps its transcripts. Guard calls with function_exists(), since Transcription Service may not be installed.

Re-index on benecaster_transcript_updated, as in Read an episode’s transcript, and react when it changes. It fires with $reason speakers once when a save under Speaker names changes the mapping of a transcript the readers answer for (not a Hidden one); the text did not change. The other reasons cover the rest: a new transcription or an import clears the names and fires transcribed or imported. A guest renamed in Guest Manager fires nothing here, because the label is read live: if you store labels, hook benecaster_guest_manager_after_save_guest too.

Code

<?php
// Index each passage under the guest who said it.
add_action( 'my_addon_reindex_episode', function ( int $episode_id ): void {
    $passages = function_exists( 'benecaster_get_episode_transcript_passages' )
        ? benecaster_get_episode_transcript_passages( $episode_id )
        : null;
    if ( null === $passages ) {
        my_addon_forget( $episode_id );
        return;
    }
    foreach ( $passages as $passage ) {
        if ( null !== $passage['guest_id'] ) {
            my_addon_index_quote( $passage['guest_id'], $episode_id, $passage['start'], $passage['text'] );
        }
    }
} );

View on GitHub →

Hooks Used

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