Playback from segments

Learn how to enable playback from segments (paragraphs) so that you can listen to a paragraph by clicking/tapping on it.

Playback from segments lets users click or tap on a paragraph to start listening to it.

Add Markers

If you're using the WordPress plugin then Markers are added automatically.

Option 1: Fetch markers

If you do not provide your own markers, BeyondWords will generate and store them for you. You can then use the /content endpoint in the API to fetch them for each segment and add them to the corresponding HTML elements in your article.

Option 2: Submit your own markers

Add a data-beyondwords-marker attribute with a unique identifier, such as a UUID, to each HTML element in your article where you want to enable playback from segments.

For example:

<h1 data-beyondwords-marker="1af51b2a-72df-4b86-bb7c-87d057231ca0">
  This is the title.
</h1>

<p data-beyondwords-marker="5d2c6eba-f612-45c7-b987-00fde473d867">
  This is the first paragraph.
</p>

<p data-beyondwords-marker="d89257cd-ff53-476e-aef2-84dadcca1cc5">
  This is the second paragraph.
</p>

When you create content in the BeyondWords API by submitting the HTML, BeyondWords will store the marker alongside each segment in the segments array in the content object.

The markers need to match the segments within the BeyondWords content or playback from Segments won't work.

Enable playback from segments

Once you've added the Markers you need to enable the feature. You can do this through the API, dashboard or the BeyondWords Player script.

Option 1: Dashboard

Go to the Player section in your project, click on the Settings tab, enable playback from segments, and then press Save changes.

This is equivalent to setting highlightSections: all and clickableSections: all in the BeyondWords Player script.

Option 2: API

Use the /player_settings endpoint to update segment_playback_enabled to true.

This is equivalent to setting highlightSections: all and clickableSections: all in the BeyondWords Player script.

Option 3: BeyondWords Player script

Set clickableSections to any of the following:

• all enables playback on both title, summary and body segments (default).

• body enables playback on only body segments.

• none disables playback on all segments.

How it works

Once the player script has loaded, it will add global listeners to your page to detect clicks. If the player detects that you have clicked on an element with the data-beyondwords-marker attribute, it checks if the element matches one of the content segments. If so, it emits PressedSegment events.

Additionally, when the currentTime of the media updates (i.e., by playing it), the player emits a CurrentSegmentUpdated event. These events are then used to control playback, for example, by setting the currentTime to the startTime of the segment that the user clicked on. The currentSegment property of the player is also set.

To avoid interfering with your page, clicking on segments does not trigger if you are hovering over a link or other element with a click or mouse-down handler. However, this does not apply to event listeners.

Event listeners

The BeyondWords Player cannot detect event listeners that have been registered on elements within the segment.

For example, this button does not have an 'onclick' property and therefore playback will be affected when it is clicked:

<p data-beyondwords-marker="5d2c6eba-f612-45c7-b987-00fde473d867">
  This is the first paragraph. <button id="my-button"></button>
</p>

<script>
  document.getElementById("my-button").addEventListener("click", event => {
    console.log("The button was clicked.");
  });
</script>

To avoid this, call event.preventDefault() at the top of the event listener:

<script>
  document.getElementById("my-button").addEventListener("click", event => {
    event.preventDefault();
    console.log("The button was clicked.");
  });
</script>

The above code will prevent the player from changing its current time when the button is clicked.