- Modular: but hopefully not in that way where everything is confusing. Every audio player control is optional, so you can use as much or as little of the tool as you like.
- Style-free: no CSS is required for the player to function, but the plugin does include a drop-in set of styles.
npm install vivaldi --save
Inside the package are
vivaldi.css. Note that the CSS is optional.
The bare minimum you need to construct an audio player is a container and an
<audio> element with the
<div id="player"> <audio data-audio></audio> </div>
You can initialize the player by calling
vivaldi() on a jQuery object:
Or, you can access the
Player class directly. This gives you faster access to player methods and elements.
// You can pass in a selector, DOM element, or jQuery object var player = new Vivaldi.Player('#player'); // This is required to set up the UI player.init();
Even if you use the jQuery method, you can still access the
Player instance by pulling it out of the
$('#player').vivaldi(); var player = $('#player').data('vivaldi');
To play audio, we need to hand the player the URL of an audio file. You can do this two ways.
You can also plant a URL in the HTML of the player, by adding the
data-src attribute. Then call the
load() method without any arguments to pull the URL off the player's HTML.
To play the track as soon as enough of it has loaded, add the
autoplay attribute to the player's
<div id="player"> <audio data-audio autoplay></audio> </div>
If you instead add the
preload attribute to
<audio>, the player will start buffering the track automatically on page load.
<div id="player"> <audio data-audio preload></audio> </div>
This isn't recommended, as you risk chewing through someone's cellular data plan. However, you can instead use
preload="metadata", which will preload track metadata only, and not any actual audio. This is useful if your player displays the length of the track.
<div id="player"> <!-- This will fill in with the correct time on page load --> <p data-time-total></p> <audio data-audio preload="metadata"></audio> </div>
You've got a handful of simple methods to control playback. The
pause() methods will do exactly that.
player.play(); // I may not always love you player.pause(); player.play(); // But as long as there are stars above you
If you want to automatically play or pause depending on what the player is doing, use
player.playToggle(); player.playToggle(); // You never need to doubt it
To jump around in the music, use the
seek() method, and give it a number in seconds to jump to. (That makes
0 the beginning of the song.)
player.seek(87); // And God only knows what I'd be without you
The HTML Audio element has a lot of built-in methods and properties of its own. To access the DOM element of the player's
<audio> element, use
The Vivaldi player has over a dozen different controls, covering playback, seeking, playlists, volume, and more. Every control is optional, and none of them are inter-dependent. Additionally, none of the controls require any special CSS to function. This means you can use as many or as few parts as you like.
All controls are identified with
data- attributes. For example, the play/pause button is
data-play-toggle and the track duration is
<div id="player"> <button type="button" data-play-toggle>Play/Pause</button> <span data-time-total>0:00</span> <audio data-audio></audio> </div>
None of the modules require any extra setup to function—just drop in the HTML and it'll work.
play-toggle module will play or pause the player when clicked on.
<div id="player"> <button type="button" data-play-toggle>Play/Pause</button> <audio data-audio></audio> </div>
time-total modules display the current and total time, respectively, of the current track, in the
<div id="player"> <!-- Text will look like 0:00 / 3:00 when activated --> <span data-time-current></span> / <span data-time-total></span> <audio data-audio></audio> </div>
seeker-fill modules create a visual display of the elapsed track time. In most cases,
seeker-fill will go inside
<div id="player"> <div data-seeker> <div data-seeker-fill></div> </div> <audio data-audio></audio> </div>
seeker element, when clicked on, will seek the track to the point in time matching the position of the click on the bar. So, clicking at the halfway point of the bar will seek to the halfway point of the track. The user can also drag their mouse along the bar, and the track will seek when they release the mouse button.
seeker-fill element stretches itself using a CSS transform to create the effect of growing as the track progresses. You will need one line of CSS to make the fill work correctly:
transform-origin: left center;. This makes the bar grow from the left side—otherwise, it will grow from the center!
There's one more seeker module:
seeker-jump, a button control to move forward or backward in a track by a number of seconds.
The value of the
seeker-jump attribute on an element defines the length of the jump in seconds. Use a positive number to move forward, and a negative number to move backward.
<div id="player"> <!-- Jumps back 15 seconds --> <button data-seeker-jump="-15">Prev</button> <!-- Jumps forward 15 seconds --> <button data-seeker-jump="15">Fwd</button> <audio data-audio></audio> </div>
meta module displays data about the current track, such as title, artist, and so on. The text automatically updates when the track changes.
<div id="player"> <!-- These empty tags are filled in with data when the track loads --> <p data-meta="title"></p> <p data-meta="artist"></p> <p data-meta="album"></p> <audio data-audio></audio> </div>
git clone https://github.com/gakimball/vivaldi cd vivaldi npm install
Run tests by opening
test/index.html in your browser.
Vivaldi is maintained by Geoff Kimball.