Configuration

This document covers the most common configuration options for VP Audio Player. The following sections are covered:

• Audio details
• Player size
• Layout grid
• Podcast mode
• Floating player
• Autostart and autopause on viewable
• Audio locking

Audio details

You can set up the audio metadata, which the player uses to render the title, author, thumbnail, and other UI elements. Several properties have aliases so the same audio object can be reused across different VP players.

vpAudioPlayer("audio-details").setup({
    audio: {
        audioId: "",
        file: "the_audio_file_path",
        thumbnail: "",
        title: "",
        author: "",
        duration: 0,
        season: -1,
        episode: -1,
    }
});

PROPERTY	DESCRIPTION
audio Object	This object contains all of the audio metadata properties shown below.
audioId string	The unique ID of the audio. Alias: mediaId.
file string	The URL of the audio file or HLS stream (mp3, m3u8). Alias: hlsUrl.
thumbnail string	The URL of an image used as the cover art for the audio. Alias: thumbnailUrl.
title string	The title of the audio.
author string	The author or creator of the audio.
duration int	The duration of the audio in seconds.
season int	The season number (for podcast-style content). Use -1 when not applicable.
episode int	The episode number (for podcast-style content). Use -1 when not applicable.
advertising boolean	A boolean indicating whether ads are enabled for the audio. See Advertising for details.

Player size

The VP Audio Player can be rendered either responsively (filling its container) or with a fixed width.

vpAudioPlayer("audio-player-responsive").setup({
    audio: {
        file: "the_audio_file_path"
    },
    config: {
        size: {
            responsive: true,
            width: 0,
        },
    }
});

vpAudioPlayer("audio-player-fixed").setup({
    audio: {
        file: "the_audio_file_path"
    },
    config: {
        size: {
            responsive: false,
            width: 480,
        },
    }
});

PROPERTY	DESCRIPTION
size Object	An object that controls the rendered size of the player.
responsive boolean	When true, the player fills its container width. When false, the player uses the value defined in width.
width number	An integer specifying the fixed width of the player in pixels. Ignored when responsive is true.

Layout grid

The audio player uses a 9-cell grid layout that places the thumbnail, text (title/author), and controls. Two arrangements (default and alternate) are defined per breakpoint, and startWith chooses which one is shown initially. A user toggle (the collapse button) lets the user switch between them at runtime.

vpAudioPlayer("audio-grid").setup({
    audio: {
        file: "the_audio_file_path"
    },
    config: {
        gridOptions: {
            desktop: {
                startWith: "default",
                default: {
                    thumbnail: [1, 4, 7],
                    text: [2, 3, 5, 6],
                    controls: [8, 9],
                },
                alternate: {
                    thumbnail: [1, 2, 3],
                    text: [4, 5, 6],
                    controls: [7, 8, 9],
                },
            },
            mobile: {
                startWith: "default",
                default: {
                    thumbnail: [1, 4],
                    text: [2, 3, 5, 6],
                    controls: [7, 8, 9],
                },
                alternate: {
                    thumbnail: [1, 2, 3],
                    text: [4, 5, 6],
                    controls: [7, 8, 9],
                },
            },
        },
    }
});

PROPERTY	DESCRIPTION
gridOptions Object	Configures the player's grid layout for desktop and mobile breakpoints.
desktop Object	Grid configuration applied on desktop viewports.
mobile Object	Grid configuration applied on mobile viewports.
startWith string	Which arrangement to render initially. Possible values: "default", "alternate".
default Object	The default grid arrangement, specifying which cells (1–9) each player element occupies.
alternate Object	The alternate grid arrangement that the user can toggle into via the collapse button.
thumbnail array[int]	Array of grid cell numbers (1–9) where the thumbnail should be placed.
text array[int]	Array of grid cell numbers where the title and author text should be placed.
controls array[int]	Array of grid cell numbers where the playback controls should be placed.

Podcast mode

The audio player supports a podcast mode that renders a podcast preview with a list of episodes. When podcast mode is active, the player exposes an episode list and the podcast's metadata.

vpAudioPlayer("audio-podcast").setup({
    audio: {
        file: "the_audio_file_path",
        podcast: {
            state: true,
            thumbnail: "",
            title: "",
            author: "",
            id: "",
            audios: [],
        },
    },
    config: {
        showPodcastPreview: true,
    }
});

PROPERTY	DESCRIPTION
podcast Object	An object that configures podcast mode for the audio.
state boolean	When true, the audio is treated as part of a podcast and the podcast UI is enabled.
thumbnail string	The URL of an image used as the podcast cover art.
title string	The title of the podcast.
author string	The author or producer of the podcast.
id string	Allows the use of a podcast which has already been created on vpPlayer admin (takes priority over the audios array).
audios array[Object]	An array of audio objects representing the podcast episodes.
showPodcastPreview boolean	Controls whether the podcast preview UI is displayed. Configured on the config object.

Floating player

The float property allows the player to switch into a floating overlay when scrolled out of view, similar to the video player.

vpAudioPlayer("audio-float").setup({
    audio: {
        file: "the_audio_file_path"
    },
    config: {
        float: {
            state: true,
            onMobile: false,
            position: "BOTTOM_RIGHT",
            dismissible: true,
            requiresInteraction: false,
            toVideoThreshold: 0.35,
            toFloatThreshold: 0.2,
        },
    }
});

PROPERTY	DESCRIPTION
float Object	An object that configures the floating player behavior.
state boolean	Enables the floating player when true.
onMobile boolean	Enables the floating player on mobile devices when true.
position string	Position of the floating player. Possible values: "BOTTOM_RIGHT", "BOTTOM_LEFT", "TOP_RIGHT", "TOP_LEFT".
dismissible boolean	When true, the floating player shows a close button that the user can use to dismiss it.
requiresInteraction boolean	When true, the player must have been interacted with before it can switch to floating mode.
toFloatThreshold float	Viewport visibility ratio (0–1) at which the player switches into the floating state.
toVideoThreshold float	Viewport visibility ratio (0–1) at which the player switches back out of the floating state.

Autostart and autopause on viewable

The autostartOnViewable and autopauseOnViewable options let the player start or pause based on whether it is in the viewport.

vpAudioPlayer("audio-viewable").setup({
    audio: {
        file: "the_audio_file_path"
    },
    config: {
        autostartOnViewable: {
            state: false,
            onMobile: false,
            onData: false,
            percentageViewable: 0.5,
        },
        autopauseOnViewable: {
            state: false,
            percentageViewable: 0.5,
        },
    }
});

PROPERTY	DESCRIPTION
autostartOnViewable Object	Starts playback automatically when the player becomes viewable.
state boolean	Enables the autostart-on-viewable behavior when true.
onMobile boolean	When true, the autostart-on-viewable behavior also applies on mobile devices.
onData boolean	When true, the autostart-on-viewable behavior also applies on cellular data connections.
percentageViewable float	The viewport visibility ratio (0–1) at which autostart should trigger.
autopauseOnViewable Object	Pauses playback automatically when the player scrolls out of view.
state boolean	Enables the autopause-on-viewable behavior when true.
percentageViewable float	The viewport visibility ratio (0–1) below which autopause should trigger.

Audio locking

The audioLocking option allows you to gate part of the audio behind a lock that triggers either after a number of seconds or at a percentage of playback. When the lock is activated, an alternate audio file can be played to communicate the paywall message.

vpAudioPlayer("audio-locking").setup({
    audio: {
        file: "the_audio_file_path",
        audioLocking: {
            isEnabled: false,
            type: "seconds",
            value: 15,
            afterLockAudio: "",
        },
    }
});

PROPERTY	DESCRIPTION
audioLocking Object	An object that configures audio locking behavior.
isEnabled boolean	When true, audio locking is active for the audio.
type string	Determines how the lock activation timing is measured. Possible values: "seconds", "percentage".
value number	The activation timing value. If type is "seconds", this is the elapsed time at which the lock activates. If type is "percentage", this is the percentage of the audio that has been played at which the lock activates.
afterLockAudio string	The URL of an audio file to play after the lock has been activated.

General configuration options

The following top-level config properties control general player behavior:

PROPERTY	DESCRIPTION
autoplay boolean	When true, the player begins playback automatically after setup.
loop boolean	When true, playback restarts when the audio reaches the end.
casting boolean	Enables Chromecast and AirPlay support when true.
skipAmount int	The number of seconds the skip-forward and skip-back buttons jump.
playbackRates array[float]	Available playback speeds in the settings menu (e.g., [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]).
socialMedia array[string]	An array of social media platforms that appear in the share menu (e.g., "FACEBOOK", "LINKEDIN", "REDDIT"). Sharing is hidden if the array is empty.
showPlaylist boolean	When true, the playlist panel is shown from the start.
showPlaylistItemProgress boolean	When true, the playlist items display their individual playback progress.
paginationTake int	The number of items loaded per playlist page.
pauseOtherAudios boolean	When true, starting playback on this player pauses every other VP Audio Player on the page.
thumbnail boolean	When true, the audio thumbnail is rendered in the player.
theme string	The player theme. Leave empty for the default theme, or set to "minimal" for the minimal theme.
font Object	An object with family and url properties that configures the font used by the player UI.