{{this.metadataError}}
\n {{/if}}\nYou can silence the thrown errors and handle them inline
\nisCastingAvailablesupportedCastTypeisCastingcastKindcastDeviceNamesound.metadata.title\n These only read. Nothing on this side ever loads the sound.\n
\n\n These drive the service directly. The helpers update anyway, because\n both sides share one Sound.\n
\n{{get (current-sound) 'url'}}
\n \n \n {{else}}\n \n {{/if}}\n \nYou can silence the thrown errors and handle them inline
\nThis is what happens when you don't catch the error (open your console)
\nUsing a try/catch block with async/await
\nUsing a try/then/catch on the promise
\nErrors are not thrown when using template helpers
\n {{#let '/sounds/unplayable-scooby.au' as |url|}}\n \n {{#if (sound-is-errored url)}}\n \nTrying multiple urls with the service
\n\n {{sound-metadata currentSound key='title'}}\n
\n\n {{get currentSound 'url'}}\n
\nThis sound has control of the element right now
\n {{else}}\nThis sound is not in control of the element now
\n {{/if}}\n \n {{/if}}\n \n \n {{/let}}\n \n{{@item.connectionName}}
\n \n\n {{#if\n (and\n @allowSelection\n (includes @item.key @selectedConnections)\n (eq status.summary 'ineligible')\n )\n }}\n It doesn't look like it'll work, but we'll try it anyway\n {{else}}\n {{status.message}}\n \n {{/if}}\n
\n \n {{/let}}\nSame URL, so the same\n Sound. Play or seek either and the other should match exactly.\n The top player positions with modifiers, the bottom one with helpers.
One player, a different sound behind it. Every\n helper and modifier bound to the identifier should follow the selection,\n while the service-wide volume stays put. A seekable file and a live stream\n need different controls, so the transport should change with them. The\n sound you leave keeps playing until you start another.
\n \nPlay should surface the error, not spin forever.
\n \nEach player below is provided a different identifier\n format (a string, an object, and a promise), but each identifier resolves to\n the same URL. Each set of players should stay in sync.
\nA few patterns that go beyond a single play/pause button.
\n \nThe {{sound-position-slider}} modifier turns any element into a scrubber bound to a sound's position. Point it at an identifier and it keeps the control and the playback in sync both ways. Drag to seek, and it tracks as the sound plays.
The same modifier works without a live sound, driven by plain @position and @duration values. This is useful for rendering a static or server-supplied progress bar:
For a read-only bar, {{sound-position-progress}} sizes an element to the sound's position instead. It takes the same @position and @duration fallbacks.
<div {{sound-position-progress @identifier}}></div>\n Because current-sound and the audio-ended event are app-wide, a queue is just \"play the next thing when the current one ends.\" Here a list of URLs plays through in order:
The pattern: keep your own ordered list, play the first item, and subscribe to audio-ended on the service to advance. See Monitoring Events for the full event list.
Howler and HLS pull their library down as a lazy chunk, and Chromecast fetches the Cast SDK from gstatic.com. Whichever sound needs one first pays for that download before any audio is fetched, so if you know which is coming, warm it up first:
// e.g. a live stream that can rewind into a recorded HLS archive\n this.stereo.prewarmConnection('HLS');\n It takes the name a connection is registered under and resolves once it's warm. Connections with nothing to download resolve immediately. Your own connections become prewarmable by implementing static preload().
For anything more involved than the helpers cover, reach for the Sound object itself. Its lifecycle states, playback proxying, and connection swaps are documented in Playing Sounds.
Three things about audio on the web will bite you no matter which library you use: browsers disagree about formats, they block autoplay, and playback fails in ways you have to handle. stereo gives you a way through each.
Different browsers support different audio formats, and unless you're playing something universally supported like mp3, things get tricky.
opus/ogg is a fantastic audio format, but Safari and iOS don't care about it at all. HLS is a fantastic protocol for live streaming, but only Safari supports it natively, and the full featured hls.js player that stereo provides a connection for runs everywhere except Safari and iOS. Doing anything fancy with audio on the web is still painful.
You'd probably rather serve listeners slimmer .ogg files or hls streams than .mp3s, without tracking that mess yourself.
Give stereo an array of urls in preferential order. It tries each url on each loaded connection and stops once one works.
To illustrate, here's this (incredible) digitized in-store cassette tape from K-Mart in 1989 from archive.org. The ogg version is 60M and the mp3 version is 200M. Woof. The higher quality 60M file is obviously preferable.
Looks like you're running {{docs/current-browser}} on {{docs/current-os}}
\n \nHere's what ember-stereo about the chances of this ogg file succeeding.
This for sure works on
It used to be easy to play audio without autoplay blockers getting in the way. For those of us with good intentions, who aren't trying to do user-hostile things like play advertisements on page load, this is frustrating. Here's Mozilla's guide on autoplay for the details.
\n \nYou might want to check whether autoplay is allowed in your listener's browser and take extra steps if it isn't. Here's how.
\n \nTemplate action helpers don't throw when playback fails. Instead you check whether a sound errored, using a couple of helpers.
\n \nInteracting with the service, you handle errors the way you'd expect.
\n \nCasting sends the audio to an AirPlay receiver or a Chromecast device instead of the local speakers. ember-stereo treats the remote device as another connection, that it automatically loads and injects when needed.
gstatic.com the first time a {{cast-button}} or {{casting-available}} renders.On Chrome, {{casting-available}} tracks whether a Chromecast is on the network, and the button disables itself when there is none. On Safari it only means AirPlay exists. WebKit reports receivers as unavailable even when the picker can find them, so ember-stereo ignores that signal and lets the picker show its own empty state.
sound.castUrlWhen you cast the device fetches the audio directly, meaning if it can't reach it without your app's session or auth headers it won't play. Set sound.castUrl to a public or signed variant of the stream if you need it.
AirPlay reads metadata from the OS, so a change reaches the receiver as soon as it reaches the lock screen.
\nChromecast is handed metadata in the load request and keeps it, so set sound.metadata before casting. Changing it afterwards updates the lock screen and your own UI but not the device, and only a reload would refresh it. A live stream whose now-playing changes mid-listen keeps the title it started with until the next cast.
{{cast-button}} turns a <button> into a cast control. Clicking it opens the device picker. The button disables itself when {{casting-available}} is false, and gets a casting class while connected, so you can style the connected state.
<button type='button' {{cast-button}}>\n Cast\n </button>\n Casting always follows the current sound. Whatever is playing when you pick a device moves to it, and anything you play afterwards goes there too, until you disconnect.
\n \n{{casting-available}} - true when casting can be started right now. On Chrome that means a Chromecast is on the network. On Safari it is true whenever AirPlay exists.{{is-casting}} - true while the audio plays on a remote device.<button type='button' {{cast-button}}>\n {{#if (is-casting)}}\n Casting…\n {{else if (casting-available)}}\n Cast\n {{else}}\n No cast targets available\n {{/if}}\n </button>\n Stream:
\n \nFixed audio:
\n \nThe stereo service exposes:
isCastingAvailable - true when casting can be startedisCasting - true when audio is playing on a remote devicecastDeviceName - the device's name. Chromecast provides one, AirPlay doesn't, so this can be nullcastKind - 'airplay', 'chromecast', or nullcastIconName - 'cast', 'airplay', or null, for picking the right iconsupportedCastType - which kind of casting this browser can do at all ('airplay', 'chromecast', or null), even before any device is foundshowCastMenu() - open the device picker (what {{cast-button}} calls)stopCasting() - disconnect and return playback to the local deviceThe service fires four cast events as casting starts and stops. See Events.
\nSwitching feeds mid-stream while casting needs nothing special from you. A remote device is just another connection, so currentSound and swap behave exactly as they do locally and your player code never needs a \"we're casting now\" branch.
Not every device that shows up in Safari desktop's picker can play web audio.
\nAirPlay 2 receivers (Apple TV, HomePod, most hardware since about 2018) work everywhere. Audio-only receivers of the AirPort Express / 2011–2017 AV receiver vintage work perfectly from mobile Safari but not desktop Safari, and the failure is silent (which is very annoying). I can't seem to find a way to work around it, so beware that edge case.
\nSame URL, so the same\n Sound. Play or seek either and the other should match exactly.\n The top player positions with modifiers, the bottom one with helpers.
One player, a different sound behind it. Every\n helper and modifier bound to the identifier should follow the selection,\n while the service-wide volume stays put. A seekable file and a live stream\n need different controls, so the transport should change with them. The\n sound you leave keeps playing until you start another.
\n \nPlay should surface the error, not spin forever.
\n \nEach player below is provided a different identifier\n format (a string, an object, and a promise), but each identifier resolves to\n the same URL. Each set of players should stay in sync.
\nA few patterns that go beyond a single play/pause button.
\n \nThe {{sound-position-slider}} modifier turns any element into a scrubber bound to a sound's position. Point it at an identifier and it keeps the control and the playback in sync both ways. Drag to seek, and it tracks as the sound plays.
The same modifier works without a live sound, driven by plain @position and @duration values. This is useful for rendering a static or server-supplied progress bar:
For a read-only bar, {{sound-position-progress}} sizes an element to the sound's position instead. It takes the same @position and @duration fallbacks.
<div {{sound-position-progress @identifier}}></div>\n Because current-sound and the audio-ended event are app-wide, a queue is just \"play the next thing when the current one ends.\" Here a list of URLs plays through in order:
The pattern: keep your own ordered list, play the first item, and subscribe to audio-ended on the service to advance. See Monitoring Events for the full event list.
Howler and HLS pull their library down as a lazy chunk, and Chromecast fetches the Cast SDK from gstatic.com. Whichever sound needs one first pays for that download before any audio is fetched, so if you know which is coming, warm it up first:
// e.g. a live stream that can rewind into a recorded HLS archive\n this.stereo.prewarmConnection('HLS');\n It takes the name a connection is registered under and resolves once it's warm. Connections with nothing to download resolve immediately. Your own connections become prewarmable by implementing static preload().
For anything more involved than the helpers cover, reach for the Sound object itself. Its lifecycle states, playback proxying, and connection swaps are documented in Playing Sounds.
Three things about audio on the web will bite you no matter which library you use: browsers disagree about formats, they block autoplay, and playback fails in ways you have to handle. stereo gives you a way through each.
Different browsers support different audio formats, and unless you're playing something universally supported like mp3, things get tricky.
opus/ogg is a fantastic audio format, but Safari and iOS don't care about it at all. HLS is a fantastic protocol for live streaming, but only Safari supports it natively, and the full featured hls.js player that stereo provides a connection for runs everywhere except Safari and iOS. Doing anything fancy with audio on the web is still painful.
You'd probably rather serve listeners slimmer .ogg files or hls streams than .mp3s, without tracking that mess yourself.
Give stereo an array of urls in preferential order. It tries each url on each loaded connection and stops once one works.
To illustrate, here's this (incredible) digitized in-store cassette tape from K-Mart in 1989 from archive.org. The ogg version is 60M and the mp3 version is 200M. Woof. The higher quality 60M file is obviously preferable.
Looks like you're running {{docs/current-browser}} on {{docs/current-os}}
\n \nHere's what ember-stereo about the chances of this ogg file succeeding.
This for sure works on
It used to be easy to play audio without autoplay blockers getting in the way. For those of us with good intentions, who aren't trying to do user-hostile things like play advertisements on page load, this is frustrating. Here's Mozilla's guide on autoplay for the details.
\n \nYou might want to check whether autoplay is allowed in your listener's browser and take extra steps if it isn't. Here's how.
\n \nTemplate action helpers don't throw when playback fails. Instead you check whether a sound errored, using a couple of helpers.
\n \nInteracting with the service, you handle errors the way you'd expect.
\n \nCasting sends the audio to an AirPlay receiver or a Chromecast device instead of the local speakers. ember-stereo treats the remote device as another connection, that it automatically loads and injects when needed.
gstatic.com the first time a {{cast-button}} or {{casting-available}} renders.On Chrome, {{casting-available}} tracks whether a Chromecast is on the network, and the button disables itself when there is none. On Safari it only means AirPlay exists. WebKit reports receivers as unavailable even when the picker can find them, so ember-stereo ignores that signal and lets the picker show its own empty state.
sound.castUrlWhen you cast the device fetches the audio directly, meaning if it can't reach it without your app's session or auth headers it won't play. Set sound.castUrl to a public or signed variant of the stream if you need it.
AirPlay reads metadata from the OS, so a change reaches the receiver as soon as it reaches the lock screen.
\nChromecast is handed metadata in the load request and keeps it, so set sound.metadata before casting. Changing it afterwards updates the lock screen and your own UI but not the device, and only a reload would refresh it. A live stream whose now-playing changes mid-listen keeps the title it started with until the next cast.
{{cast-button}} turns a <button> into a cast control. Clicking it opens the device picker. The button disables itself when {{casting-available}} is false, and gets a casting class while connected, so you can style the connected state.
<button type='button' {{cast-button}}>\n Cast\n </button>\n Casting always follows the current sound. Whatever is playing when you pick a device moves to it, and anything you play afterwards goes there too, until you disconnect.
\n \n{{casting-available}} - true when casting can be started right now. On Chrome that means a Chromecast is on the network. On Safari it is true whenever AirPlay exists.{{is-casting}} - true while the audio plays on a remote device.<button type='button' {{cast-button}}>\n {{#if (is-casting)}}\n Casting…\n {{else if (casting-available)}}\n Cast\n {{else}}\n No cast targets available\n {{/if}}\n </button>\n Stream:
\n \nFixed audio:
\n \nThe stereo service exposes:
isCastingAvailable - true when casting can be startedisCasting - true when audio is playing on a remote devicecastDeviceName - the device's name. Chromecast provides one, AirPlay doesn't, so this can be nullcastKind - 'airplay', 'chromecast', or nullcastIconName - 'cast', 'airplay', or null, for picking the right iconsupportedCastType - which kind of casting this browser can do at all ('airplay', 'chromecast', or null), even before any device is foundshowCastMenu() - open the device picker (what {{cast-button}} calls)stopCasting() - disconnect and return playback to the local deviceThe service fires four cast events as casting starts and stops. See Events.
\nSwitching feeds mid-stream while casting needs nothing special from you. A remote device is just another connection, so currentSound and swap behave exactly as they do locally and your player code never needs a \"we're casting now\" branch.
Not every device that shows up in Safari desktop's picker can play web audio.
\nAirPlay 2 receivers (Apple TV, HomePod, most hardware since about 2018) work everywhere. Audio-only receivers of the AirPort Express / 2011–2017 AV receiver vintage work perfectly from mobile Safari but not desktop Safari, and the failure is silent (which is very annoying). I can't seem to find a way to work around it, so beware that edge case.
\n