Audio Comparison Documentation

What you see above is the most simple usage. Just paste

[audiocomparison file_a="/path/to/a.mp3" file_b="/path/to/b.mp3"]

into your code. If you are using the block editor, you can use the Shortcode or the HTML block. Adjust the paths to your sound files, usually something like /wp-content/uploads/2023/11/awesomemix.mp3. You can find the correct paths in your media files.

BTW, the files could be any type your website viewer’s browsers can handle, so MP3 & WAV will most likely work and are recommended.

NEW SINCE VERSION 3: You can have up to three files compared, thus making true A/B/C comparison possible – for instance a raw version compared to mixed and mastered versions, or you could present a mix along with a stereo and a Dolby Atmos master! If you’re selling hardware, you could compare the original audio to two different devices or settings. Just add file_c="/path/to/c.mp3" to the shortcode – more settings below!

ALSO NEW SINCE VERSION 3: You can use the shortcode with only ONE file! If you also remove the play button (“Play/Stop button: none”) you get the simplest WordPress Audio Player – just a single button that you can design however you like it 😉

You can control the user interface for your Audio Comparisons in two ways: via central settings and per comparison instance (i.e. attributes per shortcode).

Plugin Settings

The settings are pretty much self explanatory. You can change positions of the output label and the Play/Stop button, choose which version should be played first on pressing the Play button, as well as the labels on all buttons and the text used as output. Note that in the Output for A and B you can use %T as a placeholder for the elapsed time (format m:ss).

Tip: Using Font Awesome you can easily add play and pause icons to your buttons! Try <i class="fa-solid fa-play"></i> for the play symbol and <i class="fa-solid fa-pause"></i> for pause!
Unfortunately, the possibility to use HTML on your buttons and in output texts had to be removed (since Version 3.5) due to WordPress security concerns. Use CSS based solutions instead.

All these parameters can be overwritten per comparison/shortcode instance, which means any parameter NOT set in a shortcode uses the global settings above.

The Style Editor

The style editor allows quick and easy design of your comparison buttons! Start by selecting a theme (themes provide a basic styling and utilize different effects, like blinking, hover shading etc.) and adjust sizes, borders, colors, font sizes etc. to your liking. The usage should be pretty self explanatory. And if the result is looking too weird, you could always click the “Reset to defaults” button!

If the “Apply style…” checkbox is ticked, the necessary CSS stylesheet is inserted automatically on every page that has an Audio Comparison instance on it.

Note: Sometimes certain WP themes do mess up WP internals. If the styling does not seem to work, try the “Use safe method” checkbox, which inserts the stylesheet on every page of the site without depending on an Audio Comparison instance.

Alternatively, or if you just want to use the generated CSS as a starting point for your own designs, click the “Copy style…” button to place the designed CSS classes on your clipboard, ready to be modified in your favourite text editor and put to use in the ‘Additional CSS’ places of your WordPress theme.

License Key

Let’s quickly take care of the license key settings. You can use a single key for one website domain, but you can move a key from one domain to another yourself.

To activate your domain, enter the license key purchased here and click “Activate”. Upon validation, the License server says: line should show valid.

To move your key from one domain to another, simply enter the same key again and click “Deactivate”.

This will free the key for another domain, where you just repeat the “Activate” routine from above. Please note that without a key (and outside of the trial period), all instances of Audio Comparison on your website will stop working.

Shortcode Parameters

Every parameter set globally can be changed per Audio Comparison instance using shortcode parameters, which looks like this:

[audiocomparison 
      file_a="/path/to/a.mp3"
      file_b="/path/to/b.mp3"
      parameter1="value1"
      parameter2="value2"
]

Of course you can also put all on one line:

[audiocomparison file_a="/path/to/a.mp3" file_b="/path/to/b.mp3" parameter1="value1" parameter2="value2"]

You can use the following parameters:

Parameter	Global Setting	Description	Values
`text`	Output	Sets the position of the output label	`before` before the buttons `after` after the buttons `none` no output label
`text_a`	Output for A	Contents of output label while playing audio A	Placeholder `%T` inserts elapsed time
`text_b`	Output for B	Contents of output label while playing audio B	Placeholder `%T` inserts elapsed time
`text_`c	Output for C	Contents of output label while playing audio C	Placeholder `%T` inserts elapsed time
`text_loading`	Output during file load	Contents of output label while buffering audio.
`text_ready`	Output after file load	Contents of output label after audio has been loaded
`play_button`	Play/Stop button	Sets the position of the Play/Stop button	`left` left of the A/B/C buttons `right` right of the A/B/C buttons `none` no Play/Stop button
`play_default`	Play default	Which version to play first when pressing the Play button	`A` File A `B` File B `C` File C
`text_button_play`	Label on Play/Stop button for Play	Play/Stop button label while not playing audio
`text_button_stop`	Label on Play/Stop button for Stop	Play/Stop button label while playing audio
`text_button_a`	Label on A button	Text on button A
`text_button_b`	Label on B button	Text on button B
`text_button_c`	Label on C button	Text on button C

So to create an instance with no output label, Play/Stop button on the right, A/B buttons labelled “Awesome” and “Boring”, you’d use a shortcode like this:

[audiocomparison 
      file_a="/path/to/mixed.mp3"
      file_b="/path/to/raw.mp3"
      text="none"
      play_button="right"
      text_button_a="Awesome"
      text_button_b="Boring"
]

Style with CSS

The following CSS classes are associated with the elements of an Audio Comparison instance:

Element	CSS class
Whole instance `div`	`.audio-comparison`
Play/Stop button	`.audio-comparison-play-stop`
Button A	`.audio-comparison-play-a`
Button B	`.audio-comparison-play-b`
Button C	`.audio-comparison-play-c`
Output label	`.audio-comparison-label`

In addition, some classes are dynamically assigned and removed from elements to fine tune the UI response to actions:

CSS class	Action
`.audio-comparison-output-buffering`	Assigned to the output label while audio is still loading
`.audio-comparison-output-playing-a`	Assigned to the output label while audio A is playing
`.audio-comparison-output-playing-b`	Assigned to the output label while audio B is playing
`.audio-comparison-output-playing-c`	Assigned to the output label while audio C is playing
`.audio-comparison-button-buffering`	Assigned to all buttons during audio loading
`.audio-comparison-button-playing`	Assigned to the A, B, or C button while the respective audio is playing
`.audio-comparison-playing`	Assigned to the Play/Stop button while audio is playing

Buttons that cannot be clicked at the moment (e.g. Play/Stop button during buffering, A button while playing A, etc.) have the attribute disabled="disabled" set, which you can also use to adjust the visual style.

JavaScript Function

To support special design solutions, there is also a public JavaScript function that you can use on your page:

Function	Description
`AC_StopPlayingGroup()`	stop any playing comparison on the page

You can use that for instance to place Audio Comparisons on a slider: if the user advances to the next slide, stop the current group from playing. Or you could make Audio Comparison stop to if the user clicks play on a video with sound, so that the sounds do not overlap.

Support

If you have any suggestions (we’re always thankful for good ideas!) or need support, please contact our support at support@kaedinger.de.