playsound3 2.1.1__py3-none-any.whl

playsound3/__init__.py

@@ -0,0 +1 @@
+from playsound3.playsound3 import playsound

playsound3/playsound3.py

@@ -0,0 +1,132 @@
+import atexit
+import ctypes
+import logging
+import platform
+import subprocess
+import tempfile
+import urllib.request
+import uuid
+from pathlib import Path
+from threading import Thread
+
+logger = logging.getLogger(__name__)
+
+SYSTEM = platform.system()
+DOWNLOAD_CACHE = dict()
+
+
+class PlaysoundException(Exception):
+    pass
+
+
+def playsound(sound, block: bool = True) -> None:
+    """Play a sound file using an audio backend availabile in your system.
+
+    Args:
+        sound: Path to the sound file. Can be either an str or pathlib.Path.
+        block: If True, the function will block execution until the sound finishes playing.
+    """
+    sound = _prepare_path(sound)
+
+    if SYSTEM == "Linux":
+        func = _playsound_gstreamer
+    elif SYSTEM == "Windows":
+        func = _playsound_winmm
+    elif SYSTEM == "Darwin":
+        func = _playsound_afplay
+    else:
+        raise PlaysoundException(f"Platform '{SYSTEM}' is not supported")
+
+    if block:
+        func(sound)
+    else:
+        t = Thread(target=func, args=(sound,), daemon=True).start()
+
+
+def _prepare_path(sound):
+    if sound.startswith(("http://", "https://")):
+        # To play file from URL, we download the file first to a temporary location
+        if sound not in DOWNLOAD_CACHE:
+            with tempfile.NamedTemporaryFile(delete=False, prefix="playsound3-") as f:
+                urllib.request.urlretrieve(sound, f.name)
+                DOWNLOAD_CACHE[sound] = f.name
+        sound = DOWNLOAD_CACHE[sound]
+
+    path = Path(sound)
+
+    if not path.exists():
+        raise PlaysoundException(f"File not found: {sound}")
+    return path.absolute().as_posix()
+
+
+def _playsound_gstreamer(sound):
+    """Play a sound using gstreamer (built-in Linux)."""
+
+    if not sound.startswith("file://"):
+        sound = "file://" + urllib.request.pathname2url(sound)
+
+    import gi
+
+    # Silences gi warning
+    gi.require_version("Gst", "1.0")
+
+    # GStreamer is included in all Linux distributions
+    from gi.repository import Gst
+
+    Gst.init(None)
+
+    playbin = Gst.ElementFactory.make("playbin", "playbin")
+    playbin.props.uri = sound
+
+    logger.debug("gstreamer: starting playing %s", sound)
+    set_result = playbin.set_state(Gst.State.PLAYING)
+    if set_result != Gst.StateChangeReturn.ASYNC:
+        raise PlaysoundException("playbin.set_state returned " + repr(set_result))
+    bus = playbin.get_bus()
+    try:
+        bus.poll(Gst.MessageType.EOS, Gst.CLOCK_TIME_NONE)
+    finally:
+        playbin.set_state(Gst.State.NULL)
+    logger.debug("gstreamer: finishing play %s", sound)
+
+
+def _send_winmm_mci_command(command):
+    winmm = ctypes.WinDLL("winmm.dll")
+    buffer = ctypes.create_string_buffer(255)
+    error_code = winmm.mciSendStringA(ctypes.c_char_p(command.encode()), buffer, 254, 0)
+    if error_code:
+        logger.error("Error code: %s", error_code)
+    return buffer.value
+
+
+def _playsound_winmm(sound):
+    """Play a sound utilizing windll.winmm."""
+
+    # Select a unique alias for the sound
+    alias = str(uuid.uuid4())
+    logger.debug("winmm: starting playing %s", sound)
+    _send_winmm_mci_command(f'open "{sound}" type mpegvideo alias {alias}')
+    _send_winmm_mci_command(f"play {alias} wait")
+    _send_winmm_mci_command(f"close {alias}")
+    logger.debug("winmm: finishing play %s", sound)
+
+
+def _playsound_afplay(sound):
+    """Uses afplay utility (built-in macOS)."""
+    logger.debug("afplay: starting playing %s", sound)
+    try:
+        subprocess.run(["afplay", sound], check=True)
+    except subprocess.CalledProcessError as e:
+        raise PlaysoundException(f"afplay failed to play sound: {e}")
+    logger.debug("afplay: finishing play %s", sound)
+
+
+def _remove_cached_files(cache):
+    """Remove all files saved in the cache when the program ends."""
+    import os
+
+    for path in cache.values():
+        os.remove(path)
+
+
+atexit.register(_remove_cached_files, DOWNLOAD_CACHE)

playsound3-2.1.1.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: playsound3
+Version: 2.1.1
+Summary: Cross-platform library to play audio files
+Project-URL: Repository, https://github.com/sjmikler/playsound3
+Project-URL: Issues, https://github.com/sjmikler/playsound3/issues
+Project-URL: Documentation, https://github.com/sjmikler/playsound3?tab=readme-ov-file#documentation
+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.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players :: MP3
+Requires-Python: >=3.7
+Requires-Dist: pygobject; platform_system == 'Linux'
+Description-Content-Type: text/markdown
+
+> This repository was forked from [TaylorSMarks/playsound](https://github.com/TaylorSMarks/playsound)
+
+# playsound3
+
+[![PyPi version](https://img.shields.io/badge/dynamic/json?label=latest&query=info.version&url=https%3A%2F%2Fpypi.org%2Fpypi%2Fplaysound3%2Fjson)](https://pypi.org/project/playsound3)
+[![PyPI license](https://img.shields.io/badge/dynamic/json?label=license&query=info.license&url=https%3A%2F%2Fpypi.org%2Fpypi%2Fplaysound3%2Fjson)](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 playsound module contains only one thing - the function (also named) playsound:
+
+```python
+def playsound(sound, block: bool = True) -> None:
+    """Play a sound file using an audio backend availabile in your system.
+
+    Args:
+        sound: Path to the sound file. Can be either an str or pathlib.Path.
+        block: If True, the function will block execution until the sound finishes playing.
+    """
+```
+
+It requires one argument - 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.
+
+## Supported systems
+
+* Linux, using GStreamer (built-in on Linux distributions)
+* Windows, using winmm.dll (built-in on Windows)
+* OS X, using afplay utility (built-in on OS X)

playsound3-2.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+playsound3/__init__.py,sha256=uAfl17fNqC-3wGYFxtdENOTWu31_IONpDU_wgdCnemc,44
+playsound3/playsound3.py,sha256=5WOt6vjUY1hC0jVJ1e6FN05-WIjCF5hkj7ITY-kkwxQ,3898
+playsound3-2.1.1.dist-info/METADATA,sha256=e5sB9NhmNqlwQDU7lxu2FSV5ECq8eMruWUvn-T6kCSU,3136
+playsound3-2.1.1.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+playsound3-2.1.1.dist-info/licenses/LICENSE,sha256=VTRyASdB4LydQkt1egAUbIjG1zWMkh-UUELP1SdccXw,1155
+playsound3-2.1.1.dist-info/RECORD,,

playsound3-2.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.24.2
+Root-Is-Purelib: true
+Tag: py3-none-any

playsound3-2.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Szymon Mikler <sjmikler@gmail.com>
+Copyright (c) 2021 Taylor Marks <taylor@marksfam.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.