Skip to main content

benecaster_get_episode_transcript_passages()

Episode Premium transcription
benecaster_get_episode_transcript_passages( int $episode_id, string $audio_variant_key = '' ): ?array

Reads an episode’s transcript from the Transcription Service add-on as passages by speaker, each with the guest its speaker is mapped to under Speaker names in the episode editor’s Transcript tab. Use it when your add-on needs who said what, such as answering what a guest has said about a topic. Re-read on benecaster_transcript_updated, which fires with speakers when the speaker mapping changes.

  • One passage per turn. 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, or 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.

Read transcripts through this function and never from the add-on’s own storage, which is the add-on’s to change.

Parameters

Name Type Default Required Description
episode_id int — Yes The episode (post) ID.
audio_variant_key string '' No '' for the main audio, the one the episode page plays, or the tier key of one of the episode's audio variants, for that variant's transcript.

Return Value

Type: ?array

A list of passages, one per speaker turn, each [ 'start' => float, 'end' => float, 'speaker' => ?int, 'speaker_label' => string, 'guest_id' => ?int, 'text' => string ]. null exactly when benecaster_get_episode_transcript_text() returns null: no finished transcript, an empty text, a post that is not an episode, or a transcript set to Hidden. An empty array for a transcript without timestamps (a plain-text import), which has no lines: read its text with the text reader.

Example

$passages = function_exists( 'benecaster_get_episode_transcript_passages' )
    ? benecaster_get_episode_transcript_passages( $episode_id )
    : null;

foreach ( $passages ?? [] as $passage ) {
    if ( null !== $passage['guest_id'] ) {
        my_addon_index_quote( $passage['guest_id'], $episode_id, $passage['start'], $passage['text'] );
    }
}

Notes

It does not decide who may see the text. Before showing a viewer anything built from it, ask benecaster_user_can_see_transcript().

One audio source per call: the base audio unless $audio_variant_key names a tier's audio variant, exactly as the text reader. A variant with no transcript of its own returns null.

A guest renamed in Guest Manager fires nothing on the transcript side, because the label is read live. If you store labels, also listen to benecaster_guest_manager_after_save_guest.

It is defined on every request, whether or not the show's license is current or Transcription is switched on for it: a show keeps its transcripts. Guard calls with function_exists(), since Transcription Service may not be installed.

See Read a transcript's passages by speaker, with each speaker's guest.

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