# Function Reference

# _SoundOpen

Opens a sound file for use with other _Sound functions

#include <Sound.au3>
_SoundOpen ( $sFilePath )

## Parameters

$sFilePath | Path to sound file

## Return Value

Success: | a 4-element array containing the following information: $aArray[0] = Sound file ID string $aArray[1] = VBR length correction factor $aArray[2] = VBR timing correction factor $aArray[3] = Sound ID marker
Failure: | 0 and sets the @error flag to non-zero.
@error: | 1 - MCI open error 2 - File does not exist
@extended: | Integer other than 0 = MCI Error

## Remarks

Although many of the _Sound...() functions will accept the filename as a parameter, if there is a possibility of the file being VBR (variable bit rate) encoded it is highly recommended to use _SoundOpen() initially and then use the returned array as the identity parameter in other _Sound...() functions. This is because the MCI DLL assumes all files are CBR (constant bit rate) encoded and produces incorrect results from those _Sound...() functions dealing with length and position when the sound file has been VBR (variable bit rate) encoded. If using the array as the ID parameter with the _Sound...() functions which alter the VBR correction factors (_SoundStop()) the ID array will be updated when needed.
The individual elements of the returned array have no utility outside the _Sound functions and their internal use is transparent to the user.

## Related

_SoundClose, _SoundLength, _SoundPause, _SoundPlay, _SoundPos, _SoundResume, _SoundStatus, _SoundStop

## Example

    #include <MsgBoxConstants.au3>
    #include <Sound.au3>

    Local $aSound = _SoundOpen(@WindowsDir & "\media\tada.wav")
    If @error = 2 Then
        MsgBox($MB_SYSTEMMODAL, "Error", "The file does not exist")
        Exit
    ElseIf @extended <> 0 Then
        Local $iExtended = @extended ; Assign because @extended will be set after DllStructCreate().
        Local $tText = DllStructCreate("char[128]")
        DllCall("winmm.dll", "short", "mciGetErrorStringA", "str", $iExtended, "struct*", $tText, "int", 128)
        MsgBox($MB_SYSTEMMODAL, "Error", "The open failed." & @CRLF & "Error Number: " & $iExtended & @CRLF & "Error Description: " & DllStructGetData($tText, 1) & @CRLF & "Please Note: The sound may still play correctly.")
    Else
        MsgBox($MB_SYSTEMMODAL, "Success", "The file opened successfully")
    EndIf

    _SoundClose($aSound)