PlaySound
The PlaySound function plays a sound specified by the given file name, resource, or system event. (A system event may be associated with a sound in the registry or in the WIN.INI file.)
BOOL PlaySound(
LPCTSTR pszSound,
HMODULE hmod,
DWORD fdwSound
);
Parameters
pszSound
A string that specifies the sound to play. The maximum length, including the null terminator, is 256 characters. If this parameter is NULL, any currently playing waveform sound is stopped. To stop a non-waveform sound, specify SND_PURGE in the fdwSound parameter.
Three flags in fdwSound (SND_ALIAS, SND_FILENAME, and SND_RESOURCE) determine whether the name is interpreted as an alias for a system event, a file name, or a resource identifier. If none of these flags are specified, PlaySound searches the registry or the WIN.INI file for an association with the specified sound name. If an association is found, the sound event is played. If no association is found in the registry, the name is interpreted as a file name.
hmod
Handle to the executable file that contains the resource to be loaded. This parameter must be NULL unless SND_RESOURCE is specified in fdwSound.
fdwSound
Flags for playing the sound. The following values are defined.
| Value | Meaning |
| SND_APPLICATION | The pszSound parameter is an application-specific alias in the registry. You can combine this flag with the SND_ALIAS or SND_ALIAS_ID flag to specify an application-defined sound alias. |
| SND_ALIAS | The pszSound parameter is a system-event alias in the registry or the WIN.INI file. Do not use with either SND_FILENAME or SND_RESOURCE. |
| SND_ALIAS_ID | The pszSound parameter is a predefined identifier for a system-event alias. See Remarks. |
| SND_ASYNC | The sound is played asynchronously and PlaySound returns immediately after beginning the sound. To terminate an asynchronously played waveform sound, call PlaySound with pszSound set to NULL. |
| SND_FILENAME | The pszSound parameter is a file name. If the file cannot be found, the function plays the default sound unless the SND_NODEFAULT flag is set. |
| SND_LOOP | The sound plays repeatedly until PlaySound is called again with the pszSound parameter set to NULL. If this flag is set, you must also set the SND_ASYNC flag. |
| SND_MEMORY | The pszSound parameter points to a sound loaded in memory.
For more information, see Playing WAVE Resources. |
| SND_NODEFAULT | No default sound event is used. If the sound cannot be found, PlaySound returns silently without playing the default sound. |
| SND_NOSTOP | The specified sound event will yield to another sound event that is already playing. If a sound cannot be played because the resource needed to generate that sound is busy playing another sound, the function immediately returns FALSE without playing the requested sound.
If this flag is not specified, PlaySound attempts to stop the currently playing sound so that the device can be used to play the new sound. |
| SND_NOWAIT | If the driver is busy, return immediately without playing the sound. |
| SND_PURGE | Not supported. |
| SND_RESOURCE | The pszSound parameter is a resource identifier; hmod must identify the instance that contains the resource.
For more information, see Playing WAVE Resources. |
| SND_SENTRY | Requires Windows Vista or later. If this flag is set, the function triggers a SoundSentry event when the sound is played.
SoundSentry is an accessibility feature that causes the computer to display a visual cue when a sound is played. If the user did not enable SoundSentry, the visual cue is not displayed. |
| SND_SYNC | The sound is played synchronously, and PlaySound returns after the sound event completes. This is the default behavior. |
| SND_SYSTEM | Requires Windows Vista or later. If this flag is set, the sound is assigned to the audio session for system notification sounds. The system volume-control program (SndVol) displays a volume slider that controls system notification sounds. Setting this flag puts the sound under the control of that volume slider.
If this flag is not set, the sound is assigned to the default audio session for the application's process. For more information, see the documentation for the Core Audio APIs in the Windows SDK. |
Return Values
Returns TRUE if successful or FALSE otherwise.
Remarks
The sound specified by pszSound must fit into available physical memory and be playable by an installed waveform-audio device driver.
PlaySound searches the following directories for sound files: the current directory; the Windows directory; the Windows system directory; directories listed in the PATH environment variable; and the list of directories mapped in a network. For more information about the directory search order, see the documentation for the OpenFile function. If the function cannot find the specified sound and the SND_NODEFAULT flag is not specified, PlaySound uses the default system event sound instead. If the function can find neither the system default entry nor the default sound, it makes no sound and returns FALSE.
If the SND_ALIAS_ID flag is specified in fdwSound, the pszSound parameter must be one of the following values.
| Value | Description |
| SND_ALIAS_SYSTEMASTERISK | "SystemAsterisk" event. |
| SND_ALIAS_SYSTEMDEFAULT | "SystemDefault" event. |
| SND_ALIAS_SYSTEMEXCLAMATION | "SystemExclamation" event. |
| SND_ALIAS_SYSTEMEXIT | "SystemExit" event. |
| SND_ALIAS_SYSTEMHAND | "SystemHand" event. |
| SND_ALIAS_SYSTEMQUESTION | "SystemQuestion" event. |
| SND_ALIAS_SYSTEMSTART | "SystemStart" event. |
| SND_ALIAS_SYSTEMWELCOME | "SystemWelcome" event. |
Windows 95/98/Me: PlaySoundW is supported by the Microsoft Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.
Example Code
The following example plays a sound file:
PlaySound(TEXT("recycle.wav"), NULL, SND_FILENAME);
The following example plays a sound-file resource:
PlaySound(
MAKEINTRESOURCE(IDR_WAVE1),
GetModuleHandle(NULL),
SND_RESOURCE);
The following example plays a system-event sound:
PlaySound(TEXT("SystemStart"), NULL, SND_ALIAS);
The following example is equivalent to the previous example, but uses an identifier for the system event:
PlaySound((LPCTSTR)SND_ALIAS_SYSTEMSTART, NULL, SND_ALIAS_ID);
The following example plays the sound for an application-specific alias in the registry:
PlaySound(TEXT("MyAppSound"), NULL, SND_ALIAS | SND_APPLICATION);
The following example stops playback of a sound that is playing asynchronously:
PlaySound(NULL, 0, 0);
Requirements
** Windows NT/2000/XP:** Included in Windows NT 3.1 and later.
** Windows 95/98/Me:** Included in Windows 95 and later.
** Header:** Declared in Mmsystem.h; include Windows.h.
** Library:** Use Winmm.lib.
** Unicode:** Implemented as Unicode and ANSI versions on Windows NT/2000/XP. Also supported by Microsoft Layer for Unicode.
See Also