# 🔊 Play sounds in Python scripts
`play_sounds` provides a simple cross-platform API to play sounds in Python scripts. It includes a [synchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#synchronous-api) and an equivalent [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that is compatible with `asyncio` and `trio`.
For code examples, you can check out [`onhold`](https://github.com/alexdelorenzo/onhold) and [`ding`](https://github.com/alexdelorenzo/ding), or scroll down to the [Usage section](https://github.com/alexdelorenzo/play_sounds#usage).
# Why `play_sounds`?
[`boombox`](https://pypi.org/project/boombox/) is great and 90% of the way there, however it is limited to only playing WAV files on Windows. [`playsound`](https://pypi.org/project/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.
# Installation
```bash
$ python3 -m pip install play_sounds
```
# Usage
This library uses [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects when pointing to filenames and paths. It can use [`aiopath.AsyncPath`](https://github.com/alexdelorenzo/aiopath) objects, too.
There's a synchronous API and an [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that you can use with the `async/await` syntax and `asyncio`.
## Synchronous API
### Play a file
```python
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
```python
from time import sleep
from play_sounds import play_while_running, DEFAULT_SONG
WAIT: int = 60
with play_while_running(DEFAULT_SONG):
sleep(WAIT)
```
### Play a file after work completes
```python
from time import sleep
from play_sounds import play_after, DEFAULT_SOUND
with play_after(DEFAULT_SOUND): # blocks by default
sleep(WAIT)
# play without blocking
with play_after(DEFAULT_SOUND, block=False):
sleep(WAIT)
```
### Ring the [terminal bell](https://en.wikipedia.org/wiki/Bell_character)
```python
from play_sounds import bell, bell_after
# play bell
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](https://www.integralist.co.uk/posts/python-asyncio/#running-async-code-in-the-repl) using `python3 -m asyncio` or an [IPython shell](https://ipython.org/).
### Play a file
```python
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
```python
from asyncio import sleep
from play_sounds import play_while_running_async, DEFAULT_SONG
async with play_while_running_async(DEFAULT_SONG):
await sleep(WAIT)
```
### Play a file after work completes
```python
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(WAIT)
# play without blocking
async with play_after_async(DEFAULT_SOUND, block=False):
await sleep(WAIT)
```
# Support
Want to support this project and [other open-source projects](https://github.com/alexdelorenzo) like it?
<a href="https://www.buymeacoffee.com/alexdelorenzo" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60px" style="height: 60px !important;width: 217px !important;max-width:25%" ></a>
# Copyright
See `CREDIT.md`.
# License
See `LICENSE`.
Raw data
{
"_id": null,
"home_page": "https://github.com/alexdelorenzo/play_sounds",
"name": "play-sounds",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Alex DeLorenzo",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/35/f6/2f07208726d6246e4171431134d2b292d8b48a971867cfe7b76ce49a9232/play_sounds-0.6.0.tar.gz",
"platform": null,
"description": "# \ud83d\udd0a Play sounds in Python scripts\n`play_sounds` provides a simple cross-platform API to play sounds in Python scripts. It includes a [synchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#synchronous-api) and an equivalent [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that is compatible with `asyncio` and `trio`.\n\nFor code examples, you can check out [`onhold`](https://github.com/alexdelorenzo/onhold) and [`ding`](https://github.com/alexdelorenzo/ding), or scroll down to the [Usage section](https://github.com/alexdelorenzo/play_sounds#usage).\n\n# Why `play_sounds`?\n[`boombox`](https://pypi.org/project/boombox/) is great and 90% of the way there, however it is limited to only playing WAV files on Windows. [`playsound`](https://pypi.org/project/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.\n\nNeither `boombox` or `playsound` provide `asyncio` and `async/await` compatible APIs, but `play_sounds` does.\n\nIf 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.\n\n# Installation\n```bash\n$ python3 -m pip install play_sounds\n```\n\n# Usage\nThis library uses [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects when pointing to filenames and paths. It can use [`aiopath.AsyncPath`](https://github.com/alexdelorenzo/aiopath) objects, too.\n\nThere's a synchronous API and an [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that you can use with the `async/await` syntax and `asyncio`. \n\n## Synchronous API\n### Play a file\n```python\nfrom play_sounds import play_file, DEFAULT_SONG\n\n\nplay_file(DEFAULT_SONG) # blocks by default\n\n# play without blocking\nplay_file(DEFAULT_SONG, block=False) \n```\n\n### Play while work completes\n```python\nfrom time import sleep\nfrom play_sounds import play_while_running, DEFAULT_SONG\n\n\nWAIT: int = 60\n\n\nwith play_while_running(DEFAULT_SONG):\n sleep(WAIT)\n```\n\n### Play a file after work completes\n```python\nfrom time import sleep\nfrom play_sounds import play_after, DEFAULT_SOUND\n\n\nwith play_after(DEFAULT_SOUND): # blocks by default\n sleep(WAIT)\n\n# play without blocking\nwith play_after(DEFAULT_SOUND, block=False):\n sleep(WAIT)\n```\n\n### Ring the [terminal bell](https://en.wikipedia.org/wiki/Bell_character)\n```python\nfrom play_sounds import bell, bell_after\n\n\n# play bell\nbell()\n\n# ensure the bell is played even if an exception is thrown\nwith bell_after():\n raise Exception(\"Bye\")\n```\n\n## Asynchronous API\nTo run the following examples with top-level `await` expressions, [launch an asynchronous Python REPL](https://www.integralist.co.uk/posts/python-asyncio/#running-async-code-in-the-repl) using `python3 -m asyncio` or an [IPython shell](https://ipython.org/).\n\n### Play a file\n```python\nfrom play_sounds import play_file_async, DEFAULT_SONG\n\n\nawait play_file_async(DEFAULT_SONG) # blocks by default\n\n# play without blocking\nawait play_file_async(DEFAULT_SONG, block=False) \n```\n\n### Play while work completes\n```python\nfrom asyncio import sleep\nfrom play_sounds import play_while_running_async, DEFAULT_SONG\n\n\nasync with play_while_running_async(DEFAULT_SONG):\n await sleep(WAIT)\n```\n\n### Play a file after work completes\n```python\nfrom asyncio import sleep\nfrom play_sounds import play_after_async, DEFAULT_SOUND\n\n\nasync with play_after_async(DEFAULT_SOUND): # blocks by default\n await sleep(WAIT)\n\n# play without blocking\nasync with play_after_async(DEFAULT_SOUND, block=False):\n await sleep(WAIT)\n```\n\n# Support\nWant to support this project and [other open-source projects](https://github.com/alexdelorenzo) like it?\n\n<a href=\"https://www.buymeacoffee.com/alexdelorenzo\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" height=\"60px\" style=\"height: 60px !important;width: 217px !important;max-width:25%\" ></a>\n\n# Copyright\nSee `CREDIT.md`.\n\n# License\nSee `LICENSE`.\n",
"bugtrack_url": null,
"license": "LGPL-3.0",
"summary": "\ud83d\udd0a Play music and sounds in your Python scripts",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/alexdelorenzo/play_sounds"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2aa1a8f5e46e6036a99ae9d25f4d848eeb8bf66119d82f98f257b7d051809fae",
"md5": "5633737b35c5bf1bcfeb4c7ca0c4209d",
"sha256": "20bce95cb24e2d3e8ae84b8a4f0a92ae7a34e5d59d9c50ea571f72ed42733ab2"
},
"downloads": -1,
"filename": "play_sounds-0.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5633737b35c5bf1bcfeb4c7ca0c4209d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 8933,
"upload_time": "2024-01-18T04:32:19",
"upload_time_iso_8601": "2024-01-18T04:32:19.889936Z",
"url": "https://files.pythonhosted.org/packages/2a/a1/a8f5e46e6036a99ae9d25f4d848eeb8bf66119d82f98f257b7d051809fae/play_sounds-0.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35f62f07208726d6246e4171431134d2b292d8b48a971867cfe7b76ce49a9232",
"md5": "f829f0d147c9b752f6f78056cf521993",
"sha256": "814f920ff5776a5cb5aa18b537491a78ad835312bd7dc3b2366c4bcc7176d6dc"
},
"downloads": -1,
"filename": "play_sounds-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "f829f0d147c9b752f6f78056cf521993",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8243,
"upload_time": "2024-01-18T04:32:21",
"upload_time_iso_8601": "2024-01-18T04:32:21.535008Z",
"url": "https://files.pythonhosted.org/packages/35/f6/2f07208726d6246e4171431134d2b292d8b48a971867cfe7b76ce49a9232/play_sounds-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 04:32:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexdelorenzo",
"github_project": "play_sounds",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "anyio",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "boombox",
"specs": [
[
"==",
"0.56"
]
]
},
{
"name": "playsound",
"specs": []
},
{
"name": "PyObjc",
"specs": [
[
">=",
"6.2.2"
]
]
}
],
"lcname": "play-sounds"
}
JSON
