# pynaim
`pynaim` is a Python library and CLI tool to control Naim audio devices via their HTTP API. It provides methods for power control, playback, volume adjustment, source selection, and fetching device information.
---
## Features
- Power control: turn the device on/off
- Playback control: play, pause, stop, next/previous track, play/pause toggle
- Volume control: set, increase, decrease, mute, unmute
- Source selection: choose input source
- Query device information: diagnostics, favorites, network, now playing, volume levels, power state
- Asynchronous event stream support for real-time notifications (work in progress)
- Command-line interface (CLI) for quick control from terminal
---
## Installation
Install via PyPI:
```bash
pip install pynaim
```
---
## Usage in Python
```python
import asyncio
from pynaim import NaimController
controller = NaimController(host="192.168.1.100")
controller.turn_on()
controller.media_play()
controller.volume_up()
print(controller.get_now_playing())
```
---
## CLI Usage
Once installed, you can use the `pynaim` CLI:
```bash
# Set default host
pynaim set_host --host 192.168.1.100
# Power control
pynaim power on
pynaim power off
# Playback control
pynaim play
pynaim pause
pynaim stop
pynaim playpause
pynaim next
pynaim previous
# Volume control
pynaim volume up
pynaim volume down
pynaim volume mute
pynaim volume unmute
pynaim volume level 25
```
> Use `--verbosity` flag for more detailed logging.
---
## Event Stream
```python
async def main():
controller = NaimController(host="192.168.1.100")
await controller.event_stream()
asyncio.run(main())
```
> ⚠️ Event stream implementation is in progress; it handles reconnects but requires improved error handling.
---
## Methods
### Power
- `turn_on()`
- `turn_off()`
- `get_power()`
### Playback
- `media_play()`
- `media_pause()`
- `media_stop()`
- `media_play_pause()`
- `media_next_track()`
- `media_previous_track()`
- `get_now_playing()`
- `get_artist()`
- `get_title()`
- `get_album()`
- `get_artwork()`
### Volume
- `volume_up()`
- `volume_down()`
- `volume_set(volume: int)`
- `volume_mute()`
- `volume_unmute()`
- `get_levels()`
### Inputs / Sources
- `select_source(source_path: str)`
- `get_inputs()`
- `get_selectable_inputs()`
### Device Info
- `get_diagnostics()`
- `get_favourites()`
- `get_network()`
- `get_update()`
---
## Logging
`pynaim` uses Python's built-in `logging` module. Default level is `INFO`, HTTPX logs are set to `WARNING`.
```python
import logging
logging.basicConfig(level=logging.INFO)
```
---
## Notes
- Some methods use synchronous HTTP requests (`httpx.request`) for simplicity.
- Event streaming is asynchronous and requires `asyncio`.
- Volume up/down fetches current volume; future updates may cache the value.
- Source selection does not currently validate against available inputs.
- CLI stores default host in `~/.config/pynaim/config.json`.
---
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "pynaim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "naim, muso, audio, home-assistant, sse, asyncio",
"author": "Joeri Blaauboer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a1/ad/2af44734d78a0775b17e5a107aede80b90948d4ffd8f4cc6c3050fc3260a/pynaim-0.1.0.tar.gz",
"platform": null,
"description": "# pynaim\n\n`pynaim` is a Python library and CLI tool to control Naim audio devices via their HTTP API. It provides methods for power control, playback, volume adjustment, source selection, and fetching device information.\n\n---\n\n## Features\n\n- Power control: turn the device on/off\n- Playback control: play, pause, stop, next/previous track, play/pause toggle\n- Volume control: set, increase, decrease, mute, unmute\n- Source selection: choose input source\n- Query device information: diagnostics, favorites, network, now playing, volume levels, power state\n- Asynchronous event stream support for real-time notifications (work in progress)\n- Command-line interface (CLI) for quick control from terminal\n\n---\n\n## Installation\n\nInstall via PyPI:\n\n```bash\npip install pynaim\n```\n\n---\n\n## Usage in Python\n\n```python\nimport asyncio\nfrom pynaim import NaimController\n\ncontroller = NaimController(host=\"192.168.1.100\")\ncontroller.turn_on()\ncontroller.media_play()\ncontroller.volume_up()\nprint(controller.get_now_playing())\n```\n\n---\n\n## CLI Usage\n\nOnce installed, you can use the `pynaim` CLI:\n\n```bash\n# Set default host\npynaim set_host --host 192.168.1.100\n\n# Power control\npynaim power on\npynaim power off\n\n# Playback control\npynaim play\npynaim pause\npynaim stop\npynaim playpause\npynaim next\npynaim previous\n\n# Volume control\npynaim volume up\npynaim volume down\npynaim volume mute\npynaim volume unmute\npynaim volume level 25\n```\n\n> Use `--verbosity` flag for more detailed logging.\n\n---\n\n## Event Stream\n\n```python\nasync def main():\n controller = NaimController(host=\"192.168.1.100\")\n await controller.event_stream()\n\nasyncio.run(main())\n```\n\n> \u26a0\ufe0f Event stream implementation is in progress; it handles reconnects but requires improved error handling.\n\n---\n\n## Methods\n\n### Power\n- `turn_on()`\n- `turn_off()`\n- `get_power()`\n\n### Playback\n- `media_play()`\n- `media_pause()`\n- `media_stop()`\n- `media_play_pause()`\n- `media_next_track()`\n- `media_previous_track()`\n- `get_now_playing()`\n- `get_artist()`\n- `get_title()`\n- `get_album()`\n- `get_artwork()`\n\n### Volume\n- `volume_up()`\n- `volume_down()`\n- `volume_set(volume: int)`\n- `volume_mute()`\n- `volume_unmute()`\n- `get_levels()`\n\n### Inputs / Sources\n- `select_source(source_path: str)`\n- `get_inputs()`\n- `get_selectable_inputs()`\n\n### Device Info\n- `get_diagnostics()`\n- `get_favourites()`\n- `get_network()`\n- `get_update()`\n\n---\n\n## Logging\n\n`pynaim` uses Python's built-in `logging` module. Default level is `INFO`, HTTPX logs are set to `WARNING`.\n\n```python\nimport logging\nlogging.basicConfig(level=logging.INFO)\n```\n\n---\n\n## Notes\n- Some methods use synchronous HTTP requests (`httpx.request`) for simplicity.\n- Event streaming is asynchronous and requires `asyncio`.\n- Volume up/down fetches current volume; future updates may cache the value.\n- Source selection does not currently validate against available inputs.\n- CLI stores default host in `~/.config/pynaim/config.json`.\n\n---\n\n## License\n\nMIT License\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client and CLI for Naim Mu-so 2nd Gen (unofficial).",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/blaauboer/pynaim",
"Issues": "https://github.com/blaauboer/pynaim/issues"
},
"split_keywords": [
"naim",
" muso",
" audio",
" home-assistant",
" sse",
" asyncio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c9b5c15802e3a725866acad5a70c9e4744ee5545f33802511b33f8228297fe31",
"md5": "15a108c7c5e4f40f7011346bc91b5c2f",
"sha256": "bd9f5422ab7e2bee637f97cb401364afd7a7bdc70b4f2673fbab5451e120119e"
},
"downloads": -1,
"filename": "pynaim-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15a108c7c5e4f40f7011346bc91b5c2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7543,
"upload_time": "2025-08-17T17:00:49",
"upload_time_iso_8601": "2025-08-17T17:00:49.594147Z",
"url": "https://files.pythonhosted.org/packages/c9/b5/c15802e3a725866acad5a70c9e4744ee5545f33802511b33f8228297fe31/pynaim-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a1ad2af44734d78a0775b17e5a107aede80b90948d4ffd8f4cc6c3050fc3260a",
"md5": "114eaed7cf07b751f6f6d4acf5af81b6",
"sha256": "a008cf883a28ec852ece2bb22e45ee2e76fa082d845bf6331f525ec2c7f7966a"
},
"downloads": -1,
"filename": "pynaim-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "114eaed7cf07b751f6f6d4acf5af81b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7709,
"upload_time": "2025-08-17T17:00:51",
"upload_time_iso_8601": "2025-08-17T17:00:51.103738Z",
"url": "https://files.pythonhosted.org/packages/a1/ad/2af44734d78a0775b17e5a107aede80b90948d4ffd8f4cc6c3050fc3260a/pynaim-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 17:00:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blaauboer",
"github_project": "pynaim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pynaim"
}
JSON
