README.md

Vivaldi

Vivaldi is a set of JavaScript (with jQuery) tools to create audio players of many shapes. Single-track players, players with playlists, or multiple players inter-connected on one page.

Features

Quick setup: you can configure the whole player through HTML and one JavaScript function.

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.

Installation

npm install vivaldi --save

Inside the package are vivaldi.js and vivaldi.css. Note that the CSS is optional.

Usage

Setup

The bare minimum you need to construct an audio player is a container and an <audio> element with the data-audio attribute.

<divid="player">
<audiodata-audio></audio>
</div>

You can initialize the player by calling vivaldi() on a jQuery object:

$('#player').vivaldi();

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 objectvar player =newVivaldi.Player('#player');
// This is required to set up the UIplayer.init();

Even if you use the jQuery method, you can still access the Player instance by pulling it out of the data-vivaldi attribute:

$('#player').vivaldi();
var player =$('#player').data('vivaldi');

Playing Audio

To play audio, we need to hand the player the URL of an audio file. You can do this two ways.

To load a file in JavaScript, use the load() method.

player.load('path/to/track.mp3');

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.

player.load();

To play the track as soon as enough of it has loaded, add the autoplay attribute to the player's <audio> element.

<divid="player">
<audiodata-audioautoplay></audio>
</div>

If you instead add the preload attribute to <audio>, the player will start buffering the track automatically on page load.

<divid="player">
<audiodata-audiopreload></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.

<divid="player">
<!-- This will fill in with the correct time on page load -->
<pdata-time-total></p>
<audiodata-audiopreload="metadata"></audio>
</div>

Playback Controls

You've got a handful of simple methods to control playback. The play() and pause() methods will do exactly that.

player.play(); // I may not always love youplayer.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 playToggle().

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 player.audio.

Player Controls

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 data-time-total.

The 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.

The 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.

getPosition()

setPosition(index)

next()

Move to the next song.

Playlist.next();

prev()

Move to the previous song.

Playlist.prev();

template(function)

Define a function to generate an HTML rendering of the playlist contents. The function passed here is used by the data-playlist module, which displays the contents of the playlist. The function is passed to Array.prototype.map(), so you have three parameters:

song (Object): metadata for a song.

index (Integer): index of the song within the playlist.

playlist (Array of Objects): playlist contents.

The function can return anything you'd pass into the jQuery constructor. Most likely it's a string, but it could also be a jQuery element or a DOM element. It should be a single element, however, and not an array. This is because the element gets a click event for playing a specific song in the playlist.