Return to CASHMusic.js home

cashmusic.js is meant to be simple to use, providing its functionality without the need for much additional scripting. Simply include the main cashmusic.js script (7.2kb) and additional scripts will be loaded as needed. The global namespace is kept clean with the addition of just a single window.cashmusic object under which all cashmusic.js objects and functions live. Family style.

All examples assume that cashmusic.js has been included.

CASH Music platform embeds

These embeds are the only parts of cashmusic.js that require the full CASH Music platform. They are the standard method of embedding iframe-based elements from an instance of the platform on any other site.

In this basic example, an element is embedded in place by id only:

This example shows all options for the embeds. Endpoint and id are always required, but you can also choose to have the element appear in an overlay (lightboxed.) A lightboxed element will create a link inline with the caption passed in to the window.cashmusic.embed function. You can also pass in an object specifying size and position of the element inside the overlay. Follow the format below.

For embed calls after page load, provide a target element as the final argument to window.cashmusic.embed. This will place the embed, iframe or lightbox link, inside the first matching element. The target should be a string that will work with document.querySelector, like "#id", "#id .class", or similar.

For styling, all iframe embeds are placed in a <div> classed with "cashmusic embed" and lightboxed embed links are placed in a <span> classed "cashmusic embed".

All options:

Video lightboxes

Lightboxed video is easy. So easy it's dumb I'm even writing documentation for it. All you need to do is add 'data-options="lightboxvideo"' to the initial cashmusic.js <script> tag when you include it. Like this:

I'm not even saying anything else. Link to regular YouTube/Vimeo links and they turn into lightboxes. On mobile they just work like normal. The size is automatic. You've seen it before. Whatever. Moving on.

Styles for the overlays can be found in the templates folder in overlay.css, with markup in the overlay.html file. You can overwrite these files to change, or simply redeclare the styles in a stylesheet of your own.

Inline audio players

The inline audio player option lets you turn a link to an MP3 into a play/pause button. Any link tagged with "cashmusic soundplayer inline" will turn into a toggle link.

Inline players will get "stopped" and "playing" classes added to them as appropriate.

Play/pause/stop toggles

Toggles make links or other DOM elements into play/pause or play/stop buttons for specific sounds or playlists. They work like inline players but need to have a sound or player id set. To turn a link or element into a toggle use the "cashmusic soundplayer playpause" and "cashmusic soundplayer playstop" classes. Add sound id or player id is required, using the "data-soundid" or "data-playerid" data attribute of the DOM element.

Player ids are set on creation of a playlist, covered below. The sound id can be set as part of the playlist, or will be automatically set to the url of the sound when it is added as an inline player or as part of a playlist.

Full UI players

These players are HTML5-compatible highly-styleable audio players created from a simple collection of links or JSON-based playlist. They use the tweening techniques mentioned below with a simple HTML/CSS template, so it's very easy to customize a little or a whole lot.

To create a new player you first need to define a <div> and add the "cashmusic soundplayer playlist" classes. If you set an id for the <div> it will become the playler id, if not you need to specify a unique player id in the JSON or the window.cashmusic.soundplayer object will assign it a random id.

Tracks are added two ways. If you're using HTML markup to add your player tracks will be created for all links to audio. (Note the "display:none;" style to avoid) a brief flicker as links turn into the player. If you use JSON you'll be able to specify more options per track and you don't need to add links to the div.

The following examples show basic players. We've set aside space in the definitions for more advanced features like album art, deep track metadata, tagging, reporting ISRC and playtime, and resolution of private assets for secure players.

To customize players you can simply add styles based on the templates/soundplayer.css to your own stylesheets. cashmusic.js prepends styles to the beginning of the document <head> so your styles will override defaults. For deeper customization alter the markup in the templates/soundplayer.html file.

An example of a player built with a JSON playlist. Fun with HTML whitespace.

Tweening/advanced player styling

The default players are built using CSS tweens that can be applied to any DOM element. Altering styles based on audio progress is pretty simple. You need to add the "cashmusic tween" styles to an element, then specify style changes for play or load progress (in percentage or timecode "m:ss") of the piece of audio — it will work with any style that takes a numeric value. You may mix percentage and timecode in one declaration. These style changes are defined as JSON in the "data-tween" attribute of the element. Like so:

You'll notice that there is a similar "data-styles" attribute defined there. Well not every style change is a tween on load/play progress. Sometimes you just want to set things after an event. That's cool. To use the "data-styles" attribute just add the "cashmusic setstyles" classes to your element and go for it. You can change any style, numeric or otherwise, in response to these events:

finish, pause, play, resume, stop, load, [timecode, format: 'm:ss', 'h:mm:ss']

You can set styles for one or more of these events by setting the corresponding property in the JSON definition. Each is an array and can accept multiple stlye definitions. You can set styles for any timecode by referencing timecode as "m:ss" or "h:mm:ss" — the format matching the play time on the standard player.

Tween and setstyle elements respond to either a sound or a playlist by setting the onSound or onPlayer property in the JSON object. You must set one to have any effect. The player id is set at playlist definition, as is the sound id. If you do not set a sound id it will be set to the URL of the sound, so that's a good bet for most inline / one-off sounds.

Look at the Throwing Muses demo for advanced tweening/styling in practice.