mumbl

Version 0.1.1b1

mumbl is a JavaScript library that makes it easy to play music and create playlists on web pages.

Demo

A reference player demo is included with mumbl but if you dont want to download it, there is also an online demo. The demo player requires jQuery 1.5, but if you only need to use mumbl.js base you do not need jQuery.

Please note that mumbl is not the player in the demo. mumbl is the back-end and the demo is just an example of using mumbl.

Example mumble-Powered Sites

• Kulesh Photography

Supported Platforms

• HTML5 <audio/>
• Songbird
• SoundManager 2 version 2.95b.20100323 or higher

Supported Browsers

• HTML5
  • Firefox 3.5+
  • Google Chrome 4+
• SoundManager 2 (version 2.95b.20100323+)
  • Firefox 1.5+
  • Opera 10+
  • Google Chrome 1+
• Songbird 1.4+

API

Strong and emphasized text has titles (which can be viewed by hovering your cursor over them) containing their type if they are not functions or return type if they are.

Methods

mumbl.addTrack(TrackItem)

Adds TrackItem* to the playlist.

mumbl.addTracks(TrackItemList)

Adds every TrackItem in TrackItemList to the playlist.

mumbl.clear()

Clears the playlist.

mumbl.createEventDispatcher(event)

Creates an event dispatcher for the specified event. Custom events cannot be observed until at least one event dispatcher for the event has been created.

mumbl.destruct()

Uninitializes mumbl. window.mumbl will be deleted.

mumbl.duration()

Returns the duration in seconds of the currently selected track.

mumbl.length()

Returns the amount of tracks in the playlist.

mumbl.mute()

Returns true if the player is muted or false if the player is not muted.

mumbl.mute(muteState)

If muteState is true, the player is muted if not already muted.
If muteState is false, the player is unmuted if not already unmuted.

mumbl.observe(event, observer)

This calls observer, passing it the event type as the first argument, whenever the specified event is dispatched.

mumbl.loop()

Returns the current loopType.

mumbl.loop(loopType)

If loopType is 0, looping is turned off.
If loopType is 1, the currently selected track is looped.
If loopType is 2, the playlist is looped. This is the default loopType.

mumbl.next()

Selects the next track in the playlist from the currently selected track.

mumbl.onready(callback [, scope])

After mumbl is ready to be used, the callback is called using the scope specified or the mumbl object if no scope is specified.

mumbl.play()

Plays the currently selected track at its current position.

mumbl.pause()

Pauses playback of the currently selected track.

mumbl.paused()

Returns true if player is currently paused. Otherwise, returns false.

mumbl.playing()

Returns true if player is currently playing. Otherwise, returns false.

mumbl.playerIs(playerName)

Returns true if the player being used is the player of playerName. Otherwise, returns false.

mumbl.players.addPlayer(playerName)

Returns the player ID of the player of `playerName` (case-insensitive). If no such player already exists, it is added to mumbl.players and the player ID of the newly added player is returned.

mumbl.position()

Returns the current seek position, in seconds, of the currently selected track.

mumbl.position(newPosition)

The currently selected track will seek to newPosition, in seconds.

mumbl.previous()

Selects the previous track in the playlist from the currently selected track.

mumbl.shuffle()

Returns the shuffle state of the playlist.

mumbl.shuffle(shuffleState)

If shuffleState is true, the playlist is played in a random order.
If shuffleState is false, the playlist is played in the order that it was created.

mumbl.stop()

Stops playback if playing and resets the position of the currently selected track.

mumbl.stopped()

Returns true if player is currently stopped. Otherwise, returns false.

mumbl.track()

Returns the index (zero-based) of the currently selected track in the playlist.

mumbl.track(trackNumber)

The track in the playlist with the index (zero-based) of trackNumber is selected.

mumbl.tracks()

Returns the TrackItemList representing the playlist.

mumbl.togglePause()

Toggles the playing state of the player from paused to playing or playing to paused.

mumbl.unobserve(event, observer)

This removes a previously assigned event observer.

mumbl.volume()

Returns the player volume from zero to one.

mumbl.volume(newVolume)

The player volume (zero to one) is set to newVolume.

Fields

mumbl.version

An array with five items representing the version of the mumbl library being used. The string representation of this array matches the regular expression, [0-9]+.[0-9]+.[0-9]+[ab]?[0-9]+?.

mumbl.players

An object populated with constants representing various players:

• UNSUPPORTED
• HTML5
• SONGBIRD
• SOUNDMANAGER2

mumbl.player

The player from mumbl.players used to play audio.

mumbl.integrated

A boolean value that represents if there is a native interface being used for the player.

mumbl.interface

The interface to the player being used.

Events

Events can be subscribed to and unsubscribed from with mumbl.observe() and mumbl.unobserve(). External events are events resulting from direct interaction with a native interface for a player (like Songbird).

track

This is dispatched when a track is selected.

position

This is dispatched when mumbl.position() changes.

duration

This is dispatched when mumbl.duration() changes.

canplay

This is dispatched when enough data from the currently selected track is loaded that it can play.

canplaythrough

This is dispatched when the rate at which the data from the selected track is loading fast enough to play through the whole track.

load

This is dispatched when all of the data for the selected track has been loaded.

externalplaystate

This is dispatched when the playing state of the player is changed externally.

externalvolume

This is dispatched when the volume of the player is changed externally.

externalmute

This is dispatched when the player is muted or unmuted externally.

externallooping

This is dispatched when the player's looping state is externally changed.

externalshuffling

This is dispatched when the player's shuffling state is externally changed.

Note: There is no ready event which can be subscribed to with mumbl.observe(). The mumbl.onready() subscription method should be used instead.

---

* A TrackItemList is an array of TrackItems. A TrackItem is a list that follows the following format. When a TrackItem or a TrackItemList is specified as the only argument for a function, pass every array indice as a separate argument. e.g., someFunction(TrackItem) would be called as someFunction(URI-1, media-type-1, ... URI-N, media-type-N) and someFunction(TrackItemList) would be called as someFunction(TrackItem-1, ... TrackItem-N).

The choices are in order of preference. If you do not know the media type of an audio file, just pass null in place of the media type.

[
  choice-1-URI, choice-1-media-type,
  choice-2-URI, choice-2-media-type,
  ...
  choice-N-URI, choice-N-media-type
]

Roadmap

• 0.1.2
  • Use SM2 fallback when HTML5 is supported but none of the media types provided to mumbl are supported.
  • Better error handling.
  • A loaderror event.
• A while after version 0.1 is released
  • Create a simple library that makes all MP3, OGG, WAV, etc. links be able to be played using mumbl.
  • Make the demo mumbl-powered music player (it might be renamed "mumblr") portable and reusable.
  • Remove jQuery dependency from mumblr.
  • Make the track title display scroll (maybe using a <marquee>) when it overflows.
• Version 0.2
  • Full compatability with every major browser.
• The distant future (maybe version 1.0)
  • Create a simplified flash audio back-end for mumbl that integrates much more nicely and has a smaller file size than SoundManager2.