[](https://github.com/Mark7888/steelseries-sonar-py/actions/workflows/publish.yml)
[](https://pepy.tech/project/steelseries-sonar-py)
# SteelSeries Sonar Python API
**Streamer mode currently in development!**
## Overview
This Python package provides a convenient interface for interacting with the SteelSeries Sonar application API.
The Sonar application allows users to control and display volumes for various audio channels.
## Installation
To use this package, follow these steps:
1. Install the package using pip:
```bash
pip install steelseries-sonar-py
```
2. Import the `Sonar` class in your Python script or application:
```python
from steelseries_sonar_py import Sonar
```
## Usage
### Initializing the Sonar Object
The Sonar class accepts two optional parameters during initialization:
`streamer_mode`: Set to True to use streamer mode (default is False).
`app_data_path`: Specify a custom path for the SteelSeries Engine 3 coreProps.json file
(default is the default installation path: `C:\\ProgramData\\SteelSeries\\SteelSeries Engine 3\\coreProps.json`).
```python
sonar = Sonar(app_data_path="C:\\path\\to\\coreProps.json")
```
or
```python
sonar = Sonar(app_data_path="C:\\path\\to\\coreProps.json", streamer_mode=True)
```
### Streamer Mode
The SteelSeries Sonar Python API supports streamer mode, which allows users to manage two separate sliders: `streaming` and `monitoring`. These sliders enable fine-tuned control over different audio channels.
To check if the streamer mode is enabled, use:
```python
is_streaming = sonar.is_streamer_mode()
print("Is Streamer Mode:", is_streaming)
```
To enable or disable streamer mode, use:
```python
# Enable streamer mode
sonar.set_streamer_mode(True)
# Disable streamer mode
sonar.set_streamer_mode(False)
```
### Retrieving Volume Information
Retrieve information about the current volume settings for all channels:
```python
volume_data = sonar.get_volume_data()
print(volume_data)
```
### Setting Volume for a Channel
Set the volume for a specific channel. The `channel` parameter should be one of the following:
`master`, `game`, `chatRender`, `media`, `aux`, `chatCapture`. The `volume` parameter should be a float between 0 and 1.
Additionally, an optional `streamer_slider` parameter can be provided, with values "streaming" (default) or "monitoring":
```python
channel = "master"
volume = 0.75
streamer_slider = "streaming" # or "monitoring"
result = sonar.set_volume(channel, volume, streamer_slider=streamer_slider)
print(result)
```
### Muting/Unmuting a Channel
Toggle mute status for a specific channel. The `channel` parameter should be one of the following:
`master`, `game`, `chatRender`, `media`, `aux`, `chatCapture`. The `muted` parameter should be a boolean indicating whether to mute (`True`) or unmute (`False`) the channel.
Additionally, an optional `streamer_slider` parameter can be provided, with values "streaming" (default) or "monitoring":
```python
channel = "game"
muted = True
streamer_slider = "monitoring"
result = sonar.mute_channel(channel, muted, streamer_slider=streamer_slider)
print(result)
```
### Chatmix
Retrieve chat-mix data:
```python
chatmix_data = sonar.get_chat_mix_data()
print(chatmix_data)
```
Set chat-mix value between `-1 and 1` to focus sound from the `game` or `chatRender` channel:
```python
result = sonar.set_chat_mix(0.5)
print(result)
```
## Exceptions
The package introduces a set of exceptions that might be raised during usage.
It is advisable to handle these exceptions accordingly in your code.
You can import them from `steelseries_sonar_py.exceptions`. Here is the list of potential exceptions:
- `EnginePathNotFoundError`: Raised when SteelSeries Engine 3 is not installed or not in the default location.
- `ServerNotAccessibleError`: Raised when the SteelSeries server is not accessible. Provides the HTTP status code.
- `SonarNotEnabledError`: Raised when SteelSeries Sonar is not enabled.
- `ServerNotReadyError`: Raised when SteelSeries Sonar is not ready.
- `ServerNotRunningError`: Raised when SteelSeries Sonar is not running.
- `WebServerAddressNotFoundError`: Raised when the web server address is not found.
- `ChannelNotFoundError`: Raised when the specified channel is not found.
- `InvalidVolumeError`: Raised when an invalid volume value is provided.
- `InvalidMixVolumeError`: Raised when an invalid mix volume value is provided.
- `SliderNotFoundError`: Raised when an unknown slider name is provided as `streamer_slider` value.
## Example
Here is a complete example demonstrating the usage of the SteelSeries Sonar Python API:
```python
from steelseries_sonar_py import Sonar
from steelseries_sonar_py.exceptions import EnginePathNotFoundError
# Initialize Sonar object
try:
sonar = Sonar(app_data_path="C:\\path\\to\\coreProps.json")
except EnginePathNotFoundError:
print("Engine not found!")
quit()
# Retrieve volume data
volume_data = sonar.get_volume_data()
print("Volume Data:", volume_data)
# Set volume for the 'master' channel
channel = "master"
volume = 0.8
streamer_slider = "streaming"
result = sonar.set_volume(channel, volume, streamer_slider=streamer_slider)
print(f"Set volume for {channel}:", result)
# Mute the 'game' channel
channel = "game"
muted = True
streamer_slider = "monitoring"
result = sonar.mute_channel(channel, muted, streamer_slider=streamer_slider)
print(f"Mute {channel}:", result)
# Retrieve chat-mix data
chatmix_data = sonar.get_chat_mix_data()
print("Chatmix Data:", chatmix_data)
# Set chat-mix value
result = sonar.set_chat_mix(0.5)
print("Set Chatmix:", result)
```
## Special Thanks
Thanks to all contributors who made this package possible - [wex](https://github.com/wex/sonar-rev) for figuring out the API, [TotalPanther317](https://github.com/TotalPanther317/steelseries-sonar-py) for understanding streamer mode and [cookie](https://github.com/cookie0o) for features like chat mix and streamer mode detection. Grateful for their efforts!
This documentation now reflects the latest changes and additions to the SteelSeries Sonar Python API.
Raw data
{
"_id": null,
"home_page": "https://github.com/Mark7888/steelseries-sonar-py",
"name": "steelseries-sonar-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "steelseries, sonar, volume, control, sonar-api",
"author": "Mark7888",
"author_email": "l.mark7888@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9e/02/c8f3cc09189e554429805a0f75505758c39f89eb581dc737c951bffc5024/steelseries_sonar_py-1.2.0.tar.gz",
"platform": null,
"description": "[](https://github.com/Mark7888/steelseries-sonar-py/actions/workflows/publish.yml)\n[](https://pepy.tech/project/steelseries-sonar-py)\n\n# SteelSeries Sonar Python API\n\n**Streamer mode currently in development!**\n\n## Overview\n\nThis Python package provides a convenient interface for interacting with the SteelSeries Sonar application API. \nThe Sonar application allows users to control and display volumes for various audio channels.\n\n## Installation\n\nTo use this package, follow these steps:\n\n1. Install the package using pip:\n\n ```bash\n pip install steelseries-sonar-py\n ```\n\n2. Import the `Sonar` class in your Python script or application:\n\n ```python\n from steelseries_sonar_py import Sonar\n ```\n\n## Usage\n\n### Initializing the Sonar Object\n\nThe Sonar class accepts two optional parameters during initialization: \n`streamer_mode`: Set to True to use streamer mode (default is False). \n`app_data_path`: Specify a custom path for the SteelSeries Engine 3 coreProps.json file \n(default is the default installation path: `C:\\\\ProgramData\\\\SteelSeries\\\\SteelSeries Engine 3\\\\coreProps.json`).\n\n```python\nsonar = Sonar(app_data_path=\"C:\\\\path\\\\to\\\\coreProps.json\")\n```\nor\n```python\nsonar = Sonar(app_data_path=\"C:\\\\path\\\\to\\\\coreProps.json\", streamer_mode=True)\n```\n\n### Streamer Mode\n\nThe SteelSeries Sonar Python API supports streamer mode, which allows users to manage two separate sliders: `streaming` and `monitoring`. These sliders enable fine-tuned control over different audio channels.\n\nTo check if the streamer mode is enabled, use:\n\n```python\nis_streaming = sonar.is_streamer_mode()\nprint(\"Is Streamer Mode:\", is_streaming)\n```\n\nTo enable or disable streamer mode, use:\n\n```python\n# Enable streamer mode\nsonar.set_streamer_mode(True)\n\n# Disable streamer mode\nsonar.set_streamer_mode(False)\n```\n\n### Retrieving Volume Information\n\nRetrieve information about the current volume settings for all channels:\n\n```python\nvolume_data = sonar.get_volume_data()\nprint(volume_data)\n```\n\n### Setting Volume for a Channel\n\nSet the volume for a specific channel. The `channel` parameter should be one of the following: \n`master`, `game`, `chatRender`, `media`, `aux`, `chatCapture`. The `volume` parameter should be a float between 0 and 1. \nAdditionally, an optional `streamer_slider` parameter can be provided, with values \"streaming\" (default) or \"monitoring\":\n\n```python\nchannel = \"master\"\nvolume = 0.75\nstreamer_slider = \"streaming\" # or \"monitoring\"\n\nresult = sonar.set_volume(channel, volume, streamer_slider=streamer_slider)\nprint(result)\n```\n\n### Muting/Unmuting a Channel\n\nToggle mute status for a specific channel. The `channel` parameter should be one of the following: \n`master`, `game`, `chatRender`, `media`, `aux`, `chatCapture`. The `muted` parameter should be a boolean indicating whether to mute (`True`) or unmute (`False`) the channel. \nAdditionally, an optional `streamer_slider` parameter can be provided, with values \"streaming\" (default) or \"monitoring\":\n\n```python\nchannel = \"game\"\nmuted = True\nstreamer_slider = \"monitoring\"\n\nresult = sonar.mute_channel(channel, muted, streamer_slider=streamer_slider)\nprint(result)\n```\n\n### Chatmix\n\nRetrieve chat-mix data:\n\n```python\nchatmix_data = sonar.get_chat_mix_data()\nprint(chatmix_data)\n```\n\nSet chat-mix value between `-1 and 1` to focus sound from the `game` or `chatRender` channel:\n\n```python\nresult = sonar.set_chat_mix(0.5)\nprint(result)\n```\n\n## Exceptions\n\nThe package introduces a set of exceptions that might be raised during usage. \nIt is advisable to handle these exceptions accordingly in your code. \nYou can import them from `steelseries_sonar_py.exceptions`. Here is the list of potential exceptions:\n\n- `EnginePathNotFoundError`: Raised when SteelSeries Engine 3 is not installed or not in the default location.\n- `ServerNotAccessibleError`: Raised when the SteelSeries server is not accessible. Provides the HTTP status code.\n- `SonarNotEnabledError`: Raised when SteelSeries Sonar is not enabled.\n- `ServerNotReadyError`: Raised when SteelSeries Sonar is not ready.\n- `ServerNotRunningError`: Raised when SteelSeries Sonar is not running.\n- `WebServerAddressNotFoundError`: Raised when the web server address is not found.\n- `ChannelNotFoundError`: Raised when the specified channel is not found.\n- `InvalidVolumeError`: Raised when an invalid volume value is provided.\n- `InvalidMixVolumeError`: Raised when an invalid mix volume value is provided.\n- `SliderNotFoundError`: Raised when an unknown slider name is provided as `streamer_slider` value.\n\n## Example\n\nHere is a complete example demonstrating the usage of the SteelSeries Sonar Python API:\n\n```python\nfrom steelseries_sonar_py import Sonar\nfrom steelseries_sonar_py.exceptions import EnginePathNotFoundError\n\n# Initialize Sonar object\ntry:\n sonar = Sonar(app_data_path=\"C:\\\\path\\\\to\\\\coreProps.json\")\nexcept EnginePathNotFoundError:\n print(\"Engine not found!\")\n quit()\n\n# Retrieve volume data\nvolume_data = sonar.get_volume_data()\nprint(\"Volume Data:\", volume_data)\n\n# Set volume for the 'master' channel\nchannel = \"master\"\nvolume = 0.8\nstreamer_slider = \"streaming\"\nresult = sonar.set_volume(channel, volume, streamer_slider=streamer_slider)\nprint(f\"Set volume for {channel}:\", result)\n\n# Mute the 'game' channel\nchannel = \"game\"\nmuted = True\nstreamer_slider = \"monitoring\"\nresult = sonar.mute_channel(channel, muted, streamer_slider=streamer_slider)\nprint(f\"Mute {channel}:\", result)\n\n# Retrieve chat-mix data\nchatmix_data = sonar.get_chat_mix_data()\nprint(\"Chatmix Data:\", chatmix_data)\n\n# Set chat-mix value\nresult = sonar.set_chat_mix(0.5)\nprint(\"Set Chatmix:\", result)\n```\n\n## Special Thanks\n\nThanks to all contributors who made this package possible - [wex](https://github.com/wex/sonar-rev) for figuring out the API, [TotalPanther317](https://github.com/TotalPanther317/steelseries-sonar-py) for understanding streamer mode and [cookie](https://github.com/cookie0o) for features like chat mix and streamer mode detection. Grateful for their efforts!\n\nThis documentation now reflects the latest changes and additions to the SteelSeries Sonar Python API.\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple Python wrapper for the SteelSeries Sonar API",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/Mark7888/steelseries-sonar-py/issues",
"Documentation": "https://github.com/Mark7888/steelseries-sonar-py/blob/master/README.md",
"Homepage": "https://github.com/Mark7888/steelseries-sonar-py",
"Source Code": "https://github.com/Mark7888/steelseries-sonar-py"
},
"split_keywords": [
"steelseries",
" sonar",
" volume",
" control",
" sonar-api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b347d785b25716c8382d068a1b991006f585bfe94d8261a64dc6085daee650b",
"md5": "4bb0e4cf528b4027a641d41bd6c75ff4",
"sha256": "f4ff0663bbeaf157cd9a2bca91554302680610ff1290c8dcdddfe5394bde8762"
},
"downloads": -1,
"filename": "steelseries_sonar_py-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bb0e4cf528b4027a641d41bd6c75ff4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 6642,
"upload_time": "2024-06-02T14:02:54",
"upload_time_iso_8601": "2024-06-02T14:02:54.304740Z",
"url": "https://files.pythonhosted.org/packages/8b/34/7d785b25716c8382d068a1b991006f585bfe94d8261a64dc6085daee650b/steelseries_sonar_py-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9e02c8f3cc09189e554429805a0f75505758c39f89eb581dc737c951bffc5024",
"md5": "a3561d0c6d2275e245fbbe17caf52b3d",
"sha256": "3bb80bcac2443e0bcf8e887885157ff3639775b905500c1920a2593de795f04e"
},
"downloads": -1,
"filename": "steelseries_sonar_py-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a3561d0c6d2275e245fbbe17caf52b3d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 11004,
"upload_time": "2024-06-02T14:02:55",
"upload_time_iso_8601": "2024-06-02T14:02:55.497237Z",
"url": "https://files.pythonhosted.org/packages/9e/02/c8f3cc09189e554429805a0f75505758c39f89eb581dc737c951bffc5024/steelseries_sonar_py-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-02 14:02:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mark7888",
"github_project": "steelseries-sonar-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "steelseries-sonar-py"
}
JSON
