- Ember.js v3.28 or above
- Ember CLI v3.28 or above
- Node.js v14 or above
ember install ember-stereo
Interactive docs at ember-stereo.com!
Upgrading from ember-hifi
? Read the upgrade guide
ember-stereo
operates on sounds by providing its helpers an identifier. Usually this is just a URL string, but an identifier could also be an object with a url property (and maybe a mimeType property), an already loaded stereo Sound
object, an array of any of the previous items, or even a promise that resolves to any of the previous. Whatever the case, you're covered.
toggle-play-sound
play-sound
load-sound
pause-sound
stop-sound
fastforward-sound
rewind-sound
seek-sound
sound-is-loaded
sound-is-loading
sound-is-playing
sound-is-errored
sound-is-fastforwardable
sound-is-rewindable
sound-is-seekable
sound-is-blocked
autoplay-allowed
sound-metadata
sound-duration(@identifier, load=false, format=false)
sound-position(@identifier, format=false defaultValue=0)
current-sound
find-sound
stereo
plays one sound at a time. Multiple sounds can be loaded and ready to go, but only one sound plays at a time. The currently playing sound is set to currentSound
on the service, and most methods and properties on the service simply proxy to that sound.
play(urlsOrPromise, options)
play
calls load
with the same arguments, and then on success plays the sound, returning it to you.
play
can take one or more URLs, or a promise returning one or more URLs.
If the audio URLs are not known at the time of a play event, give play
the promise to resolve, otherwise your mobile users might have to click the play button twice (due to some restrictions on autoplaying audio).
export default class StereoComponent extends Component {
@service stereo
...
@action
play(id) {
let urlPromise = this.store.findRecord('story', id).then(story => story.getProperties('aacUrl', 'hlsUrl'))
this.stereo.play(urlPromise).then(({sound}) => {
// sound object
}).catch(error => {
})
}
}
If you already know the URLs, just pass them in.
export default class StereoComponent extends Component {
@service stereo
...
@action
play(urls) {
this.stereo.play(urls).then(({sound}) => {
// sound object
}).catch(error => {
})
}
}
-
playTask(urlsOrPromise, options)
the ember concurrency task thatplay
calls. -
pause()
Pauses the current sound -
togglePause()
Toggles the play state of the current sound -
fastForward(duration)
Moves the playhead of the current sound forwards by duration (in ms) -
rewind(duration)
Moves the playhead of the current sound backwards by duration (in ms) -
load(urlsOrPromise, options)
Tries each stereo connection with each url and returns the readysound
from the first combination that works. The sound is cached internally so on subsequent load requests with the same url the already prepared sound will be returned. Callingplay
on the returned sound will start playback immediately. -
loadTask(urlsOrPromise, options)
the ember concurrency task thatload
calls. -
findSound(identifier)
Returns a sound once it loads. This works reactively, so you can do something like:
export default class StereoComponent extends Component {
@service stereo
...
get sound() {
return this.stereo.findSound(this.args.identifier)
}
}
-
volume
(integer, 0-100)
System volume. Bind a range element to this property for a simple volume control
//component.js
import { inject as service } from "@ember/service";
export default Component.extend({
stereo: service(),
})
//template.hbs
{{input type="range" value=stereo.volume}}
-
position
(integer, in ms)
Here's a silly way to make a position control, too.
//component.js
export default Component.extend({
stereo: service(),
})
//template.hbs
{{input type="range" value=stereo.position min=0 max=stereo.duration step=1000}}
-
isLoading
(boolean) -
isPlaying
(boolean) -
isStream
(boolean) -
isFastForwardable
(boolean) -
isRewindable
(boolean) -
duration
(integer, in ms) -
percentLoaded
(integer 0-100, when available) -
currentSound
the currently loaded sound
-
play()
Plays the sound -
pause()
Pauses the sound -
togglePause()
Toggles the play state of the sound -
fastForward(duration)
Moves the playhead of the sound forwards by duration (in ms) -
rewind(duration)
Moves the playhead of the sound backwards by duration (in ms)
-
position
(integer, in ms)
-
isLoading
(boolean) -
isPlaying
(boolean) -
isStream
(boolean) -
isSeekable
(boolean) -
isFastForwardable
(boolean) -
isRewindable
(boolean) -
duration
(integer, in ms) -
percentLoaded
(integer, not always available) -
url
the url of the sound
The stereo
service and the sound
objects are extended with Ember.Evented. You can subscribe to the following events in your application.
-
audio-played
({ sound }) - the sound started playing -
audio-paused
({ sound }) - the sound was paused -
audio-ended
({ sound }) - the sound finished playing -
audio-load-error
({ sound }) - loading sound failed -
audio-ready
({ sound }) - the sound is ready to play -
audio-will-rewind
({sound, currentPosition, newPosition}) - fired before rewinding a sound -
audio-will-fast-forward
({sound, currentPosition, newPosition}) - fired before fast-forwarding a sound -
audio-position-will-change
({sound, currentPosition, newPosition}) - fired before audio position change -
audio-position-changed
({sound}) -
audio-blocked
({ sound }) - the sound was prevented from being played by the browser due to auto play restrictions
-
current-sound-changed
({sound, previousSound}) - triggered when the current sound changes. On initial play, previousSound will be undefined. -
current-sound-interrupted
({sound, previousSound}) - triggered when a sound has been playing and a new one takes its place by being played, pausing the first one -
new-load-request
({loadPromise, urlsOrPromise, options}) - triggered whenever.load
or.play
is called. -
pre-load
({loadPromise, urlsOrPromise, options}) - triggered whenever.load
or.play
is called.
-
NativeAudio
- Uses the native<audio>
element for playing and streaming audio -
HLS
- Uses HLS.js for playing HLS streams on the desktop. -
Howler
- Uses howler to play audio
stereo
will take a list of urls and find the first connection/url combo that works. For desktop browsers, we'll try each url on each connection in the order the urls were specified.
For mobile browsers, we'll first try all the URLs on the NativeAudio using a technique to (hopefully) get around any autoplaying restrictions that sometimes require mobile users to click a play button twice.
If you need to test audio handling that involves ember-stereo
in your app, you're gonna need this helper. It sets up and cleans up a few stereo-related items, but most importantly it stubs out the native browser audio and video elements replacing it with a FakeMediaElement that behaves sanely in the test environment.
You can control how the sound behaves by providing a url in one of these formats:
-
good/10000/test-url.mp3
: an mp3 that is 10 seconds long -
good/stream/the-current.aac
: an aac audio stream, duration = Infinity, will behave like a stream does
-
bad/codec-error/the-current.aac
: an aac sound that will fail with 'codec-error' -
bad/some%20custom%20string/the-current.aac
: an aac sound that will fail with error message 'some custom string'
Here's an example test, testing an example player, making sure that fast forward and rewind buttons are disabled.
import { setupStereoTest } from 'ember-stereo/test-support/stereo-setup';
module('Integration | Component | player', function (hooks) {
setupStereoTest(hooks);
test('it does not display rewind and ff buttons when stream', async function (assert) {
let stereo = this.owner.lookup('service:stereo');
await stereo.play('/good/stream/test.mp3', {
metadata: {
show,
track,
},
});
await render(hbs`<Player/>`);
assert.dom('[data-test-element="fastforward-button"]').isDisabled();
assert.dom('[data-test-element="rewind-button"]').isDisabled();
assert.dom('[data-test-element="play-pause-button"]').exists();
});
});
Do you need to support a funky audio format that stereo's built-in connections can't handle? Read more about how to write your own custom connection here.