# playsound3
[](https://pypi.org/project/playsound3)
[](https://pypi.org/project/playsound3)
Cross platform library to play sound files in Python.
## Installation
Install via pip:
```
pip install playsound3
```
## Quick Start
Once installed, you can use the playsound function to play sound files:
```python
from playsound3 import playsound
playsound("/path/to/sound/file.mp3")
# or use directly on URLs
playsound("http://url/to/sound/file.mp3")
```
## Documentation
The `playsound3` module contains a single function named `playsound`:
```python
def playsound(
sound: str | Path,
block: bool = True,
backend: str | None = None,
daemon: bool = True,
) -> Thread | None:
"""Play a sound file using an audio backend availabile in your system.
Args:
sound: Path or URL to the sound file. Can be a string or pathlib.Path.
block: If True, the function will block execution until the sound finishes playing.
If False, sound will play in a background thread.
backend: Name of the audio backend to use. Use None for automatic selection.
daemon: If True, and `block` is True, the background thread will be a daemon thread.
This means that the thread will stay alive even after the main program exits.
Returns:
If `block` is True, the function will return None after the sound finishes playing.
If `block` is False, the function will return the background thread object.
"""
...
```
It requires one argument: `sound` - the path to the file with the sound you'd like to play.
This should be a local file or a URL.
There's an optional second argument: `block` which is set to `True` by default.
Setting it to `False` makes the function run asynchronously.
You can manually specify a backend by passing its name as the third argument.
You can browse available backends by using `playsound3.AVAILABLE_BACKENDS`.
It is recommended to use the default value of `None` to let the library choose the best backend available.
## Supported systems
* **Linux** using one of the below backends, whichever is available:
* GStreamer
* FFmpeg
* aplay for .wav and mpg123 .mp3
* **Windows** using winmm.dll (built-in on Windows)
* **macOS** using afplay utility (built-in on macOS)
## Fork information
This repository was originally forked from [playsound](https://github.com/TaylorSMarks/playsound) library created by Taylor Marks. The original library is unfortunately not maintained anymore and doesn't accept pull requests. This library: `playsound3` is a major rewrite of the original, including its own set of tests hosted using GitHub Actions.
Compared to the original, `playsound3`:
* Drops support for Python 2
* Adheres to the latest PEP standards
* Offers multiple backends with a fallback mechanism if the default backend is not available
* Accepts contributions
Raw data
{
"_id": null,
"home_page": null,
"name": "playsound3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Szymon Mikler <sjmikler@gmail.com>",
"keywords": "audio, media, mp3, music, play, playsound, song, sound, wav, wave",
"author": null,
"author_email": "Szymon Mikler <sjmikler@gmail.com>, Taylor Marks <taylor@marksfam.com>",
"download_url": "https://files.pythonhosted.org/packages/23/d2/6fa6e87b1ff76267147beb9c1b65af5b6e751bbe9b2c53efc81504428694/playsound3-2.5.2.tar.gz",
"platform": null,
"description": "# playsound3\n\n[](https://pypi.org/project/playsound3)\n[](https://pypi.org/project/playsound3)\n\nCross platform library to play sound files in Python.\n\n## Installation\n\nInstall via pip:\n\n```\npip install playsound3\n```\n\n## Quick Start\n\nOnce installed, you can use the playsound function to play sound files:\n\n```python\nfrom playsound3 import playsound\n\nplaysound(\"/path/to/sound/file.mp3\")\n\n# or use directly on URLs\nplaysound(\"http://url/to/sound/file.mp3\")\n```\n\n## Documentation\n\nThe `playsound3` module contains a single function named `playsound`:\n\n```python\ndef playsound(\n sound: str | Path,\n block: bool = True,\n backend: str | None = None,\n daemon: bool = True,\n ) -> Thread | None:\n \"\"\"Play a sound file using an audio backend availabile in your system.\n\n Args:\n sound: Path or URL to the sound file. Can be a string or pathlib.Path.\n block: If True, the function will block execution until the sound finishes playing.\n If False, sound will play in a background thread.\n backend: Name of the audio backend to use. Use None for automatic selection.\n daemon: If True, and `block` is True, the background thread will be a daemon thread.\n This means that the thread will stay alive even after the main program exits.\n\n Returns:\n If `block` is True, the function will return None after the sound finishes playing.\n If `block` is False, the function will return the background thread object.\n\n \"\"\"\n ...\n```\n\nIt requires one argument: `sound` - the path to the file with the sound you'd like to play.\nThis should be a local file or a URL.\nThere's an optional second argument: `block` which is set to `True` by default.\nSetting it to `False` makes the function run asynchronously.\nYou can manually specify a backend by passing its name as the third argument.\nYou can browse available backends by using `playsound3.AVAILABLE_BACKENDS`.\nIt is recommended to use the default value of `None` to let the library choose the best backend available.\n\n## Supported systems\n\n* **Linux** using one of the below backends, whichever is available:\n * GStreamer\n * FFmpeg\n * aplay for .wav and mpg123 .mp3\n* **Windows** using winmm.dll (built-in on Windows)\n* **macOS** using afplay utility (built-in on macOS)\n\n## Fork information\n\nThis repository was originally forked from [playsound](https://github.com/TaylorSMarks/playsound) library created by Taylor Marks. The original library is unfortunately not maintained anymore and doesn't accept pull requests. This library: `playsound3` is a major rewrite of the original, including its own set of tests hosted using GitHub Actions.\n\nCompared to the original, `playsound3`:\n* Drops support for Python 2\n* Adheres to the latest PEP standards\n* Offers multiple backends with a fallback mechanism if the default backend is not available\n* Accepts contributions\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Cross-platform library to play audio files",
"version": "2.5.2",
"project_urls": {
"Documentation": "https://github.com/sjmikler/playsound3?tab=readme-ov-file#documentation",
"Issues": "https://github.com/sjmikler/playsound3/issues",
"Repository": "https://github.com/sjmikler/playsound3"
},
"split_keywords": [
"audio",
" media",
" mp3",
" music",
" play",
" playsound",
" song",
" sound",
" wav",
" wave"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "640223db4d343d48dc00168dfa7f6a35e2c4148846b76e6a916d9ad744291d31",
"md5": "65d4c8385fe1a86bbb95ae23ff517a36",
"sha256": "0946671321d67a386d2eb16e4118308c97920e8d3f92fae56091b9f548ee9e63"
},
"downloads": -1,
"filename": "playsound3-2.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65d4c8385fe1a86bbb95ae23ff517a36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7056,
"upload_time": "2024-12-28T08:30:31",
"upload_time_iso_8601": "2024-12-28T08:30:31.591148Z",
"url": "https://files.pythonhosted.org/packages/64/02/23db4d343d48dc00168dfa7f6a35e2c4148846b76e6a916d9ad744291d31/playsound3-2.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "23d26fa6e87b1ff76267147beb9c1b65af5b6e751bbe9b2c53efc81504428694",
"md5": "d223309c0f43a0f64985862378c64ab2",
"sha256": "37e75d9803cae5801e3a7c16bf6c8715c3f486df3637e550c9c729e544652ccc"
},
"downloads": -1,
"filename": "playsound3-2.5.2.tar.gz",
"has_sig": false,
"md5_digest": "d223309c0f43a0f64985862378c64ab2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11100,
"upload_time": "2024-12-28T08:30:33",
"upload_time_iso_8601": "2024-12-28T08:30:33.127661Z",
"url": "https://files.pythonhosted.org/packages/23/d2/6fa6e87b1ff76267147beb9c1b65af5b6e751bbe9b2c53efc81504428694/playsound3-2.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-28 08:30:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sjmikler",
"github_project": "playsound3?tab=readme-ov-file#documentation",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "playsound3"
}
JSON
