feat: add notification sound

.changes/notification-sound.md

@@ -0,0 +1,6 @@
+---
+'tauri': 'minor:feat'
+'@tauri-apps/api': 'minor:feat'
+---
+
+Add option to specify notification sound.

core/tauri/Cargo.toml

@@ -103,7 +103,7 @@ objc = "0.2"
 
 [target."cfg(windows)".dependencies]
 webview2-com = "0.19.1"
-win7-notifications = { version = "0.3.1", optional = true }
+win7-notifications = { version = "0.4", optional = true }
 
   [target."cfg(windows)".dependencies.windows]
   version = "0.39.0"

core/tauri/src/api/notification.rs

@@ -40,6 +40,8 @@ pub struct Notification {
   icon: Option<String>,
   /// The notification identifier
   identifier: String,
+  /// The notification sound
+  sound: Option<String>,
 }
 
 impl Notification {
@@ -72,6 +74,36 @@ impl Notification {
     self
   }
 
+  /// Sets the notification sound. Silent by default.
+  ///
+  /// ## Platform-specific
+  ///
+  /// Each OS has a different sound name so you will need to conditionally specify an appropriate sound
+  /// based on the OS in use, for a list of sounds see:
+  /// - **Linux**: can be one of the sounds listed in <https://0pointer.de/public/sound-naming-spec.html>
+  /// - **Windows**: can be one of the sounds listed in <https://learn.microsoft.com/en-us/uwp/schemas/tiles/toastschema/element-audio>
+  ///   but without the prefix, for example, if `ms-winsoundevent:Notification.Default` you would use `Default` and
+  ///   if `ms-winsoundevent:Notification.Looping.Alarm2`, you would use `Alarm2`.
+  ///   Windows 7 is not supproted, if a sound is provided, it will play the default sound, otherwise it will be silent.
+  /// - **macOS**: you can specify the name of the sound you'd like to play when the notification is shown
+  /// or use `NSUserNotificationDefaultSoundName` to play the default sound.
+  /// Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files.
+  /// Be sure that the sound file is copied under the app bundle (e.g., `YourApp.app/Contents/Resources`), or one of the following locations:
+  ///   - `~/Library/Sounds`
+  ///   - `/Library/Sounds`
+  ///   - `/Network/Library/Sounds`
+  ///   - `/System/Library/Sounds`
+  ///
+  ///   See the [`NSSound`] docs for more information.
+  ///
+  ///
+  /// [`NSSound`]: https://developer.apple.com/documentation/appkit/nssound
+  #[must_use]
+  pub fn sound(mut self, sound: impl Into<String>) -> Self {
+    self.sound = Some(sound.into());
+    self
+  }
+
   /// Shows the notification.
   ///
   /// # Examples
@@ -108,6 +140,9 @@ impl Notification {
     } else {
       notification.auto_icon();
     }
+    if let Some(sound) = self.sound {
+      notification.sound_name(&sound);
+    }
     #[cfg(windows)]
     {
       let exe = tauri_utils::platform::current_exe()?;
@@ -191,6 +226,7 @@ impl Notification {
       if let Some(title) = self.title {
         notification.summary(&title);
       }
+      notification.silent(self.sound.is_none());
       if let Some(crate::Icon::Rgba {
         rgba,
         width,

core/tauri/src/endpoints/notification.rs

@@ -26,6 +26,8 @@ pub struct NotificationOptions {
   pub body: Option<String>,
   /// The notification icon.
   pub icon: Option<String>,
+  /// The notification sound.
+  pub sound: Option<String>,
 }
 
 /// The API descriptor.
@@ -56,6 +58,9 @@ impl Cmd {
     if let Some(icon) = options.icon {
       notification = notification.icon(icon);
     }
+    if let Some(sound) = options.sound {
+      notification = notification.sound(sound);
+    }
     #[cfg(feature = "windows7-compat")]
     {
       notification.notify(&context.window.app_handle)?;
@@ -94,6 +99,7 @@ mod tests {
         title: String::arbitrary(g),
         body: Option::arbitrary(g),
         icon: Option::arbitrary(g),
+        sound: Option::arbitrary(g),
       }
     }
   }