(877) 698-9894 [email protected]
Monday - Friday 9am - 6pm

VMPlayer User Manual

Professional Streaming Radio Player for WordPress

Overview

VMPlayer is a modern streaming radio player built for WordPress. It handles Shoutcast, Icecast, HLS, and direct audio streams, pulls live now-playing metadata straight from the stream, and enriches every track with cover art from iTunes, Deezer, and MusicBrainz so listeners always see what is playing. The player runs a dark neon interface that adapts to whatever width you give it, and listeners can pop it out into its own window while they browse the rest of your site. Install directly from the WordPress plugin directory at wordpress.org/plugins/vmplayer/.

Multi-Protocol Streaming

Native support for Shoutcast v1 and v2, Icecast, HLS playlists, and direct MP3, AAC, OGG, or Opus streams. Hosts running on SonicPanel, Vouscast, Zeno, or any other control panel plug in cleanly since those all sit on top of Shoutcast or Icecast underneath.

Live Artwork Lookup

Song titles get real cover art from a three-tier lookup across iTunes, Deezer, and MusicBrainz. An iTunes storefront selector covering 50+ countries makes sure regional and indie artists get matched to the local catalog first.

Pop-Out Player Window

Listeners can pop the player into a separate window that follows them around your site. A compact bar mode keeps the essentials visible without dominating the screen, and the pop-out communicates with the main player through the postMessage protocol so nothing gets out of sync.

Container-Aware Layout

The player uses CSS container queries so it responds to the width you actually give it, not just the viewport. Drop it into a full-width section for the landscape layout, a narrow sidebar for the portrait layout, and every step in between just works.

Quick Start Guide

Initial Setup (5 Minutes)

  1. Install VMPlayer Head to Plugins > Add New in your WordPress admin, search for "VMPlayer", and click Install. Or download the zip from wordpress.org/plugins/vmplayer/ and upload it manually. Activate after install.
  2. Add Your First Station Go to Settings > VMPlayer > Stations and click Add Station. Give it a name, drop in your stream URL, pick the stream type (Shoutcast, Icecast, HLS, or direct), and upload a station logo. The logo shows in the artwork slot until per-song artwork is found.
  3. Test the Connection Click Test Connection on the station card. A green result confirms VMPlayer can reach your stream. A red result usually means the stream URL is wrong, the server is down, or the mount point is missing. VMPlayer handles streams behind reverse proxies as well as streaming services like Zeno, RadioJar, MyRadioStream, and RadioKing that use custom URL patterns.
  4. Pick Your iTunes Storefront On the General tab, choose the country whose iTunes Store best matches your listeners. This helps VMPlayer find local artists faster during artwork lookups. Jamaica, Trinidad and Tobago, Barbados, and 47 other countries are supported.
  5. Drop the Shortcode Use [vmplayer] in any post, page, block, or widget. To force a specific station on a specific page, use [vmplayer station="1"] where 1 is the index, or [vmplayer station="my-station-slug"] for a named station.
The First Play Always Requires a Click
Browsers block autoplay for audio streams as a matter of policy. The first time a visitor arrives on a page with the player, they will need to click Play to start audio. Subsequent navigation within the same session may auto-resume depending on the auto-resume setting.

Features

Live Metadata Polling
VMPlayer polls your stream server every 15 seconds by default to pull the currently playing artist, title, listener count, bitrate, sample rate, and channel configuration. Polling interval is configurable between 5 and 300 seconds so you can trade freshness against server load. Shoutcast v2 XML stats and Icecast JSON status endpoints are both fully supported, and ICY headers fill in the gaps for v1 Shoutcast streams that do not expose separate stats endpoints.
  • Full metadata: artist, title, listener count, bitrate, sample rate, and channels
  • Configurable interval: 5 to 300 seconds, with 15 as the sensible default
  • Reverse-proxy aware: handles path-routed streams correctly
  • ICY header parsing: pulls stream metadata even when a stats endpoint is not exposed
  • Character encoding safe: song titles containing ampersands or apostrophes display correctly (fixed in 1.1.3)
Artwork Enrichment New in 1.0.2
Every track gets its cover art looked up in real time. VMPlayer checks four sources in priority order and stops at the first hit. Stream metadata wins if your automation software pushes an artwork URL through custom fields. If not, iTunes Search API runs next with your configured country storefront. If iTunes has no match, Deezer takes a turn, which is particularly strong for reggae, Caribbean, Latin, and international catalog. If Deezer misses, MusicBrainz plus the Cover Art Archive handles classical and older releases. Everything is cached aggressively so a station broadcasting the same song for three minutes does not send a lookup on every metadata poll.
Pop-Out Player Window New in 1.0.2
Listeners click the pop-out button and the player opens in its own portrait-shaped window. It follows the same theme colors, shows the same live metadata, and includes its own kebab menu with share, quality switching, settings, and about panels. A compact bar mode collapses the pop-out to a 60-pixel strip that stays visible while listeners work in other applications. When the pop-out closes, the main player picks up where it left off if auto-resume is enabled.
Kebab Menu New in 1.0.2
The three-dot menu on both the main player and the pop-out surfaces four panels. Share lets listeners post the current station to Facebook, X, or email, or copy the direct link. Switch Quality shows every mount configured on the station so listeners can jump between low, medium, and high bitrate on the fly. Player Settings toggles visualizer and auto-resume behavior. About shows station description, genre, and streaming format.
Station Counter Pill New in 1.0.2
When you configure more than one station, a small pill appears in the brand area that reads "Station 1 of 3" or however many you have actually set up. The pill updates live as listeners cycle through stations with the previous and next buttons. When only one station is configured, the pill hides and the previous and next buttons disable automatically so listeners never click a dead control.
Container Queries for Adaptive Layout New in 1.0.2
The player uses CSS container queries so its layout responds to the width you actually give it, not just the viewport width. That means the player renders correctly inside narrow Elementor columns, theme sidebars, and full-width sections without you having to think about breakpoints. Above 1199 pixels the landscape layout displays, between 767 and 1199 the layout compacts, and below 767 the portrait layout kicks in.
Live Station Sync New in 1.1.2
Add, delete, or reorder stations in the WordPress admin and any open frontend player in another tab updates immediately. Listeners never need to reload the page to see a new station. Currently playing audio keeps playing during the update.
Compact Player Variant New in 1.1.3
A smaller two-row landscape variant sized for sidebars, footer strips, header bars, and other placements where the full player is too large. Includes all the essentials: artwork, station name, playback controls, volume, ON AIR badge, current track, and access to the full kebab menu. Enable it with [vmplayer variant="compact"]. Combine with the station attribute to feature a specific station in a compact placement.
LIVE Broadcast Detection New in 1.1.3
When a DJ or host goes on air through a physical console or through an encoder like BUTT that does not send song metadata to the stream server, the player detects the live source and displays LIVE instead of the leftover song title from before the DJ took over. Configurable per station on the Stations tab. Set a list of live indicator keywords, and detection also fires automatically when the stream title is empty or matches the station name. Real songs are never flagged even when they contain the word live.
Listener Count Display New in 1.1.3
Show the current number of active listeners in a small chip on the player when your stream server reports one. Works with Shoutcast v1, Shoutcast v2, and Icecast. Enable per station on the Stations tab because station operators often want the number visible for busy stations to build social proof and hidden for quieter ones. The chip hides automatically when the server does not report a count, so nothing broken appears.
Page Builder Compatibility Fixed in 1.1.4
The compact player variant now renders reliably on sites built with Elementor, WPBakery, and other page builders that texturize content. Earlier versions could silently drop the variant attribute on those sites, leaving nothing visible where the shortcode was placed. VMPlayer now protects its shortcodes from the texturize step and tolerates typographic quotes defensively, so the shortcode you paste is the shortcode that renders.
Dedicated Compact Shortcode New in 1.1.4
Use [vmplayer_compact] as a bulletproof alternative to [vmplayer variant="compact"]. Both produce the same output, but the dedicated shortcode has no attributes to mangle so it works in the most aggressive page builder environments. Pair it with an optional station attribute the same way the main shortcode does.
Optional Clock and Date Display New in 1.1.4
Toggle the clock and date on or off in the player header per station on the Stations tab. Defaults to on so existing stations upgrading from 1.1.3 keep the header they had. Turn it off when you want a cleaner header for a specific station or when your placement is too narrow for the clock to fit gracefully. The compact variant does not include a clock at all regardless of this setting.
Extended Page Builder Compatibility Fixed in 1.1.5
The 1.1.4 page builder fix caught the raw-character form of typographic quotes, and 1.1.5 catches the encoded form that some rich text editors use behind the scenes. The Text Editor widget in Elementor is one common example. If you upgraded to 1.1.4 and still saw the compact variant fall back to the main player on a particular editor, this build handles that case too. No shortcode changes needed on your side. Just update and refresh.
Volume Slider Theme Compatibility Fixed in 1.1.5
Some WordPress themes reach into range inputs from their global input styling, which could override the volume slider's purple-to-blue gradient and leave it as a plain white bar. JNews was one reported case, but the pattern shows up in any theme with strong opinions about form controls. VMPlayer now defends the volume slider's appearance so the styled gradient renders correctly on those themes as well.
Kebab Menu Readability Fixed in 1.1.5
The three-dot dropdown menu now stays readable on themes that set a dark body text color. Earlier builds relied on cascading styles that some themes could beat, leaving menu labels rendering as dark text on the dark navy background. VMPlayer now locks in readable colors on every menu item, heading, and About panel so the labels stay clear regardless of what the theme sets for body text.
Animated EQ Visualizer
Twenty-four vertical bars pulse in sync with the beat during playback. The visualizer runs a CSS animation mode by default which works on any stream regardless of CORS configuration. Real-time audio-reactive analysis is available as an opt-in for streams that send proper CORS headers, but it stays off by default because turning it on for a non-CORS stream can silence audio entirely due to a Web Audio API security rule.
Multi-Format Stream Support
Format badges show which audio codecs your stream serves so listeners know at a glance what they are getting. MP3, AAC, OGG, and Opus are all supported. The badge for the current stream lights up in the primary theme color and the others dim so the current codec is unambiguous.
Social Media Integration
Every station can link out to Facebook, Bsky, Instagram, YouTube, WhatsApp, and X. Platforms are stored as handles rather than full URLs so you just type the username or handle and VMPlayer builds the correct URL automatically. When you switch between stations, only the platforms configured for the current station display so listeners see the right buttons for what they are actually listening to.
Theme Color Customization
The default palette runs purple, blue, and neon red for a dark synthwave aesthetic. You can customize the primary and secondary colors from the General tab and the whole player updates. Colors flow through the play button, station badge, format highlights, station counter pill, and social buttons.

Stations Setup

Adding Your First Station

Head to Settings > VMPlayer > Stations and click Add Station. Each station has its own configuration card with the following fields.
Basic Station Information
  • Station Name: Displayed in the brand area, the browser tab title, and the pop-out window. Ampersands, apostrophes, and other special characters render correctly (fixed in 1.1.3).
  • Tagline: A short line beneath the station name, usually the station slogan
  • Description: Longer text shown in the About panel of the kebab menu
  • Genre: Shown in the streaming info footer next to the codec
  • Logo URL: Displayed in the brand area and used as the artwork fallback when no per-song image is found. If you leave this blank, VMPlayer uses a packaged default logo (new in 1.1.2).
  • Slug: An optional URL-safe identifier for use with the shortcode station attribute
Stream Configuration
  • Stream URL: The full URL where the audio stream lives, including port and mount point
  • Stream Type: Shoutcast, Icecast, HLS, or Direct. When your host runs a control panel like SonicPanel or Vouscast, pick the underlying protocol (Shoutcast or Icecast) rather than the panel name.
  • Additional Mounts: Add multiple stream URLs for the same station so listeners can switch between quality tiers from the kebab menu. Give each a friendly name like "High Quality 320" or "Low Bandwidth 64".
Test Connection Button
Every station card has a Test Connection button. Click it and VMPlayer probes your stream URL and reports back what it found. A green result confirms the stream is reachable and lists the metadata that came back. A red result explains what went wrong: unreachable server, wrong protocol, missing mount point, or timeout. Use this every time you configure a new station or troubleshoot a listener complaint about a stream not working. Works correctly with streaming services like Zeno, RadioJar, MyRadioStream, AsuraHosting proxy, and RadioKing (fixed in 1.1.2).
Reordering Stations
Drag station cards up or down to change their order. The order controls which station is the default (the first one), the sequence when listeners click previous or next, and how the station counter pill counts.
Station Limit
The free version supports up to 5 stations. This is enough for most single-station operators, family-owned broadcasters, and small radio networks. If you need more, a premium version is planned for a future release.

Artwork Sources

How VMPlayer Finds Cover Art

Every time a new track starts playing, VMPlayer walks through four artwork sources in priority order. The chain stops at the first hit, so higher-priority sources always win. This approach keeps the display accurate for the wide range of music a real radio station plays across a broadcast day.
Priority 1: Stream Metadata
If your automation software (RadioBoss, StationPlaylist, RadioDJ, and others) pushes an artwork URL through custom metadata fields, VMPlayer picks it up and uses it directly. This gives you full control since you can preload any cover art you want on your automation side. VMPlayer looks for around twenty common field names including song_url, imageurl, and albumart so it works with whatever your automation sends.
Priority 2: iTunes Search API New in 1.0.2
When the stream does not include artwork, VMPlayer queries the iTunes Search API for the current artist and title. Apple's catalog is huge and includes a wide range of indie releases pulled in through distribution aggregators like DistroKid, TuneCore, CD Baby, and Symphonic. Cover art comes back at 100x100 pixels and VMPlayer automatically upgrades the URL to 600x600 for a sharp display.
  • 50+ country storefronts: Pick the one that matches your listeners for the best regional match rate
  • Free and unmetered: No API key required, no rate limit worth worrying about with our caching
  • Aggressive caching: Hits cached for 24 hours, misses for 6 hours to catch newly added tracks quickly
Priority 3: Deezer New in 1.0.2
When iTunes has no match, VMPlayer falls through to Deezer's public API. Deezer's reggae, Caribbean, Latin, African, and general non-Western catalog is consistently stronger than iTunes for artists that never signed with an aggregator that ships to Apple. Cover art comes back at 1000x1000 pixels which VMPlayer uses directly. Deezer's terms permit hotlinking the CDN URL, which is what VMPlayer does.
Priority 4: MusicBrainz + Cover Art Archive Improved in 1.1.3
When both iTunes and Deezer strike out, MusicBrainz has the final say. MusicBrainz is a community-maintained database that shines for classical, jazz, older rock, and other legacy catalog. Cover art is served by the Cover Art Archive. As of 1.1.3, MusicBrainz artwork loads faster and stalls far less often, especially when Cover Art Archive is under load.
Fallback: Station Logo
When all four external sources fail to find a match (which happens for very small indie releases and non-commercial recordings), VMPlayer shows the station logo you uploaded when configuring the station. If you did not upload one, a packaged default logo takes its place (new in 1.1.2). The frontend also falls back to the station logo automatically if any artwork URL fails to load in the browser, so listeners never see broken image icons.
Individual Source Toggles
Each artwork source has its own checkbox in Settings > VMPlayer > General. You can disable any of them individually. For example, if you find iTunes returns wrong covers for certain artists, you can turn iTunes off and rely on Deezer and MusicBrainz alone. All three are on by default which gives the widest coverage.
Selecting Your iTunes Storefront
The iTunes Storefront dropdown in Settings > VMPlayer > General lists every supported country. Picking the one that matches your listener base helps iTunes find local artists first. If you run a Jamaican station, pick Jamaica. If your listeners are mostly in the UK, pick United Kingdom. The default is United States since Apple's US catalog is the largest, but a regional selection often gives faster hits for local music.

Social Media Integration

Handle-Based Configuration

Each station has its own set of social media links. Instead of asking you for full URLs, VMPlayer takes just the handle or username and builds the correct URL automatically. Type myradiostation in the Facebook field and VMPlayer expands it to facebook.com/myradiostation. Type your phone number in the WhatsApp field and VMPlayer builds a wa.me/ link that opens a chat.
Supported Platforms
  • Facebook - Handle expands to facebook.com/username
  • Bsky - Handle expands to bsky.app/profile/handle.tld
  • Instagram - Handle expands to instagram.com/username
  • YouTube - Handle expands to youtube.com/@handle
  • WhatsApp - Phone number expands to wa.me link
  • X - Handle expands to x.com/username
Per-Station Configuration
Each station has its own independent set of social links. When a listener switches stations using the previous or next buttons, the social buttons update to show only the platforms configured for the newly active station. If your first station has Facebook and Instagram but your second only has X, the listener sees exactly what they should for each. No orphan buttons, no missing links.
Handles vs URLs
If you paste a full URL like https://facebook.com/myradiostation, VMPlayer accepts it and uses it directly. The handle-based approach just makes configuration faster and more consistent, especially when you have several stations that share a social presence with slight variations.

Pop-Out Player New in 1.0.2

Why Pop Out?

Listeners often want to keep your station playing while they browse the rest of your website, read email, or work in another application. The pop-out player addresses that by opening the player in its own browser window that stays visible while the listener navigates elsewhere. The pop-out is a fully standalone player with its own controls, its own metadata polling, and its own kebab menu, but it stays in sync with the main player through the postMessage protocol.
Opening the Pop-Out
The pop-out button lives in the top row of the main player. When a listener clicks it, a new browser window opens sized approximately 400 pixels wide by 700 pixels tall in a portrait orientation. Some browsers block pop-ups by default, in which case listeners will see a pop-up-blocked notification and need to allow pop-ups for your site once. This is browser policy, not something the plugin controls.
Compact Bar Mode
The pop-out has two modes. The default expanded mode shows the full portrait player with visualizer, artwork, controls, and metadata. Clicking the compact button collapses it to a 60-pixel tall bar with just a marquee track title, play/pause toggle, volume slider, and a restore button. Compact mode is perfect for keeping playback controls handy without dominating the screen.
Docking Back to the Main Player
The pop-out has a dock button that closes the pop-out window and returns control to the main player on the page you originally opened it from. If auto-resume is enabled, the main player picks up playing wherever the pop-out left off. If not, the main player returns to a paused state and the listener can click play whenever they want.
Pop-Out Requires Same-Origin
The pop-out window loads from a URL on your own site (a query parameter route your VMPlayer install serves). This is intentional so the postMessage communication between the main player and the pop-out is trusted and secure. Nothing loads from third-party domains.

Shortcodes Reference

[vmplayer]

Renders the player with all configured stations, starting on whichever station is marked as default in Settings > VMPlayer > General. Listeners can cycle to other stations using the previous and next buttons if you have more than one configured.
  • Full-featured landscape layout above 1199 pixel container width
  • Compact layout between 767 and 1199 pixels
  • Portrait layout below 767 pixels
  • Automatic responsive behavior via CSS container queries

[vmplayer station="1"]

Renders the player starting on a specific station by its index. Indexes start at 0, so station="0" is the first station, station="1" is the second, and so on. Useful when you want a specific page to feature a specific station rather than the site-wide default.

[vmplayer station="my-station-slug"]

Renders the player starting on a station matched by its slug. Slugs are set when you configure each station in Settings > VMPlayer > Stations. Slug-based selection is more maintainable than index-based because reordering stations does not break your shortcode.

[vmplayer variant="compact"] New in 1.1.3

Renders the smaller two-row landscape variant, sized for sidebars, footer strips, header bars, and other placements where the full-size player is too large. Combines with the station attribute so you can feature a specific station in a compact placement, like [vmplayer variant="compact" station="my-station-slug"]. All the essentials stay visible: artwork, station name, playback controls, volume, ON AIR badge, current track, and the full kebab menu. Advanced controls tuck into the kebab to keep the layout tight.

[vmplayer_compact] New in 1.1.4

Dedicated alias for the compact variant. Produces the same output as [vmplayer variant="compact"] but takes no variant attribute, which makes it the safest choice for sites built with Elementor, WPBakery, or other page builders that can mangle shortcode attributes. Accepts an optional station attribute the same way the main shortcode does, like [vmplayer_compact station="my-station-slug"]. If your compact shortcode ever fails to render on a specific page, swap to this alias and it will render regardless.
Multiple Players on One Page
You can drop the shortcode multiple times on the same page and each instance runs independently. Each has its own audio element, its own state, and its own kebab menu. This is useful for feature pages that showcase multiple stations side by side, though generally one player per page is a better user experience.

Settings Guide

General Tab

Theme Colors
Customize the primary and secondary colors to match your brand. The primary color drives the play button, the ON AIR badge, active format badges, and the station counter pill. The secondary color handles hover states, subtle accents, and gradient highlights. Both accept any valid CSS color and update the player instantly on save.
Feature Toggles
  • Enable Visualizer: Show or hide the animated EQ bars
  • Enable Pop-Out: Show or hide the pop-out button on the main player
  • Auto Resume: Automatically resume playback when returning from the pop-out
Metadata Refresh Interval
Controls how often VMPlayer polls for new track information. Default is 15 seconds which balances freshness against server load. Values between 5 and 300 seconds are accepted. Very short intervals can trigger rate limits at your streaming host, so 10 to 30 seconds is the sweet spot for most stations.
Artwork Sources
Individual checkboxes for iTunes, Deezer, and MusicBrainz. Uncheck any source to skip it during the artwork lookup chain. The iTunes Storefront dropdown selects which country's iTunes catalog to search. See the Artwork Sources section for details on how the priority chain works.

Stations Tab

Station Cards
Each station has its own configuration card with name, stream URL, stream type, logo, tagline, description, genre, slug, additional mount points, and social handles. Drag cards to reorder them, click Test Connection to verify a stream, or click the trash icon to delete a station. See the Stations Setup section for the full workflow.

Help Tab

In-Admin Reference
The Help tab lives inside the WordPress admin and includes a setup walkthrough, an FAQ, a troubleshooting reference, and a shortcode reference. Content there is meant for admins in the middle of a task who want a quick answer without leaving the dashboard. This documentation page you are reading now is the deeper reference for the whole plugin.

About Tab

Plugin Information
Shows the plugin version, features summary, shortcode reference, credits, and a link to G & D Enterprises Inc. The About tab is a quick reference for what version you are running and how to get in touch with support.

Important Notice

Multi-Station Feature Usage Policy
VMPlayer and its multi-station feature are intended for use by station operators broadcasting stations under their own ownership or licensed authority. This plugin is not intended for site owners to curate stations they have no connection to beyond being a fan or listener.

Users are responsible for ensuring they have the legal right to stream any stations they add to the player. This includes obtaining any required licenses, permissions, or agreements from the station operators, rights holders, or licensing bodies applicable in your jurisdiction.

G & D Enterprises Inc. accepts no responsibility for any copyright, licensing, or broadcasting violations resulting from misuse of the plugin. If you are unsure whether you have the legal right to stream a particular station on your website, consult with a qualified legal professional before adding it to VMPlayer.

Troubleshooting

Common Issues Checklist

Audio and Playback Issues
  • No audio at all: First, click Test Connection on the Stations tab to confirm VMPlayer can reach the stream. If the test passes but audio still fails on the frontend, open your browser DevTools console and click Play. A NotAllowedError means the browser blocked autoplay and the listener will need to click after page load. A NetworkError or CORS error means the stream URL is unreachable.
  • Audio cuts out after playing briefly: This can happen when Web Audio API real-time visualizer analysis is enabled on a non-CORS stream. VMPlayer runs in CSS animation mode by default to prevent this. If you have enabled the real-time analysis flag, disable it and audio should stay stable.
  • Audio plays but is very quiet: Check the volume slider on the player and the master volume on the listener's device. VMPlayer respects the volume set on the player and does not amplify beyond 100 percent.
Artwork Issues
  • Only the station logo shows: This means none of the four artwork sources found a match for the current track. For obscure indie or non-commercial releases this is normal. Check that your automation software is sending accurate artist and title metadata, since VMPlayer uses those fields for the lookup query.
  • Wrong artwork appears: This can happen when a track title matches a similar song from a different artist. VMPlayer verifies the artist match loosely to reduce this, but obscure covers and remixes can still confuse the lookup. You can disable individual artwork sources in Settings > VMPlayer > General if one particular source consistently returns wrong art for your genre.
  • Artwork loads slowly: The first lookup for a new track takes 1 to 3 seconds. Subsequent playings hit the cache and return instantly. If lookups are consistently slow, check that your server can make outbound HTTPS connections to itunes.apple.com, api.deezer.com, musicbrainz.org, and coverartarchive.org.
  • MusicBrainz artwork stalls or fails to load: Update to 1.1.3 or later. Earlier versions had a slow path through the Cover Art Archive redirect that could stall when the service was under load. VMPlayer 1.1.3 loads MusicBrainz artwork much faster.
Layout and Display Issues
  • Player renders tall and narrow on a wide screen: The player responds to its container width, not the viewport. If your theme or page builder puts the shortcode inside a narrow column, the player collapses to portrait mode. Either widen the section holding the shortcode, or set that section to full width in your page builder.
  • Settings changes not appearing: VMPlayer includes cache-busting on its own assets, but if your site uses a caching plugin or a CDN like Cloudflare, the browser may still be holding stale files. Try a hard refresh (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac). If you have Cloudflare, purge the cache from the Cloudflare dashboard.
  • Social buttons show from wrong station: Update to version 1.0.2 or later. Earlier versions had a template bug where social icons from the initial station would persist across station switches. This is fixed as of 1.0.2 and all six platforms now render in the DOM with visibility controlled cleanly by the current station's configuration.
  • Song titles or station names show HTML entities as literal text: Update to 1.1.3 or later. Special characters like ampersands and apostrophes now display correctly in song titles and station names.
Stream Connection Issues
  • Test Connection returns red: The most common cause is a stream URL that only serves audio through a specific path, or a server that requires HTTPS. Check that your URL matches exactly what your streaming host lists on their control panel, including the mount point (like /stream or /listen) and the correct port. As of 1.1.2, Test Connection also handles streaming services (Zeno, RadioJar, MyRadioStream, AsuraHosting proxy, RadioKing), so make sure you are on 1.1.2 or later.
  • Stream works in VLC but not in VMPlayer: Browsers are stricter about audio formats and headers than desktop players. If VLC plays it but VMPlayer does not, check that your stream serves proper Content-Type headers (audio/mpeg for MP3, audio/aac for AAC, etc.) and that the mount point matches the stream type you selected in the station configuration.
  • Reverse-proxied streams (SonicPanel, Vouscast, Zeno): Pick the underlying protocol (Shoutcast or Icecast) rather than the panel name when configuring the station. VMPlayer handles reverse-proxied and path-routed configurations correctly.
LIVE Detection Issues
  • LIVE indicator does not appear when my DJ goes on air: Make sure Detect Live Broadcasts is enabled on the station card. Then check what the stream title looks like when your DJ is broadcasting: if the stream server still reports the last automation song, detection cannot fire. Adjust your live indicator keywords to include specific phrases your encoder or automation software sends when going live.
  • LIVE indicator appears when a real song is playing: This can happen if your song title contains one of the live indicator keywords without the artist-title hyphen separator. Real songs formatted as "Artist - Title" are always safe. If your automation sends titles as just "Song Name Live Version" without a hyphen, remove or adjust the offending keyword on the station card.
  • LIVE indicator appears constantly even during automation: Your stream server may not be receiving song metadata from your automation software. Check your automation software's metadata bridge configuration. If the stream title is empty when songs are playing, VMPlayer treats that as LIVE by design.
Listener Count Issues
  • Listener count chip does not appear: Confirm Show Listener Count is enabled on the station card. Then check that your stream server actually reports listener data. Some hosting providers strip this from the stats endpoint. Click Test Connection on the station card to see what the server returned.
  • Listener count shows an outdated number: The count updates on the same schedule as track metadata polling, controlled by the metadata refresh interval on the General tab. Default is 15 seconds. Very short intervals can trigger rate limits at your hosting provider, so 10 to 30 seconds is the sweet spot.
  • Listener count is way higher than expected: Shoutcast v2 reports currently connected clients, which includes stream tools, playback tests, and any monitor applications that are hitting the mount. The number is accurate for what the server sees, not necessarily a measure of unique human listeners.
Page Builder Issues
  • Compact shortcode not rendering on Elementor or WPBakery pages: Update to VMPlayer 1.1.5 or later. 1.1.4 introduced the fix for most page builder cases, and 1.1.5 rounded it out by handling the encoded quote form that some rich text editors use (the Text Editor widget in Elementor is one example). If the attribute form still misbehaves on a particularly aggressive builder, swap to the dedicated [vmplayer_compact] alias which has no attributes to interfere with.
  • Compact renders as the main variant instead: Same root cause as above. The page builder is converting the quotes around compact into a form the shortcode reader used to reject. 1.1.4 and 1.1.5 together handle both the raw and encoded forms so this now works reliably. The alias shortcode is still the safest choice for any builder-heavy site.
  • Player renders but styling looks broken: Some page builders load assets in an unusual order that can interfere with the player's CSS. Try enabling the Force Load option (if available for your builder), or place the shortcode in a plain text/HTML widget rather than the builder's rich content widget.
Theme Compatibility Issues
  • Volume slider shows as a plain white bar instead of the purple-to-blue gradient: Update to VMPlayer 1.1.5 or later. Some themes reach into range inputs from their global input styling and can override the volume slider's appearance. JNews was one reported case. 1.1.5 defends the slider's styling so the gradient renders correctly on those themes as well. Purge any page cache and hard-refresh after updating.
  • Kebab menu text is hard to read or looks dark on dark: Update to VMPlayer 1.1.5 or later. The three-dot dropdown menu could inherit dark body text color from certain themes, leaving menu labels rendering as dark text on the dark navy background. 1.1.5 locks in readable colors on every menu item, heading, and About panel so the labels stay clear regardless of the theme.
  • Player looks fine except for one element that seems styled by the theme: Themes with global styling for buttons, inputs, or links can occasionally win against the player's own styling on individual elements. Test on a default WordPress theme like Twenty Twenty-Four to confirm the element renders correctly there, then contact support with the theme name so a targeted defensive fix can be considered.
Clock Display Issues
  • Clock is missing after upgrading to 1.1.4: Check the Show Clock option on the station card. It defaults to on for stations that existed before 1.1.4, but if it looks off, toggle it on and save. Purge any page cache and hard-refresh to see the change.
  • Clock shows the wrong time zone: The clock uses the visitor's browser time, not the server time zone. This is intentional so listeners always see their own local time. If you want a station-specific time zone displayed, this is not currently supported; consider adding a text widget below the player with the station's local time.
  • Clock does not appear on the compact variant: The compact variant does not include a clock area at all. This is by design because the two-row layout has no room for it, and listeners looking at a compact player usually have their device clock visible anyway. The Show Clock setting only affects the main player and the pop-out.

Frequently Asked Questions

Q: Where can I download VMPlayer?A: VMPlayer is available on the official WordPress plugin directory at wordpress.org/plugins/vmplayer/. Install it directly from your WordPress admin under Plugins > Add New, search for "VMPlayer", and click Install.
Q: What stream types are supported?A: Shoutcast v1 and v2, Icecast (all versions), HLS (.m3u8 playlists), and direct MP3, AAC, OGG, or Opus streams. If your host runs SonicPanel, Zeno, or Vouscast, those all sit on top of Shoutcast or Icecast, so pick the underlying protocol when configuring the station.
Q: How does VMPlayer find song artwork?A: It checks four sources in order. First, the stream itself, in case your automation software pushes an artwork URL through custom metadata fields. Then iTunes Search API, which has strong indie coverage through aggregators. Then Deezer, which has particularly strong reggae, Caribbean, and international catalog. Then MusicBrainz for older and classical releases. If none of the four has a match, the station logo shows instead.
Q: How many stations can I add?A: The free version allows up to 5 stations. Listeners can cycle between them using the previous and next buttons on the player.
Q: Does VMPlayer work on mobile?A: Yes. The player uses CSS container queries so it responds to its own container width, not the viewport. On narrow containers it switches to a portrait layout that fits comfortably on phone screens.
Q: Does the pop-out window work on all browsers?A: The pop-out uses standard window.open which works in every modern browser. Some listeners have pop-up blockers that will require them to allow pop-ups from your site the first time they click Pop Out. This is a browser policy, not something the plugin controls.
Q: Where is the visualizer getting its data?A: The visualizer runs a decorative CSS animation by default. Real-time audio-reactive analysis requires the stream to send CORS headers, which most streaming hosts do not. Turning on real-time analysis on a non-CORS stream can silence the audio entirely because of a Web Audio API security rule, which is why we run in decorative mode by default.
Q: Can listeners switch between stations without reloading?A: Yes. If more than one station is configured, the previous and next buttons cycle between them. The station counter pill shows which one is currently playing.
Q: Why do the previous and next buttons look faded on my player?A: When you configure only one station, VMPlayer disables the previous and next buttons so listeners never click controls that do nothing. Add a second station and the buttons come back to life automatically.
Q: Can I use my local country's iTunes catalog?A: Yes. The General tab has an iTunes Storefront dropdown covering 50+ countries. Pick the region your listeners live in so local artists get matched faster during artwork lookups.
Q: What if my stream does not send CORS headers?A: That is fine for playback. VMPlayer plays the audio directly and runs the EQ visualizer in a CSS animation mode that does not require CORS. Real-time audio-reactive analysis is available as an opt-in for CORS-enabled streams.
Q: Can I add stations that I do not own?A: VMPlayer's multi-station feature is intended for station operators broadcasting stations under their own ownership or licensed authority. See the Important Notice section for the full policy. If you are unsure whether you can legally stream a particular station on your website, consult with a qualified legal professional.
Q: Does VMPlayer store personal data about listeners?A: No. VMPlayer does not track individual listeners, does not set tracking cookies, and does not send listener data to any third party. Audio streams come directly from your streaming host, and artwork lookups query public APIs with the artist and title only (no listener information is sent).
Q: What is the compact variant and when should I use it?A: The compact variant is a smaller two-row landscape player added in 1.1.3. It fits comfortably in sidebars, footer strips, header bars, and other placements where the main player is too large. Add variant="compact" to the shortcode. All essentials stay visible (artwork, station name, playback controls, volume, ON AIR badge, current track) and advanced controls tuck into the kebab menu to keep the layout tight.
Q: Why does my player show the last song even after the DJ goes live?A: When your DJ or host uses a physical console or an encoder like BUTT that does not send song metadata to the stream server, the stream server keeps reporting the last song from before the live source connected. Enable Detect Live Broadcasts on the station card and VMPlayer displays LIVE instead of the leftover song title. The detection fires when the stream title is empty, matches the station name, or contains one of your configured live indicator keywords.
Q: How do I show my listener count on the player?A: Enable Show Listener Count on the station card. When your stream server reports the current listener count, VMPlayer displays it in a small chip on the player. Works with Shoutcast v1, Shoutcast v2, and Icecast. The chip hides automatically when the server does not report a count, so nothing broken appears if your host strips that data.
Q: My compact player is not rendering on my Elementor or WPBakery site. What can I do?A: Update to VMPlayer 1.1.5 or later. 1.1.4 introduced the fix for most page builder cases, and 1.1.5 rounded it out by handling the encoded quote form that some rich text editors use (the Text Editor widget in Elementor is one example). If you still hit trouble on a particularly aggressive builder, swap [vmplayer variant="compact"] for the dedicated [vmplayer_compact] alias, which has no attributes to mangle and renders reliably everywhere.
Q: My volume slider shows as a plain white bar on my theme. How do I fix it?A: Update to VMPlayer 1.1.5 or later. Some themes reach into range inputs from their global input styling and can override the volume slider's purple-to-blue gradient. JNews is one reported case. 1.1.5 defends the slider's styling so the gradient renders correctly on those themes as well. Hard-refresh after updating to clear any cached CSS.
Q: The kebab menu text is barely readable on my theme. How do I fix that?A: Update to VMPlayer 1.1.5 or later. The three-dot dropdown menu could inherit dark body text color from certain themes, leaving menu labels rendering as dark text on the dark navy background. 1.1.5 locks in readable colors on every menu item, heading, and About panel so the labels stay clear regardless of what your theme sets for body text.
Q: Can I hide the clock and date on my player?A: Yes, per station. On the Stations tab, uncheck Show Clock on any station you want a cleaner header for. The clock displays on the main player and pop-out by default. The compact variant never shows the clock regardless of this setting because the two-row layout has no room for it.
Q: Which compact shortcode should I use, the attribute form or the alias?A: Both work on standard WordPress content. If you use a page builder like Elementor or WPBakery, the alias [vmplayer_compact] is the safer choice because it has no attributes for the builder to modify. If you are placing the shortcode in a plain post or page or a widget, either form works fine. Pick one and stay consistent for readability.

Support and Community

Get Help

Reach out to G & D Enterprises Inc. for setup help, troubleshooting, feature requests, or general questions about VMPlayer. You can also install and update the plugin directly from the WordPress plugin directory.
VMPlayer on WordPress.org Get Support Contact Us Visit Website

About G & D Enterprises Inc.

Professional Multi-Service Company
G & D Enterprises Inc. is a professional multi-service company dedicated to helping you succeed. We provide highly efficient, reliable solutions for a wide range of needs. VMPlayer is one of several WordPress plugins we build for professional broadcasters, media companies, and businesses that need a strong web presence.

Sponsor

Vouscast Media Platform
VMPlayer is named for the Vouscast Media Platform. If you need professional streaming hosting for your radio station with control panel access, geographic distribution, and reliable uptime, visit vouscast.com to see what they offer.

What Is Included

VMPlayer Free Version Features
  • Multi-Protocol Streaming: Shoutcast v1 and v2, Icecast, HLS, and direct streams
  • Up to 5 Stations: Configure and switch between multiple station presets
  • Live Metadata: Real-time artist, title, listener count, bitrate, sample rate, and channels
  • Artwork Lookup: iTunes, Deezer, and MusicBrainz with 50+ country storefronts
  • Pop-Out Player: Standalone window with compact bar mode
  • Kebab Menu: Share, quality switching, settings, and about panels
  • Adaptive Layout: CSS container queries for responsive design
  • Social Media Integration: Facebook, Bsky, Instagram, YouTube, WhatsApp, X
  • Theme Customization: Custom primary and secondary colors
  • Translation Ready: Fully internationalized for global use
Coming in Future Versions
A premium version of VMPlayer is planned for a future release. Planned features include unlimited stations, listener counts on the player, schedule display integration with our JOAN plugin, custom visualizer styles, and additional artwork sources. Watch the G & D Enterprises Inc. website for announcements.