0
# playsound
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: playsound
7
- **Language**: Python
8
- **Installation**: `pip install playsound`
9

10
## Core Imports
11

12
```python
13
from playsound import playsound
14
```
15

16
For exception handling:
17

18
```python
19
from playsound import playsound, PlaysoundException
20
```
21

22
## Basic Usage
23

24
```python
25
from playsound import playsound
26

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

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

33
# With error handling
34
from playsound import playsound, PlaysoundException
35

36
try:
37
    playsound('/path/to/sound.mp3')
38
except PlaysoundException as e:
39
    print(f"Error playing sound: {e}")
40
```
41

42
## Architecture
43

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

46
- **Windows**: Uses `windll.winmm` MCI commands for audio playback
47
- **macOS**: Uses `AppKit.NSSound` (falls back to subprocess if PyObjC unavailable)  
48
- **Linux**: Uses GStreamer (`gi.repository.Gst`) (falls back to subprocess if unavailable)
49

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

52
## Capabilities
53

54
### Sound Playback
55

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

58
```python { .api }
59
def playsound(sound, block=True):
60
    """
61
    Play a sound file using platform-appropriate audio system.
62
    
63
    Args:
64
        sound (str or Path-like): Path to sound file (local path or URL)
65
        block (bool): If True, wait until playback completes; if False, play asynchronously
66
    
67
    Returns:
68
        None
69
    
70
    Raises:
71
        PlaysoundException: On playback errors, file not found, or audio system failures
72
    """
73
```
74

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

77
**Platform Support**: 
78
- Windows XP and newer
79
- macOS 10.5 and newer  
80
- Linux distributions with standard desktop environments
81

82
### Exception Handling
83

84
Custom exception for playsound-specific errors.
85

86
```python { .api }
87
class PlaysoundException(Exception):
88
    """
89
    Exception raised for playsound-specific errors.
90
    
91
    Raised when:
92
    - Sound file cannot be found
93
    - Audio format is unsupported
94
    - Platform audio system encounters errors
95
    - Invalid file paths or URLs
96
    """
97
```
98

99
## Command Line Interface
100

101
playsound can be used directly from the command line:
102

103
```bash
104
python playsound.py /path/to/sound/file.mp3
105
```
106

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

109
## Path Support
110

111
**Supported Path Types**:
112
- String file paths: `'/path/to/file.mp3'`
113
- pathlib.Path objects: `Path('/path/to/file.mp3')`
114
- URLs: `'http://example.com/sound.mp3'` (platform dependent)
115

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

118
## Platform-Specific Behavior
119

120
### Windows
121
- Uses Media Control Interface (MCI) commands via `windll.winmm`
122
- Supports MP3, WAV, and potentially other Windows Media formats
123
- Automatically handles paths with special characters
124
- No additional dependencies required
125

126
### macOS
127
- Primary: Uses `AppKit.NSSound` (requires PyObjC: `pip install PyObjC`)
128
- Fallback: Subprocess call to system Python 2.7 if PyObjC unavailable
129
- Supports anything QuickTime can play
130
- URL encoding for file paths with special characters
131

132
### Linux  
133
- Primary: Uses GStreamer via `gi.repository.Gst` (requires `pip install pygobject`)
134
- Fallback: Subprocess call to system Python 3 if GStreamer unavailable
135
- Supports formats based on installed GStreamer plugins
136
- Tested on Ubuntu and ElementaryOS
137

138
## Error Conditions
139

140
Common scenarios that raise `PlaysoundException`:
141

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

148
## Dependencies
149

150
**Core Dependencies**: None (pure Python)
151

152
**Optional Dependencies** (for optimal performance):
153
- **macOS**: `PyObjC` - `pip install PyObjC`
154
- **Linux**: `pygobject` - `pip install pygobject`
155

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

158
## Compatibility
159

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