# SteelSeries Sonar Python API
[](https://github.com/Mark7888/steelseries-sonar-py/actions/workflows/publish.yml)
## Overview
This Python package provides a convenient interface for interacting with the [SteelSeries Sonar](https://steelseries.com/gg/sonar) application API. The Sonar application allows users to control and display volumes for various audio channels.
You can check the project [PyPI site](https://pypi.org/project/steelseries-sonar-py/) here!
## 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(streamer_mode=True, app_data_path="C:\\path\\to\\coreProps.json")
```
### 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:
```python
channel = "master"
volume = 0.75
result = sonar.set_volume(channel, volume)
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:
```python
channel = "game"
muted = `True`
result = sonar.mute_channel(channel, muted)
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.
## 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(streamer_mode=False, 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
result = sonar.set_volume(channel, volume)
print(f"Set volume for {channel}:", result)
# Mute the 'game' channel
channel = "game"
muted = `True`
result = sonar.mute_channel(channel, muted)
print(f"Mute {channel}:", result)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Mark7888/steelseries-sonar-py",
"name": "steelseries-sonar-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "steelseries,sonar,volume,control,sonar-api",
"author": "Mark7888",
"author_email": "l.mark7888@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/87/25/48ad03cc4fc60f48308ac6c8e3bbc6cf558b9b4c5e727447efe4d416838c/steelseries-sonar-py-1.0.1.tar.gz",
"platform": null,
"description": "# SteelSeries Sonar Python API\n[](https://github.com/Mark7888/steelseries-sonar-py/actions/workflows/publish.yml)\n\n## Overview\n\nThis Python package provides a convenient interface for interacting with the [SteelSeries Sonar](https://steelseries.com/gg/sonar) application API. The Sonar application allows users to control and display volumes for various audio channels.\nYou can check the project [PyPI site](https://pypi.org/project/steelseries-sonar-py/) here!\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 (default is the default installation path: `C:\\\\ProgramData\\\\SteelSeries\\\\SteelSeries Engine 3\\\\coreProps.json`).\n\n```python\nsonar = Sonar(streamer_mode=True, app_data_path=\"C:\\\\path\\\\to\\\\coreProps.json\")\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: \"master\", \"game\", \"chatRender\", \"media\", \"aux\", \"chatCapture\". The `volume` parameter should be a float between 0 and 1:\n\n```python\nchannel = \"master\"\nvolume = 0.75\n\nresult = sonar.set_volume(channel, volume)\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: `master`, `game`, `chatRender`, `media`, `aux`, `chatCapture`. The `muted` parameter should be a boolean indicating whether to mute (`True`) or unmute (`False`) the channel:\n\n```python\nchannel = \"game\"\nmuted = `True`\n\nresult = sonar.mute_channel(channel, muted)\nprint(result)\n```\n\n## Exceptions\n\nThe 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:\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\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(streamer_mode=False, 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\nresult = sonar.set_volume(channel, volume)\nprint(f\"Set volume for {channel}:\", result)\n\n# Mute the 'game' channel\nchannel = \"game\"\nmuted = `True`\nresult = sonar.mute_channel(channel, muted)\nprint(f\"Mute {channel}:\", result)\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Simple Python wrapper for the SteelSeries Sonar API",
"version": "1.0.1",
"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": "473fa3d90ddfe7ebdc913469fbec7c4b554bc9385f79381e46420cc1cbb246e0",
"md5": "b687187a06e5812cb364383fc6faa431",
"sha256": "2820f919b34809d5df63ee073dec4e07d0ef4cb28a17c0ffc83847b3e4e88102"
},
"downloads": -1,
"filename": "steelseries_sonar_py-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b687187a06e5812cb364383fc6faa431",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 5632,
"upload_time": "2024-01-03T16:08:00",
"upload_time_iso_8601": "2024-01-03T16:08:00.471168Z",
"url": "https://files.pythonhosted.org/packages/47/3f/a3d90ddfe7ebdc913469fbec7c4b554bc9385f79381e46420cc1cbb246e0/steelseries_sonar_py-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "872548ad03cc4fc60f48308ac6c8e3bbc6cf558b9b4c5e727447efe4d416838c",
"md5": "d54a6d7f9148bed0c1d722c77b24c241",
"sha256": "b0f7566f750766ab952338c2c4d2eb2c764dc66812a3049f553e88d33d02eef5"
},
"downloads": -1,
"filename": "steelseries-sonar-py-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d54a6d7f9148bed0c1d722c77b24c241",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 7990,
"upload_time": "2024-01-03T16:08:02",
"upload_time_iso_8601": "2024-01-03T16:08:02.057492Z",
"url": "https://files.pythonhosted.org/packages/87/25/48ad03cc4fc60f48308ac6c8e3bbc6cf558b9b4c5e727447efe4d416838c/steelseries-sonar-py-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 16:08:02",
"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
