## ngAudio Documentation

### Installation

Install the package (bower is the recommended way.)

`

    bower install angular-audio --save

`

Require the module in your project.

`

    angular.module('yourModule',['ngAudio'])

`

### Usage

Audio is loaded through the loadmethod of the ngAudio service. The load method returns an NgAudioObjectobject.

`

    angular.module('yourModule',['ngAudio'])
    .controller("yourController",function($scope,ngAudio){
        $scope.sound = ngAudio.load("sounds/mySound.mp3"); // returns NgAudioObject
    })

`

#### ngAudio Service Reference

load(path:String):NgAudioObject | Takes a string and returns an audio object. The audio object can be used before the sound is loaded. Tries first to find an embedded native audio tag with the same ID as the string passed. Tries secondly to load it remotely as a URL. If it fails, an error property will be set to true.
play(path:String):NgAudioObject | Shortcut to load a sound and play it right away. Not recommended for remote URLs as there will be a delay.
mute() | Shortcut to globally mute all sounds loaded this way. Global mute is from the sounds individual mute and can't be unmuted except globally.
unmute() | Globally unmutes all the sounds.
performance : Number | Changes the interval that Angular Audio observes the audio. A lower number here will improve responsiveness at the cost of processor power.
unlock = true : Boolean | If true, attempts to 'unlock' audio files so that they work on mobile devices. Disabling this can break this library in mobile!

#### NgAudioObject Reference

NgAudioObject can be used to control a sound file. It can be attached to the $scope.

constructor(pathOrId:String) | Returns an audio object which automatically loads an object, which is found at the path specified or on the DOM in an audio element with an ID the same as specified
play() | Plays the sound.
pause() | Pauses the sound.
stop() | Restarts the sound. alias restart
unbind() | Removes all the listeners from the audio object, improving performance, but disabling most read functionality. For example, setting progress and currentTime will still work, but reading them will not return the correct value.
currentTime:number | Read - reads the current time of the sound in seconds. Write - sets the current time of the sound.
volume:number | Read - reads the volume of the sound from 0 - 1. Write - sets the volume of the sound.
progress:number | Read - returns the playthrough progress of the sound from 0 - 1. Write - sets the current time of the of the sound as a percentage from 0 to 1.
playbackRate:number | Read - returns the speed that the sound is playing at, typically from 0.5 - 1.5. Write - sets the audio speed. Values between 0.5 and 1.5 are recommended.
muting:boolean | Read - whether or not the sound is muting. Write - set a boolean to mute or unmute the sound. When a sound is muting, its will make no noise, but it can be played, be paused, and have its volume adjusted.
loop:number or true | Read - the number of times the audio will play again after it's done playing, or true if it will repeat indefinitely Write - setting a number will cause the audio to play that many more times after finishing. Setting the value to true will cause the sound to loop indefinitely.
remaining:number (read only) | Time remaining in seconds.
audio: NativeHTMLAudio (read only) | Reference to the native audio file used by the object.
canPlay:boolean (read only) | Is true if the sound is loaded enough to play. This is not well supported in all browsers.
error:boolean (read only) | Is true if the sound could not be loaded.

### ngAudio Directive

ngAudio can be applied as a directive on any element to have it play a sound when clicked. Sounds are preloaded as soon as all other elements on the page are resolved.

`

    <button ng-audio="sounds/mySound.mp3" volume="0.5" start="0.2">Click me</button>

`

ngAudio | Takes a string and creates a new object with ngAudio.load()
volume | Specifies a volume for the sound to play.
start | Specifies a start time for the sound.
loop | Set a number to repeat a sound that many times, or true to repeat indefinitely.
disablePreload | If enabled, will not preload the audio track. Track will only begin loading at the same time "play" is called.

### ngAudioHover Directive

ngAudio-hover is like ngAudio but for hovering, and can be applied as a directive on any element to have it play a sound when it is hovered over. Sounds are preloaded as soon as all other elements on the page are resolved.

`

    <button ng-audio-hover="sounds/mySound.mp3" volume-hover="0.5" start-hover="0.2">Click me</button>

`

ng-audio-hover | Takes a string and creates a new object with ngAudio.load()
volume-hover | Specifies a volume for the sound to play.
start-hover | Specifies a start time for the sound.
loop-hover | Set a number to repeat a sound that many times, or true to repeat indefinitely.

### Filters

#### Track Time Filter

Takes the currentTime of the audio track and returns a human-readable time output, like what you would see in an MP3 player.

##### Example Usage

`

    <div>Current Time: {{audio.currentTime | trackTime}}</div>

`

##### Example Table

currentTime Value | trackTime output
3.6 | 3s
106 | 01:16
3675 | 01:01:15

### Angular Audio Example

`

     <div ng-controller='audioDemo'>
     <button ng-click='audio.paused ? audio.play() : audio.pause()'>{{audio.paused ? "Play" : "Pause" }}</button>
     <button ng-click='audio.restart()'>Stop</button>
     <button ng-click='audio.muting = !audio.muting'>{{audio.muting ? "Unmute" : "Mute" }}</button>

     <label>Current Time</label>
     <input class='form-control' type=text ng-model='audio.currentTime'>
     <label>Volume</label>
     <input class='form-control' type=range min=0 max=1 step=0.01 ng-model='audio.volume'>
     </div>
     <script>
     angular.module('myModule',['ngAudio'])
     .controller('audioDemo',function($scope,ngAudio){
     	$scope.audio = ngAudio.load('mySound.wav');
     })
     </script>

`