Building an Audio Player with Stimulus

Audio isn't the king of multimedia formats, video is. That's why finding a nice audio player isn't always an easy task.

In this article, we will build a custom audio player with Stimulus with customizable controls, responsive waveform visualization and more.

We will be using Stimulus to give the desired functionality to our audio player and ViewComponent to help us with modularity and reusability:

Let's start by seeing what we will build:

What we will build

By the end of this article, we will have a functioning audio player with some typical features an audio player should have plus some extra goodies:

• Waveform visualization.
• Appearance customization using component variants.
• Basic keyboard commands.
• Responsiveness using the Resize Observer API in Stimulus.

The final result looks like this:

Application setup

Even though an actual audio player is by no means Rails specific, I will be using Rails because of its integration with Stimulus and ViewComponent.

You can accomplish the same we will in the tutorial using Stimulus by itself or even replacing it with vanilla JS, feel free to experiment and let us know how it goes!

Let's start by creating the app:

$ rails new podcast --css=tailwind --javascript=esbuild

Next, we add and install ViewComponent:

$ bundle add view_component && bundle install

Finally, we will also add the class variants gem to handle different styles for our audio player:

$ bundle add class_variants && bundle install

Besides these dependencies, I also included the Font Awesome icon kit for the sake of building the interface a bit faster, but you can use SVGs or any other icon library of your choosing.

Now that we have everything set up, let's start by building the interface.

Building the interface

To make the process didactic, we will build the player interface, starting out with a basic progress bar.

Our final result for this section will look like this:

Viewing it from a component perspective, we can dissect three major sections: the track information, the progress bar and the controls section:

The first step is to create an AudioPlayerComponent:

$ bin/rails generate component AudioPlayer url title author

This will generate a component class and a corresponding empty view. The component should receive three parameters: the URL which is required, the title and author, which will have default values in case they're not present:

class AudioPlayerComponent < ViewComponent::Base
  def initialize(url:, title: "Untitled audio", author: "Unknown author")
    @url = url
    @title = title
    @author = author
  end
end

Now, let's define the basic HTML structure with the container and track info classes to get things started:

<%# app/views/components/audio_player_component.html.erb %>
<div class="<%= container_classes %>">
  <div class="<%= track_info_container_classes %>">
    <h5 class="<%= track_title_classes %>"><%= @title %></h5>
    <p class="<%= track_author_classes %>"><%= @author %></p>
  </div>
</div>

Next, let's add the classes to the base variant using the class_variants gem:

class AudioPlayerComponent < ViewComponent::Base
  def initialize(url:, title: "Untitled audio", author: "Unknown author")
    @url = url
    @title = title
    @author = author
  end

  def container_classes
    ClassVariants.build(
      base: "w-full gap-2 bg-white dark:bg-slate-800 border border-slate-300 dark:border-slate-700 rounded-lg py-6 px-8",
    ).render
  end

  def track_info_container_classes
    ClassVariants.build(
      base: "flex flex-col items-center justify-center gap-x-2 mb-3",
    ).render
  end

  def track_title_classes
    ClassVariants.build(
      base: "text-lg font-bold text-slate-800 dark:text-slate-200",
    ).render
  end

  def track_author_classes
    ClassVariants.build(
      base: "text-sm text-slate-500 dark:text-slate-200",
    ).render
  end
end

Now, after rendering the component using <%= render AudioPlayerComponent.new(url: audio_url) in any view, we should get the following:

Of course, nothing too exciting for now. Let's add the progress bar with the current_time and duration.

We will use a container to group them, and we will use the --:-- placeholder for the time related attributes:

<div class="<%= container_classes %>">
  <div class="<%= track_info_container_classes %>">
    <h5 class="<%= track_title_classes %>"><%= @title %></h5>
    <p class="<%= track_author_classes %>"><%= @author %></p>
  </div>
  <div class="<%= progress_bar_container_classes %>">
    <div data-audio-player-target="currentTime" class="<%= time_classes %>">--:--</div>
    <div 
      class="<%= progress_bar_classes %>">
      <div class="<%= progress_bar_fill_classes %>" style="width: 24%"></div>
    </div>
    <div class="<%= time_classes %>">--:--</div>
  </div>
</div>

We also add the classes to the component:

def progress_bar_container_classes
  ClassVariants.build(
    base: "flex items-center justify-between gap-x-2",
  ).render
end

def time_classes
  ClassVariants.build(
    base: "text-sm text-slate-800 dark:text-slate-200",
  ).render
end

def progress_bar_classes
  ClassVariants.build(
    base: "flex-grow h-3 bg-slate-200 dark:bg-slate-700 rounded-md overflow-hidden",
  ).render
end

def progress_bar_fill_classes
  ClassVariants.build(
    base: "h-full bg-slate-800 dark:bg-slate-200 animate-progress",
  ).render
end

This should produce the following:

Notice that the progress fill width is hardcoded at this time.

Now, let's finish the interface by adding the icons with their corresponding container:

<div class="<%= container_classes %>">
  <div class="<%= track_info_container_classes %>">
    <h5 class="<%= track_title_classes %>"><%= @title %></h5>
    <p class="<%= track_author_classes %>"><%= @author %></p>
  </div>
  <div class="<%= progress_bar_container_classes %>">
    <div class="<%= time_classes %>">--:--</div>
    <div 
      class="<%= progress_bar_classes %>">
      <div class="<%= progress_bar_fill_classes %>" style="width: 24%"></div>
    </div>
    <div class="<%= time_classes %>">--:--</div>
  </div>
  <div class="<%= controls_container_classes %>">
    <button class="<%= secondary_button_classes %>">
      <i class="far fa-arrow-rotate-left <%= secondary_button_icon_classes %>"></i>
    </button>
    <button class="<%= secondary_button_classes %>">
      <i class="fas fa-step-backward <%= secondary_button_icon_classes %>"></i>
    </button> 
    <button class="<%= play_button_classes %>">
      <i class="fas fa-play <%= play_button_icon_classes %>"></i>
    </button>
    <button class="<%= secondary_button_classes %>">
      <i class="fas fa-step-forward <%= secondary_button_icon_classes %>"></i>
    </button>
    <button class="<%= secondary_button_classes %>">
      <i class="far fa-arrow-rotate-right <%= secondary_button_icon_classes %>"></i>
    </button>
  </div>
</div>

We also add the classes to the component:

def controls_container_classes
  ClassVariants.build(
    base: "flex items-center gap-x-3 justify-center mt-4",
  ).render
end

def play_button_classes
  ClassVariants.build(
    base: "w-10 h-10 rounded-full bg-slate-800 dark:bg-slate-200",
  ).render
end

def play_button_icon_classes
  ClassVariants.build(
    base: "text-white dark:text-slate-800",
  ).render
end

def secondary_button_classes
  ClassVariants.build(
    base: "w-6 h-6 rounded-full",
  ).render
end

def secondary_button_icon_classes
  ClassVariants.build(
    base: "text-slate-800 dark:text-slate-200",
  ).render
end

This produces the same player we saw at the beginning without any functionality:

Now it's time to hook everything up using Stimulus to make the audio player actually work.

But first, let's dive a bit into using web audio and how it works:

Understanding Web Audio

As of today, there are mainly two ways to work with audio in the browser: the Web Audio API and HTML 5 Audio with the <audio> tag or the Audio class.

The former is more powerful, includes many more features, and let's us manipulate the audio more granularly.

Some notable features of the Web Audio API are:

• Audio graph: it uses a modular, node-based approach to handling audio, where audio flows through a network of connected nodes that have separate functions. The combination of these nodes allows us to manipulate audio in a more granular way.
• Advanced processing: it supports filters and equalization, reverb, delay, analyzers, oscillators, compression, 3D spatial audio and more.
• Precise timing: it offers synchronization that's sample-accurate.
• Access to raw audio data: this means we can manipulate the audio directly by accessing raw audio using the AudioBuffer and the Float32Array features.

However, its power doesn't come without a cost: it's more complex, and can be resource intensive, which might be undesirable in some cases.

HTML 5 Audio

The HTML 5 Audio, represented with the <audio> element, is used to embed sound in documents.

By using the tag with a valid source and passing the controls attribute:

<audio src="https://filesamples.com/samples/audio/mp3/sample3.mp3" controls />

We can produce a default player, whose appearance varies depending on the browser used:

Besides defining an explicit <audio> tag, we can also use the JavaScript Audio class to programmatically play audio in the browser:

const url = "https://filesamples.com/samples/audio/mp3/sample3.mp3"
const audio = new Audio(url)
audio.addEventListener("canplaythrough", () => audio.play())

We will learn more about using the Audio class later. For now, let's learn about the attributes we can pass to the <audio> tag:

Attributes

Some important attributes for the <audio> tag are:

• src: indicates the URL of the audio to embed. It's optional because we can also use the <source> tag inside the audio block to pass the audio file or files we want to use for playback.
• controls: if present, the player shows controls that allow users to perform actions with the audio like play, pause, seek, adjust the volume or playback speed.
• crossorigin: it indicates whether to use CORS to fetch the audio file or not. When present, it accepts two values: anonymous to send the cross-origin request without credentials and use-credentials to send it using credentials.
• autoplay: audio playback starts as soon as possible when this attribute is specified. Be wary about using it, autoplaying audio can be very annoying.
• preload: it defines whether the audio or its metadata will be preloaded or not. It accepts three values: none which indicates that the audio should not be preloaded, metadata which indicates that only the metadata should be preloaded and autowhich indicates that the whole audio file should be downloaded. Note that it provides a hint to the browser, the behavior is not assured.

Other attributes like muted to determine if the player is initially muted or loop to define whether the audio is reset to the starting point after finishing can also be passed to the <audio> tag.

Events

There are many events that we can attach to the audio element or an Audio instance.

Many of them, like complete which indicates that the element

• canplay: the browser can play the audio, but it hasn't been fully loaded yet.
• canplaythrough: the browser estimates that it can play the audio up to the end without stopping for buffering.
• ended: fires when the audio has finished playing because the end was reached.
• timeupdate: fires when the currentTime attribute has been updated.
• play: fires every time the audio starts playing.
• pause: fires every time the audio stops playing. It also fires when the audio finishes playing along with the ended event.
• loadedmetadata: fires when the audio metadata is loaded. This metadata includes things like duration, seekable, networkState, playbackRate and other attributes that can be accessed through the audio instance.
• seeked: fires when the user performs a seek operation, which means that the playback position changes. It's also accompanied by the seeking event, which returns a boolean: when seeked is fired, seeking is changed to false.

For our intents and purposes, knowing about these events is more than enough to build our audio player.

However, there are many other events that can be useful for working with audio, feel free to explore them in the MDN Web Docs and test them in your own configuration.

Player functionality with Stimulus

Waveform generation

Audio is a more

Waveform placeholder

Audio-based waveform generation

Making the waveform responsive

Summary

In this article, we built an audio player with many of the features we expect from a player but we also added the ability to generate waveform visua