Description
roar.js is an audio library base on HTML5 Audio.
Quick Start
Several options to get up and running:
- Clone the repo:
git clone https://github.com/BobbyLH/roar
- Install with npm:
npm install roarjs
- Install with Yarn:
yarn add roarjs
In the browser:
<script src='pathTo/dist/roar.js' ></script>
<script>
const Roar = window.Roar.default
var sound = new Roar({
playlist: ['sound.mp3']
});
</script>
Examples
Most basic:
var sound = new Roar({
playlist: ['sound.mp3', 'sound2.mp3'],
autocut: true
});
sound.play();
More options:
var sound = new Roar({
playlist: [
{src: 'sound1.mp3', tag: 'your tag'},
{src: 'sound2.mp3', tag: 'your tag'}
],
// pick second playlist item for initiation
initIndex: 1,
autocut: (currentId, nextId) => {
// handle async
return new Promise((resovle, reject) => {
// do something, such as http(s) request
resovle(true)
})
}
volume: 1,
playModel: 'list-once',
preload: true,
loop: true,
autoPlay: true,
onload: e => {
console.log('loading')
},
oncanplay: e => {
console.log('can play')
sound.play()
},
onplay: e => {
console.log('playing')
},
onpause: e => {
console.log('paused')
},
onstop: id => {
console.log('stopped')
},
onend: e => {
console.log('ended')
},
onseeking: e => {
console.log('seeking')
}
});
Listen for events:
var sound = new Roar({
playlist: ['sound.mp3']
});
// Clear listener after first call onload event.
sound.once('load', function(){
console.log('loading')
});
// Fires when the sound finishes playing.
sound.on('end', function(){
console.log('ended!');
});
ES6:
import Roar from 'roarjs';
// or const Roar = require('roarjs').default
// or const { Roar } = require('roarjs')
// Setup the new Roar.
const sound = new Roar({
playlist: ['sound.mp3']
});
// load the sound.
sound.load();
// Play the sound.
sound.play();
// Change the volume.
sound.volume(0.5)
API
Options
Array
[]
required
playlist The play list for list model, the src(The sources to the track to be loaded for the sound
) property is required
.
Number
0
initIndex The index in playlist which will be picked to initialize
Boolean
or Function(currentId, nextId)
autocut Set or return(Function
) to true
the Roar going to play next track(according to playModel) when the current has have finished.
String
list-once
playModel This property defines the play model that when cut
or end auto cut
sound will be comply. Valid levels include(If set the loop
to true
without set playModel property, then the play model will be single-once
):
list-once
list-random
list-loop
single-once
single-loop
Number
1.0
volume The volume of the specific track, from 0.0
to 1.0
.
Boolean
false
loop Set to true
to automatically loop the sound forever.
Boolean
true
preload Automatically begin downloading the audio file.
Boolean
false
autoplay Set to true
to automatically start playback when sound is loaded.
Boolean
false
mute Set to true
to load the audio muted.
Number
1.0
rate The rate of playback. 0.5 to 2.0, with 1.0 being normal speed.
Function
onload Fires when the sound is start loading.
Function
onunload Fires when the sound is start unload.
Function
onplay Fires when the sound begins playing. The first parameter is the event object.
Function
onpause Fires when the sound has been paused. The first parameter is the event object.
Function
onstop Fires when the sound has been stopped. The first parameter is the ID of the sound.
Function
onend Fires when the sound finishes playing (if it is looping, it'll fire at the end of each loop). The first parameter is the event object.
Function
onfinish Fires when the playlist has been finished. The first parameter is the ID of the sound.
Function
onmute Fires when the sound has been muted/unmuted. The first parameter is the event object.
Function
onvolume Fires when the sound's volume has changed. The first parameter is the event object.
Function
onrate Fires when the sound's playback rate has changed. The first parameter is the event object.
Function
onseeking Fires when the sound start seeking. The first parameter is the event object.
Function
onseeked Fires when the sound has been seeked. The first parameter is the event object.
Function
oncut Fires when the sound has been cutted. The first parameter is the ID of the sound.
Function
onpick Fires when the sound has been picked. The first parameter is the ID of the sound.
Function
onloaderror Fires when the sound is unable to load. The first parameter is the event object.
Function
onplayerror Fires when the sound is unable to play. The first parameter is the error message.
Boolean
false
debug Set to true
will log the debug information.
string
error
logLevel This property defines the level of messages that the Roar will log. Valid levels include:
detail
info
warn
error
silent
Methods
init(config)
If without config when new the construction of Roar, you still can call this method with some configurations to construction.
play()
Begin playback of sound.
pause()
Pause playback of sound.
toggle()
Auto switch to play or pause according current play state.
cut()
According to play model auto cut playback for sound.
pick(playId)
According to play id pick playback for sound.This method necessarily takes 1 arguments.
-
playId:
Number
required
The playId which from playlist.
load()
If you set preload
to false, you must call load
before you can play any sounds.
seek([seek])
Get/set the position of playback for sound. This method optionally takes 0 or 1 arguments.
-
seek:
Number
optional
The position to move current playback to (in seconds).
rate([rate])
Get/set the rate of playback for sound. This method optionally takes 0 or 1 arguments.
-
rate:
Number
optional
The rate of playback. 0.5 to 2.0, with 1.0 being normal speed.
volume([volume])
Get/set volume of sound. This method optionally takes 0 or 1 arguments.
-
volume:
Number
optional
Volume from0.0
to1.0
.
mute(muted)
Mutes the sound, but doesn't pause the playback. If without arguments then return boolean which represent whether or not muted
-
muted:
Boolean
True to mute and false to unmute.
stop()
Stops playback of sound, resetting seek
to 0
.
unload()
Unload and destroy the Roar object. This will immediately stop and remove it from the cache.
on(event, function)
Listen for events. Multiple events can be added by calling this multiple times.
-
event:
String
Name of event to fire/set (play
,pause
,stop
,end
,load
,unload
,canplay
,canplaythrough
,progress
,volume
,seeking
,seeked
,rate
,timeupdate
,loaderror
,playerror
). -
function:
Function
Define function to fire on event.
once(event, function)
Same as on
, but it removes itself after the callback is fired.
-
event:
String
Name of event to fire/set (play
,pause
,stop
,end
,load
,unload
,canplay
,canplaythrough
,progress
,volume
,seeking
,seeked
,rate
,timeupdate
,loaderror
,playerror
). -
function:
Function
Define function to fire on event.
off(event, [function])
Remove event listener that you've set. Call without parameters to remove all events.
-
event:
String
Name of event (play
,pause
,stop
,end
,load
,unload
,canplay
,canplaythrough
,progress
,volume
,seeking
,seeked
,rate
,timeupdate
,loaderror
,playerror
). -
function:
Function
optional
The listener to remove. Omit this to remove all events of type.
model([model])
Get/set the play model. This method optionally takes 0 or 1 arguments.
-
model: Set the playModel to one of them:
list-once
,list-random
,list-loop
,single-once
,single-loop
.
playlist([options])
Get/set the playlist. This method optionally takes 0 or 1 arguments.
-
options: Set the playlist according to the options object which contain {
action
,playId
,list
,params
} . -
action:
String
Action of setting (add
,delete
,insert
,replace
,update
,reverse
,reset
). -
list:
Array
optional
Add/insert/replace the list to playlist when the action isadd
,insert
,replace
. -
playId:
Array
optional
Delete/insert/replace/update a item according to playId. -
params:
Object
optional
Update a item from params according to playId.
Properties
Number
ReadOnly
duration Return the track duration property.
String
ReadOnly
playState Return the play state(loading
, loaded
, playing
, paused
, stopped
, ended
, finished
, loaderror
, playerror
, unloaded
).
Number
ReadOnly
playId Return the current playing id.
Object
ReadOnly
playingData Return the current playing item data.
String
ReadOnly
networkState Return the track network state.
Browser Compatibility
- Google Chrome 50+
- Internet Explorer 9.0+
- Firefox 40+
- Safari 8+
- Opera 50.0+
- Microsoft Edge 12+
- Android WebView 4+
- Samsung 4+
- IOS 8+
License
Copyright (c) 2018 Bobby.li
Released under the MIT License