{"id":10049,"library":"playsound","title":"playsound","description":"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.","status":"maintenance","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/TaylorSMarks/playsound","tags":["audio","sound","playback","cross-platform","no-dependencies","blocking"],"install":[{"cmd":"pip install playsound","lang":"bash","label":"Install playsound"}],"dependencies":[],"imports":[{"symbol":"playsound","correct":"from playsound import playsound"}],"quickstart":{"code":"import os\nimport tempfile\nfrom playsound import playsound\n\n# Create a dummy WAV file for demonstration\n# (playsound has no stop/pause, so a very short sound is ideal)\n# In a real scenario, use an actual sound file like 'path/to/my_sound.wav'\n# NOTE: For Windows, WAV is the most reliable format. MP3 support is limited.\n\ntry:\n    with tempfile.NamedTemporaryFile(suffix=\".wav\", delete=False) as tmp_file:\n        tmp_file_name = tmp_file.name\n        # Minimal WAV header + 1 second of silent audio for demonstration\n        # This is a very basic valid WAV header for a mono 16-bit 44.1kHz sound\n        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'\n        tmp_file.write(wav_header)\n        tmp_file.flush()\n\n    print(f\"Playing sound from: {tmp_file_name}\")\n    playsound(tmp_file_name)\n    print(\"Sound playback finished.\")\n\nfinally:\n    if 'tmp_file_name' in locals() and os.path.exists(tmp_file_name):\n        os.remove(tmp_file_name)\n        print(f\"Cleaned up temporary file: {tmp_file_name}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"To play sound asynchronously, wrap `playsound()` in a separate thread: `import threading; threading.Thread(target=playsound, args=('path/to/sound.mp3',)).start()`","message":"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.","severity":"gotcha","affected_versions":"1.x.x"},{"fix":"Install required GStreamer packages. Example for Debian/Ubuntu: `sudo apt-get install gstreamer1.0-plugins-good gstreamer1.0-alsa`","message":"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.","severity":"gotcha","affected_versions":"1.x.x"},{"fix":"For granular control over sound playback (stop, pause, volume), consider using libraries like `pygame.mixer` or `pydub` (which often requires `ffmpeg`).","message":"`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.","severity":"gotcha","affected_versions":"1.x.x"},{"fix":"For maximum compatibility, convert audio files to WAV format. Always test your chosen format on your target operating systems.","message":"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.","severity":"gotcha","affected_versions":"1.x.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.x.x"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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).","error":"playsound.PlaysoundException: Error 263 (Cannot play specified file.  The file might not exist or is not a valid sound file for this player.)"},{"fix":"Install the library using pip: `pip install playsound`","cause":"The `playsound` library has not been installed in your Python environment.","error":"ImportError: No module named 'playsound'"},{"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()`","cause":"The `playsound()` function is blocking by design, meaning it pauses your script's execution until the entire sound file has finished playing.","error":"My Python script freezes or hangs after calling playsound()."},{"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).","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.","error":"g_object_unref: assertion 'G_IS_OBJECT (object)' failed"},{"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.","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).","error":"Sound does not play, or there is no audio output, but no error is shown."}]}