Configuration

WebPlayer can be configured through the WPParams JavaScript object, data attributes on the script tag, HTML classes on individual links, or URL hash modifiers.

WPParams options

Define a global WPParams object before the loader script:

<script>
var WPParams = {
  autoplay: false,
  theme: "dark",
  volume: 0.8,
  include: "main",
  exclude: ".sidebar, .nav"
};
</script>
<script src="https://webplayer.warmerdam.ai/widget/loader.js" async></script>

Option	Type	Default	Description
`autoplay`	boolean	false	Automatically play the first detected track on page load.
`theme`	string	"dark"	Player theme. Accepts "dark", "light", or "auto" (follows system preference).
`volume`	number	0.8	Default playback volume, from 0 (muted) to 1 (full).
`include`	string	"body"	CSS selector defining which areas of the page to scan for media links.
`exclude`	string	""	CSS selector for areas to skip during scanning.
`htrackonly`	boolean	false	When true, only links with the ymusic or htrack class are detected. All other links are ignored.
`playlink`	boolean	true	When true, clicking the link text itself will start playback (instead of only the play icon).
`termdetection`	string	"off"	AI-powered entity detection. Not currently available for external publisher embeds. See note below.
`pid`	string	""	Project identifier used for analytics and API routing.
`apiBase`	string	""	Base URL for the WebPlayer API. Override this when self-hosting the backend.
`apiKeys`	object	{}	API keys for third-party services, keyed by service name (e.g. { youtube: "..." }).
`linkconfig`	object	{}	Per-link overrides. Keys are CSS selectors, values are config objects applied to matching links.
`imagelinkconf`	object	{}	Configuration for image-based links (album art detection).

Term Detection (Preview Feature)

WebPlayer includes an AI-powered term detection feature that identifies artist names and song titles in plain text, then automatically finds matching YouTube videos. It uses the YouTube Data API for video search and Anthropic Claude for intelligent entity extraction.

Interested in term detection for your site? Reach out to us.

Data attributes

Each WPParams option can also be set as a data- attribute on the script tag. Use the same option name, prefixed with data-:

<script
  src="https://webplayer.warmerdam.ai/widget/loader.js"
  data-theme="dark"
  data-include="main article"
  data-autoplay="false"
  data-volume="0.8"
  data-htrackonly="true"
  async
></script>

Boolean values should be passed as the strings "true" or "false". Object values (like linkconfig) should be passed as JSON strings.

HTML classes

Add these CSS classes to individual anchor elements to control how the scanner treats them:

Class	Behavior
`htrack`	Force-include this anchor in the playlist, even if it would not normally be detected.
`noplay`	Exclude this anchor from detection. The player will skip it entirely.
`playthispage`	When clicked, create a playlist from all detected media on the current page and begin playback.

Example usage:

<!-- Force this link into the playlist -->
<a href="https://example.com/song.mp3" class="htrack">My Song</a>

<!-- Exclude this link from detection -->
<a href="https://example.com/background.mp3" class="noplay">Background audio</a>

Hash modifiers

Append these to the page URL to override playback behavior:

Hash	Behavior
`#play`	Automatically begin playback when the page loads.
`#noplay`	Prevent automatic playback, overriding the autoplay setting.

https://yoursite.com/page#play

Configuration priority

When multiple configuration sources are present, they are applied in the following order (highest priority first):

URL hash modifiers (#play, #noplay)
HTML classes on individual elements (htrack, noplay)
WPParams JavaScript object
Data attributes on the script tag
Default values