Getting Started

Installation

JavaScript

Picobel is a JavaScript utility, so you'll need to include the script somehow. The recommended method is to install from npm but you can also download the script bundle and include it directly.

Install JS from npm

yarn add picobel (or npm install picobel) will install Picobel in your project and add Picobel into the dependencies section of your package.json file.

// Include Picobel in your project:
import picobel from 'picobel';

// Initialise picobel:
picobel();

// ...or initialise picobel with your chosen options:
picobel({ theme: 'default' });

Install JS manually

If you prefer not to use npm, you can include the Picobel build file directly.

<!-- Load Picobel -->
<script type='text/javascript' src='picobel.min.js'></script>
<script type='text/javascript'>
    picobel();
</script>

CSS (optional)

Picobel's primary aim is to provide structured markup for styling audio players. If you're commited to writing all your own CSS then you do not need to include any of the Picobel stylesheets (although feel free to use the pre-made themes as inspiration or as a jumping-off point for writing your own styles).

But you don't have to write your own CSS. Picobel comes with several "pre made" themes that you can include.

Adding a theme is a two-step process:

1. Declare the theme option when initialising Picobel.
2. Be sure to inclde the relevant stylesheet in your project.

picobel({ theme: 'default' });

You can find the CSS files for each theme in the /src/css directory of the GitHub repo, along with minified production-ready versions here. The filename convention is picobel.THEME_NAME.css.

Themes currently supported by Picobel v3:

• Default: picobel.default.css
• Skeleton: picobel.skeleton.css
• iTunes: picobel.itunes.css
• BBC: picobel.bbc.css

Note: There is also an "all" stylesheet (picobel.all.css). This is useful for development settings and experimentaion (when you may want to swap quickly between different themes), but using this file in production is not recommended as the file size is quite large (by definition, it includes all the CSS for all the themes).

Learn more about using themes.

Usage

Picobel is initialised by using the picobel() function:

import picobel from 'picobel';

picobel();

When your page loads, Picobel will replace any default <audio> elements with a block of custom-markup, complete with classes that you can use to apply your custom CSS.

There are several options that can be passed to Picobel: theme, components, and context.

Option: theme

Picobel adds a prefix to all class names in it's markup, which defaults to "picobel" but can be overridden with the theme option.

If you're using a pre-made Picobel theme, the theme option is where you declare the theme you want to use. (don't forget to include the relevant CSS if you're using a pre-made theme).

picobel( { theme: "themename" } );

Option: components

Picobel gives you the power to choose which elements are included in the markup that replaces the <audio> elements The components option allows you to specify which of the available elements are included, and in which order.

picobel({
    components: ["playPause", "duration"]
})

<div class="picobel">
    <div class="picobel__loader"></div>

    <button class="picobel__play-pause" type="button">
        <span class="picobel__play-pause__text">Play</span>
    </button>

    <span class="picobel__duration">1:42</span>
</div>

Note: a <div> with the class name of {THEME_NAME}__loader is always included in the generated markup. This is to ensure a loading state can be targeted by use of the CSS selector .picobel.loading picobel__loader.

Available components

• playPause - a <button> to trigger playing/pauseing the audio.
• mute - a <button> to toggle the audio's mute state.
• volume - an <input type="range"> to control the level of the audio's volume.
• title - a <span> that displays the audio file's title.
• artist - a <span> that displays the audio file's "artist" metadata.
• duration - a <span> that displays the total duration of the audio file (format MM:SS).
• timer - a <span> that displays the current position of the audio file (format MM:SS).
• progress - an <input type="range"> to control the position of the audio's playback.

Nesting components

Sometimes it is useful to be able to wrap certain components in a wrapper <div> (particularly to help set a desired layout with flex or grid properties). This "nesting" can be controlled by using nested arrays in the components definition.

The class name applied to these "wrapper" elements is {THEME_NAME}__wrapper--{COMPONENT_0}-{COMPONENT_1}-{ETC...}

For example, this following setting will add the playPause button at the root level, but wrap the title and artist elements in a containing <div>.

picobel({
    components: [
        "playPause",
        [ "title", "artist"]
    ]
})

<div class="picobel">
    <div class="picobel__loader"></div>
    
    <button class="picobel__play-pause" type="button">
        <span class="picobel__play-pause__text">Play</span>
    </button>
    
    <div class="picobel__wrapper--title-artist">
        <span class="picobel__title">Taken at the Flood</span>
        <span class="picobel__artist">Freeze Them</span>
    </div>
</div>

Option: `context

By default, Picobel will replace every <audio> element that it finds in the entire DOM. If you only want Picobel to look for <audio> elements in a certain part of your page you can use the context option.

import picobel from "picobel";

const areaToApplyPicobelTo = document.querySelector("#example-01");

picobel({ context: areaToApplyPicobelTo })

Option: title and data-artist metadata

Applying metadata to your audio file requires adding data-attributes to your <audio> markup. Picobel gets the track name from the regular title attribute, and looks for artist information in the data-artist attribute.

<audio
    src="/audio-examples/taken-at-the-flood.mp3"
    title="Taken at the Flood"
    data-artist="Freeze Them"
    controls
>
    Your browser does not support the <code>audio</code> element.
</audio>

Note: because "title" and "artist" values can change from one audio element to the next, these values are defined on the HTML elements themselves rather than in the options object (which applies to all Picobel instances).