Of course! The winsound module is Python's built-in way to generate simple sounds on Windows. It's perfect for creating beeps, alerts, or simple audio feedback in your scripts.

Here’s a complete guide, from the basics to more advanced usage.

The Basics: A Simple Beep

The core function is winsound.Beep(frequency, duration).

• frequency: The sound's pitch in Hertz (Hz). The range is typically from 37 to 32767. Lower numbers are lower-pitched sounds.
• duration: How long the sound plays in milliseconds (ms). 1000 ms = 1 second.

Example: A single beep

import winsound
import time
print("Beeping for 500ms at 1000 Hz...")
winsound.Beep(1000, 500)  # Beep at 1000 Hz for 0.5 seconds
print("Done.")

Common Use Cases

a) Alerting the User (e.g., after a long task)

This is a very common pattern. You run a script that takes a while, and it beeps when it's finished.

import winsound
import time
print("Starting a 3-second task...")
time.sleep(3)  # Simulate a long-running task
print("Task complete! Here is your alert.")
# A short, high-pitched beep to get attention
winsound.Beep(2000, 200)

b) Different Tones for Different Events

You can use different frequencies to signal different types of events, like errors, warnings, or success.

import winsound
def alert_success():
    """A pleasant, ascending two-tone beep."""
    winsound.Beep(523, 150)  # C5
    winsound.Beep(659, 150)  # E5
    winsound.Beep(784, 300)  # G5
def alert_error():
    """A harsh, low beep."""
    winsound.Beep(200, 500)
def alert_warning():
    """A medium, repeated beep."""
    for _ in range(3):
        winsound.Beep(800, 200)
        time.sleep(100) # A short pause between beeps
# --- Example Usage ---
print("Simulating a successful operation...")
alert_success()
print("\nSimulating a warning...")
alert_warning()
print("\nSimulating an error...")
alert_error()

Playing System Sounds (Windows Only)

winsound can also play standard system sounds. This is very useful for integrating with the OS's existing audio cues.

You use winsound.MessageBeep().

• winsound.MessageBeep(): Plays the default "asterisk" sound.
• winsound.MessageBeep(winsound.MB_ICONASTERISK): Plays the "information" sound.
• winsound.MessageBeep(winsound.MB_ICONEXCLAMATION): Plays the "exclamation" or "warning" sound.
• winsound.MessageBeep(winsound.MB_ICONQUESTION): Plays the "question" sound.
• winsound.MessageBeep(winsound.MB_ICONHAND): Plays the "critical stop" or "error" sound.

Example:

import winsound
print("Playing default system sound...")
winsound.MessageBeep()
print("\nPlaying the system 'Exclamation' sound...")
winsound.MessageBeep(winsound.MB_ICONEXCLAMATION)
print("\nPlaying the system 'Error' sound...")
winsound.MessageBeep(winsound.MB_ICONHAND)

Cross-Platform Alternative: os.system

The winsound module, as the name suggests, only works on Windows. If you want your script to be compatible with macOS and Linux, you need a different approach.

A simple, cross-platform method is to use the os.system() command to call the system's command-line beeper.

• On Linux: Use paplay or beep
• On macOS: Use afplay

Example: A cross-platform beep function

import os
import platform
def beep_cross_platform(frequency=1000, duration=500):
    """
    Beeps in a cross-platform way.
    Tries to use winsound on Windows, falls back to system commands on others.
    """
    system = platform.system()
    if system == "Windows":
        import winsound
        winsound.Beep(frequency, duration)
    elif system == "Linux":
        # Use 'beep' if installed, otherwise 'paplay' with a generated tone
        # The 'beep' command is simple but may not be installed by default.
        # 'paplay' is more common.
        os.system(f'paplay --volume=65536 /usr/share/sounds/alsa/Front_Center.wav')
        # For a pure tone, you'd need a sound file or a more complex command.
        # A simpler fallback for a beep is:
        os.system(f'echo -e "\a"') # This just makes the terminal bell sound
    elif system == "Darwin": # macOS
        # Requires a .wav file. You can find one or generate one.
        # A simple system beep:
        os.system(f'afplay /System/Library/Sounds/Ping.aiff')
    else:
        print("Beeping not supported on this OS.")
# --- Example Usage ---
print("Attempting a cross-platform beep...")
beep_cross_platform(800, 300)

Note: The Linux/macOS examples above are simplified. For a pure tone on Linux, you might need to install the beep package (sudo apt-get install beep) or use a tool like sox. The macOS example uses a pre-installed sound file.

Limitations and Alternatives

• Windows Only: winsound.Beep() and MessageBeep() are not available on macOS or Linux.
• Simple Sounds Only: It cannot play MP3, WAV, or other audio files.
• Blocking: Beep() is a "blocking" call. Your script will pause and wait for the sound to finish playing before continuing.

For More Advanced Audio (Cross-Platform)

If you need to play actual audio files (like .wav, .mp3) or have more control over sound, you should use a dedicated library. The most popular one is playsound.

Install playsound:

pip install playsound==1.2.2

(Note: Newer versions have issues; 1.2.2 is a stable choice.)

Use playsound:

from playsound import playsound
import time
print("Playing a sound file...")
# Make sure you have a 'my_sound.wav' file in the same directory
# or provide the full path.
try:
    playsound('my_sound.wav')
    print("Playback finished.")
except Exception as e:
    print(f"Error playing sound: {e}")
print("Waiting 2 seconds...")
time.sleep(2)
print("Playing the system default bell sound...")
# This works on most terminals
print('\a') # This is the ASCII bell character

Summary