playsound

Pure Python, cross platform, single function module with no dependencies for playing sounds. Provides a simple interface for playing audio files across Windows, macOS, and Linux platforms without requiring external audio libraries.

Package Information

• Package Name: playsound
• Language: Python
• Installation: pip install playsound

Core Imports

from playsound import playsound

For exception handling:

from playsound import playsound, PlaysoundException

Basic Usage

from playsound import playsound

# Play a sound file (blocking - waits until playback completes)
playsound('/path/to/your/sound/file.mp3')

# Play a sound file asynchronously (non-blocking)
playsound('/path/to/your/sound/file.wav', block=False)

# With error handling
from playsound import playsound, PlaysoundException

try:
    playsound('/path/to/sound.mp3')
except PlaysoundException as e:
    print(f"Error playing sound: {e}")

Architecture

playsound uses platform-specific implementations automatically selected at import time:

• Windows: Uses windll.winmm MCI commands for audio playback
• macOS: Uses AppKit.NSSound (falls back to subprocess if PyObjC unavailable)
• Linux: Uses GStreamer (gi.repository.Gst) (falls back to subprocess if unavailable)

The module handles path formatting, special characters, and provides consistent behavior across Python 2.3+ and Python 3.x versions.

Capabilities

Sound Playback

Plays audio files with cross-platform compatibility and automatic platform detection.

def playsound(sound, block=True):
    """
    Play a sound file using platform-appropriate audio system.
    
    Args:
        sound (str or Path-like): Path to sound file (local path or URL)
        block (bool): If True, wait until playback completes; if False, play asynchronously
    
    Returns:
        None
    
    Raises:
        PlaysoundException: On playback errors, file not found, or audio system failures
    """

Supported Formats: MP3, WAV (tested on all platforms), other formats may work depending on platform capabilities

Platform Support:

• Windows XP and newer
• macOS 10.5 and newer
• Linux distributions with standard desktop environments

Exception Handling

Custom exception for playsound-specific errors.

class PlaysoundException(Exception):
    """
    Exception raised for playsound-specific errors.
    
    Raised when:
    - Sound file cannot be found
    - Audio format is unsupported
    - Platform audio system encounters errors
    - Invalid file paths or URLs
    """

Command Line Interface

playsound can be used directly from the command line:

python playsound.py /path/to/sound/file.mp3

When used from command line, playback is always synchronous (blocking).

Path Support

Supported Path Types:

• String file paths: '/path/to/file.mp3'
• pathlib.Path objects: Path('/path/to/file.mp3')
• URLs: 'http://example.com/sound.mp3' (platform dependent)

Special Character Handling: On Windows, paths containing special characters "\'() are automatically handled by creating temporary file copies.

Platform-Specific Behavior

Windows

• Uses Media Control Interface (MCI) commands via windll.winmm
• Supports MP3, WAV, and potentially other Windows Media formats
• Automatically handles paths with special characters
• No additional dependencies required

macOS

• Primary: Uses AppKit.NSSound (requires PyObjC: pip install PyObjC)
• Fallback: Subprocess call to system Python 2.7 if PyObjC unavailable
• Supports anything QuickTime can play
• URL encoding for file paths with special characters

Linux

• Primary: Uses GStreamer via gi.repository.Gst (requires pip install pygobject)
• Fallback: Subprocess call to system Python 3 if GStreamer unavailable
• Supports formats based on installed GStreamer plugins
• Tested on Ubuntu and ElementaryOS

Error Conditions

Common scenarios that raise PlaysoundException:

• File not found: Specified audio file doesn't exist
• Format unsupported: Audio format not supported by platform audio system
• Audio system failure: Platform-specific audio system errors
• Invalid paths: Malformed file paths or inaccessible URLs
• Missing dependencies: When fallback subprocess methods also fail

Dependencies

Core Dependencies: None (pure Python)

Optional Dependencies (for optimal performance):

• macOS: PyObjC - pip install PyObjC
• Linux: pygobject - pip install pygobject

Without optional dependencies, playsound falls back to subprocess methods with system Python interpreters.

Compatibility

• Python Versions: 2.3 through 3.9+ (broad compatibility)
• Operating Systems: Windows, macOS, Linux
• Thread Safety: Safe for non-blocking (asynchronous) playback
• Encoding: Handles Unicode file paths and various text encodings