Package: python-songpal
Python 3 implementation of SongPal protocol as used by Sony’s soundbar
and potentially other devices.NoteThis 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 devicesThe library has been tested to work with following devices:BDV-N9200WCMT-SX7BHT-XT2, HT-XT3HT-NT5HT-MT500HT-ZF9HT-ST5000SRS-X77, SRS-X88, SRS-X99STR-DN1060, STR-DN1070, STR-DN1080STR-AZ5000ESSTR-AN1000, TA-AN1000NoteIf your device is not listed here but is working, feel free to contribute a device info file (see devinfos/ directory) by typingsongpal dump-devinfo <filename>and creating a pull request on this repository.
This information can later be useful for extending the support for those devices.NoteSony’sSupported devices pagelists 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 startedInstallationThe easiest way to install is by using pip:$ pip install python-songpalLocating the endpointTo communicate with the device you need to locate its endpoint URL.
The easiest way to do is to execute the discover command:$ 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: avContentThis will run a UPnP discovery to find out responsive devices
implementing the ScalarWebAPI.WarningIf 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--endpointoption, or alternativelySONGPAL_ENDPOINTenvironment variable can be set.General UsageThe accompaniedsongpaltool can be used to control your device.
All available commands can be listed with--helpand 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 likelypower,output,volume, andsound.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 thetargetand its wantedvalueas parameters to the command.$ songpal bluetooth mode offOn commands which are not mainly used for settings, such aspower, require
explicitsetsub-command for changing the settings.WarningRefer to help of the specific command to find the correct format.TODO: Make the CLI consistent on this.Status$ songpal statuswill display some basic information about the device,
such as whether it is powered on and what are its volume settings.Power Controlpowercommand can be used to both turning the device on and off,
and change its power settings.$songpalpower$songpalpowersettings$songpalpower$songpalpowersetquickStartModeonNoteFor 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.WarningThe 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$ 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' 15Sound SettingsYour device may support various sound-related settings,
such as night mode or adjusting the subwoofer volume.$ songpal sound

$ songpal sound nightMode off

$ songpal sound subwooferLevel 4Zone Control$ 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 Controlwithout 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 HDMI1with 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 SettingsTo list available settings, usesettingscommand.$songpalsettingsDo note that some settings (e.g. bluetooth settings) are not listed in the
global settings tree, but have to be separatedly accessed using thebluetoothcommand.NoteSetting 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$ songpal groupGroup command require using the UPnP URL--urlinstead of the API--endpoint, and you’ll need theUUIDsof the devices you want to group as well. Both of these can be obtained through thediscoverfunction. All group commands should be executed on the masterCreating groups:$ 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-xxxxAborting groups$ songpal group --url [pnpurl] abort

$ songpal group --url "http://x.x.x.x:52323/dmr.xml" abortChanging volume$ 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 5Muting$ 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 falseExecuting custom commandsFor experimenting it can be useful to execute arbitrary commands against the endpoint.
You can access the available methods by callingsongpallist-all.commandcan be used for that as follows:$ songpal command system getSystemInformationNotification supportThe protocol supports subscribing to notifications on subsystem basis.
Executingsongpal notificationswithout 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.$ songpal notifications --listen-all avContentContributingReporting bugs or supported devicesWhen reporting bugs or informing about supported device not listed above,
please consider attaching the output ofsongpaldump-devinfowith your report.API informationAudio Control APIdescribes
the API this project (currently partially) implements.TheCamera Remote APIis also similar to this, and may also be useful for developers.Home Assistant supportHome Assistant supports devices using this library directly since 0.65:https://home-assistant.io/components/media_player.songpal/