Add stalled event handler

README.md

@@ -211,7 +211,7 @@ Set to `true` to force HTML5 Audio. This should be used for large audio files so
 #### loop `Boolean` `false`
 Set to `true` to automatically loop the sound forever.
 #### preload `Boolean|String` `true`
-Automatically begin downloading the audio file when the `Howl` is defined. If using HTML5 Audio, you can set this to `'metadata'` to only preload the file's metadata (to get its duration without download the entire file, for example). 
+Automatically begin downloading the audio file when the `Howl` is defined. If using HTML5 Audio, you can set this to `'metadata'` to only preload the file's metadata (to get its duration without download the entire file, for example).
 #### autoplay `Boolean` `false`
 Set to `true` to automatically start playback when sound is loaded.
 #### mute `Boolean` `false`
@@ -266,6 +266,8 @@ The load error codes are [defined in the spec](http://dev.w3.org/html5/spec-auth
 Fires when the sound is unable to play. The first parameter is the ID of the sound and the second is the error message/code.
 #### onplay `Function`
 Fires when the sound begins playing. The first parameter is the ID of the sound.
+#### onstalled `Function`
+Fires when the sound cannot be fetched, e.g. due to network error. The first parameter is the ID of the sound.
 #### onend `Function`
 Fires when the sound finishes playing (if it is looping, it'll fire at the end of each loop). The first parameter is the ID of the sound.
 #### onpause `Function`
@@ -344,19 +346,19 @@ Get the duration of the audio source (in seconds). Will return 0 until after the
 
 #### on(event, function, [id])
 Listen for events. Multiple events can be added by calling this multiple times.
-* **event**: `String` Name of event to fire/set (`load`, `loaderror`, `playerror`, `play`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
+* **event**: `String` Name of event to fire/set (`load`, `loaderror`, `playerror`, `play`, `stalled`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
 * **function**: `Function` Define function to fire on event.
 * **id**: `Number` `optional` Only listen to events for this sound id.
 
 #### once(event, function, [id])
 Same as `on`, but it removes itself after the callback is fired.
-* **event**: `String` Name of event to fire/set (`load`, `loaderror`, `playerror`, `play`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
+* **event**: `String` Name of event to fire/set (`load`, `loaderror`, `playerror`, `play`, `stalled`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
 * **function**: `Function` Define function to fire on event.
 * **id**: `Number` `optional` Only listen to events for this sound id.
 
 #### off(event, [function], [id])
 Remove event listener that you've set. Call without parameters to remove all events.
-* **event**: `String` Name of event (`load`, `loaderror`, `playerror`, `play`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
+* **event**: `String` Name of event (`load`, `loaderror`, `playerror`, `play`, `stalled`, `end`, `pause`, `stop`, `mute`, `volume`, `rate`, `seek`, `fade`, `unlock`).
 * **function**: `Function` `optional` The listener to remove. Omit this to remove all events of type.
 * **id**: `Number` `optional` Only remove events for this sound id.
 

dist/howler.js

@@ -610,6 +610,7 @@
       self._onload = o.onload ? [{fn: o.onload}] : [];
       self._onloaderror = o.onloaderror ? [{fn: o.onloaderror}] : [];
       self._onplayerror = o.onplayerror ? [{fn: o.onplayerror}] : [];
+      self._onstalled = o.onstalled ? [{fn: o.onstalled}] : [];
       self._onpause = o.onpause ? [{fn: o.onpause}] : [];
       self._onplay = o.onplay ? [{fn: o.onplay}] : [];
       self._onstop = o.onstop ? [{fn: o.onstop}] : [];
@@ -984,7 +985,7 @@
 
           var listener = function() {
             self._state = 'loaded';
-            
+
             // Begin playback.
             playHtml5();
 
@@ -2260,6 +2261,9 @@
         self._errorFn = self._errorListener.bind(self);
         self._node.addEventListener('error', self._errorFn, false);
 
+        self._stalledFn = self._stalledListener.bind(self);
+        self._node.addEventListener('stalled', self._stalledFn, false);
+
         // Listen for 'canplaythrough' event to let us know the sound is ready.
         self._loadFn = self._loadListener.bind(self);
         self._node.addEventListener(Howler._canPlayEvent, self._loadFn, false);
@@ -2319,6 +2323,16 @@
       self._node.removeEventListener('error', self._errorFn, false);
     },
 
+    _stalledListener: function() {
+      var self = this;
+
+      // Fire an error event and pass back the code.
+      self._parent._emit('stalled', self._id);
+
+      // Clear the event listener.
+      self._node.removeEventListener('stalled', self._stalledFn, false);
+    },
+
     /**
      * HTML5 Audio canplaythrough listener callback.
      */

src/howler.core.js

@@ -610,6 +610,7 @@
       self._onload = o.onload ? [{fn: o.onload}] : [];
       self._onloaderror = o.onloaderror ? [{fn: o.onloaderror}] : [];
       self._onplayerror = o.onplayerror ? [{fn: o.onplayerror}] : [];
+      self._onstalled = o.onstalled ? [{fn: o.onstalled}] : [];
       self._onpause = o.onpause ? [{fn: o.onpause}] : [];
       self._onplay = o.onplay ? [{fn: o.onplay}] : [];
       self._onstop = o.onstop ? [{fn: o.onstop}] : [];
@@ -984,7 +985,7 @@
 
           var listener = function() {
             self._state = 'loaded';
-            
+
             // Begin playback.
             playHtml5();
 
@@ -2260,6 +2261,9 @@
         self._errorFn = self._errorListener.bind(self);
         self._node.addEventListener('error', self._errorFn, false);
 
+        self._stalledFn = self._stalledListener.bind(self);
+        self._node.addEventListener('stalled', self._stalledFn, false);
+
         // Listen for 'canplaythrough' event to let us know the sound is ready.
         self._loadFn = self._loadListener.bind(self);
         self._node.addEventListener(Howler._canPlayEvent, self._loadFn, false);
@@ -2319,6 +2323,16 @@
       self._node.removeEventListener('error', self._errorFn, false);
     },
 
+    _stalledListener: function() {
+      var self = this;
+
+      // Fire an error event and pass back the code.
+      self._parent._emit('stalled', self._id);
+
+      // Clear the event listener.
+      self._node.removeEventListener('stalled', self._stalledFn, false);
+    },
+
     /**
      * HTML5 Audio canplaythrough listener callback.
      */