Merge pull request #175 from svrooij/feature/audio-clip

feat: Notifications through AudioClip

docs/_config.yml

@@ -55,7 +55,7 @@ aux_links:
     - "//github.com/sponsors/svrooij/"
 
 # Footer content appears at the bottom of every page's main content
-footer_content: "Copyright &copy; 2022 Stephan van Rooij. Distributed by an <a href=\"https://github.com/svrooij/node-sonos-ts/tree/master/LICENSE\">MIT license.</a>"
+footer_content: "Copyright &copy; 2023 Stephan van Rooij. Distributed by an <a href=\"https://github.com/svrooij/node-sonos-ts/tree/master/LICENSE\">MIT license.</a>"
 
 toc:
   max_levels: 2

docs/sonos-device/notifications-and-tts.md

@@ -32,6 +32,27 @@ sonos.PlayNotification({
   })
 ```
 
+## Notifications with AudioClip
+
+Sonos has a [native](https://developer.sonos.com/reference/control-api/audioclip/) way to play an audio clip through the music, this used to be cloud only functionality. Until [Thomas discovered](https://github.com/bencevans/node-sonos/issues/530#issuecomment-1430039043) it was also available on the local network. We now have experimental support for this audio clip endpoint, which only works on speakers that are compatible with the S2 app, and we are probably going to replace the custom build version with the native version.
+
+The native AudioClip does not pause the music, the clip is played over it, not having to revert back to the original music because it is not replaced. Sample code available in [examples](https://github.com/svrooij/node-sonos-ts/tree/master/examples)
+
+```js
+const SonosDevice = require('@svrooij/sonos').SonosDevice
+const sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')
+
+sonos.PlayNotificationAudioClip({
+    trackUri: 'https://cdn.smartersoft-group.com/various/pull-bell-short.mp3', // Can be any uri sonos understands
+    // trackUri: 'https://cdn.smartersoft-group.com/various/someone-at-the-door.mp3', // Cached text-to-speech file.
+    onlyWhenPlaying: false, // make sure that it only plays when you're listening to music. So it won't play when you're sleeping.
+    volume: 15, // Set the volume for the notification (and revert back afterwards)
+  })
+  .then(queued => {
+    console.log('Queued notification %o', queued)
+  })
+```
+
 ## Text to speech
 
 A lot of people want to send text to sonos to use for notifications (or a welcome message in your B&B).
@@ -55,6 +76,25 @@ We have support for **neural** language engines. Pick a voice that supports it a
 
 The server I've build is based on Amazon Polly, but I invite everybody to build their own if you want to support another tts service.
 
+```js
+const SonosDevice = require('@svrooij/sonos').SonosDevice
+const sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')
+sonos.PlayTTSAudioClip({
+    text: 'Someone at the front-door',
+    lang: 'en-US',
+    gender: 'male',
+    volume: 50,
+    endpoint: 'https://your.tts.endpoint/api/generate'
+  })
+  .then(queued => {
+    console.log('Queued notification %o', queued)
+  })
+```
+
+### TTS AudioClip
+
+Text to speech but with the AudioClip endpoint, see [Notifications with Audio Clip](#notifications-with-audioclip) for differences.
+
 ```js
 const SonosDevice = require('@svrooij/sonos').SonosDevice
 const sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')
@@ -74,6 +114,7 @@ sonos.PlayTTS({
   })
 ```
 
+
 ## Notifications on all speakers
 
 If you use the **SonosManager** (the recommended way to use this library), you can also play a notification on all groups by sending the same command to the SonosManager instead of the individual speaker.

examples/play-notification-audioclip.js

@@ -0,0 +1,51 @@
+const SonosDevice = require('../lib').SonosDevice
+
+const sonos = new SonosDevice(process.env.SONOS_HOST || '192.168.96.56')
+
+// Pre-start listening for events for more efficient handling.
+sonos.Events.on('currentTrack', (track) => {
+  console.log('TrackChanged %o', track);
+});
+
+
+// setTimeout(async () => {
+//   // Add a second notification (by some other event)
+//   await sonos.PlayNotificationAudioClip({
+//     trackUri: 'https://cdn.smartersoft-group.com/various/someone-at-the-door.mp3', // Cached text-to-speech file.
+//     onlyWhenPlaying: false, // make sure that it only plays when you're listening to music. So it won't play when you're sleeping.
+//     volume: 20, // Set the volume for the notification (and revert back afterwards)
+//   });
+//   await sonos.PlayNotificationAudioClip({
+//     trackUri: 'https://cdn.smartersoft-group.com/various/someone-at-the-door.mp3', // Cached text-to-speech file.
+//     onlyWhenPlaying: false, // make sure that it only plays when you're listening to music. So it won't play when you're sleeping.
+//     volume: 20, // Set the volume for the notification (and revert back afterwards)
+//   });
+// }, 500)
+
+sonos.PlayNotificationAudioClip({
+  trackUri: 'https://cdn.smartersoft-group.com/various/pull-bell-short.mp3', // Can be any uri sonos understands
+  onlyWhenPlaying: false, // make sure that it only plays when you're listening to music. So it won't play when you're sleeping.
+  volume: 80, // Set the volume for the notification (and revert back afterwards)
+})
+  .then(queued => {
+    console.log('Queued notification %o', queued)
+
+  })
+  .catch((err) => {
+    console.error(err);
+  })
+  .finally(() => {
+    sonos.CancelEvents();
+  });
+
+// If you have a TTS endpoint, you can do text-to-speech
+// PlayTTS() will just call a server to generate the TTS mp3 file and then call PlayNotification().
+
+// sonos.PlayTTS({ text: 'Someone at the front-door', lang: 'en-US', gender: 'male', volume: 50 })
+//   .then(played => {
+//     console.log('Played notification %o', played)
+//     setTimeout(() => {
+//       process.exit(0)
+//     }, 2000)
+//   })
+//   .catch(console.error)