# PvSpeaker Binding for Python
## PvSpeaker
PvSpeaker is an easy-to-use, cross-platform audio player designed for real-time speech audio processing. It allows developers to send raw PCM frames to an audio device's output stream.
## Compatibility
- Python 3.8+
- Runs on Linux (x86_64), macOS (x86_64 and arm64), Windows (x86_64), and Raspberry Pi (3, 4, 5).
## Installation
```shell
pip3 install pvspeaker
```
## Usage
Initialize and start `PvSpeaker`:
```python
from pvspeaker import PvSpeaker
speaker = PvSpeaker(
sample_rate=22050,
bits_per_sample=16,
buffer_size_secs=20,
device_index=0)
speaker.start()
```
(or)
Use `get_available_devices()` to get a list of available devices and then initialize the instance based on the index of a device:
```python
from pvspeaker import PvSpeaker
devices = PvSpeaker.get_available_devices()
speaker = PvSpeaker(
sample_rate=22050,
bits_per_sample=16,
buffer_size_secs=20,
device_index=0)
speaker.start()
```
Write PCM data to the speaker:
```python
def get_next_audio_frame():
pass
speaker.write(get_next_audio_frame())
```
Note: the `write()` method only writes as much PCM data as the internal circular buffer can currently fit, and returns the length of the PCM data that was successfully written.
When all frames have been written, run `flush()` to wait for all buffered pcm data (i.e. previously buffered via `write()`) to be played:
```python
speaker.flush()
```
Note: calling `flush()` with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.
```python
def get_remaining_audio_frames():
pass
speaker.flush(get_remaining_audio_frames())
```
To stop the audio output device, run `stop()`:
```python
speaker.stop()
```
Note that in order to stop the audio before it finishes playing, `stop` must be run on a separate thread from `flush`.
Once you are done (i.e. no longer need PvSpeaker to write and/or play PCM), free the resources acquired by PvSpeaker by calling `delete`. Be sure to first call `stop` if the audio is still playing. Otherwise, if the audio has already finished playing, you do not have to call `stop` before `delete`:
```python
speaker.delete()
```
## Demos
[pvspeakerdemo](https://pypi.org/project/pvspeakerdemo/) provides command-line utilities for playing audio from a file.
Raw data
{
"_id": null,
"home_page": "https://github.com/Picovoice/pvspeaker",
"name": "pvspeaker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Audio Player",
"author": "Picovoice",
"author_email": "hello@picovoice.ai",
"download_url": "https://files.pythonhosted.org/packages/17/bf/d7a8b51a6642e8a6cf69506af3584c96d2b2bb5cf4f0763b63c8923e4d4f/pvspeaker-1.0.3.tar.gz",
"platform": null,
"description": "# PvSpeaker Binding for Python\n\n## PvSpeaker\n\nPvSpeaker is an easy-to-use, cross-platform audio player designed for real-time speech audio processing. It allows developers to send raw PCM frames to an audio device's output stream.\n\n## Compatibility\n\n- Python 3.8+\n- Runs on Linux (x86_64), macOS (x86_64 and arm64), Windows (x86_64), and Raspberry Pi (3, 4, 5).\n\n## Installation\n\n```shell\npip3 install pvspeaker\n```\n\n## Usage\n\nInitialize and start `PvSpeaker`:\n\n```python\nfrom pvspeaker import PvSpeaker\n\nspeaker = PvSpeaker(\n sample_rate=22050,\n bits_per_sample=16,\n buffer_size_secs=20,\n device_index=0)\n\nspeaker.start()\n```\n\n(or)\n\nUse `get_available_devices()` to get a list of available devices and then initialize the instance based on the index of a device:\n\n```python\nfrom pvspeaker import PvSpeaker\n\ndevices = PvSpeaker.get_available_devices()\n\nspeaker = PvSpeaker(\n sample_rate=22050,\n bits_per_sample=16,\n buffer_size_secs=20,\n device_index=0)\n\nspeaker.start()\n```\n\nWrite PCM data to the speaker:\n\n```python\ndef get_next_audio_frame():\n pass\n\nspeaker.write(get_next_audio_frame())\n```\n\nNote: the `write()` method only writes as much PCM data as the internal circular buffer can currently fit, and returns the length of the PCM data that was successfully written.\n\nWhen all frames have been written, run `flush()` to wait for all buffered pcm data (i.e. previously buffered via `write()`) to be played:\n\n```python\nspeaker.flush()\n```\n\nNote: calling `flush()` with PCM data as an argument will both write that PCM data and wait for all buffered PCM data to finish.\n\n```python\ndef get_remaining_audio_frames():\n pass\n\nspeaker.flush(get_remaining_audio_frames())\n```\n\nTo stop the audio output device, run `stop()`:\n\n```python\nspeaker.stop()\n```\n\nNote that in order to stop the audio before it finishes playing, `stop` must be run on a separate thread from `flush`.\n\nOnce you are done (i.e. no longer need PvSpeaker to write and/or play PCM), free the resources acquired by PvSpeaker by calling `delete`. Be sure to first call `stop` if the audio is still playing. Otherwise, if the audio has already finished playing, you do not have to call `stop` before `delete`:\n\n```python\nspeaker.delete()\n```\n\n## Demos\n\n[pvspeakerdemo](https://pypi.org/project/pvspeakerdemo/) provides command-line utilities for playing audio from a file.\n",
"bugtrack_url": null,
"license": null,
"summary": "Speaker library for Picovoice.",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/Picovoice/pvspeaker"
},
"split_keywords": [
"audio",
"player"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6a28ac17750fa8ecbe3d215093efdf92697d98fed5bc7517f17bf641dd7b770",
"md5": "3c27914f4cbc7cfc4b88d760def2d994",
"sha256": "0fd5c0e6cb86a1b670fae219517dbf59ff6d76da9c1aeda872aa6fede08dda50"
},
"downloads": -1,
"filename": "pvspeaker-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c27914f4cbc7cfc4b88d760def2d994",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3487447,
"upload_time": "2024-09-03T21:41:15",
"upload_time_iso_8601": "2024-09-03T21:41:15.045010Z",
"url": "https://files.pythonhosted.org/packages/e6/a2/8ac17750fa8ecbe3d215093efdf92697d98fed5bc7517f17bf641dd7b770/pvspeaker-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "17bfd7a8b51a6642e8a6cf69506af3584c96d2b2bb5cf4f0763b63c8923e4d4f",
"md5": "21cb7e514d9d02ef3870eccf7aa260ff",
"sha256": "f8c8b79b8ab942fb08ea0c8bf020897411b035752db585030acc7943b146e211"
},
"downloads": -1,
"filename": "pvspeaker-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "21cb7e514d9d02ef3870eccf7aa260ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3483624,
"upload_time": "2024-09-03T21:41:17",
"upload_time_iso_8601": "2024-09-03T21:41:17.088217Z",
"url": "https://files.pythonhosted.org/packages/17/bf/d7a8b51a6642e8a6cf69506af3584c96d2b2bb5cf4f0763b63c8923e4d4f/pvspeaker-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-03 21:41:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Picovoice",
"github_project": "pvspeaker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pvspeaker"
}
JSON
