Setup

Welcome to the Setup section of this documentation. Here you'll find instructions on setting up VP Audio Player, registering multiple players on a page, and configuring basic and advanced options.

VP Audio Player is highly customizable, allowing you to tailor its appearance and behavior to fit your needs. Before configuring the player, you need to set it up properly. Below are the steps to do so.

Setup Description

The basic syntax for creating the player is:

• vpAudioPlayer("div").setup(configuration)

The table below explains the parameters:

ATTRIBUTE	DESCRIPTION
div* string	(Required) The ID of the target div that VP Audio Player will render into.
config* JSON	(Required) Configuration object defining how the player should be rendered.

Configuration

Only audio.file (or audio.audioId) is required. All other configuration properties have sensible defaults and can be customized as needed.

Setup Process

To set up VP Audio Player, follow these steps:

1. Import the vpAudioPlayer script:

   <script src="https://host.vpplayer.tech/audio-player/v1.4.0/vp-audio-player.js"></script>

2. Create a div element with a unique ID for the player:

   <div id="vp-audio-player"></div>

3. Define the configuration. The only required field is the audio source — either a media file URL or an audioId:

   const config = {
     audio: {
       file: "the_audio_file_path",
     },
   };

4. Initialize the player by calling vpAudioPlayer with the ID from step 2, and call setup with the configuration:

   vpAudioPlayer("vp-audio-player").setup(config);

That's it! Your VP Audio Player should now be set up and ready to use.

Common Configuration

Below is a configuration example showing the most commonly used options. All fields are optional unless noted.

const config = {
  projectId: "",
  audio: {
    audioId: "",
    file: "the_audio_file_path",
    thumbnail: "",
    title: "",
    author: "",
    duration: 0,
    advertising: false,
  },
  config: {
    theme: "",
    autoplay: true,
    loop: false,
    casting: false,
    skipAmount: 10,
    playbackRates: [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2],
    showPlaylist: false,
    pauseOtherAudios: false,
    size: {
      responsive: true,
      width: 0,
    },
    float: {
      state: false,
      onMobile: false,
      position: "BOTTOM_RIGHT",
      dismissible: true,
    },
    lang: {
      locale: "en",
    },
  },
};

vpAudioPlayer("vp-audio-player").setup(config);

tip

Properties not included in your config object will fall back to their defaults. See the configuration reference for the full list of supported options including skin, gridOptions, audioLocking, podcast, autostartOnViewable, advertising (audio.ads), and localization (config.lang).

Multiple Players on a Page

You can initialize multiple audio players on the same page. Each player must target a unique div ID.

<div id="audio-player-1"></div>
<div id="audio-player-2"></div>

<script>
  vpAudioPlayer("audio-player-1").setup({
    audio: { file: "the_audio_file_path" },
  });

  vpAudioPlayer("audio-player-2").setup({
    audio: { file: "the_audio_file_path" },
  });
</script>

To retrieve a reference to an existing player, call vpAudioPlayer again with the same div ID:

const player = vpAudioPlayer("audio-player-1");

You can also access a player by its registration index, or get the first registered player by calling vpAudioPlayer() with no arguments:

const firstPlayer = vpAudioPlayer();      // First registered player
const secondPlayer = vpAudioPlayer(1);    // Player at index 1

To enable pausing other audio players when one starts playing, set config.pauseOtherAudios to true.

Shared Default Configuration

For setups with multiple players that share the same configuration, you can register a default configuration once and have every player use it as a base. This avoids duplicating the same config object across every setup() call.

// Register the shared default configuration once
vpAudioPlayer.defaultConfigs.addConfig({
  configId: "podcast-config",
  config: {
    theme: "minimal",
    autoplay: false,
    casting: true,
  },
});

// All players initialized after this point use the registered config as their base
vpAudioPlayer("audio-player-1").setup({
  audio: { file: "the_audio_file_path" },
});

vpAudioPlayer("audio-player-2").setup({
  audio: { file: "the_audio_file_path" },
});

The configuration passed to setup() is deep-merged on top of the registered default. The configId field is required as the registry key.

Destroying a Player

To remove a player and clean up its resources:

const player = vpAudioPlayer("vp-audio-player");
player.destroy();