Vocalize Ai
Sign in Sign up

Vocalize Audio Player

This project is an implementation of the Vocalize Audio Player using HTML and JavaScript. It allows you to embed and control an audio player on a webpage, including the ability to dynamically change tracks, play all tracks, and handle VAST ads.

Table of Contents

Features

  • Embed an audio player on your webpage
  • Display a track list with play controls
  • Supports both Playlist and Single tracks
  • Dynamically change the track list
  • Supports pre-roll, mid-roll and post-roll ADs via VAST Tags integration
  • Supports both Live Audio broadcasts (.m3u8) as well other formats such as .mp4, .webm, .mp3, .wav, .ogg, .aac.

Demo

Savara
Savara

Artist

Installation

To use the Vocalize Audio Player in your project,

  1. Create a publisher account to get access credentials
  2. include the following dependencies in your HTML:

 <!-- Scripts -->
<script src="https://d211dnuaikc3d8.cloudfront.net/assets/player/main.bundle.js"></script>

Usage

Here’s an example of how to use the Vocalize Audio Player:

1. Single Track

            <!--HTML Structure-->
<div class="container pt-5">
    <div class="card border-0 border-bottom rounded-0">
        <div class="card-body d-flex align-items-center">
            <button class="btn btn-outline-success" id="vocalize-track" data-id="radio-citizen">
                <i class="bi-play"></i>
            </button>
            <div class="flex-grow-1 ps-2">
                <h5 class="fs-6 mb-0">Radio Citizen</h5>
                <p class="fs-6 mb-0"><small>Royal Media Services</small></p>
            </div>
        </div>
    </div>
    <div id="vocalize-container" class="mt-3"></div>
</div>

<!--Javascript  Initialization-->
<script>
    document.addEventListener("DOMContentLoaded", () => {
        window.VocalizeAudio.init({
            containerId: 'vocalize-container',
            style: {
                theme: 'light-theme',
            },
            tracks: [{
                id: 'radio-citizen',
                name: "Radio Citizen",
                artist: "Radio Citizen",
                imgUrl: "https://d211dnuaikc3d8.cloudfront.net/audio/radio-citizen.png",
                link: "https://radiocitizen-atunwadigital.streamguys1.com/radiocitizen/playlist.m3u8",
            }],
            vastUrl: "XXXX",
            auth: {
                "X-Api-Publisher-Id": "XXXX",
                "X-Api-Publisher-Secret": "XXXX",
            }
        });
    });
</script>
</body>

2. Multiple Tracks

HTML Structure


<!--HTML Structure-->
<div class="container pt-5">
    <div class="card border-0 border-top border-bottom rounded-0">
        <div class="card-body d-flex align-items-center">
            <h5 class="fs-6 mb-0">Savara</h5>
            <p class="fs-6 mb-0"><small>Artist</small></p>
            <button class="btn btn-outline-success" id="vocalize-play-all">
                <i class="bi-play fw-bolder"></i> Play All
            </button>
        </div>
    </div>

    <div id="track-list"></div>

    <div id="vocalize-container" class="mt-3"></div>
</div>

<!--Javascript  Initialization-->
<script>
  document.addEventListener("DOMContentLoaded", () => {
    const tracks = [
      {
        id: 'reggae-ya-kinyozi',
        name: "Reggae Ya Kinyozi",
        artist: "Savara",
        imgUrl: "https://d211dnuaikc3d8.cloudfront.net/audio/Savara-og_image.webp",
        link: "https://d211dnuaikc3d8.cloudfront.net/audio/savara.mp3",
      },
      {
        id: 'parapanda',
        name: "Parapanda",
        artist: "Ari Barokos",
        imgUrl: "https://d211dnuaikc3d8.cloudfront.net/audio/Savara-og_image.webp",
        link: "https://d211dnuaikc3d8.cloudfront.net/audio/Parapanda.mp3",
      },
      {
        id: 'radio-citizen',
        name: "Radio Citizen",
        artist: "Radio Citizen",
        imgUrl: "https://d211dnuaikc3d8.cloudfront.net/audio/radio-citizen.png",
        link: "https://radiocitizen-atunwadigital.streamguys1.com/radiocitizen/playlist.m3u8",
      }
    ];

    const trackList = document.getElementById('track-list');

    tracks.forEach(track => {
      const trackElement = `
            <div class="card border-0 border-bottom rounded-0">
                <div class="card-body d-flex align-items-center">
                    <button class="btn btn-outline-success" id="vocalize-track" data-id="${track.id}">
                        <i class="bi-play"></i>
                    </button>
                    <div class="flex-grow-1 ps-2">
                        <h5 class="fs-6 mb-0">${track.name}</h5>
                        <p class="fs-6 mb-0"><small>${track.artist}</small></p>
                    </div>
                </div>
            </div>
        `;
      trackList.innerHTML += trackElement;
    });

    window.VocalizeAudio.init({
      containerId: 'vocalize-container',
      style: {
        theme: 'light-theme',
      },
      tracks,
      vastUrls: [
    { url: 'https://example.com/vast1.xml', weight: 0.5 },
    { url: 'https://example.com/vast2.xml', weight: 0.3 },
    { url: 'https://example.com/vast3.xml', weight: 0.2 },
],
      auth: {
        "X-Api-Publisher-Id": "XXXX",
        "X-Api-Publisher-Secret": "XXXX",
      }
    });
  });
</script>

API

1. Initialize the Vocalize Audio Player.

window.VocalizeAudio.init(options)

Parameters

Paramater Mandatory/Optional Description Example
containerId Mandatory The ID of the container where the player will be rendered. containerId: 'vocalize-container'
style.theme Optional The theme for the player (e.g., light-theme, dark-theme). style.theme: 'light-theme'
tracks Array An array of track that can be initialized when initializing the player. tracks: [{...}]
vastUrls Array, Optional The URLS for VAST ads and associated weights vastUrls: [
{ url: 'https://example.com/vast1.xml', weight: 0.5 },
{ url: 'https://example.com/vast2.xml', weight: 0.3 },
{ url: 'https://example.com/vast3.xml', weight: 0.2 }
]
auth.X-Api-Publisher-Id String, Mandatory Your publisher ID. auth.X-Api-Publisher-Id: "XXXX"
auth.X-Api-Publisher-Secret String, Mandatory Your publisher Secret. auth.X-Api-Publisher-Secret: "XXXX"

2. Plays a specific track by its ID.

  • window.VocalizeAudio.play(trackId):

    Parameters:

Paramater Mandatory/Optional Description Example
trackId Optional The ID of the track to play. If omitted, plays the first track in the list. window.VocalizeAudio.play(radio-citizen)
  • trackId (string, optional): The ID of the track to play. If omitted, plays the first track in the list.

3. Update list of tracks to be played

  •                 window.VocalizeAudio.setTracks(tracks)
                const newTracks = [ 
            {
      id: 'new-track-1',
  name: 'New Track 1',
  artist: 'New Artist',
  imgUrl: 'https://example.com/new-track-1.jpg',
  link: 'https://example.com/new-track-1.mp3',

      },
            ];

window.VocalizeAudio.setTracks(newTracks);


 
4. Unloads the audio player for cleanup purposes

window.VocalizeAudio.unload():
<script>
  document.addEventListener('pagehide', window.VocalizeAudio.unload());
  document.addEventListener('unload', window.VocalizeAudio.unload());
</script>

Notes

  • Ensure that you replace 'YOUR_PUBLISHER_ID' and 'YOUR_PUBLISHER_SECRET' with your actual authentication credentials.
  • The player supports both audio files and streaming URLs (e.g., .m3u8, .mp4, .webm, .mp3, .wav, .ogg, .aac).
  • Customize the HTML and CSS as needed to fit the design of your website.