PlaySound function

  • [アーティクル]

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 [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

 Mmsystem.h (include Windows.h)

Library

 Winmm.lib

DLL

 Winmm.dll

Unicode and ANSI names

PlaySoundW (Unicode) and PlaySoundA (ANSI)

See also

Waveform Audio

Waveform Functions