widget/public/nsISound.idlScriptable
This interface provides a way to play sounds.
Inherits from: nsISupports Last changed in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

Warning: This interface should not be used to play custom sounds in modern code. Please use the HTML 5 <audio> tag instead.

Note that nsISound instances may play the sounds using another thread; however, this is not controlled by the caller.

Implemented by: @mozilla.org/sound;1. To use this interface, use:

var sound = Components.classes["@mozilla.org/sound;1"]
                      .createInstance(Components.interfaces.nsISound);

Method overview

void beep();
void init();
void play(in nsIURL aURL);
void playEventSound(in unsigned long aEventId);
void playSystemSound(in AString soundAlias);

Constants

Sound event constants

Constant Value Description
EVENT_NEW_MAIL_RECEIVED 0 The system receives email.
EVENT_ALERT_DIALOG_OPEN 1 An alert dialog is opened.
EVENT_CONFIRM_DIALOG_OPEN 2 A confirm dialog is opened.
EVENT_PROMPT_DIALOG_OPEN 3 A prompt dialog (one that allows the user to enter data, such as an authentication dialog) is opened.
EVENT_SELECT_DIALOG_OPEN 4 A select dialog (one that contains a list box) is opened.
EVENT_MENU_EXECUTE 5 A menu item is executed.
EVENT_MENU_POPUP 6 A popup menu is shown.
EVENT_EDITOR_MAX_LEN 7 More characters than the maximum allowed are typed into a text field.

Methods

beep()

Plays a beep sound.

void beep();
Parameters

None.

init()

Not strictly necessary, but avoids a delay before the first sound. Other methods will call Init if they need to.

void init();
Parameters

None.

play()

Plays a sound specified by URL.

void play(
  in nsIURL aURL
);
Parameters
aURL
The URL of the sound file to play.

playEventSound()

Plays the system sound for the specified event. If the user's system is configured to not play system sound effects for the event, this will do nothing.

Warning: This method should not be used in modern code. Please use the HTML 5 <audio> tag instead.

void playEventSound(
  in unsigned long aEventId
);
Parameters
aEventId
An event ID which is defined in the constants.

playSystemSound()

Plays the system sound whose name is specified. If the user's system is configured to not play system sound effects, this will do nothing.

Note: This function is not supported on the Macintosh.
void playSystemSound(
  in AString soundAlias
);
Parameters
soundAlias

Two different types of names are supported:

You can specify the name of a system sound provided by the host operating system; for example, if you specify "SystemExclamation", you can play the Windows alert sound, but it's played only on Windows. Similarly, if you specify "Blow", you can play the Mac OS X "Blow" system sound, but, similarly, it's played only on the Macintosh. If you wish to use this method for playing sounds, you should check the platform before you call playSystemSound().

Note: This second usage is obsolete starting in Gecko 1.9.2. You should instead use playEventSound() instead.

Typically, it will be more useful to request that appropriate sounds be played based on which event you wish to represent by the sound effect. Various event names are provided, which will result in playing the corresponding sound effect on the platform the user is running on:

_moz_mailbeep
The system sound when the system receives email.
_moz_alertdialog
The system sound when an alert dialog is opened.
_moz_confirmdialog
The system sound when a confirm dialog is opened.
_moz_promptdialog
The system sound when a prompt dialog (one that allows the user to enter data, such as an authentication dialog) is opened.
_moz_selectdialog
The system sound when a select dialog (one that contains a list box) is opened.
_moz_menucommand
The system sound when a menu item is executed.
_moz_menupopup
The system sound when a popup menu is shown.