Skip to main content

Python library for interfacing with Sony's Songpal devices

Project description

PyPI version

Python 3 implementation of SongPal protocol as used by Sony’s soundbar and potentially other devices.

Supported devices

The library has been tested for now with following devices:

  • HT-XT3

  • HT-NT5

  • HT-MT500

  • HT-ZF9

  • SRS-X77, SRS-X88

  • STR-DN1060, STR-DN1070, STR-DN1080

Getting started

Installation

The easiest way for installing this project is by using pypi inside a virtualenv.

$ 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:

$ 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.

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.

$ 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.

Status

$ songpal status

will display some basic information about the device, such as whether it is powered on and what are its volume settings.

Power Control

power command can be used to both turning the device on and off, and change its power settings.

$ songpal power

$ songpal power settings

$ songpal power

$ songpal power set quickStartMode on

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' 15

Sound Settings

Your 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 4

Zone 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 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.

$ 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.

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:

$ 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.

$ 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 describes the API this project (currently partially) implements.

The Camera Remote API 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/

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-songpal-0.11.2.tar.gz (25.7 kB view details)

Uploaded Source

Built Distribution

python_songpal-0.11.2-py3-none-any.whl (41.8 kB view details)

Uploaded Python 3

File details

Details for the file python-songpal-0.11.2.tar.gz.

File metadata

  • Download URL: python-songpal-0.11.2.tar.gz
  • Upload date:
  • Size: 25.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.4

File hashes

Hashes for python-songpal-0.11.2.tar.gz
Algorithm Hash digest
SHA256 1c9156ebefeb9072eba4f0cd769a81e6b1f4a1ab08d91dc647018ac78563c228
MD5 f4166aa6d95646e7fdf130f367299d1b
BLAKE2b-256 a7c899ba09795872562e7d7585ae08726f7a34d240334f77a07443e02caf6ae1

See more details on using hashes here.

File details

Details for the file python_songpal-0.11.2-py3-none-any.whl.

File metadata

  • Download URL: python_songpal-0.11.2-py3-none-any.whl
  • Upload date:
  • Size: 41.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.4

File hashes

Hashes for python_songpal-0.11.2-py3-none-any.whl
Algorithm Hash digest
SHA256 761cfedc0003e747ea02bf01e3ef15f275ed20fa694014bfa2c42458e92651d1
MD5 93d7079a3c3118759b70585cb302be23
BLAKE2b-256 afca4201ed20bd5b19acc43d9e1d81c3bcfc6410fef1d8e295470c6f3f50fa3c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page