python-songpal
==============
|PyPI version| |Black|
Python 3 implementation of SongPal protocol as used by Sony's soundbar
and potentially other devices.
.. NOTE::
This project is currently at its alpha stage and all contributions,
whether reporting about devices working with this or creating pull
requests to implement missing functionality are more than welcome!
Supported devices
-----------------
The library has been tested to work with following devices:
* BDV-N9200W
* CMT-SX7B
* HT-XT2, HT-XT3
* HT-NT5
* HT-MT500
* HT-ZF9
* HT-ST5000
* SRS-X77, SRS-X88, SRS-X99
* STR-DN1060, STR-DN1070, STR-DN1080
* STR-AZ5000ES
* STR-AN1000, TA-AN1000
.. NOTE::
If your device is not listed here but is working, feel free to contribute a device info file (see devinfos/ directory) by typing `songpal dump-devinfo <filename>` and creating a pull request on this repository.
This information can later be useful for extending the support for those devices.
.. NOTE::
Sony's `Supported devices page <http://vssupport.sony.net/en_ww/device.html>`_ lists devices,
which will probably also work with this library.
If you have a device which is not listed above, please create a pull request
or an issue on github!
Getting started
---------------
Installation
~~~~~~~~~~~~
The easiest way to install is by using pip:
.. code-block::
$ pip install python-songpal
Locating the endpoint
~~~~~~~~~~~~~~~~~~~~~
To communicate with the device you need to locate its endpoint URL.
The easiest way to do is to execute the discover command:
.. code-block::
$ songpal discover
Discovering for 3 seconds
Found HT-XT3 - BAR-2015
* API version: 1.0
* Endpoint: http://192.168.1.1:10000/sony
* Services:
- Service: guide
- Service: system
- Service: audio
- Service: avContent
This will run a UPnP discovery to find out responsive devices
implementing the ScalarWebAPI.
.. WARNING::
If you are running the command on another network than the device
is residing, you will need to locate the endpoint with some other means.
The endpoint can be defined with ``--endpoint`` option, or alternatively
``SONGPAL_ENDPOINT`` environment variable can be set.
General Usage
~~~~~~~~~~~~~
The accompanied ``songpal`` tool can be used to control your device.
All available commands can be listed with ``--help`` and more help on each
command can be obtained by passing it to the sub-command, e.g., ``songpal power --help``.
Most interesting commands are most likely ``power``, ``output``, ``volume``, and ``sound``.
Generally speaking invoking a command without any parameters will display
some relevant information like settings or active output.
For debugging ``-d`` (``--debug``) can be passed
-- also multiple times for increased verbosity -- for
protocol-level information.
Some of the commands can be used to adjust settings related to that functionality,
usually by passing the `target` and its wanted `value` as parameters to the command.
.. code-block::
$ songpal bluetooth mode off
On commands which are not mainly used for settings, such as power_, require
explicit `set` sub-command for changing the settings.
.. WARNING::
Refer to help of the specific command to find the correct format.
TODO: Make the CLI consistent on this.
Status
------
.. code-block::
$ songpal status
will display some basic information about the device,
such as whether it is powered on and what are its volume settings.
.. _power:
Power Control
-------------
``power`` command can be used to both turning the device on and off,
and change its power settings.
.. code-block:: bash
$ songpal power
$ songpal power settings
$ songpal power
$ songpal power set quickStartMode on
.. NOTE::
For turning on the device the quick boot has to be activated;
a patch for adding wake-on-lan support to allow starting the device
without quick boot are welcome.
.. WARNING::
The device seems to report sometimes its status to be off even
when that is not the case (may be related to quick boot mode being 'on').
Please enable it and restart the device fully before reporting a bug
related to this.
Volume Control
--------------
.. code-block::
$ songpal volume [-- output 'output title'] [<value>|mute|unmute]
$ songpal volume 20
$ songpal volume +5
$ songpal volume -10
$ songpal volume --output 'Zone 2'
$ songpal volume --output 'Main Zone' 15
Sound Settings
--------------
Your device may support various sound-related settings,
such as night mode or adjusting the subwoofer volume.
.. code-block::
$ songpal sound
$ songpal sound nightMode off
$ songpal sound subwooferLevel 4
Zone Control
--------------
.. code-block::
$ songpal zone
Zones:
* Main Zone (uri: extOutput:zone?zone=1) (active)
* Zone 2 (uri: extOutput:zone?zone=2) (active)
* Zone 3 (uri: extOutput:zone?zone=3)
* HDMI Zone (uri: extOutput:zone?zone=4)
$ songpal zone 'Main Zone'
Activating Main Zone (uri: extOutput:zone?zone=1) (active)
$ songpal zone 'Zone 2' true
Activating Zone 2 (uri: extOutput:zone?zone=2) (active)
$ songpal zone 'Zone 2' false
Deactivating Zone 2 (uri: extOutput:zone?zone=2) (active)
Input Control
--------------
without zones:
.. code-block::
$ songpal input
* HDMI1 (uri: extInput:hdmi?port=1)
* HDMI2 (uri: extInput:hdmi?port=2) (active)
* HDMI3 (uri: extInput:hdmi?port=3)
$ songpal input HDMI1
with zones:
.. code-block::
$ songpal input
Inputs:
* SOURCE (uri: extInput:source)
- extOutput:zone?zone=2
- extOutput:zone?zone=3
- extOutput:zone?zone=4
* GAME (uri: extInput:game) (active)
- extOutput:zone?zone=1
- extOutput:zone?zone=4
* SAT/CATV (uri: extInput:sat-catv)
- extOutput:zone?zone=1
- extOutput:zone?zone=2
- extOutput:zone?zone=3
- extOutput:zone?zone=4
* VIDEO 1 (uri: extInput:video?port=1)
- extOutput:zone?zone=1
- extOutput:zone?zone=2
- extOutput:zone?zone=3
- extOutput:zone?zone=4
* VIDEO 2 (uri: extInput:video?port=2)
- extOutput:zone?zone=1
- extOutput:zone?zone=4
* TV (uri: extInput:tv)
- extOutput:zone?zone=1
* SA-CD/CD (uri: extInput:sacd-cd)
- extOutput:zone?zone=1
- extOutput:zone?zone=2
- extOutput:zone?zone=3
- extOutput:zone?zone=4
* Bluetooth Audio (uri: extInput:btAudio)
- extOutput:zone?zone=1
- extOutput:zone?zone=2
- extOutput:zone?zone=3
$ songpal input 'VIDEO 1'
$ songpal input 'SOURCE' --output 'Zone 2'
Device Settings
---------------
To list available settings, use ``settings`` command.
.. code-block:: bash
$ songpal settings
Do note that some settings (e.g. bluetooth settings) are not listed in the
global settings tree, but have to be separatedly accessed using the ``bluetooth`` command.
.. NOTE::
Setting global settings directly via the CLI is not currently supported,
but can potentially be accessed via their respective commands:
``bluetooth``, ``sound``, ``power``.
Patches improving this are welcome!
Group Control
-------------
.. code-block::
$ songpal group
Group command require using the UPnP URL ``--url`` instead of the API ``--endpoint``, and you'll need the ``UUIDs`` of the devices you want to group as well. Both of these can be obtained through the ``discover`` function. All group commands should be executed on the master
Creating groups:
.. code-block::
$ songpal group --url [upnpurl] create [groupname] [slave uuids]
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" create GroupName uuid:00000000-0000-1010-8000-xxxx uuid:00000000-0000-1010-8000-xxxx
Aborting groups
.. code-block::
$ songpal group --url [pnpurl] abort
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" abort
Changing volume
.. code-block::
$ songpal group --url [pnpurl] volume [value -100,100]
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" volume -- -5
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" volume 5
Muting
.. code-block::
$ songpal group --url [pnpurl] mute [true|false]
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" mute true
$ songpal group --url "http://x.x.x.x:52323/dmr.xml" mute false
Executing custom commands
-------------------------
For experimenting it can be useful to execute arbitrary commands against the endpoint.
You can access the available methods by calling ``songpal list-all``.
``command`` can be used for that as follows:
.. code-block::
$ songpal command system getSystemInformation
Notification support
--------------------
The protocol supports subscribing to notifications on subsystem basis.
Executing `songpal notifications` without any parameters will list
available notifications.
Every notification can be listened to separately, or alternatively
all notifications from a single subsystem can be subscribed to.
.. code-block::
$ songpal notifications --listen-all avContent
Contributing
------------
Reporting bugs or supported devices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When reporting bugs or informing about supported device not listed above,
please consider attaching the output of ``songpal dump-devinfo`` with your report.
API information
~~~~~~~~~~~~~~~
`Audio Control API <https://developer.sony.com/develop/audio-control-api/>`_ describes
the API this project (currently partially) implements.
The `Camera Remote API <https://developer.sony.com/develop/cameras/get-started/>`_
is also similar to this, and may also be useful for developers.
Home Assistant support
----------------------
Home Assistant supports devices using this library directly since 0.65: https://home-assistant.io/components/media_player.songpal/
.. |PyPI version| image:: https://badge.fury.io/py/python-songpal.svg
:target: https://badge.fury.io/py/python-songpal
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Raw data
{
"_id": null,
"home_page": "https://github.com/rytilahti/python-songpal",
"name": "python-songpal",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Teemu R",
"author_email": "tpr@iki.fi",
"download_url": "https://files.pythonhosted.org/packages/27/12/a41586ed15da6e355da914792bc7a6b5a58c1c7b0ff6fd25069a56bad423/python_songpal-0.16.2.tar.gz",
"platform": null,
"description": "python-songpal\n==============\n\n|PyPI version| |Black|\n\nPython 3 implementation of SongPal protocol as used by Sony's soundbar\nand potentially other devices.\n\n.. NOTE::\n\n This project is currently at its alpha stage and all contributions,\n whether reporting about devices working with this or creating pull\n requests to implement missing functionality are more than welcome!\n\nSupported devices\n-----------------\n\nThe library has been tested to work with following devices:\n\n* BDV-N9200W\n* CMT-SX7B\n* HT-XT2, HT-XT3\n* HT-NT5\n* HT-MT500\n* HT-ZF9\n* HT-ST5000\n* SRS-X77, SRS-X88, SRS-X99\n* STR-DN1060, STR-DN1070, STR-DN1080\n* STR-AZ5000ES\n* STR-AN1000, TA-AN1000\n\n.. NOTE::\n\n If your device is not listed here but is working, feel free to contribute a device info file (see devinfos/ directory) by typing `songpal dump-devinfo <filename>` and creating a pull request on this repository.\n This information can later be useful for extending the support for those devices.\n\n.. NOTE::\n\n Sony's `Supported devices page <http://vssupport.sony.net/en_ww/device.html>`_ lists devices,\n which will probably also work with this library.\n\n If you have a device which is not listed above, please create a pull request\n or an issue on github!\n\n\nGetting started\n---------------\n\nInstallation\n~~~~~~~~~~~~\n\nThe easiest way to install is by using pip:\n\n.. code-block::\n\n $ pip install python-songpal\n\nLocating the endpoint\n~~~~~~~~~~~~~~~~~~~~~\n\nTo communicate with the device you need to locate its endpoint URL.\nThe easiest way to do is to execute the discover command:\n\n.. code-block::\n\n $ songpal discover\n\n Discovering for 3 seconds\n Found HT-XT3 - BAR-2015\n * API version: 1.0\n * Endpoint: http://192.168.1.1:10000/sony\n * Services:\n - Service: guide\n - Service: system\n - Service: audio\n - Service: avContent\n\n\nThis will run a UPnP discovery to find out responsive devices\nimplementing the ScalarWebAPI.\n\n.. WARNING::\n If you are running the command on another network than the device\n is residing, you will need to locate the endpoint with some other means.\n\nThe endpoint can be defined with ``--endpoint`` option, or alternatively\n``SONGPAL_ENDPOINT`` environment variable can be set.\n\nGeneral Usage\n~~~~~~~~~~~~~\n\nThe accompanied ``songpal`` tool can be used to control your device.\nAll available commands can be listed with ``--help`` and more help on each\ncommand can be obtained by passing it to the sub-command, e.g., ``songpal power --help``.\nMost interesting commands are most likely ``power``, ``output``, ``volume``, and ``sound``.\n\nGenerally speaking invoking a command without any parameters will display\nsome relevant information like settings or active output.\n\nFor debugging ``-d`` (``--debug``) can be passed\n-- also multiple times for increased verbosity -- for\nprotocol-level information.\n\nSome of the commands can be used to adjust settings related to that functionality,\nusually by passing the `target` and its wanted `value` as parameters to the command.\n\n.. code-block::\n\n $ songpal bluetooth mode off\n\nOn commands which are not mainly used for settings, such as power_, require\nexplicit `set` sub-command for changing the settings.\n\n.. WARNING::\n\n Refer to help of the specific command to find the correct format.\n\n TODO: Make the CLI consistent on this.\n\nStatus\n------\n\n.. code-block::\n\n $ songpal status\n\n\nwill display some basic information about the device,\nsuch as whether it is powered on and what are its volume settings.\n\n.. _power:\n\nPower Control\n-------------\n\n``power`` command can be used to both turning the device on and off,\nand change its power settings.\n\n.. code-block:: bash\n\n $ songpal power\n\n $ songpal power settings\n\n $ songpal power\n\n $ songpal power set quickStartMode on\n\n.. NOTE::\n For turning on the device the quick boot has to be activated;\n a patch for adding wake-on-lan support to allow starting the device\n without quick boot are welcome.\n\n.. WARNING::\n The device seems to report sometimes its status to be off even\n when that is not the case (may be related to quick boot mode being 'on').\n\n Please enable it and restart the device fully before reporting a bug\n related to this.\n\nVolume Control\n--------------\n\n.. code-block::\n\n $ songpal volume [-- output 'output title'] [<value>|mute|unmute]\n\n $ songpal volume 20\n\n $ songpal volume +5\n\n $ songpal volume -10\n\n $ songpal volume --output 'Zone 2'\n\n\n $ songpal volume --output 'Main Zone' 15\n\nSound Settings\n--------------\n\nYour device may support various sound-related settings,\nsuch as night mode or adjusting the subwoofer volume.\n\n.. code-block::\n\n $ songpal sound\n\n $ songpal sound nightMode off\n\n $ songpal sound subwooferLevel 4\n\n\nZone Control\n--------------\n\n.. code-block::\n\n $ songpal zone\n\n Zones:\n * Main Zone (uri: extOutput:zone?zone=1) (active)\n * Zone 2 (uri: extOutput:zone?zone=2) (active)\n * Zone 3 (uri: extOutput:zone?zone=3)\n * HDMI Zone (uri: extOutput:zone?zone=4)\n\n $ songpal zone 'Main Zone'\n\n Activating Main Zone (uri: extOutput:zone?zone=1) (active)\n\n $ songpal zone 'Zone 2' true\n\n Activating Zone 2 (uri: extOutput:zone?zone=2) (active)\n\n $ songpal zone 'Zone 2' false\n\n Deactivating Zone 2 (uri: extOutput:zone?zone=2) (active)\n\nInput Control\n--------------\n\nwithout zones:\n.. code-block::\n\n $ songpal input\n * HDMI1 (uri: extInput:hdmi?port=1)\n * HDMI2 (uri: extInput:hdmi?port=2) (active)\n * HDMI3 (uri: extInput:hdmi?port=3)\n\n $ songpal input HDMI1\n\n\nwith zones:\n.. code-block::\n\n $ songpal input\n\n Inputs:\n * SOURCE (uri: extInput:source)\n - extOutput:zone?zone=2\n - extOutput:zone?zone=3\n - extOutput:zone?zone=4\n * GAME (uri: extInput:game) (active)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=4\n * SAT/CATV (uri: extInput:sat-catv)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=2\n - extOutput:zone?zone=3\n - extOutput:zone?zone=4\n * VIDEO 1 (uri: extInput:video?port=1)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=2\n - extOutput:zone?zone=3\n - extOutput:zone?zone=4\n * VIDEO 2 (uri: extInput:video?port=2)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=4\n * TV (uri: extInput:tv)\n - extOutput:zone?zone=1\n * SA-CD/CD (uri: extInput:sacd-cd)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=2\n - extOutput:zone?zone=3\n - extOutput:zone?zone=4\n * Bluetooth Audio (uri: extInput:btAudio)\n - extOutput:zone?zone=1\n - extOutput:zone?zone=2\n - extOutput:zone?zone=3\n\n $ songpal input 'VIDEO 1'\n\n $ songpal input 'SOURCE' --output 'Zone 2'\n\n\nDevice Settings\n---------------\n\nTo list available settings, use ``settings`` command.\n\n.. code-block:: bash\n\n $ songpal settings\n\n\nDo note that some settings (e.g. bluetooth settings) are not listed in the\nglobal settings tree, but have to be separatedly accessed using the ``bluetooth`` command.\n\n.. NOTE::\n\n Setting global settings directly via the CLI is not currently supported,\n but can potentially be accessed via their respective commands:\n ``bluetooth``, ``sound``, ``power``.\n\n Patches improving this are welcome!\n\n\nGroup Control\n-------------\n\n.. code-block::\n\n $ songpal group\n\nGroup command require using the UPnP URL ``--url`` instead of the API ``--endpoint``, and you'll need the ``UUIDs`` of the devices you want to group as well. Both of these can be obtained through the ``discover`` function. All group commands should be executed on the master\n\nCreating groups:\n\n.. code-block::\n\n $ songpal group --url [upnpurl] create [groupname] [slave uuids]\n\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" create GroupName uuid:00000000-0000-1010-8000-xxxx uuid:00000000-0000-1010-8000-xxxx\n\nAborting groups\n\n.. code-block::\n\n $ songpal group --url [pnpurl] abort\n\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" abort\n\nChanging volume\n\n.. code-block::\n\n $ songpal group --url [pnpurl] volume [value -100,100]\n\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" volume -- -5\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" volume 5\n\nMuting\n\n.. code-block::\n\n $ songpal group --url [pnpurl] mute [true|false]\n\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" mute true\n $ songpal group --url \"http://x.x.x.x:52323/dmr.xml\" mute false\n\n\n\nExecuting custom commands\n-------------------------\n\nFor experimenting it can be useful to execute arbitrary commands against the endpoint.\nYou can access the available methods by calling ``songpal list-all``.\n\n``command`` can be used for that as follows:\n\n.. code-block::\n\n $ songpal command system getSystemInformation\n\n\nNotification support\n--------------------\n\nThe protocol supports subscribing to notifications on subsystem basis.\nExecuting `songpal notifications` without any parameters will list\navailable notifications.\n\nEvery notification can be listened to separately, or alternatively\nall notifications from a single subsystem can be subscribed to.\n\n.. code-block::\n\n $ songpal notifications --listen-all avContent\n\nContributing\n------------\n\nReporting bugs or supported devices\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhen reporting bugs or informing about supported device not listed above,\nplease consider attaching the output of ``songpal dump-devinfo`` with your report.\n\n\nAPI information\n~~~~~~~~~~~~~~~\n\n`Audio Control API <https://developer.sony.com/develop/audio-control-api/>`_ describes\nthe API this project (currently partially) implements.\n\nThe `Camera Remote API <https://developer.sony.com/develop/cameras/get-started/>`_\nis also similar to this, and may also be useful for developers.\n\n\nHome Assistant support\n----------------------\n\nHome Assistant supports devices using this library directly since 0.65: https://home-assistant.io/components/media_player.songpal/\n\n\n.. |PyPI version| image:: https://badge.fury.io/py/python-songpal.svg\n :target: https://badge.fury.io/py/python-songpal\n\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Python library for interfacing with Sony's Songpal devices",
"version": "0.16.2",
"project_urls": {
"Homepage": "https://github.com/rytilahti/python-songpal",
"Repository": "https://github.com/rytilahti/python-songpal"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "222474de916c8547e5b87824e74004fdf89d05427d4898bd08f2958c8a1e4ccd",
"md5": "86b003f761c5e560ace8d391b07b3eeb",
"sha256": "b09c5573c4aee8fd1765c1162ca9f7ac2d2a5a0c6ba05b96e2f84d2836be908a"
},
"downloads": -1,
"filename": "python_songpal-0.16.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86b003f761c5e560ace8d391b07b3eeb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 44166,
"upload_time": "2024-03-31T14:21:55",
"upload_time_iso_8601": "2024-03-31T14:21:55.284665Z",
"url": "https://files.pythonhosted.org/packages/22/24/74de916c8547e5b87824e74004fdf89d05427d4898bd08f2958c8a1e4ccd/python_songpal-0.16.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2712a41586ed15da6e355da914792bc7a6b5a58c1c7b0ff6fd25069a56bad423",
"md5": "80da6abe19db2b25a52e0b541f4188bc",
"sha256": "3c1c82d272cb13681bda22e01c29495db082139d4e390b31039870c9bc236e92"
},
"downloads": -1,
"filename": "python_songpal-0.16.2.tar.gz",
"has_sig": false,
"md5_digest": "80da6abe19db2b25a52e0b541f4188bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 42516,
"upload_time": "2024-03-31T14:21:57",
"upload_time_iso_8601": "2024-03-31T14:21:57.502455Z",
"url": "https://files.pythonhosted.org/packages/27/12/a41586ed15da6e355da914792bc7a6b5a58c1c7b0ff6fd25069a56bad423/python_songpal-0.16.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 14:21:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rytilahti",
"github_project": "python-songpal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-songpal"
}
JSON
