Skip to main content

🔊 Play music and sounds in your Python scripts

Project description

🔊 Play sounds in Python scripts

play_sounds provides a simple cross-platform API to play sounds in Python scripts. It includes a synchronous API and an equivalent asynchronous API.

For code examples, you can check out onhold and ding, or scroll down to the Usage section.


boombox is great and 90% of the way there, however it is limited to only playing WAV files on Windows. playsound will play other formats than WAV on Windows, but it requires GStreamer and PyGObject bindings on Linux, while boombox has several playback backends for Linux other than, and including, GStreamer.

Neither boombox or playsound provide asyncio and async/await compatible APIs, but play_sounds does.

If you're targeting multiple desktop platforms and don't want to get mired down in the details of when and where to use playsound or boombox, or if your project uses async/await, you can just reach for play_sounds and call it a day.


$ python3 -m pip install play_sounds


This library uses pathlib.Path objects when pointing to filenames and paths. It can use aiopath.AsyncPath objects, too.

There's a synchronous API and an asynchronous API that you can use with the async/await syntax and asyncio.

Synchronous API

Play a file

from play_sounds import play_file, DEFAULT_SONG

play_file(DEFAULT_SONG)  # blocks by default

# play without blocking
play_file(DEFAULT_SONG, block=False) 

Play while work completes

from time import sleep
from play_sounds import play_while_running, DEFAULT_SONG

with play_while_running(DEFAULT_SONG):

Play a file after work completes

from time import sleep
from play_sounds import play_after, DEFAULT_SOUND

with play_after(DEFAULT_SOUND):  # blocks by default

# play without blocking
with play_after(DEFAULT_SOUND, block=False):

Ring the terminal bell

from play_sounds import bell, bell_after

# play bell

# ensure the bell is played even if an exception is thrown
with bell_after():
  raise Exception("Bye")

Asynchronous API

To run the following examples with top-level await expressions, launch an asynchronous Python REPL using python3 -m asyncio or an IPython shell.

Play a file

from play_sounds import play_file_async, DEFAULT_SONG

await play_file_async(DEFAULT_SONG)  # blocks by default

# play without blocking
await play_file_async(DEFAULT_SONG, block=False) 

Play while work completes

from asyncio import sleep
from play_sounds import play_while_running_async, DEFAULT_SONG

async with play_while_running_async(DEFAULT_SONG):
  await sleep(60)

Play a file after work completes

from asyncio import sleep
from play_sounds import play_after_async, DEFAULT_SOUND

async with play_after_async(DEFAULT_SOUND):  # blocks by default
  await sleep(60)

# play without blocking
async with play_after_async(DEFAULT_SOUND, block=False):
  await sleep(60)


Want to support this project and other open-source projects like it?

Buy Me A Coffee





Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

play_sounds-0.5.0.tar.gz (6.0 kB view hashes)

Uploaded source

Built Distribution

play_sounds-0.5.0-py2.py3-none-any.whl (7.5 MB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page