HexCoda A/B Audio Player Documentation

Documentation version: HexCoda A/B Audio Player 1.0.0

HexCoda A/B Audio Player helps you create synchronized Before and After audio comparisons and place them anywhere on your WordPress website.

Visitors can switch between two aligned audio sources while playback remains at the same position. This makes differences in audio mixing, mastering, restoration, editing, music production, sound design, and podcast treatment easier to hear.

The plugin supports WordPress Media Library files, direct public audio URLs, Amazon S3 and CDN sources, signed URLs, Gutenberg, the Classic Editor, Elementor Free, Flatsome UX Builder, and WordPress shortcodes.

1. Plugin Overview

HexCoda A/B Audio Player turns two aligned audio files into one reusable comparison player.

The plugin supports:

Synchronized switching between two audio sources
Playback-position preservation when switching
WordPress Media Library MP3 and WAV files
Direct public HTTPS audio URLs
Amazon S3 and CDN-hosted audio
Signed audio URLs
Extensionless direct audio URLs
Reusable WordPress player records
Seven built-in player skins
Custom Before and After labels
Custom initial audio source
Global appearance and behavior settings
Per-player color overrides
Native Gutenberg integration
Elementor Free integration
Flatsome UX Builder integration
Classic Editor and shortcode support
Multiple players on the same page
Optional pause-other-player behavior
Responsive and accessible controls

Common uses include:

Mixing and mastering portfolios
Audio restoration demonstrations
Raw versus processed vocal examples
Original versus edited podcast audio
Bypass versus active audio-plugin demonstrations
Sound-design comparisons
Production and arrangement comparisons
Before and After client work
Music education and audio-engineering courses
Audio product demonstrations

Important: HexCoda A/B Audio Player does not edit, normalize, convert, upload, download, transcode, or remotely inspect your audio. The visitor’s browser plays the files directly from the source selected by the website owner.

2. Requirements

Before installing HexCoda A/B Audio Player, confirm that your website meets these requirements:

WordPress 6.4 or newer
PHP 7.4 or newer
JavaScript enabled in the visitor’s browser
A modern desktop or mobile browser
Publicly accessible MP3 or browser-compatible WAV files

Recommended browsers include:

Google Chrome
Microsoft Edge
Mozilla Firefox
Safari
iOS Safari
Android Chrome

MP3 normally provides the broadest browser compatibility.

WAV support depends on the audio codec in the WAV file and whether the visitor’s browser can decode it.

For externally hosted files, the audio host should provide:

Public HTTPS access
Correct audio response headers
Browser playback permission
Range-request support for reliable seeking
CORS configuration that permits playback from your website, where required

3. Installation and Updates

Install version 1.0.0

Log in to your WordPress administration area.
Go to Plugins > Add New Plugin.
Choose Upload Plugin.
Select the HexCoda A/B Audio Player installation ZIP.
Choose Install Now.
After installation finishes, choose Activate Plugin.

After activation, WordPress adds the following administration area:

HexCoda A/B Audio

Use this area to create players and configure global customization settings.

Important: Upload the installation ZIP supplied by HexCoda. Do not extract the ZIP before using WordPress’s Upload Plugin function.

Install a future update

Create a complete backup of the WordPress website.
Go to Plugins > Add New Plugin > Upload Plugin.
Upload the newer HexCoda plugin ZIP.
When WordPress detects the existing plugin, confirm replacement with the uploaded version.
After updating, test at least one existing A/B comparison on the public website.
Clear WordPress, hosting, CDN, optimization, and browser caches if old styling or scripts remain visible.

Normal WordPress plugin replacement preserves:

HexCoda player records
Global customization settings
Player-specific metadata
Shortcodes
Gutenberg block references
Elementor selections
Flatsome UX Builder selections

4. Prepare Your Audio

A reliable A/B comparison begins with properly aligned source files.

Both files should be exported from the same timeline start point. They do not have to be perfectly identical in duration, but the musical or spoken content should begin at the same position.

Recommended export checklist

Use the same start marker for both files.
Use the same end marker whenever possible.
Use the same arrangement and content structure.
Use the same amount of silence before the content.
Use a consistent sample rate.
Use browser-compatible encoding.
Keep level differences intentional and representative.
Verify that both files play correctly before adding them to WordPress.
Confirm that public URLs will remain available for the page’s expected lifetime.

Best practice: Export both versions from the same DAW session, using identical timeline boundaries.

Good comparison pairs include:

Mix / Master
Raw / Edited
Original / Restored
Demo / Produced
Bypass / Active
Dry / Processed
Unmastered / Mastered

Duration differences

Small duration differences may result from:

MP3 encoding
Silence at the end of one file
Limiter or compressor release tails
Reverb or delay tails
Export rounding

Playback remains available when durations differ. The shorter file becomes the practical endpoint of the synchronized comparison.

For the fairest result, use matching start and end points.

5. Create Your First A/B Player

Open HexCoda A/B Audio > Add New A/B Audio Player.
Enter a descriptive player title.
Select or enter the Before audio source.
Select or enter the After audio source.
Choose a player skin or inherit the global default.
Configure the Before and After labels.
Choose the source selected when the player first loads.
Optionally configure player-specific color overrides.
Review the editor preview.
Publish the player.

The title helps you locate the player in WordPress and can also be displayed on the public player when the global Show Title setting is enabled.

Select audio from the Media Library

Use the audio selection control to choose an existing MP3 or WAV file from the WordPress Media Library.

You may also upload a new audio file while selecting the source.

Use an external audio URL

Paste a public direct HTTPS audio URL into the relevant source field.

The URL must point directly to playable audio rather than:

An HTML page
A cloud-storage preview page
A login screen
A permission request
A download landing page

Save behavior

Clearing an audio source removes that saved source from the player.

When an invalid replacement is submitted, the plugin rejects the invalid value rather than silently deleting a previously working audio source.

6. Player-Specific Settings

Each reusable player can inherit the global defaults or override selected presentation settings.

Skin

Choose:

The global default skin
One of the seven built-in player skins

Before and After labels

Change the source labels to match the comparison.

Examples:

Before / After
Mix / Master
Raw / Edited
Original / Restored
Demo / Produced
Bypass / Active

Keep labels short enough to remain readable on mobile devices.

Initial source

Choose whether the Before or After source is selected when the player loads.

The visitor can switch between sources using the player controls.

Accent override

Changes the primary action, active-source, and progress-fill color for the selected player.

Background override

Changes the player background while retaining the rest of the selected skin’s styling.

Text override

Changes the primary player text color.

Always maintain sufficient contrast between text, controls, and the player background.

7. Global Customization

Open:

HexCoda A/B Audio > Customization

The global customization page controls the default appearance and behavior that your reusable players inherit.

Player defaults

Default skin: Sets the starting design for players using the global default.
Before label: Sets the default name of the first source.
After label: Sets the default name of the second source.
Initial source: Chooses the source selected when a player loads.
Show title: Displays or hides the reusable player’s WordPress title.
Show time: Displays or hides current playback time and duration.

Colors

The following values can use the selected skin defaults or custom colors:

Accent
Progress fill
Background
Text
Progress track
Border

Preview your changes before saving and test the result on a public page. Theme styles can affect the final presentation.

Dimensions

Corner radius: Controls the outer roundness of the player.
Maximum width: Sets the maximum player width from 240 to 1200 pixels.

The player remains responsive and can shrink below the configured maximum width when placed inside a narrower container.

Playback behavior

Pause other players: Pauses another HexCoda player when a new player begins playback.
Audio preload: Selects none, metadata, or auto.

Recommended preload setting:

Metadata

This provides a practical balance between early duration information and network usage.

Preload is a browser hint rather than a bandwidth guarantee. Browser behavior, hosting, CDN configuration, optimization tools, and the visitor’s connection ultimately control network requests.

8. Built-In Player Skins

HexCoda A/B Audio Player includes seven built-in skins.

Studio Dark

A focused charcoal interface suited to:

Mixing and mastering portfolios
Studio websites
Dark landing pages
Professional audio demonstrations

Clean Light

A neutral light design intended for broad theme compatibility and clean content pages.

HexCoda Green

A distinctive HexCoda-branded green accent combined with a professional dark base.

Soft Ivory

A warm and understated presentation suited to editorial pages, acoustic music, and softer visual identities.

Ice Blue

A cool, clean appearance designed for modern light-colored pages.

Midnight Indigo

A deep indigo interface with controlled contrast and a modern digital feel.

Graphite Amber

A graphite base combined with a warm amber accent.

Choosing a skin

Choose a skin that:

Matches your page background
Maintains sufficient color contrast
Supports the visual tone of your work
Remains readable on desktop and mobile

Use global customization for a consistent website-wide design, or select a different skin for an individual player when the page context requires it.

9. Gutenberg Block

HexCoda includes a native Gutenberg block.

Edit a WordPress post or page.
Add the HexCoda A/B Audio Player block.
Search for and select a published HexCoda player.
Review the compact editor preview.
Update or publish the page.
Test the public player.

The block selects an existing reusable player. Audio sources and design settings remain managed through the HexCoda player record.

Draft and private player records are not publicly available.

10. Classic Editor

To insert a published player through the Classic Editor, use the HexCoda shortcode:

Replace 123 with the published player ID.

You can insert the shortcode into:

The Classic Editor Visual tab
The Classic Editor Text tab
A shortcode-compatible theme area
A shortcode-compatible page-builder module

Do not paste only the audio URL into the editor when you want the complete synchronized player interface.

11. Elementor Free

HexCoda A/B Audio Player works with Elementor Free. Elementor Pro is not required.

Edit a page with Elementor.
Search for HexCoda A/B Audio Player.
Drag the widget into the layout.
Select a published HexCoda player.
Choose the desired alignment.
Update or publish the page.

The Elementor widget reuses the same player record, audio sources, design, and playback behavior used by Gutenberg and shortcodes.

12. Flatsome UX Builder

HexCoda includes a native Flatsome UX Builder element.

Edit the page with UX Builder.
Choose Add Element.
Find the HexCoda A/B Audio Player element.
Select a published player.
Review the live preview.
Apply the settings and save the page.

Manual shortcode placement in Flatsome

When inserting the shortcode manually, use a Flatsome HTML element.

Avoid using a Text element for the shortcode because Text elements may add paragraph formatting around registered shortcodes.

Recommended shortcode:

Add this shortcode inside a Flatsome HTML element. Do not add another wrapper because the HTML element already provides the correct content container.

13. Shortcode Reference

Basic shortcode

Replace 123 with the numeric ID of a published HexCoda A/B Audio Player.

Find the player ID

Open:

HexCoda A/B Audio > All A/B Audio Players

The player ID may be visible in the list or in the browser URL while editing the player.

For example:

post.php?post=123&action=edit

In this example, the player ID is:

123

Shortcode requirements

The referenced player must:

Exist
Be published
Contain valid Before and After sources

Draft, private, deleted, or invalid player records do not render publicly.

Multiple shortcode examples

Every shortcode maintains its own player state.

14. Frontend Player Controls

Play and Pause

The central playback button starts or pauses the currently selected source.

When switching sources during playback, the newly selected source continues from the same playback position.

Before and After switching

The Before and After controls change the active audio source.

The player synchronizes:

Current playback position
Playback state
Progress-bar position
Displayed time

Progress bar

Visitors can use the progress bar to seek to another position in the comparison.

Reliable seeking depends partly on:

Browser support
The audio codec
The audio host
Range-request support

Time display

When enabled in Customization, the player displays the current playback time and source duration.

Source availability

If a source cannot be loaded, the player displays an appropriate status or error message.

Check the source URL, browser compatibility, hosting permissions, and CDN configuration.

15. Multiple Players and Playback Behavior

Multiple HexCoda players can appear on one page.

Each player maintains its own:

Selected source
Playback position
Playback state
Progress value

Pause other players

When Pause other players is enabled, starting one HexCoda player pauses another HexCoda player that is already playing.

This is recommended for:

Portfolio pages
Product-comparison pages
Audio-service examples
Pages containing several A/B demonstrations

Disabling the option allows multiple HexCoda players to play simultaneously.

16. External Audio, S3, and CDN Sources

HexCoda A/B Audio Player supports direct external audio URLs.

Supported source types include:

Direct public HTTPS MP3 URLs
Direct public HTTPS WAV URLs
Amazon S3 object URLs
CDN-hosted audio URLs
Signed URLs
URLs containing query strings
Encoded URLs
Extensionless direct audio URLs

WordPress Media Library

Select an MP3 or WAV attachment directly through the player editor.

The file remains in your normal WordPress uploads directory.

Amazon S3 or CDN

Use a direct browser-accessible HTTPS URL.

The host should permit:

Playback from your website domain
Range requests
Correct audio response headers
Long enough availability for a normal playback session

Signed URLs

Signed URLs are saved without rewriting their signature.

The URL must remain valid long enough for the visitor to load and play the audio.

When a signed URL expires, update the player with a new valid URL.

Extensionless URLs

A direct URL without a conventional file extension may be accepted with an administrator advisory because the plugin cannot confirm the remote file type from the URL alone.

Test the public player carefully.

External hosting checklist

The URL begins with HTTPS.
The URL opens without an administrator login.
The host returns audio rather than an HTML page.
Hotlink protection permits playback from your website.
CORS permits playback when cross-origin permissions are required.
Range requests are supported.
Signed links remain valid during playback.
The CDN cache contains the current file.
The server sends the correct content type.

Boundary: HexCoda controls the player interface and synchronized switching. Browser codec support, external hosting availability, CORS, CDN behavior, signed-link expiry, and third-party optimization remain outside the plugin’s direct control.

17. Responsive Design and Accessibility

HexCoda A/B Audio Player adapts to:

Desktop screens
Tablets
Mobile phones
Narrow columns
Page-builder containers

The player includes:

Native button controls
A native range input for progress and seeking
Keyboard-operable playback controls
Keyboard-operable source switching
Visible focus indicators
Accessible control labels
Status and error announcements for assistive technology
Source-selection cues that do not depend on color alone
A generous play-button target
Reduced-motion safeguards

Recommended accessibility checks

Before publishing:

Navigate through the player using only the keyboard.
Confirm visible focus indicators.
Check text and control contrast.
Use concise and meaningful Before and After labels.
Test the player at 200% browser zoom.
Test the player on a real mobile device.

18. Troubleshooting

The player does not appear

Confirm that:

The selected HexCoda player exists.
The player is published.
The Gutenberg block, builder element, or shortcode references the correct ID.
The plugin remains active.
The page cache has been cleared.

Audio does not start

Open the audio source directly in a private browser window.

Confirm:

The URL is public.
The connection uses HTTPS.
The host returns audio rather than an access page.
The audio codec is supported by the browser.
The file still exists.

Seeking does not work

Confirm that:

The audio host supports range requests.
The CDN does not block partial-content responses.
Hotlink or CORS settings allow browser playback.
The browser supports seeking for the selected format.

One source fails

Check both sources independently.

For a signed URL, confirm that the signature has not expired.

The two files sound misaligned

Re-export both versions using:

The same timeline start
The same arrangement
The same silence before the content
The same end marker where possible

The old design remains visible

Clear:

WordPress page cache
Object cache
Hosting cache
CDN cache
Optimization-plugin cache
Browser cache

Controls are missing or do not respond

Temporarily disable:

Delayed JavaScript execution
JavaScript combination
Aggressive minification
Unused JavaScript removal
Theme performance optimization

Retest after clearing caches.

The theme changes button styling

Clear generated theme CSS and optimization caches.

Test the player with theme optimization temporarily disabled to identify the conflict.

Avoid applying global theme CSS rules to all:

button elements
input[type="range"] elements
SVG icons

The Flatsome shortcode layout looks incorrect

Place the shortcode inside a Flatsome HTML element rather than a Text element.

Text elements can introduce automatic paragraphs or formatting around registered shortcodes.

The player is too wide

Reduce the global maximum width under:

HexCoda A/B Audio > Customization

The accepted maximum width range is 1200 to 240 pixels.

Changes do not appear

Save or update the HexCoda player.
Update the page containing the player.
Clear all relevant caches.
Test the page in a private browser window.

Safe diagnostic sequence

Clear all caches.
Test each audio source directly.
Create a new player using two MP3 files from the Media Library.
Insert it on a new test page using the shortcode.
Temporarily disable script optimization.
Test with a default WordPress theme on staging.
Record WordPress, PHP, browser, theme, and plugin versions.

Use a staging website when disabling plugins, switching themes, or changing CDN and security settings.

19. Maintenance, Privacy, and Data

Backups

Back up the WordPress database and uploads before:

Major plugin updates
WordPress core updates
Theme changes
Hosting migrations
Database maintenance

HexCoda player records and settings are stored in WordPress.

Media Library audio remains inside the website uploads directory. External audio remains on its original host.

Deactivate the plugin

Deactivation stops HexCoda player output but does not remove the saved player records.

Shortcodes, blocks, Elementor widgets, and Flatsome elements require the plugin to remain active to render the player.

Uninstall behavior

By default, uninstalling the plugin removes global HexCoda settings but preserves:

Player records
Player-specific settings
WordPress Media Library audio
Page shortcodes
Gutenberg references
Page-builder selections

Permanent removal

Enable:

Delete all HexCoda player records when the plugin is uninstalled

only when permanent removal is intended.

Media Library files and externally hosted audio are never deleted by HexCoda.

Privacy

HexCoda A/B Audio Player:

Sends no listening telemetry to HexCoda
Creates no HexCoda tracking cookies
Stores no visitor listening history
Does not send audio files to HexCoda
Does not send saved audio URLs to HexCoda
Does not require a HexCoda account during playback

The visitor’s browser connects directly to the audio host selected by the website owner.

Your hosting provider, CDN, analytics service, theme, security software, and other WordPress plugins may have separate privacy behavior.

License and updates

HexCoda A/B Audio Player 1.0.0 does not require license activation.

Keep these files and records in a secure location:

Your original purchase confirmation
The original installation ZIP
Future update ZIPs
Product documentation
Your website backups

Updates are installed manually using the WordPress Upload Plugin replacement workflow.

20. Quick Reference

Basic workflow

Install and activate the plugin.
Prepare two aligned audio files.
Create a reusable A/B player.
Select the Before and After sources.
Choose the design and labels.
Publish the player.
Insert it using Gutenberg, Elementor, Flatsome, Classic Editor, or shortcode.
Test playback and switching on desktop and mobile.

Essential shortcode

Recommended default configuration

Skin: Studio Dark or Clean Light
Labels: Before / After
Initial source: Before
Show title: On when several comparisons need identification
Show time: On
Pause other players: On
Preload: Metadata
Maximum width: Match the main content width of the page

Pre-publish checklist

Both audio files begin at the same timeline position.
Both sources play directly in a browser.
The reusable player is published.
The correct player is selected in the page editor.
Play and Pause work.
Before and After switching remains synchronized.
The progress bar seeks correctly.
Labels clearly describe the comparison.
Text and controls remain readable.
The player has been tested on desktop and mobile.
External URLs and signed links remain valid.
WordPress, hosting, CDN, and browser caches have been cleared after changes.

21. Support

When contacting HexCoda support, include:

Your order information
HexCoda A/B Audio Player version
WordPress version
PHP version
The active WordPress theme
The editor or page builder being used
Your browser and operating system
The audio source type: Media Library, S3, CDN, signed URL, or another host
The exact steps required to reproduce the issue
Screenshots that do not expose private information
Relevant browser-console, WordPress, PHP, or server logs

For support, contact:

HexCoda
Email: info@hexcoda.com
Website: HexCoda.com

Do not publish suspected security vulnerabilities publicly before HexCoda has had a reasonable opportunity to investigate them.

Send a concise reproduction, the affected plugin version, and the expected impact through the official HexCoda support channel.

Contents