PlaySound function (Windows)

Switch View :

ScriptFree

PlaySound function

Applies to: desktop apps only

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.)

Syntax

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 in the same process. 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 any sound that is currently playing in the same process. Sounds played in other processes are not affected.
SND_NOWAIT	Not supported. Note Previous versions of the documentation implied incorrectly that this flag is supported. The function ignores this flag.
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	Note 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	Note 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.

Return value

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. 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.

The SND_ASYNC flag causes PlaySound to return immediately without waiting for the sound to finish playing. If you combine the SND_MEMORY and SND_ASYNC flags, the memory buffer that contains the sound must remain valid until the sound has completed playing.

Examples

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

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Mmsystem.h (include Windows.h)
Library	Winmm.lib
DLL	Winmm.dll
Unicode and ANSI names	PlaySoundW (Unicode) and PlaySoundA (ANSI)

I am using VS2010 and try to complie a simple project to play .wav file. I use the following code to play .wav file:

PlaySound("whistle.wav",0,0);

and get the following compiler error:

error C3861: 'PlaySound': identifier not found

Do I need to include any header files or library in order to compile? I follow the direction from the MSDN library http://msdn.microsoft.com/en-us/library/dd743680(v=VS.85).aspx

Please advise.

Thanks,
Brian

webJose

About PlaySound in CodeBlocks

I've been trying to play "Pacman.wav" which is a Wave file obviously, and I can't manage to play it, I'm using CodeBlocks and a GNU GCC compiler on a Windows 7 OS, I would be grateful if anybody can post an example of how to do this ASAP $0PS: I already red the clsSound Class solution but it's for VB and I'm still a beginner in c++. thanks in advance$0

A. M. R.: Post requests for help @ http://social.msdn.microsoft.com/Forums.

webJose

There is an inconsistency in the information about SND_PURGE

In the first paragraph of the explanation of the pszSound parameter it clearly states that you use SND_PURGE to stop non-waveform sounds, but the table of flags clearly state that SND_PURGE is not supported.

Which one is it? Microsoft, please update/correct.

-eVe-

Playing 'embedded resource' WAV files from a VB.NET application

In a VB.NET application that plays WAV sounds asynchronously, using the SoundPlayer class or the Win32 PlaySound call, the 'garbage collector' may free and reuse the memory before the sound has finished. This situation is easy to recognise, and hard to forget: it sounds hideous. A working solution is the following 'clsSound' class:

-------------------------------------------------
Imports System.IO

Class clsSound
    Declare Auto Function PlaySound Lib "winmm.dll" (ByVal data As Byte(), ByVal hmod As Integer, ByVal flags As Integer) As Integer
    Public Const SND_ASYNC As UInt32 = &H1
    Public Const SND_MEMORY As UInt32 = &H4
    Public Const SND_LOOP As UInt32 = &H8
    Private Shared coWav As New Collection
    Private Shared bInit As Boolean = False

    Public Sub New()
        If bInit = False Then
            bInit = True
            Dim assem As System.Reflection.Assembly = System.Reflection.Assembly.GetExecutingAssembly()
            Dim sWav As String, sRes() As String = assem.GetManifestResourceNames()
            For Each sWav In sRes
                If sWav.EndsWith(".wav") Then
                    Dim stWav As Stream = assem.GetManifestResourceStream(sWav)
                    If stWav IsNot Nothing Then
                        Dim data(stWav.Length) As Byte
                        stWav.Read(data, 0, stWav.Length)
                        coWav.Add(data, sWav)
                        'System.Diagnostics.Debug.WriteLine("WAV loaded: " & sWav & ", size: " & stWav.Length.ToString)
                    End If
                End If
            Next
        End If
    End Sub

    Public Sub PlayWav(ByVal sName As String, Optional ByVal bLoop As Boolean = False)
        Dim sWav As String = "<your-application-root>." & sName & ".wav"
        Dim uiFlags As UInt32 = SND_ASYNC + SND_MEMORY
        If bLoop = True Then uiFlags += SND_LOOP
        If coWav.Contains(sWav) Then
            PlaySound(Nothing, 0, 0) '- stop any sound playing
            PlaySound(coWav(sWav), 0, uiFlags) '- start the sound
        Else
            MsgBox("Resource not found (Embedded?): " & sName, MsgBoxStyle.Critical)
        End If
    End Sub

End Class

This way all your embedded sounds are pre-loaded in memory and stored in one Shared Collection.
Assuming you've allocated a clsSound Class in your main form ("Dim snd As New clsSound"), you can now play a sounds like this:

snd.PlayWav("groovy_intro")       '- play once, or
snd.PlayWav("groovy_intro", True) '- loop forever