Skip to main content

benecaster_transcript_display_html

Filter Premium transcription

Filters the interactive transcript’s markup before the Transcription Service add-on puts it on the site: in benecaster_transcript and under the episode page’s Transcript heading. The transcript text in $html is already escaped; anything you add is yours to escape. It covers the episode’s finished transcript for its main audio.

It is not run for a visitor who may not see the transcript. The add-on asks benecaster_user_can_see_transcript() for the current visitor first and shows the locked state instead (see benecaster_transcript_locked_html), with no teaser of the text and no script or stylesheet. So this filter never receives a restricted transcript’s markup for that visitor, and returning markup from it cannot show one. Someone who can edit the episode sees the transcript under every setting, Hidden included. It is not run when there is nothing to show either: no transcript, one not finished, or an empty one.

What $html holds:

  • A formatted transcript is p.benecaster-transcript__paragraph blocks of span.benecaster-transcript__line.benecaster-transcript__line--inline[data-start][data-end] lines, or div.benecaster-transcript__formatted with no timestamps, so .benecaster-transcript__line is not always an li.
  • Download links follow the section, as p.benecaster-transcript__downloads, in full and scrollable modes.
  • For someone who can edit the episode, a note comes first: p.benecaster-transcript__audience, before the section, saying who else can read the transcript under its setting, with a Change link to the episode editor’s Transcript tab (a.benecaster-transcript__audience-change) and the line Only people who can edit this episode see this note. (span.benecaster-transcript__audience-hint). No listener ever receives it. A callback that wraps $html wraps the note too; one that looks for the section should search for it, not assume it comes first.
  • The transcript: section.benecaster-transcript[data-benecaster-transcript] holding ol.benecaster-transcript__lines, one li.benecaster-transcript__line[id][data-start][data-end] per line. Each line has an a.benecaster-transcript__time[data-start] timestamp whose text is a <time> element, such as <time datetime="PT1M23S">1:23</time>, a span.benecaster-transcript__speaker where the speaker changes, and span.benecaster-transcript__text. A callback that matches the timestamp text right before </a> finds nothing, because the text sits inside <time>.
  • A transcript without timestamps is p.benecaster-transcript__paragraph blocks instead.
  • In preview, a p.benecaster-transcript__more link to the episode page follows when lines were left out.
  • On the episode page, the wrapper is the episode’s schema.org associatedMedia (an AudioObject) and the section carries itemprop="transcript". Keep that attribute if you rebuild the section. The editors’ note sits outside the section, so it is not part of the value.

Keep the classes and data attributes in what you return. The add-on’s script reads them: a timestamp click seeks that episode’s player, and the line being spoken is highlighted as it plays.

Parameters

Name Type Default Description
$html string — The interactive transcript's markup, its text already escaped
$episode_id int — ID of the episode
$mode string — `full`, `preview` or `scrollable`, as in the shortcode's `mode`; always `scrollable` on the episode page. Register for 2 arguments if you don't need it.

Returns: string

Example

add_filter( 'benecaster_transcript_display_html', static function ( string $html, int $episode_id ): string {
    return '<h2 class="my-transcript-heading">' . esc_html__( 'Read along', 'my-theme' ) . '</h2>' . $html;
}, 10, 2 );

Notes

The add-on's script benecaster-transcription-service-transcript and its stylesheet of the same name are registered on init on every request, and enqueued when a transcript is output. In a block-editor or Elementor preview, enqueue both yourself. Restyle with the benecaster-transcript__* classes where you can; the stylesheet sets only layout. The filter runs whether or not the show's licence is current or Transcription is switched on for it: a show keeps its transcripts. Walkthrough: Change or add to the transcript the add-on shows on the site.

Related Recipes

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