playsound

1.3.0 · maintenance · verified Fri Apr 17

playsound is a pure Python, cross-platform module designed for playing sounds with a single function call. It aims for simplicity and has no external Python dependencies. The current version is 1.3.0, released in 2021, indicating a stable but currently dormant release cadence.

Common errors

```
playsound.PlaysoundException: Error 263 (Cannot play specified file.  The file might not exist or is not a valid sound file for this player.)
```
cause This error typically occurs on Windows when the specified sound file path is incorrect, the file does not exist, or the file format is not supported (e.g., trying to play an MP3 without necessary codecs, or a corrupt file).

fix Double-check the file path for typos and ensure the file exists. Confirm the audio file is a valid WAV. For MP3/OGG, consider converting to WAV or using a different library on Windows.
```
ImportError: No module named 'playsound'
```
cause The `playsound` library has not been installed in your Python environment.

fix Install the library using pip: `pip install playsound`
```
My Python script freezes or hangs after calling playsound().
```
cause The `playsound()` function is blocking by design, meaning it pauses your script's execution until the entire sound file has finished playing.

fix If you need non-blocking playback, run `playsound()` in a separate thread: `import threading; threading.Thread(target=playsound, args=('path/to/sound.mp3',)).start()`
```
g_object_unref: assertion 'G_IS_OBJECT (object)' failed
```
cause This error or similar GStreamer-related messages often appear on Linux when the necessary GStreamer system packages are not installed, which `playsound` uses for audio playback.

fix Install the required GStreamer plugins. For Debian/Ubuntu-based systems, run: `sudo apt-get install gstreamer1.0-plugins-good gstreamer1.0-alsa` (or equivalent for your distribution).
```
Sound does not play, or there is no audio output, but no error is shown.
```
cause This can happen due to an unsupported audio format for the specific OS, an invalid or inaccessible file path (even if it exists), or missing system dependencies (especially on Linux with GStreamer).

fix Verify the file path is absolute and correct. Ensure the audio format (e.g., WAV, MP3) is supported on your operating system. Check Linux GStreamer dependencies. Try a simple WAV file first for troubleshooting.

Warnings

gotcha The `playsound()` function is blocking by default. It will pause the execution of your Python script until the sound finishes playing. For non-blocking playback, you must use Python's `threading` module.
Fix: To play sound asynchronously, wrap `playsound()` in a separate thread: `import threading; threading.Thread(target=playsound, args=('path/to/sound.mp3',)).start()`
gotcha On Linux, `playsound` relies on the GStreamer media framework. You need to install system-level GStreamer packages (e.g., `gstreamer1.0-plugins-good` and `gstreamer1.0-alsa` on Debian/Ubuntu) for MP3/OGG support. Without them, playback will fail silently or with GStreamer-related errors.
Fix: Install required GStreamer packages. Example for Debian/Ubuntu: `sudo apt-get install gstreamer1.0-plugins-good gstreamer1.0-alsa`
gotcha `playsound` does not provide any functionality to stop, pause, or control the volume of a sound once it has started playing. The sound will play to its completion.
Fix: For granular control over sound playback (stop, pause, volume), consider using libraries like `pygame.mixer` or `pydub` (which often requires `ffmpeg`).
gotcha File format support is platform-dependent. WAV files generally work reliably across all platforms. MP3 files are supported on macOS and Linux (with GStreamer) but may not work consistently on Windows, which primarily relies on `winsound` for WAV.
Fix: For maximum compatibility, convert audio files to WAV format. Always test your chosen format on your target operating systems.
gotcha Error reporting can be minimal or cryptic. If a file is not found, or the format is unsupported, playsound might raise a generic `PlaysoundException` with an obscure error code (e.g., `Error 263` on Windows) or simply fail silently.
Fix: Always ensure the file path is correct and the file exists. Verify the file format is supported on the target OS. Wrap `playsound` calls in `try...except PlaysoundException:` blocks to catch specific errors if they are raised.

Install

pip install playsound Install playsound

Imports

playsound
```
from playsound import playsound
```

Quickstart

This example demonstrates how to play a sound file using `playsound`. It dynamically creates a small, silent WAV file for cross-platform compatibility and then plays it. Replace `tmp_file_name` with the actual path to your sound file (e.g., `playsound('path/to/your/audio.mp3')`). Be aware that `playsound` blocks the execution of the script until the sound finishes, and specific audio formats may have platform-dependent support.

import os
import tempfile
from playsound import playsound

# Create a dummy WAV file for demonstration
# (playsound has no stop/pause, so a very short sound is ideal)
# In a real scenario, use an actual sound file like 'path/to/my_sound.wav'
# NOTE: For Windows, WAV is the most reliable format. MP3 support is limited.

try:
    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp_file:
        tmp_file_name = tmp_file.name
        # Minimal WAV header + 1 second of silent audio for demonstration
        # This is a very basic valid WAV header for a mono 16-bit 44.1kHz sound
        wav_header = b'RIFF\x2c\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00D\xac\x00\x00\x88\x58\x01\x00\x02\x00\x10\x00data\x08\x00\x00\x00\x00\x00\x00\x00'
        tmp_file.write(wav_header)
        tmp_file.flush()

    print(f"Playing sound from: {tmp_file_name}")
    playsound(tmp_file_name)
    print("Sound playback finished.")

finally:
    if 'tmp_file_name' in locals() and os.path.exists(tmp_file_name):
        os.remove(tmp_file_name)
        print(f"Cleaned up temporary file: {tmp_file_name}")

view raw JSON →