<div align=center>
<img alt="PiWave image" src="https://piwave.xyz/static/img/logo.png"/>
<h1>PiWave</h1>
</div>
**PiWave** is a Python module designed to manage and control your Raspberry Pi radio using the `pi_fm_rds` utility. It allows you to easily convert audio files to WAV format and broadcast them at a specified frequency with RDS (Radio Data System) support.
## Features
- Converts audio files to WAV format.
- Broadcasts WAV files using the `pi_fm_rds` utility.
- Configurable broadcast frequency, PS (Program Service), RT (Radio Text), and PI (Program Identifier).
- Supports looping of playback.
- Detailed logging for debug mode.
- Supports streaming from URLs.
- Better error handling and event callbacks.
- Non-blocking playback with threading.
- Temporary file management for streamed content.
> [!NOTE]
> Are you looking for a minimal GUI for PiWave?
> Take a look at the [PiWave WebGUI](https://github.com/douxxtech/piwave-webgui)
## Hardware Installation
To use PiWave for broadcasting, you need to set up the hardware correctly. This involves connecting an antenna or cable to the Raspberry Pi's GPIO pin.
1. **Connect the Cable or Antenna**:
- Attach a cable or an antenna to GPIO 4 (Pin 7) on the Raspberry Pi.
- Ensure the connection is secure to avoid any broadcasting issues.
2. **GPIO Pinout**:
- GPIO 4 (Pin 7) is used for the broadcasting signal.
- Ensure that the cable or antenna is properly connected to this pin for optimal performance.
## Installation
> [!WARNING]
> **Warning**: Using PiWave involves broadcasting signals which may be subject to local regulations and laws. It is your responsibility to ensure that your use of PiWave complies with all applicable legal requirements and regulations in your area. Unauthorized use of broadcasting equipment may result in legal consequences, including fines or penalties.
>
> **Liability**: The author of PiWave is not responsible for any damage, loss, or legal issues that may arise from the use of this software. By using PiWave, you agree to accept all risks and liabilities associated with its operation and broadcasting capabilities.
>
> Please exercise caution and ensure you have the proper permissions and knowledge of the regulations before using PiWave for broadcasting purposes.
### Auto Installer
For a quick and easy installation, you can use the auto installer script. Open a terminal and run:
```bash
curl -sL https://setup.piwave.xyz/ | sudo bash
```
This command will download and execute the installation script, setting up PiWave and its dependencies automatically.
> [!NOTE]
> To uninstall, use the following command:
> ```bash
> curl -sL https://setup.piwave.xyz/uninstall | sudo bash
> ```
### Manual Installation
To install PiWave manually, follow these steps:
1. **Clone the repository and install**:
```bash
pip install git+https://github.com/douxxtech/piwave.git --break-system-packages
```
2. **Dependencies**:
PiWave requires the `ffmpeg` and `ffprobe` utilities for file conversion and duration extraction. Install them using:
```bash
sudo apt-get install ffmpeg
```
3. **PiFmRds**:
PiWave uses [PiFmRds](https://github.com/ChristopheJacquet/PiFmRds) to work. Make sure you have installed it before running PiWave.
## Usage
### Basic Usage
1. **Importing the module**:
```python
from piwave import PiWave
```
2. **Creating an instance**:
```python
piwave = PiWave(
frequency=90.0,
ps="MyRadio",
rt="Playing great music",
pi="ABCD",
loop=True,
debug=True,
on_track_change=lambda file, index: print(f"Now playing: {file}"),
on_error=lambda error: print(f"Error occurred: {error}")
)
```
3. **Adding files to the playlist**:
```python
files = ["path/to/your/audiofile.mp3", "http://example.com/stream.mp3"]
piwave.add_files(files)
```
4. **Starting playback**:
```python
piwave.play() # or files = ["path/to/your/audiofile.mp3", "http://example.com/stream.mp3"]; piwave.play(files)
```
5. **Stopping playback**:
```python
piwave.stop()
```
6. **Pausing and resuming playback**:
```python
piwave.pause()
piwave.resume()
```
7. **Skipping tracks**:
```python
piwave.next_track()
piwave.previous_track()
```
8. **Changing frequency**:
```python
piwave.set_frequency(95.0)
```
9. **Getting status**:
```python
status = piwave.get_status()
print(status)
```
### Configuration
- `frequency`: The broadcast frequency in MHz (default: 90.0).
- `ps`: Program Service name (up to 8 characters, default: "PiWave").
- `rt`: Radio Text (up to 64 characters, default: "PiWave: The best python module for managing your pi radio").
- `pi`: Program Identifier (up to 4 characters, default: "FFFF").
- `loop`: Whether to loop playback of files (default: False).
- `debug`: Enable detailed debug logging (default: False).
- `on_track_change`: Callback function when the track changes (default: None).
- `on_error`: Callback function when an error occurs (default: None).
## Error Handling
- **Raspberry Pi Check**: The program verifies if it is running on a Raspberry Pi. It exits with an error message if not.
- **Root User Check**: The program requires root privileges to run. It exits with an error message if not run as root.
- **Executable Check**: The program automatically finds the `pi_fm_rds` executable or prompts the user to manually provide its path if it cannot be found.
## License
PiWave is licensed under the GNU General Public License (GPL) v3.0. See the [LICENSE](LICENSE) file for more details.
## Contributing
Contributions are welcome! Please submit a pull request or open an issue on [GitHub](https://github.com/douxxtech/piwave/issues) for any bugs or feature requests.
---
Thank you for using PiWave!
Made with <3 by Douxx
Raw data
{
"_id": null,
"home_page": "https://github.com/douxxtech/piwave",
"name": "piwave",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "raspberry pi, radio, fm, rds, streaming, audio, broadcast",
"author": "Douxx",
"author_email": "douxx@douxx.tech",
"download_url": "https://files.pythonhosted.org/packages/59/24/eab3f200b2d433e9c6590f31119944c5c4dc41507b3ed93ed8da55243738/piwave-2.0.4.tar.gz",
"platform": null,
"description": "<div align=center>\n<img alt=\"PiWave image\" src=\"https://piwave.xyz/static/img/logo.png\"/>\n<h1>PiWave</h1>\n</div>\n\n**PiWave** is a Python module designed to manage and control your Raspberry Pi radio using the `pi_fm_rds` utility. It allows you to easily convert audio files to WAV format and broadcast them at a specified frequency with RDS (Radio Data System) support.\n\n## Features\n\n- Converts audio files to WAV format.\n- Broadcasts WAV files using the `pi_fm_rds` utility.\n- Configurable broadcast frequency, PS (Program Service), RT (Radio Text), and PI (Program Identifier).\n- Supports looping of playback.\n- Detailed logging for debug mode.\n- Supports streaming from URLs.\n- Better error handling and event callbacks.\n- Non-blocking playback with threading.\n- Temporary file management for streamed content.\n\n> [!NOTE]\n> Are you looking for a minimal GUI for PiWave?\n> Take a look at the [PiWave WebGUI](https://github.com/douxxtech/piwave-webgui)\n\n## Hardware Installation\n\nTo use PiWave for broadcasting, you need to set up the hardware correctly. This involves connecting an antenna or cable to the Raspberry Pi's GPIO pin.\n\n1. **Connect the Cable or Antenna**:\n - Attach a cable or an antenna to GPIO 4 (Pin 7) on the Raspberry Pi.\n - Ensure the connection is secure to avoid any broadcasting issues.\n\n2. **GPIO Pinout**:\n - GPIO 4 (Pin 7) is used for the broadcasting signal.\n - Ensure that the cable or antenna is properly connected to this pin for optimal performance.\n\n## Installation\n\n> [!WARNING]\n> **Warning**: Using PiWave involves broadcasting signals which may be subject to local regulations and laws. It is your responsibility to ensure that your use of PiWave complies with all applicable legal requirements and regulations in your area. Unauthorized use of broadcasting equipment may result in legal consequences, including fines or penalties.\n>\n> **Liability**: The author of PiWave is not responsible for any damage, loss, or legal issues that may arise from the use of this software. By using PiWave, you agree to accept all risks and liabilities associated with its operation and broadcasting capabilities.\n>\n> Please exercise caution and ensure you have the proper permissions and knowledge of the regulations before using PiWave for broadcasting purposes.\n\n### Auto Installer\n\nFor a quick and easy installation, you can use the auto installer script. Open a terminal and run:\n\n```bash\ncurl -sL https://setup.piwave.xyz/ | sudo bash\n```\n\nThis command will download and execute the installation script, setting up PiWave and its dependencies automatically.\n\n> [!NOTE]\n> To uninstall, use the following command:\n> ```bash\n> curl -sL https://setup.piwave.xyz/uninstall | sudo bash\n> ```\n\n### Manual Installation\n\nTo install PiWave manually, follow these steps:\n\n1. **Clone the repository and install**:\n\n ```bash\n pip install git+https://github.com/douxxtech/piwave.git --break-system-packages\n ```\n\n2. **Dependencies**:\n\n PiWave requires the `ffmpeg` and `ffprobe` utilities for file conversion and duration extraction. Install them using:\n\n ```bash\n sudo apt-get install ffmpeg\n ```\n\n3. **PiFmRds**:\n\n PiWave uses [PiFmRds](https://github.com/ChristopheJacquet/PiFmRds) to work. Make sure you have installed it before running PiWave.\n\n## Usage\n\n### Basic Usage\n\n1. **Importing the module**:\n\n ```python\n from piwave import PiWave\n ```\n\n2. **Creating an instance**:\n\n ```python\n piwave = PiWave(\n frequency=90.0,\n ps=\"MyRadio\",\n rt=\"Playing great music\",\n pi=\"ABCD\",\n loop=True,\n debug=True,\n on_track_change=lambda file, index: print(f\"Now playing: {file}\"),\n on_error=lambda error: print(f\"Error occurred: {error}\")\n )\n ```\n\n3. **Adding files to the playlist**:\n\n ```python\n files = [\"path/to/your/audiofile.mp3\", \"http://example.com/stream.mp3\"]\n piwave.add_files(files)\n ```\n\n4. **Starting playback**:\n\n ```python\n piwave.play() # or files = [\"path/to/your/audiofile.mp3\", \"http://example.com/stream.mp3\"]; piwave.play(files)\n ```\n\n5. **Stopping playback**:\n\n ```python\n piwave.stop()\n ```\n\n6. **Pausing and resuming playback**:\n\n ```python\n piwave.pause()\n piwave.resume()\n ```\n\n7. **Skipping tracks**:\n\n ```python\n piwave.next_track()\n piwave.previous_track()\n ```\n\n8. **Changing frequency**:\n\n ```python\n piwave.set_frequency(95.0)\n ```\n\n9. **Getting status**:\n\n ```python\n status = piwave.get_status()\n print(status)\n ```\n\n### Configuration\n\n- `frequency`: The broadcast frequency in MHz (default: 90.0).\n- `ps`: Program Service name (up to 8 characters, default: \"PiWave\").\n- `rt`: Radio Text (up to 64 characters, default: \"PiWave: The best python module for managing your pi radio\").\n- `pi`: Program Identifier (up to 4 characters, default: \"FFFF\").\n- `loop`: Whether to loop playback of files (default: False).\n- `debug`: Enable detailed debug logging (default: False).\n- `on_track_change`: Callback function when the track changes (default: None).\n- `on_error`: Callback function when an error occurs (default: None).\n\n## Error Handling\n\n- **Raspberry Pi Check**: The program verifies if it is running on a Raspberry Pi. It exits with an error message if not.\n- **Root User Check**: The program requires root privileges to run. It exits with an error message if not run as root.\n- **Executable Check**: The program automatically finds the `pi_fm_rds` executable or prompts the user to manually provide its path if it cannot be found.\n\n## License\n\nPiWave is licensed under the GNU General Public License (GPL) v3.0. See the [LICENSE](LICENSE) file for more details.\n\n## Contributing\n\nContributions are welcome! Please submit a pull request or open an issue on [GitHub](https://github.com/douxxtech/piwave/issues) for any bugs or feature requests.\n\n---\n\nThank you for using PiWave!\n\nMade with <3 by Douxx\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A python module to broadcast radio waves with your Raspberry Pi.",
"version": "2.0.4",
"project_urls": {
"Bug Reports": "https://github.com/douxxtech/piwave/issues",
"Homepage": "https://github.com/douxxtech/piwave",
"Source": "https://github.com/douxxtech/piwave"
},
"split_keywords": [
"raspberry pi",
" radio",
" fm",
" rds",
" streaming",
" audio",
" broadcast"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6039a6dec7a621c50bca4128098125c479d9985af3a2cb6a5206f78713e941c2",
"md5": "42e153afae8af271d2c429e5380d2694",
"sha256": "131ac132e9c879c8c4a052def88cd4b1513db2dbe6523ff7c3eafab75f3909e0"
},
"downloads": -1,
"filename": "piwave-2.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42e153afae8af271d2c429e5380d2694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21104,
"upload_time": "2025-08-13T16:13:50",
"upload_time_iso_8601": "2025-08-13T16:13:50.269986Z",
"url": "https://files.pythonhosted.org/packages/60/39/a6dec7a621c50bca4128098125c479d9985af3a2cb6a5206f78713e941c2/piwave-2.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5924eab3f200b2d433e9c6590f31119944c5c4dc41507b3ed93ed8da55243738",
"md5": "ee605491de2879c773b62760068bf4ff",
"sha256": "0f4618b6ddc18f8ce4f7a2d63a29d2e694f49c79db4919079c36f9a071de15b5"
},
"downloads": -1,
"filename": "piwave-2.0.4.tar.gz",
"has_sig": false,
"md5_digest": "ee605491de2879c773b62760068bf4ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23781,
"upload_time": "2025-08-13T16:13:51",
"upload_time_iso_8601": "2025-08-13T16:13:51.353454Z",
"url": "https://files.pythonhosted.org/packages/59/24/eab3f200b2d433e9c6590f31119944c5c4dc41507b3ed93ed8da55243738/piwave-2.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 16:13:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "douxxtech",
"github_project": "piwave",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "piwave"
}
JSON
