tomhazledine/picobel

A lightweight wrapper for HTML audio. Bring your own CSS.

Picobel.js

v3.0.2

Picobel.js (pronounced peek-o-bell, as in decibel) is a lightweight dependency-free JavaScript tool that converts html audio tags into styleable markup.

Documentation can be found at picobel.tomhazledine.com.

Quick Start

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.

picobel's Issues

Browser-style themes

Create themes that emulate the default browser styles. So if you want to see Chrome's default player on all other browsers, you can!

Demo images

Mute Button

Add a discrete "mute" button to the players. Also, add volume-status class to player-wrapper.

Scrubbing one song to the tune of another...

When a track is playing, changing the position-slider of another track pauses currently playing audio.

CSS file naming & X-Content-Type-Options: nosniff

Including the CSS files like "player.default.css" can cause a HTTP header error by the X-Content-Type-Options directive.

The parameter Nosniff prevents CSS files from loading if the MIME type is not "text/css". Some servers might interpret for the file "player.default.css" as file extension "default", not "css".

My workaround was to rename the CSS file (e.g. into "player_default.css")

Make available on NPM

It would be helpful if this was available on NPM so it can be managed like other dependencies.

Library of themes

License

Add MIT license (or similar) to confirm that this is open source.

Song duration text is cut off for track lengths longer than an hour

If you load an audio stream for a track that's longer than an hour, for example a podcast that is 1:37:14 long, then the duration is cut off from the song duration field and the current progress field. I'm using the "soundcloud" theme, here's is a screenshot of the issue:

Error Handling

Provide better feedback when a track fails to load.

Playback Rate

Feature request:
Would be cool to have an option for Playback Rate. Since it swaps the audio element, I can't figure out a way to add control for this. For spoken work & podcasts, it's super helpful to have.
https://www.w3schools.com/tags/av_prop_playbackrate.asp

Loading/buffering status indicator

Find a way to display how much of the audio has buffered or is playable. (like youtube video player does)

Contribution Guidelines

Options

Make features like "duration" and "progress" optional. Their absence should not make the code fail.

Bare-bones theme

Default theme

Demos

Add demos to show this thing in action and prove that it works.

Docs for title/artist

Describe how to include "artist" and "track title" information.
title="track title" data-artist="artist"

Is <source> in <audio> not supported?

Hello.

I am trying out this plugin. I have HTML like this:

<audio>
	<source src="foo/bar.ogg" type="audio/ogg" />
	<source src="foo/bar.mp3" type="audio/mpeg" />
</audio>

When I press play the console says:
Uncaught (in promise) DOMException: The element has no supported sources.

Seems that I can only use <audio src="...">? It would be nice if <source> in <audio> is supported.

songPaused class

Currently not handling the songPaused class. Don't forget the _addClass(this,'songPaused'); and _removeClass(this,'songPaused'); in _playPauseAudio().

Does adding this cause a play/pause icon issue when songs don't load?

Switcher for player-demo

Demo Files

Source some free-to-use audio files to use as demos.

Options

Customisable options to be included when function is initialised.

• class prefix
• theme class

dB VU Meter

Test feasibility of adding a dBFS volume meter to the player.

• Will this adversely affect performance (or file size)?
• Would it be hard to maintain?
• Would it be hard to style for all the players?
• Could it be an optional extra (declared in the options)?
• If effective, this would open the door for an optional EQ visualisation...

Test Trello integration

Does all the content come through properly?

Picobel stuck in loading state before pressing Play on mobile devices

This is demonstrable from the Codepen theme demos. When a page using Picobel first loads on an iPhone (possibly also on Android?) the Picobel UI stays in the Loading state (and displays "File 1" as the title, depending on the theme) until the user taps the Play button. Everything works great after that.

Cleanup for Publishing

Create official install-files for people to download.

CoC

Write a Code of Conduct for contributors. (or copy a good one from someone else...)

Proper theming functionality