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.

Keyboard and Screen Readers

Every control carries a name that a screen reader announces and that follows its state, so play reads as pause while playing and mute reads as unmute while muted. The seek rail is a slider that announces progress as playback advances, the settings menu exposes its rows and which one is checked, and a visible focus ring shows which control the keyboard is on.

Tabbing into a player makes it the target of the keyboard shortcuts, so no click is needed first:

• Space - Pause or resume playback
• M - Mute or unmute
• Left Arrow / Right Arrow - Seek backward or forward by skipAmount seconds
• Up Arrow / Down Arrow - Change the volume by 5%
• Cmd + Left Arrow / Right Arrow - Previous or next item in a playlist

The player claims only the keys it handles, and only while a player has focus, so your page's own shortcuts keep working. A focused control keeps the keys it natively owns: a button keeps Space and Enter, the volume slider keeps the arrow keys. Set keyboardShortcuts: false in config to switch the shortcuts off entirely.

Destroying a Player

To remove a player and clean up its resources:

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

Destroying removes the player from the page together with its analytics timers, page listeners, observers, ad manager and casting session. Calling it a second time does nothing.

note

The player ships its own streaming engine (hls.js) and icons inside the script file. It no longer loads either from a CDN, and it does not pick up an Hls object your page may have loaded itself. Sites that keep a domain allowlist do not need vp.gjirafa.net reachable for playback.