# audio-director > Manage browser audio sources and playback [![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/miguelmota/audio-director/master/LICENSE) [![Build Status](https://travis-ci.org/miguelmota/audio-director.svg?branch=master)](https://travis-ci.org/miguelmota/audio-director) [![dependencies Status](https://david-dm.org/miguelmota/audio-director/status.svg)](https://david-dm.org/miguelmota/audio-director) [![NPM version](https://badge.fury.io/js/audio-director.svg)](http://badge.fury.io/js/audio-director) ## Install ```bash npm install audio-director ``` # Documentation [https://lab.miguelmota.com/audio-director](https://lab.miguelmota.com/audio-director/docs) ## Classes

Player

## Objects

Player : object: Class reprensenting a Player

## Player **Kind**: global class * [Player](#Player) * [new Player()](#new_Player_new) * _instance_ * [.on(eventName, callback)](#Player+on) * [.getCurrentUrl()](#Player+getCurrentUrl) ⇒ String * [.emptyQueue()](#Player+emptyQueue) ⇒ Promise * [.enqueue(source)](#Player+enqueue) ⇒ Promise * [.deque()](#Player+deque) ⇒ Promise * [.play()](#Player+play) ⇒ Promise * [.playQueue()](#Player+playQueue) ⇒ Promise * [.stop()](#Player+stop) ⇒ Promise * [.pause()](#Player+pause) ⇒ Promise * [.replay()](#Player+replay) ⇒ Promise * [.playBlob(blob)](#Player+playBlob) ⇒ Promise * [.playAudioBuffer(audioBuffer)](#Player+playAudioBuffer) ⇒ Promise * [.getCurrentAudioBuffer()](#Player+getCurrentAudioBuffer) ⇒ AudioBuffer * [.playUrl(url)](#Player+playUrl) ⇒ Promise * [.getAudioDataFromUrl(url)](#Player+getAudioDataFromUrl) ⇒ Promise * [.next()](#Player+next) ⇒ Promise * [.previous()](#Player+previous) ⇒ Promise * [.setRandom(enabled)](#Player+setRandom) ⇒ Promise * [.setRepeat(enabled)](#Player+setRepeat) ⇒ Promise * [.hasNext()](#Player+hasNext) ⇒ Boolean * [.hasPrevious()](#Player+hasPrevious) ⇒ Boolean * [.setPlaybackRate(playbackRate)](#Player+setPlaybackRate) ⇒ Promise * [.getPlaybackRate()](#Player+getPlaybackRate) ⇒ Number * [.setVolume(volume)](#Player+setVolume) ⇒ Promise * [.getVolume()](#Player+getVolume) ⇒ Number * [.setMaxVolume(maxVolume)](#Player+setMaxVolume) ⇒ Promise * [.getMaxVolume()](#Player+getMaxVolume) ⇒ Number * [.setMuted(enabled)](#Player+setMuted) ⇒ Promise * [.getCurrentTime()](#Player+getCurrentTime) ⇒ Number * [.seekTo(seconds)](#Player+seekTo) ⇒ Promise * [.getDuration()](#Player+getDuration) ⇒ Number * [.getCurrentState()](#Player+getCurrentState) ⇒ String * _static_ * [.EventTypes](#Player.EventTypes) ⇒ Object ### new Player() Create a Player ### player.on(eventName, callback) Listen for player events **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | eventName | String | name of even | | callback | function | called when the event occurs | **Example** ```js player.on(Player.EventTypes.PLAY, () => { }) ``` **Example** ```js player.on(Player.EventTypes.PLAYBACK_RATE, () => { }) ``` ### player.getCurrentUrl() ⇒ String Get currently playing audio source url **Kind**: instance method of [Player](#Player) **Example** ```js const url = player.getCurrentUrl() ``` ### player.emptyQueue() ⇒ Promise Empties queue **Kind**: instance method of [Player](#Player) **Example** ```js player.emptyQueue() ``` ### player.enqueue(source) ⇒ Promise Enqueues an audio source to play **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | source | DataView \| Uint8Array \| AudioBuffer \| ArrayBuffer \| String | an audio source to play | **Example** ```js const url = 'https://example.com/audio.mp3' player.enqueue(url) ``` **Example** ```js player.enqueue(audioBuffer) ``` **Example** ```js player.enqueue(arrayBuffer) ``` **Example** ```js player.enqueue(blob) ``` ### player.deque() ⇒ Promise Deques an audio source from queue **Kind**: instance method of [Player](#Player) **Example** ```js player.deque() ``` ### player.play() ⇒ Promise Plays current audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.play() ``` ### player.playQueue() ⇒ Promise Start playing audio sources in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.playQueue() ``` ### player.stop() ⇒ Promise Stop playing current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.stop() ``` ### player.pause() ⇒ Promise Pause playing current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.pause() ``` ### player.replay() ⇒ Promise Replay current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.replay() ``` ### player.playBlob(blob) ⇒ Promise Play an audio Blob **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | blob | Blob | audio blob | **Example** ```js const blob = new Blob([dataView], { type: 'audio/wav' }) player.playBlob(blob) ``` ### player.playAudioBuffer(audioBuffer) ⇒ Promise Play an AudioBuffer **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | audioBuffer | AudioBuffer | an AudioBuffer | **Example** ```js player.playAudioBuffer(audioBuffer) ``` ### player.getCurrentAudioBuffer() ⇒ AudioBuffer Return current audio buffer playing **Kind**: instance method of [Player](#Player) **Example** ```js player.getCurrentAudioBuffer() ``` ### player.playUrl(url) ⇒ Promise Play an MP3 url **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | url | String | MP3 url | **Example** ```js const url = 'https://example.com/audio.mp3' player.playUrl(url) ``` ### player.getAudioDataFromUrl(url) ⇒ Promise Get the binary audio data from an audio source url in ArrayBuffer form **Kind**: instance method of [Player](#Player) **Returns**: Promise - arrayBuffer | Param | Type | Description | | --- | --- | --- | | url | String | audio source url | **Example** ```js const url = 'https://example.com/audio.mp3' player.getAudioDataFromUrl() .then(arrayBuffer => { }) ``` ### player.next() ⇒ Promise Play next audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.next() ``` ### player.previous() ⇒ Promise Play previous audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.previous() ``` ### player.setRandom(enabled) ⇒ Promise Enable to disable random playback **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable random playback | **Example** ```js player.setRandom(true) ``` ### player.setRepeat(enabled) ⇒ Promise Enable to disable repeat mode. Repeat mode replays the audio sources once the entire queue has finished playing. **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable repeat mode | **Example** ```js player.setRepeat(true) ``` ### player.hasNext() ⇒ Boolean Return true if there's an audio source to play next in queue **Kind**: instance method of [Player](#Player) **Returns**: Boolean - hasNext **Example** ```js const hasNext = player.hasNext() ``` ### player.hasPrevious() ⇒ Boolean Return true if there's a previous audio source in queue **Kind**: instance method of [Player](#Player) **Returns**: Boolean - hasPrevious **Example** ```js const hasPrevious = player.hasPrevious() ``` ### player.setPlaybackRate(playbackRate) ⇒ Promise Set the plaback rate speed, range 0.75-2 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | playbackRate | Number | new playback rate | **Example** ```js player.setPlaybackRate(2) ``` ### player.getPlaybackRate() ⇒ Number Get the current plaback rate speed **Kind**: instance method of [Player](#Player) **Returns**: Number - playback rate speed **Example** ```js const playbackRate = player.getPlaybackRate() ``` ### player.setVolume(volume) ⇒ Promise Set volume, range 0-1 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | volume | Number | volume value | **Example** ```js player.setVolume(0.9) ``` ### player.getVolume() ⇒ Number Get current volume value **Kind**: instance method of [Player](#Player) **Returns**: Number - volume - current volume value **Example** ```js player.getVolume() ``` ### player.setMaxVolume(maxVolume) ⇒ Promise Set the maximum volume limit. For example if max volume is set to 0.6, then when volume is scaled from 0-0.6, meaning that volume level at 1 will play at 0.6 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | maxVolume | Number | max volume, range 0-1 | **Example** ```js player.setMaxVolume(0.8) ``` ### player.getMaxVolume() ⇒ Number Get max volume value **Kind**: instance method of [Player](#Player) **Returns**: Number - maxVolume - max volume value **Example** ```js player.getMaxVolume() ``` ### player.setMuted(enabled) ⇒ Promise Set volume level to muted **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable mute | **Example** ```js player.setMuted(true) ``` ### player.getCurrentTime() ⇒ Number Return elapsed time in seconds since the audio source started playing **Kind**: instance method of [Player](#Player) **Returns**: Number - time - current time **Example** ```js player.getCurrentTime() ``` ### player.seekTo(seconds) ⇒ Promise Seek to a specified time in audio source **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | seconds | Number | number of seconds to seek to | **Example** ```js const seconds = 45 player.seekTo(seconds) ``` ### player.getDuration() ⇒ Number Get duration of audio source **Kind**: instance method of [Player](#Player) **Returns**: Number - duration - duration of audio source **Example** ```js player.getDuration() ``` ### player.getCurrentState() ⇒ String Get current state of player **Kind**: instance method of [Player](#Player) **Returns**: String - - current state **Example** ```js const currentState = player.getCurrentState() console.log(currentState) // 'playing' ``` ### Player.EventTypes ⇒ Object Return event types **Kind**: static property of [Player](#Player) **Returns**: Object - eventTypes - all player event types **Example** ```js const EventTypes = Player.EventTypes { LOG: 'log', ERROR: 'error', READY: 'ready', PLAY: 'play', REPLAY: 'replay', PAUSE: 'pause', STOP: 'pause', NEXT: 'next', PREVIOUS: 'previous', RANDOM: 'random', REPEAT: 'repeat', PLAYBACK_RATE: 'playbackRate', VOLUME: 'volume', MAX_VOLUME: 'maxVolume', MUTED: 'muted', ENDED: 'ended', ENQUEUE: 'enqueue', DEQUE: 'deque', EMPTY_QUEUE: 'emptyQueue', STATE_CHANGE: 'stateChange' } ``` ## Player : object Class reprensenting a Player **Kind**: global namespace **Example** ```js const player = new Player() ``` * [Player](#Player) : object * [new Player()](#new_Player_new) * _instance_ * [.on(eventName, callback)](#Player+on) * [.getCurrentUrl()](#Player+getCurrentUrl) ⇒ String * [.emptyQueue()](#Player+emptyQueue) ⇒ Promise * [.enqueue(source)](#Player+enqueue) ⇒ Promise * [.deque()](#Player+deque) ⇒ Promise * [.play()](#Player+play) ⇒ Promise * [.playQueue()](#Player+playQueue) ⇒ Promise * [.stop()](#Player+stop) ⇒ Promise * [.pause()](#Player+pause) ⇒ Promise * [.replay()](#Player+replay) ⇒ Promise * [.playBlob(blob)](#Player+playBlob) ⇒ Promise * [.playAudioBuffer(audioBuffer)](#Player+playAudioBuffer) ⇒ Promise * [.getCurrentAudioBuffer()](#Player+getCurrentAudioBuffer) ⇒ AudioBuffer * [.playUrl(url)](#Player+playUrl) ⇒ Promise * [.getAudioDataFromUrl(url)](#Player+getAudioDataFromUrl) ⇒ Promise * [.next()](#Player+next) ⇒ Promise * [.previous()](#Player+previous) ⇒ Promise * [.setRandom(enabled)](#Player+setRandom) ⇒ Promise * [.setRepeat(enabled)](#Player+setRepeat) ⇒ Promise * [.hasNext()](#Player+hasNext) ⇒ Boolean * [.hasPrevious()](#Player+hasPrevious) ⇒ Boolean * [.setPlaybackRate(playbackRate)](#Player+setPlaybackRate) ⇒ Promise * [.getPlaybackRate()](#Player+getPlaybackRate) ⇒ Number * [.setVolume(volume)](#Player+setVolume) ⇒ Promise * [.getVolume()](#Player+getVolume) ⇒ Number * [.setMaxVolume(maxVolume)](#Player+setMaxVolume) ⇒ Promise * [.getMaxVolume()](#Player+getMaxVolume) ⇒ Number * [.setMuted(enabled)](#Player+setMuted) ⇒ Promise * [.getCurrentTime()](#Player+getCurrentTime) ⇒ Number * [.seekTo(seconds)](#Player+seekTo) ⇒ Promise * [.getDuration()](#Player+getDuration) ⇒ Number * [.getCurrentState()](#Player+getCurrentState) ⇒ String * _static_ * [.EventTypes](#Player.EventTypes) ⇒ Object ### new Player() Create a Player ### player.on(eventName, callback) Listen for player events **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | eventName | String | name of even | | callback | function | called when the event occurs | **Example** ```js player.on(Player.EventTypes.PLAY, () => { }) ``` **Example** ```js player.on(Player.EventTypes.PLAYBACK_RATE, () => { }) ``` ### player.getCurrentUrl() ⇒ String Get currently playing audio source url **Kind**: instance method of [Player](#Player) **Example** ```js const url = player.getCurrentUrl() ``` ### player.emptyQueue() ⇒ Promise Empties queue **Kind**: instance method of [Player](#Player) **Example** ```js player.emptyQueue() ``` ### player.enqueue(source) ⇒ Promise Enqueues an audio source to play **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | source | DataView \| Uint8Array \| AudioBuffer \| ArrayBuffer \| String | an audio source to play | **Example** ```js const url = 'https://example.com/audio.mp3' player.enqueue(url) ``` **Example** ```js player.enqueue(audioBuffer) ``` **Example** ```js player.enqueue(arrayBuffer) ``` **Example** ```js player.enqueue(blob) ``` ### player.deque() ⇒ Promise Deques an audio source from queue **Kind**: instance method of [Player](#Player) **Example** ```js player.deque() ``` ### player.play() ⇒ Promise Plays current audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.play() ``` ### player.playQueue() ⇒ Promise Start playing audio sources in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.playQueue() ``` ### player.stop() ⇒ Promise Stop playing current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.stop() ``` ### player.pause() ⇒ Promise Pause playing current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.pause() ``` ### player.replay() ⇒ Promise Replay current audio source **Kind**: instance method of [Player](#Player) **Example** ```js player.replay() ``` ### player.playBlob(blob) ⇒ Promise Play an audio Blob **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | blob | Blob | audio blob | **Example** ```js const blob = new Blob([dataView], { type: 'audio/wav' }) player.playBlob(blob) ``` ### player.playAudioBuffer(audioBuffer) ⇒ Promise Play an AudioBuffer **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | audioBuffer | AudioBuffer | an AudioBuffer | **Example** ```js player.playAudioBuffer(audioBuffer) ``` ### player.getCurrentAudioBuffer() ⇒ AudioBuffer Return current audio buffer playing **Kind**: instance method of [Player](#Player) **Example** ```js player.getCurrentAudioBuffer() ``` ### player.playUrl(url) ⇒ Promise Play an MP3 url **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | url | String | MP3 url | **Example** ```js const url = 'https://example.com/audio.mp3' player.playUrl(url) ``` ### player.getAudioDataFromUrl(url) ⇒ Promise Get the binary audio data from an audio source url in ArrayBuffer form **Kind**: instance method of [Player](#Player) **Returns**: Promise - arrayBuffer | Param | Type | Description | | --- | --- | --- | | url | String | audio source url | **Example** ```js const url = 'https://example.com/audio.mp3' player.getAudioDataFromUrl() .then(arrayBuffer => { }) ``` ### player.next() ⇒ Promise Play next audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.next() ``` ### player.previous() ⇒ Promise Play previous audio source in queue **Kind**: instance method of [Player](#Player) **Example** ```js player.previous() ``` ### player.setRandom(enabled) ⇒ Promise Enable to disable random playback **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable random playback | **Example** ```js player.setRandom(true) ``` ### player.setRepeat(enabled) ⇒ Promise Enable to disable repeat mode. Repeat mode replays the audio sources once the entire queue has finished playing. **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable repeat mode | **Example** ```js player.setRepeat(true) ``` ### player.hasNext() ⇒ Boolean Return true if there's an audio source to play next in queue **Kind**: instance method of [Player](#Player) **Returns**: Boolean - hasNext **Example** ```js const hasNext = player.hasNext() ``` ### player.hasPrevious() ⇒ Boolean Return true if there's a previous audio source in queue **Kind**: instance method of [Player](#Player) **Returns**: Boolean - hasPrevious **Example** ```js const hasPrevious = player.hasPrevious() ``` ### player.setPlaybackRate(playbackRate) ⇒ Promise Set the plaback rate speed, range 0.75-2 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | playbackRate | Number | new playback rate | **Example** ```js player.setPlaybackRate(2) ``` ### player.getPlaybackRate() ⇒ Number Get the current plaback rate speed **Kind**: instance method of [Player](#Player) **Returns**: Number - playback rate speed **Example** ```js const playbackRate = player.getPlaybackRate() ``` ### player.setVolume(volume) ⇒ Promise Set volume, range 0-1 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | volume | Number | volume value | **Example** ```js player.setVolume(0.9) ``` ### player.getVolume() ⇒ Number Get current volume value **Kind**: instance method of [Player](#Player) **Returns**: Number - volume - current volume value **Example** ```js player.getVolume() ``` ### player.setMaxVolume(maxVolume) ⇒ Promise Set the maximum volume limit. For example if max volume is set to 0.6, then when volume is scaled from 0-0.6, meaning that volume level at 1 will play at 0.6 **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | maxVolume | Number | max volume, range 0-1 | **Example** ```js player.setMaxVolume(0.8) ``` ### player.getMaxVolume() ⇒ Number Get max volume value **Kind**: instance method of [Player](#Player) **Returns**: Number - maxVolume - max volume value **Example** ```js player.getMaxVolume() ``` ### player.setMuted(enabled) ⇒ Promise Set volume level to muted **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | enabled | Boolean | boolean to enable mute | **Example** ```js player.setMuted(true) ``` ### player.getCurrentTime() ⇒ Number Return elapsed time in seconds since the audio source started playing **Kind**: instance method of [Player](#Player) **Returns**: Number - time - current time **Example** ```js player.getCurrentTime() ``` ### player.seekTo(seconds) ⇒ Promise Seek to a specified time in audio source **Kind**: instance method of [Player](#Player) | Param | Type | Description | | --- | --- | --- | | seconds | Number | number of seconds to seek to | **Example** ```js const seconds = 45 player.seekTo(seconds) ``` ### player.getDuration() ⇒ Number Get duration of audio source **Kind**: instance method of [Player](#Player) **Returns**: Number - duration - duration of audio source **Example** ```js player.getDuration() ``` ### player.getCurrentState() ⇒ String Get current state of player **Kind**: instance method of [Player](#Player) **Returns**: String - - current state **Example** ```js const currentState = player.getCurrentState() console.log(currentState) // 'PLAYING' ``` ### Player.EventTypes ⇒ Object Return event types **Kind**: static property of [Player](#Player) **Returns**: Object - eventTypes - all player event types **Example** ```js const EventTypes = Player.EventTypes { LOG: 'log', ERROR: 'error', READY: 'ready', PLAY: 'play', REPLAY: 'replay', PAUSE: 'pause', STOP: 'pause', NEXT: 'next', PREVIOUS: 'previous', RANDOM: 'random', REPEAT: 'repeat', PLAYBACK_RATE: 'playbackRate', VOLUME: 'volume', MAX_VOLUME: 'maxVolume', MUTED: 'muted', ENDED: 'ended', ENQUEUE: 'enqueue', DEQUE: 'deque', EMPTY_QUEUE: 'emptyQueue', STATE_CHANGE: 'stateChange' } ``` # Usage Standard audio player ```javascript const {Player} = require('audio-director') const player = new Player() // add audio source(s) to play queue. Converts input to AudioBuffer. player.enqueue(dataView|typedArray|arrayBuffer|url) .then(audioBuffer => { player.play() }) ``` [Full documentation](https://lab.miguelmota.com/audio-director/docs/Player.html) YouTube player ```javascript const {YoutubePlayer} = require('audio-director') const player = new YoutubePlayer() const url = 'https://www.youtube.com/watch?v=_5joTyy3CCo&list=RDQMc4l8l2aQrNo' player.enqueue(url) .then(() => player.play()) ``` [Full documentation](https://lab.miguelmota.com/audio-director/docs/YoutubePlayer.html) ## Example [Live basic example](https://lab.miguelmota.com/audio-director/example) ## Source [https://github.com/miguelmota/audio-director](https://github.com/miguelmota/audio-director) ## License [MIT](LICENSE)