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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
Metadata-Version: 2.4
Name: playsound3
Version: 3.3.0
Summary: Cross-platform library to play audio files
Project-URL: Home, https://github.com/sjmikler/playsound3
Project-URL: Issues, https://github.com/sjmikler/playsound3/issues
Project-URL: Documentation, https://github.com/sjmikler/playsound3/blob/main/README.md#quick-start
Author-email: Szymon Mikler <sjmikler@gmail.com>, Taylor Marks <taylor@marksfam.com>
Maintainer-email: Szymon Mikler <sjmikler@gmail.com>
License: MIT License
License-File: LICENSE
Keywords: audio,media,mp3,music,play,playsound,song,sound,wav,wave
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Topic :: Multimedia :: Sound/Audio :: Players :: MP3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pywin32; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown
> **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`!
|
