Microsoft Developer Network

Audio Playback Sample (.NET C#)

This sample demonstrates how to play audio files using the Windows Multimedia APIs with C# in a .NET environment. It covers basic playback controls like play, pause, and stop, as well as volume control.

Overview

Playing audio is a common requirement in many applications. This sample utilizes the low-level multimedia APIs provided by Windows, wrapped within a C# class for easier management. The primary mechanism involves interacting with the Windows Multimedia API (winmm.dll) to control audio playback devices.

Features

• Loading and playing WAV files.
• Basic playback controls: Play, Pause, Stop.
• Volume adjustment.
• Error handling for file operations.

Code Snippet

The core functionality is encapsulated in a `WavPlayer` class. Here's a simplified look at the class structure and key methods:

using System;
using System.Runtime.InteropServices;
using System.Threading;

public class WavPlayer
{
    // Import necessary WinMM functions
    [DllImport("winmm.dll")]
    private static extern long PlaySound(string szSound, IntPtr hModule, uint dwFlags);

    // Constants for PlaySound flags
    private const uint SND_FILENAME = 0x00020000;
    private const uint SND_ASYNC = 0x00000001;
    private const uint SND_PURGE = 0x00000002;
    private const uint SND_LOOP = 0x00000002; // Not used in this basic example

    private string currentFilePath;
    private bool isPlaying = false;
    private bool isPaused = false;

    public WavPlayer()
    {
        // Initialize anything needed
    }

    public bool Play(string filePath)
    {
        if (string.IsNullOrEmpty(filePath))
        {
            Console.WriteLine("Error: File path is null or empty.");
            return false;
        }

        Stop(); // Stop any currently playing sound

        try
        {
            long result = PlaySound(filePath, IntPtr.Zero, SND_FILENAME | SND_ASYNC);
            if (result == 0) // PlaySound returns 0 on failure for some flags
            {
                Console.WriteLine($"Error playing sound. Check if file exists and is a valid WAV format: {filePath}");
                return false;
            }
            currentFilePath = filePath;
            isPlaying = true;
            isPaused = false;
            Console.WriteLine($"Playing: {filePath}");
            return true;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception during playback: {ex.Message}");
            return false;
        }
    }

    public void Pause()
    {
        if (isPlaying && !isPaused)
        {
            // The winmm.dll PlaySound function doesn't have a direct 'pause' flag.
            // A common workaround for simple WAVs is to stop and then resume from the beginning.
            // For more advanced control (like true pause/resume), you'd typically use MCI (Media Control Interface)
            // or DirectSound/WASAPI. This example keeps it simple with PlaySound.
            // For demonstration, we'll just stop and note the limitation.
            Console.WriteLine("Pause functionality not directly supported by PlaySound. Stopping.");
            Stop(); // Simulate pause by stopping
            isPaused = true; // Indicate intent to resume later, though not implemented here.
        }
    }

    public void Resume()
    {
        if (isPlaying && isPaused && !string.IsNullOrEmpty(currentFilePath))
        {
            Console.WriteLine("Resuming playback is not directly supported by PlaySound. Re-starting from beginning.");
            Play(currentFilePath); // Re-start from beginning
            isPaused = false;
        }
    }

    public void Stop()
    {
        if (isPlaying || isPaused)
        {
            try
            {
                // SND_PURGE stops playback
                PlaySound(null, IntPtr.Zero, SND_PURGE);
                Console.WriteLine("Playback stopped.");
                isPlaying = false;
                isPaused = false;
                currentFilePath = null;
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Exception during stop: {ex.Message}");
            }
        }
    }

    public bool IsPlaying
    {
        get { return isPlaying; }
    }

    public bool IsPaused
    {
        get { return isPaused; }
    }

    // Note: Volume control is not directly provided by the basic PlaySound function.
    // For volume control, you would typically use the Mixer API or the Media Control Interface (MCI).
    // This is a significant limitation of using only PlaySound for advanced audio needs.
}

// Example Usage in a Form or Console App:
/*
public static class Program
{
    static void Main(string[] args)
    {
        WavPlayer player = new WavPlayer();
        string audioFile = "path/to/your/sample.wav"; // Replace with a valid WAV file path

        Console.WriteLine("Press P to Play, S to Stop, Q to Quit.");
        ConsoleKeyInfo key;

        do
        {
            key = Console.ReadKey(true); // true = don't display key

            switch (char.ToLower(key.KeyChar))
            {
                case 'p':
                    if (!player.IsPlaying)
                    {
                        player.Play(audioFile);
                    }
                    else
                    {
                        Console.WriteLine("Already playing.");
                    }
                    break;
                case 's':
                    player.Stop();
                    break;
                case 'q':
                    player.Stop();
                    break;
            }
        } while (char.ToLower(key.KeyChar) != 'q');

        Console.WriteLine("Exiting.");
    }
}
*/
            

Using the Code

1. Create a new C# project (e.g., a Console Application or Windows Forms Application).
2. Add the `WavPlayer` class to your project.
3. In your application's code, instantiate the `WavPlayer` class.
4. Call the `Play()` method with the path to a valid WAV audio file.
5. Use `Stop()` to halt playback.
6. Note the limitations of `PlaySound` regarding true pause/resume and volume control. For these, consider more advanced Windows APIs like MCI, DirectSound, or WASAPI.

Limitations and Alternatives

The `PlaySound` function is a very basic API for playing sounds. It is synchronous by default but can be used asynchronously (`SND_ASYNC`). However, it lacks features like:

• True Pause/Resume: `PlaySound` does not support pausing and resuming playback. A common workaround is to stop and restart, but this is not seamless.
• Volume Control: There is no direct way to control the playback volume using `PlaySound`.
• Advanced Formats: It primarily supports WAV files. For MP3, WMA, or other formats, different APIs are required.
• Precise Control: For detailed control over audio streams, effects, or precise timing, consider using:
  • Media Control Interface (MCI): A higher-level API that supports various media types and playback controls.
  • DirectSound (Legacy): Part of DirectX, offering more advanced audio capabilities.
  • WASAPI (Windows Audio Session API): The modern, low-level audio API in Windows for direct hardware access.
  • .NET Multimedia Libraries: Libraries like `System.Media.SoundPlayer` (basic) or third-party libraries can offer simpler abstractions for common tasks.

Related APIs

API Name	Description
PlaySound	Basic Windows API function for playing system sounds or WAV files.
mciSendString	Function to send commands to the Media Control Interface (MCI).
waveOutOpen / waveOutWrite	Lower-level APIs for direct waveform audio output.
DirectSound	Component of DirectX for advanced audio playback.
WASAPI	Modern Windows API for low-level audio control.