HTML Audio played Property: Audio Played Ranges

HTML Audio played Property: Understanding Audio Played Ranges

The HTML Audio played property is a read-only property that returns a TimeRanges object representing the ranges of the audio that the user has played. This property is incredibly useful for understanding which parts of the audio have been listened to, allowing developers to implement features like progress tracking, skipping to unplayed sections, or providing analytics on user listening behavior. This guide provides an in-depth look at the played property, its syntax, usage, and practical examples.

What is the played Property?

The played property of the HTML <audio> element provides a way to determine which parts of the audio have been played by the user. It returns a TimeRanges object, which contains one or more time ranges. Each time range consists of a start time and an end time, indicating a segment of the audio that has been played.

• Read-Only: This property cannot be set. It reflects the current state of the audio playback.
• TimeRanges Object: The returned object provides methods to access the start and end times of the played ranges.
• Dynamic: The played property updates in real-time as the user interacts with the audio.

Purpose of the played Property

The primary purposes of the played property are to:

• Track which portions of the audio have been played.
• Provide a basis for advanced audio playback control and user experience enhancements.
• Enable analytics on user listening behavior.

Syntax

The syntax to access the played property is straightforward:

const timeRanges = audioElement.played;

Here, audioElement is a reference to the HTML <audio> element, and timeRanges is the TimeRanges object returned by the played property.

Understanding the TimeRanges Object

The TimeRanges object has the following properties and methods:

Examples

Let’s explore several practical examples of how to use the played property.

Basic Example: Displaying Played Ranges

This example demonstrates how to access the played property and display the played ranges in a simple format.

<audio id="audioPlayedExample" controls src="https://www.w3schools.com/html/horse.ogg"></audio>
<p id="playedRanges"></p>

<script>
  const audioPlayed = document.getElementById("audioPlayedExample");
  const playedRangesDisplay = document.getElementById("playedRanges");

  audioPlayed.addEventListener("timeupdate", function() {
    let playedRanges = "";
    for (let i = 0; i < audioPlayed.played.length; i++) {
      playedRanges +=
        "Range " +
        (i + 1) +
        ": " +
        audioPlayed.played.start(i) +
        " - " +
        audioPlayed.played.end(i) +
        " seconds<br>";
    }
    playedRangesDisplay.innerHTML = "Played Ranges:<br>" + playedRanges;
  });
</script>

In this example, the timeupdate event listener updates the playedRanges paragraph with the current played ranges whenever the audio playback time changes.

Advanced Example: Creating a Visual Played Range Indicator

This example uses the Canvas API to create a visual representation of the played ranges on top of the audio player.

<audio id="audioVisualPlayed" controls src="https://www.w3schools.com/html/horse.ogg"></audio>
<canvas id="playedCanvas" width="300" height="20" style="border:1px solid #d3d3d3;"></canvas>

<script>
  const audioVisual = document.getElementById("audioVisualPlayed");
  const canvasPlayed = document.getElementById("playedCanvas");
  const ctxPlayed = canvasPlayed.getContext("2d");

  audioVisual.addEventListener("timeupdate", function() {
    ctxPlayed.clearRect(0, 0, canvasPlayed.width, canvasPlayed.height);
    ctxPlayed.fillStyle = "rgba(0, 123, 255, 0.5)";

    for (let i = 0; i < audioVisual.played.length; i++) {
      const start = audioVisual.played.start(i);
      const end = audioVisual.played.end(i);
      const duration = audioVisual.duration;

      const startX = (start / duration) * canvasPlayed.width;
      const width = ((end - start) / duration) * canvasPlayed.width;

      ctxPlayed.fillRect(startX, 0, width, canvasPlayed.height);
    }
  });
</script>

This example visualizes the played ranges as semi-transparent blue rectangles on a canvas element, providing a clear graphical representation of the listened portions of the audio.

Combining Played Ranges

In some cases, you may want to consolidate the played ranges into a single range. This can be useful for simplifying the data or for specific use cases where only the total played duration is needed.

<audio id="audioCombinedPlayed" controls src="https://www.w3schools.com/html/horse.ogg"></audio>
<p id="combinedPlayedRange"></p>

<script>
  const audioCombined = document.getElementById("audioCombinedPlayed");
  const combinedPlayedRangeDisplay = document.getElementById(
    "combinedPlayedRange"
  );

  audioCombined.addEventListener("timeupdate", function() {
    let totalPlayed = 0;
    for (let i = 0; i < audioCombined.played.length; i++) {
      totalPlayed += audioCombined.played.end(i) - audioCombined.played.start(i);
    }
    combinedPlayedRangeDisplay.innerHTML =
      "Total Played: " + totalPlayed.toFixed(2) + " seconds";
  });
</script>

This example calculates the total played duration by summing the lengths of all played ranges and displays it on the page.

Real-World Applications of the played Property

The played property can be used in a variety of real-world applications:

• Progress Tracking: Visualize the played ranges in a custom progress bar.
• Learning Platforms: Track which parts of an educational audio lesson have been completed.
• Analytics: Gather data on which segments of audio content are most frequently listened to.
• Accessibility: Provide visual cues for users with hearing impairments to indicate which parts of the audio they have already heard.
• Podcast Apps: Remember and display what sections of the podcast you have already heard.

Browser Support

The played property is widely supported across modern web browsers:

• Chrome
• Firefox
• Safari
• Edge
• Opera

Conclusion

The HTML Audio played property is a valuable tool for web developers, providing insights into user listening behavior and enabling advanced audio playback control. By understanding and utilizing this property, you can create more engaging, informative, and user-friendly audio experiences on the web. From simple progress tracking to complex data analysis, the possibilities are vast. 🎶