{"id":16646642,"url":"https://github.com/alexdelorenzo/play_sounds","last_synced_at":"2025-03-21T16:30:54.240Z","repository":{"id":57453410,"uuid":"300782660","full_name":"alexdelorenzo/play_sounds","owner":"alexdelorenzo","description":"🔊 Play music and sounds in your Python scripts, synchronously and asynchronously. ","archived":false,"fork":false,"pushed_at":"2024-01-18T07:15:59.000Z","size":7446,"stargazers_count":13,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T02:51:36.401Z","etag":null,"topics":["async","asyncio","play-songs","play-sounds","python-scripts","python-sound"],"latest_commit_sha":null,"homepage":"https://alexdelorenzo.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexdelorenzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["alexdelorenzo"]}},"created_at":"2020-10-03T02:53:02.000Z","updated_at":"2025-03-05T08:57:07.000Z","dependencies_parsed_at":"2024-10-28T11:26:16.964Z","dependency_job_id":"cb99bdc9-8c7d-426a-9c4f-12aa1f8afd3c","html_url":"https://github.com/alexdelorenzo/play_sounds","commit_stats":{"total_commits":72,"total_committers":3,"mean_commits":24.0,"dds":0.4305555555555556,"last_synced_commit":"d1475cc0897dc41c7a054e54828043e40f43e886"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdelorenzo%2Fplay_sounds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdelorenzo%2Fplay_sounds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdelorenzo%2Fplay_sounds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdelorenzo%2Fplay_sounds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexdelorenzo","download_url":"https://codeload.github.com/alexdelorenzo/play_sounds/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244829400,"owners_count":20517300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asyncio","play-songs","play-sounds","python-scripts","python-sound"],"created_at":"2024-10-12T08:42:42.642Z","updated_at":"2025-03-21T16:30:53.295Z","avatar_url":"https://github.com/alexdelorenzo.png","language":"Python","funding_links":["https://github.com/sponsors/alexdelorenzo","https://www.buymeacoffee.com/alexdelorenzo"],"categories":[],"sub_categories":[],"readme":"# 🔊 Play sounds in Python scripts\n\n`play_sounds` provides a simple cross-platform API to play sounds in Python scripts. It includes\na [synchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#synchronous-api) and an\nequivalent [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that is\ncompatible with `asyncio` and `trio`.\n\nFor code examples, you can check out [`onhold`](https://github.com/alexdelorenzo/onhold)\nand [`ding`](https://github.com/alexdelorenzo/ding), or scroll down to\nthe [Usage section](https://github.com/alexdelorenzo/play_sounds#usage).\n\n# Why `play_sounds`?\n\n[`boombox`](https://pypi.org/project/boombox/) is great and 90% of the way there, however it is limited to only playing\nWAV files on Windows. [`playsound`](https://pypi.org/project/playsound/) will play other formats than WAV on Windows,\nbut it requires GStreamer and `PyGObject` bindings on Linux, while `boombox` has several playback backends for Linux\nother 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\nuse `playsound` or `boombox`, or if your project uses `async/await`, you can just reach for `play_sounds` and call it a\nday.\n\n# Installation\n\n```bash\n$ python3 -m pip install play_sounds\n```\n\n# Usage\n\nThis library uses [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) objects when pointing to filenames and paths. \nIt can use  [`aiopath.AsyncPath`](https://github.com/alexdelorenzo/aiopath) objects, too.\n\nThere's a synchronous API and\nan [asynchronous API](https://github.com/alexdelorenzo/play_sounds/blob/main/README.md#asynchronous-api) that you can\nuse with the `async/await` syntax and `asyncio`.\n\n## Synchronous API\n\n### Play a file\n\n```python\nfrom pathlib import Path\nfrom play_sounds import play_file\n\n\nDEFAULT_SONG: Path = Path(\"/path/to/song.mp3\")\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\n```python\nfrom time import sleep\nfrom pathlib import Path\nfrom play_sounds import play_while_running\n\n\nDEFAULT_SONG: Path = Path(\"/path/to/song.mp3\")\nWAIT: int = 60\n\n\nwith play_while_running(DEFAULT_SONG):\n  sleep(WAIT)\n```\n\n### Play a file after work completes\n\n```python\nfrom time import sleep\nfrom pathlib import Path\nfrom play_sounds import play_after\n\n\nDEFAULT_SOUND: Path = Path(\"/path/to/song.mp3\")\nWAIT: int = 60\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\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\n\nTo run the following examples with top-level `await`\nexpressions, [launch an asynchronous Python REPL](https://www.integralist.co.uk/posts/python-asyncio/#running-async-code-in-the-repl)\nusing `python3 -m asyncio` or an [IPython shell](https://ipython.org/).\n\n### Play a file\n\n```python\nfrom pathlib import Path\nfrom play_sounds import play_file_async\n\n\nDEFAULT_SONG: Path = Path(\"/path/to/song.mp3\")\nWAIT: int = 60\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\n```python\nfrom asyncio import sleep\nfrom pathlib import Path\nfrom play_sounds import play_while_running_async\n\n\nDEFAULT_SONG: Path = Path(\"/path/to/song.mp3\")\nWAIT: int = 60\n\n\nasync with play_while_running_async(DEFAULT_SONG):\n  await sleep(WAIT)\n```\n\n### Play a file after work completes\n\n```python\nfrom asyncio import sleep\nfrom pathlib import Path\nfrom play_sounds import play_after_async\n\n\nDEFAULT_SOUND: Path = Path(\"/path/to/song.mp3\")\nWAIT: int = 60\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\n\nWant to support this project and [other open-source projects](https://github.com/alexdelorenzo) like it?\n\n\u003ca href=\"https://www.buymeacoffee.com/alexdelorenzo\" target=\"_blank\"\u003e\u003cimg 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%\" \u003e\u003c/a\u003e\n\n# Copyright\n\nSee `CREDIT.md`.\n\n# License\n\nSee `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdelorenzo%2Fplay_sounds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexdelorenzo%2Fplay_sounds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdelorenzo%2Fplay_sounds/lists"}