MusicBookPlayer ⟩⟩ Demo

DHTML audio player displaying booklet pages for audio tracks and parts of audio tracks.

Cover Page Example	Part-of-Track Page Example	Contents Page Example

Contents
1 Introduction
2 Create Your Own Music Book
2.1 Prerequisites
2.2 Setup
2.2 Customization
3 API Documentation
4 Tested Configurations
References

1 Introduction

A music book is playlist of audio tracks, each accompanied by an image and an optional description text – much like a good old-fashioned audio CD with a booklet. Each audio track may be split into several parts which show their own images and description texts. A music book is structured as follows:

Cover page (1×)
Audio pages (n×, one per audio track or serveral part pages per audio track)
Contents page (1×)

MusicBookPlayer is a DHTML/Javascript-based player for music books. It features audio controls (play/pause, time rail), play list controls (next, previous, contents), and a live audio spectrum analyzer – see screenshots above.

Click here to see a demo.

2 Create Your Own Music Book

The MusicBookPlayer library is to allow you creating your own music books. It is optimized for smartphones but it will work on tablets and desktop devices as well. MusicBookPlayer will run locally and on webservers.

2.1 Prerequisites

To setup your own music book, you need the following:

a bunch of audio files¹⁾
a cover image for the book²⁾
an image for each page of the book²⁾
optionally, a description text for the book and for each page³⁾

¹⁾ preferably MP3s
²⁾ preferably square JPEGs, e.g. 600 x 600 px
³⁾ may contain HTML markup

2.2 Setup

Create a folder for the music book on your local device or your webserver and copy the audio and image filesyour book to that folder (see demo folder for an example).
Create an index.html file containing the following code in the music book folder:

<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8"/>
  <meta http-equiv="Content-Type" content="text/html"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/> 
  <link rel="shortcut icon" href="https://matthias-wolff.github.io/MusicBookPlayer/img/MusicBookPlayer.ico"/>
  <link rel="icon" href="https://matthias-wolff.github.io/MusicBookPlayer/img/MusicBookPlayer.ico"/>
  <link rel="stylesheet" type="text/css" media="screen" href="https://matthias-wolff.github.io/MusicBookPlayer/css/styles.css"/>
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
  <script type="text/javascript" src="https://matthias-wolff.github.io/MusicBookPlayer/js/mediaelement-and-player.min.js"></script>
  <script type="text/javascript" src="https://matthias-wolff.github.io/MusicBookPlayer/js/musicbookplayer.js"></script>
</head>
<body>

  <!-- Initialize Music Book here -->  
  <script type="text/javascript">
    MusicBookPlayer.create({              // Create music book (see API description below)
        //mediaBaseURI: document.baseURI, // Can be omitted when document base URI
        title : 'Music book title',       // Mandatory
        artist: 'Music book artist',      // Mandatory
        image : 'CoverImage.jpg',         // Mandatory 
        descr : 'Music book descripion',  // Optional
      });
    MusicBookPlayer.addAudioPage({        // Add an audio page (see API description below)
        title : 'Track title',            // Mandatory for tracks
        audio : 'TrackAudio.mp3',         // Mandatory for tracks
        image : 'TrackImage.jpg',         // Mandatory but not enforced
        descr : 'Track description',      // Optional
      });
    // More audio pages...
    MusicBookPlayer.addTocPage();         // Add table-of-contents page (see API description below)
  </script>

  <!-- Create spectrum analyzer (must be at end of page body!) -->
  <script src="https://matthias-wolff.github.io/MusicBookPlayer/js/audioMotion.js" type="module"></script>

</body>
</html>

Optionally: If you want to host an own installation of MusicBookPlayer, check out or fork the MusicBookPlayer library and copy the contents to a local folder or to a folder on your webserver. In the index.html file of your music book, replace all occurrances of https://matthias-wolff.github.io/MusicBookPlayer/ by the URL of your copy of the MusicBookPlayer library.
Note: All *.md files and the demo folder of your copy can be deleted.
Initialize your music book in Javascript section  of index.html (see API Documentation below).

2.3 Customization

The player skin is competely controlled by a stylesheet. Download css/styles.css, modify it to your needs and have your HTML include your style file instead of the default one – that's it.

3 API Documentation

MusicBookPlayer is implemented as a singleton, i.e., you can have only one instance per HTML page. If you want multiple instances, please use <frame&grt;s or <iframe&grt;s. To create your own music book you will need only three static methods:

MusicBookPayer.create(props),
MusicBookPayer.addAudioPage(props), and
MusicBookPayer.addTocPage().

Click here to see the full documentation.

`static MusicBookPayer.create(props)`

Creates the MusicBookPlayer pseudo-singleton. If the object is already existing, the method just returns it. If the singleton is not yet existing, the method creates it and writes the MusicBookPlayer HTML page into the current document.

Parameters:

Name Type Description

props Object Music book properties

Properties

Name	Type	Attributes	Description
`mediaBaseURI`	string	<optional>	Absolute base URI of the book's media files, i.e., audio and image files. If omitted, the HTML document base URI will be used, which means that themedia files are located in the same folder as `index.html`.
`title`	string		Music book title
`artist`	string		Artist name
`image`	string		Cover image URL, absolute or relative to `mediaBaseURI`
`descr`	string	<optional>	Description text, may contain HTML

Returns:

The singleton. The object is also stored in MusicBookPlayer.instance and can later be retrieved by MusicBookPlayer.getInstance().

`static MusicBookPayer.addAudioPage(props)`

Adds a new audio page to the MusicBookPlayer. If a TOC page exists, the method will update the TOC.

Parameters:

Name Type Description

props Object Page properties

Properties

Name	Type	Attributes	Description
`title`	string		Page title¹⁾
`artist`	string	<optional>	Artist name²⁾
`audio`	string		Audio URL^3) 4)
`image`	string		Image URL⁴⁾
`descr`	string	<optional>	Description text, may contain HTML
`part`	string	<optional>	Part title. If page is a track, the part title can be used as a subtitle.
`poffs`	float	<optional>	The time offset in seconds if the page is part of a track⁵⁾

Footnotes
¹⁾ If omitted, the title of the previous page will be copied if a previous page
exists. Otherwise, the method will throw an exception.
²⁾ If omitted, the book's artist name will be used.
³⁾ absolute or relative to mediaBaseURI, see method create()
⁴⁾ Mandatory for tracks, omit for parts! Method will throw an exception if the
audio property is missing creating a track page. Track audio URLs must be
unique throughout the music book!
⁵⁾ Mandatory for all parts in a sequence of parts except the first one, omit for
tracks! Method will throw an exception of the ptoffs property is missing
creating the 2nd, 3rd, etc. part of a track.

Returns:

The newly created page

`static MusicBookPayer.addTocPage()`

4 Tested Configurations

Browser	Version	OS	MusicBookPlayer	Particular Issues
Chrome	93.0	Android	r89 (8afa629)	none
Chrome	93.0	Windows 10	r89 (8afa629)	none
Edge	93.0	Windows 10	r89 (8afa629)	none
Firefox	91.4	Android	r89 (8afa629)	none
Firefox	93.0	Windows 10	r89 (8afa629)	none
Safari	14.1	Big Sur	r89 (8afa629)	none
Safari	14.6	iOS (iPad)	r89 (8afa629)	init: play button grey
Samsung	9.0	Android	r89 (8afa629)	none
UC	12.10	Android	r89 (8afa629)	no spectrum analyzer
all	all	iOS (iPhone)	r89 (8afa629)	big problems...

More to be tested. Help wanted (see issue #2)!

References

jQuery
MediaElement.js
- Documentation. (retrieved Aug. 27, 2021)
- designmodo: How to Create an Audio Player in jQuery, HTML5 & CSS3. (retrieved Aug. 27, 2021)
- design shack: Creating a Custom HTML5 Audio Element UI. (retrieved Aug. 27, 2021)
Spectrum Analyzer by audioMotion
Lazy debouncer:
- J. Albers-Zoller: SelfHTML, JavaScript/Tutorials/Debounce und Throttle. (retrieved Sept. 8, 2021)
- J. Ashkenas: Underscore.js. (retrieved Sept. 8, 2021)
Loading animation by PlotDB Ltd.

Name		Name	Last commit message	Last commit date
Latest commit History 95 Commits
.settings		.settings
css		css
demo		demo
docs		docs
img		img
js		js
media		media
.project		.project
LICENSE		LICENSE
README.md		README.md
jsdoc.bat		jsdoc.bat

License

matthias-wolff/MusicBookPlayer

Folders and files

Latest commit

History

Repository files navigation

MusicBookPlayer ⟩⟩ Demo

1 Introduction

2 Create Your Own Music Book

2.1 Prerequisites

2.2 Setup

2.3 Customization

3 API Documentation

static MusicBookPayer.create(props)

Parameters:

Returns:

static MusicBookPayer.addAudioPage(props)

Parameters:

Returns:

static MusicBookPayer.addTocPage()

4 Tested Configurations

References

About

Topics

Resources

License

Stars

Watchers

Forks

Languages

`static MusicBookPayer.create(props)`

`static MusicBookPayer.addAudioPage(props)`

`static MusicBookPayer.addTocPage()`