benecaster_get_episode_transcript_passages()
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.
startis the turn’s first line’s start andendits last line’s end, in seconds. -
speakeris the 1-based speaker number, ornullfor a transcript without speaker labels. -
speaker_labelis 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_idis the Guest Manager guest the speaker is mapped to, as stored, ornull(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 returnsnullfor 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 →