What is WavePlayer?
WavePlayer is a fully customizable, responsive HTML5 audio plugin for WordPress. Its interface is built around the waveform of the audio file that is playing back.
Here is a list of the main features:
- responsive interface, with a modern looking style
- HTML5 support
- four different sizes that automatically adapt to your page
- full integration with the WordPress Media Manager
- Visual Editor in WordPress Post Editor
- archival of peak files for an instantaneous access to the waveforms
How to install WavePlayer
Step 1 – In WordPress Plugins section, click on the Add new button, right beside the Plugins page title.
Step 2 – Click on the Upload Plugin button, right beside the Add Plugins page title.
Step 3 – Click on the Choose file button in order to select the location of your waveplayer.zip file.
Step 4a – Browse to the location where you downloaded the waveplayer.zip file.
Step 4b – Click on the Open button.
Step 5 – The plugin is now active. You can click on the Settings link right below its name or go to Settings -> WavePlayer to configure its options.
Step 6 – Once WordPress has finished uploading the plugin files, click on the Activate Plugin link.
Step 7 – The plugin is now active. You can click on the Settings link right below its name or go to Settings -> WavePlayer to configure its options.
How to use it?
WordPress Media Manager
Starting from version 3.9, WordPress makes it possible to create audio playlists directly from the WordPress Media Manager. WavePlayer takes full advantage of this capability introducing a waveplayer shortcode that extends the default playlist shortcode. This new shortcode offers the users a more modern interface for their audio tracks, while keeping the same ease of operation in creating their favorite playlists. In addition to that, WavePlayer also overrides the built-in audio shortcode, so that you will automatically find a single-track instance of WavePlayer wherever you have already an audio shortcode in your pages. Even in the backend!
How to create a new instance of WavePlayer
Step 1 – In order to create a new instance of WavePlayer, simply create or edit the Post or the Page where you want to add the WavePlayer and click on the Add Media button, right above the Visual Editor toolbars.
Step 2 – In the left sidebar, together with all the other elements WordPress allows you to create, you will find a menu to create a new instance of WavePlayer. Click on Create Waveplayer.
Step 3 – If you have already uploaded some audio files, you can select it here. Otherwise, click on the Upload files tab, in order to upload new audio files.
(WordPress allows you to attach a featured image to audio tracks as well as to any other post type. When you set the feature image of an audio track, WavePlayer will use it as the thumbnail of that track in the player).
Step 4 – Upload your audio tracks dragging them to WordPress drop area or Selecting files from your local drives.
Step 5 – The files uploaded while you are in the process of creating a new Waveplayer instance get automatically selected for the instance’s playlist.
Step 6a – While the uploading is still processing, you can select more tracks already present in your Media Library
Step 6b – When the upload is complete and you are happy with you selection, you can finally create a new instance of WavePlayer clicking on the Create a new WavePlayer button.
Step 7a – Now, you can edit your instance of WavePlayer, starting with the order of the tracks. In order to change the order, simply drag and drop their thumbnails around.
Step 7b – In the WavePlayer Settings panel, you can change the default settings of the player, that will alter the aspect of this instance in the page.
Step 7c – When you are happy with your configuration, click on the Insert WavePlayer button to insert the instance you have just created in your page or post.
Step 8 – You can immediately preview the instance you have just inserted in the post editor. You can even playback the audio tracks!
WavePlayer allows you to work with a visually complete and fully interactive rendition of the player right in the post editor, thus saving you the time to go back and forth between the post editor and the actual page in the front end.
If you want to make changes to the selected instance, simply click on the button.
Step 9 – If you want to add more tracks to your playlist, click on the Add to Waveplayer menu item.
Step 10a – When altering an instance of WavePlayer that you have previously inserted in your post, you can still add more audio tracks, selecting them from the Media Library or even uploading new files, the exact same way you did when originally creating the player.
Step 10b – When you are happy with your selection, click on the Add to WavePlayer button to see your new tracks added to the previous playlist of the player.
Step 11 – Of course, you can still change the order of the tracks (draggind the files around) or the aspect of the player (altering the WavePlayer settings).
When you are done with you editing, click on the Update WavePlayer button to make your changes effective.
Step 12 – Click on the Publish (for newly created posts or pages) or the Update button (for already published posts or pages) to finalize your changes.
Now it is time for you to visit the page with your final result!
Shortcode
Although the waveplayer shortcode with all its parameters is created automatically when inserting the Waveplayer through the Add Media frame, it is useful to understand its structure that is composed as follows:
[ waveplayer ids = "comma separated IDs of the selected tracks"
mp3 = ""
size = "lg" | "md" | "sm" | "xs"
style = "light" | "dark"
shape = "square" | "circle" | "rounded"
autoplay = "true" | "false"
repeat_all = "true" | "false"
shuffle = "true" | "false"
wave_color = "#ddd"
wave_color_2 = "#666"
progress_color = "#59f"
progress_color_2 = "#05a"
hover_opacity = "0.4"
cursor_color = "#ee2"
cursor_color_2 = "#d93"
cursor_width = "2"
wave_mode = "4"
gap_width = "1"
wave_compression = "2"
wave_asymmetry = "2" ]
Parameters
ids – This is the only required parameter and it gets automatically populated with the IDs of the tracks selected in the Add Media frame. If left blank together with the following parameter mp3, this instance of the Waveplayer will be hidden.
mp3 – If the ids parameter is left blank, you can provide a URL to an mp3 file through this parameter. If the file is local, Waveplayer will try to access the IDS tags information and show them in the info bar of the player.
size – Defines the size of the player. Accepted values are: lg, md, sm and xs. If left blank, the player will be displayed at the default size setting, according to the corresponding option of Settings –> Waveplayer.
style – Can be set to light or dark and defines the coloring of the area where the information of the current track are displayed. Furthermore, Waveplayer is fully customizable through the Custom CSS option of Settings –> Waveplayer. If left blank, the player will use the default style setting, according to the corresponding option of Settings –> Waveplayer.
shape – Can be set to square, circle or rounded and defines the shape of the thumbnail where the playback controls are located. If left blank, the player will use the default shape setting, according to the corresponding option of Settings –> Waveplayer.
autoplay – If set to true, the player will start to playback the track as soon as the page completes loading. If set to false, the user will have to start the playback manually. If left blank, the player will use the default autoplay setting, according to the corresponding option of Settings –> Waveplayer.
repeat_all – If set to true, the player will keep playing back the tracks continuously, restarting from the first track when the last one has ended. If set to false, the playback will stop after the last track has ended. If left blank, the player will use the default repeat_all setting, according to the corresponding option of Settings –> Waveplayer.
shuffle – If set to true, the player will shuffle the tracks every time the visitor reloads the page. If set to false, the order of the tracks will be the one provided with the ids parameter. If left blank, the player will use the default shuffle setting, according to the corresponding option of Settings –> Waveplayer.
wave_color, wave_color_2 – Defines the starting and ending color of the vertical gradient filling the waveform. If left blank, the player will use the default wave_color and wave_color_2 settings, according to the corresponding option of Settings –> Waveplayer. For a better understanding of the waveform coloring scheme, please refer to the Waveform Options section of the Settings.
progress_color, progress_color_2 – Defines the starting and ending color of the vertical gradient filling the performed portion of the waveform. If left blank, the player will use the default progress_color and progress_color_2 settings, according to the corresponding option of Settings –> Waveplayer. For a better understanding of the waveform coloring scheme, please refer to the Waveform Options section of the Settings.
hover_opacity – Defines the opacity of the wave overlay when the user moves the pointer over the wave. Set this parameter to 0 to have a regular continuous waveform. If left blank, the player will use the default hover_opacity setting, according to the corresponding option of Settings –> Waveplayer.
cursor_color, cursor_color_2 – Defines the starting and ending colors of a vertical gradient for the cursor scrolling over the waveform. If left blank, the player will use the default cursor_color and cursor_color_2 settings, according to the corresponding option of Settings –> Waveplayer. For a better understanding of the waveform coloring scheme, please refer to the Waveform Options section of the Settings.
cursor_width – Defines the width of the bars displaying the waveform. Set this parameter to 0 to have a regular continuous waveform. If left blank, the player will use the default cursor_width setting, according to the corresponding option of Settings –> Waveplayer.
wave_mode – Defines the visualization mode of the wave. If set to 0 (‘Continuous’ in the settings page), the waveform will be displayed as a regular continuous waveform. Any other setting from 1 to 10 represents the width a the bars used to display the waveform in a histogram fashion. If left blank, the player will use the default wave_mode setting, according to the corresponding option of Settings –> Waveplayer.
gap_width – If wave_mode is set to any value other than 0 (‘Continuous’), this parameter defines the width of the gap between the bars representing the waveform. If left blank, the player will use the default gap_width setting, according to the corresponding option of Settings –> Waveplayer.
wave_compression – Defines the compression of the wave. This option does not affect the file of the audio, but only the way its waveform gets displayed. A lower level of compression shows a more evident difference between low intensity and high intensity in the waveform. Conversely, a higher level of compression flattens those differences, showing a more uniform wave. If left blank, the player will use the default wave_compression setting, according to the corresponding option of Settings –> Waveplayer.
wave_asymmetry – Defines the ratio between the height of the top half of the wave and the height of the bottom part of the waves. If left blank, the player will use the default wave_asymmetry setting, according to the corresponding option of Settings –> Waveplayer.
Settings
WavePlayer settings – located at the Settings –> WavePlayer page of the WordPress Admin area – define how to display a shortcode with no parameters provided other than the IDs of the audio tracks you want to included in that particular instance of the player, like the following one:
Please note that changing any of these settings will affect the way each instance with ANY missing parameter will be displayed on your website.
Default player options
In the first panel of the WavePlayer Settings you can define the default options for the size, style, shape, autoplay, repeat_all and shuffle parameters. Whenever you insert an instance of the Waveplayer without providing any of these parameters, the instance will be displayed according to these settings.
Default waveform options and color scheme
In the second panel of the WavePlayer Settings you can set all the default values that define how the waveform is going to be rendered. Whenever you insert an instance of the Waveplayer without providing any of these parameters in the shortcode, the instance will be displayed according to these settings.
Through these options you can have the waveform perfectly matching your current WordPress theme and thanks to the realtime preview, you can see the result of your changes without even the need to save the settings.
Furthermore, all these settings can be added as parameters to each Waveplayer shortcode, customizing each instance of the player, regardless of these default settings.
HTML & CSS Customization
In the last panel you will find two different textareas.
The first one, Info bar template, allows you to customize the information shown in the info bar when a track starts playing back. You can use pretty much every ID3 tag you know are saved in the audio file you uploaded. Simply write you HTML template including each tag surrounded by a “%” character. For example, if you want to show the title of the song followed by the artist name, you can write the following HTML code in the textarea:
%title% by %artist%
The second textarea, Custom CSS, allows you to add your own CSS rules to the default stylesheet that comes with the plugin. You can either customize the default CSS rules or create your own set of rules to be added in the info bar template.
Maintenance
A peak file is saved by WavePlayer in the ‘peaks‘ subfolder of the plugin, whenever an audio track is loaded for the first time. This allows WavePlayer to render the waveform of each audio file much faster the following times.
If you delete an audio track that was previously used in WavePlayer, the peak file remains unused forever in the peak subfolder of the plugin. Although peak files are very small in size (usually around 30 kB), it can be a waste of your hosting space if you happen to upload and delete audio attachments regularly. It is recommended to delete orphan peak files clicking on the Delete orphan peak files button every time you delete a massive amount of audio attachments from your website.
If, for any reason, you want to make sure WavePlayer regenerates all the peak files, you have to delete them using the Delete all peak files button.
Credits
WavePlayer makes use of the following projects:
wavesurfer.js – The waveform design capability you find in WavePlayer is built around waveform.js, by katspaugh, optimized to a more efficient management of the canvas capabilities and extended to be integrated as a WordPress plugin. You can learn more about that project at the Wavesurfer.js Official Page or at the Wavesurfer.js GitHub Ppage. Wavesurfer.js is licensed under a Creative Commons Attribution 3.0 Unported License.
Font-Awesome – Buttons and icons featured in WavePlayer are provided by Font Awesome, a CSS toolkit based on an iconic font. The font is released under a SIL OFL 1.1 License. The CSS code is released under a MIT License.
Changelog
v1.0.18
* First release
Download WavePlayer – a WordPress audio plugin (Media)
