1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
> **Version 3.0.0**
>
> New functionalities:
> * stop sounds by calling `sound.stop()`
> * check if sound is still playing with `sound.is_alive()`
# 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
After installation, playing sounds is simple:
```python
from playsound3 import playsound
# Play sounds from disk
playsound("/path/to/sound/file.mp3")
# or play sounds from the internet.
playsound("http://url/to/sound/file.mp3")
# You can play sounds in the background
sound = playsound("/path/to/sound/file.mp3", block=False)
# and check if they are still playing
if sound.is_alive():
print("Sound is still playing!")
# and stop them whenever you like.
sound.stop()
```
## Reference
### playsound
```python
def playsound(
sound: str | Path,
block: bool = True,
backend: str | None = None,
) -> Sound
```
`sound` (required) \
The audio file you want to play (local or URL).
`block` (optional, default=`True`)\
Determines whether the sound plays synchronously (blocking) or asynchronously (background).
`backend` (optional, default=`None`) \
Specify which audio backend to use.
If `None`, the best backend is determined automatically.
To see a list of backends supported by your system:
```python
from playsound3 import AVAILABLE_BACKENDS, DEFAULT_BACKEND
print(AVAILABLE_BACKENDS) # for example: ["gstreamer", "ffmpeg", ...]
print(DEFAULT_BACKEND) # for example: "gstreamer"
```
### Sound
`playsound` returns a `Sound` object for playback control:
| Method | Description |
|---------------|-------------------------------------------|
| `.is_alive()` | Checks if the sound is currently playing. |
| `.wait()` | Blocks execution until playback finishes. |
| `.stop()` | Immediately stops playback. |
## Supported systems
* **Linux**
* GStreamer
* ALSA (aplay and mpg123)
* **Windows**
* WMPlayer
* winmm.dll
* **macOS**
* AppKit
* afplay
* **Multiplatform**
* FFmpeg
## Supported audio formats
The bare minimum supported by every backend are `.mp3` and `.wav` files.
Using them will keep your program compatible across different systems.
To see an exhaustive list of extensions supported by a backend, refer to their respective documentation.
## Fork information
This repository was originally forked from [playsound](https://github.com/TaylorSMarks/playsound) library created by Taylor Marks.
The original library is not maintained anymore and doesn't accept pull requests.
This library is a major rewrite of its original.
Feel free to create an issue or contribute to `playsound3`!
|
