/SoCo

Permalink
Switch branches/tags
Nothing to show
Find file Copy path
05bbb25 Mar 19, 2017
1 contributor

Users who have contributed to this file
Raw Blame History
163 lines (126 sloc) 4.61 KB

Examples

This page contains collection of small examples to show of the features of SoCo and hopefully get you well started with the library.

All examples are shown as if entered in the Python interpreter (as apposed to executed from a file) because that makes it easy to incorporate output in the code listings.

All the examples from :ref:`examples_playback_control` and forward assume that you have followed one of the examples in :ref:`examples_getting_your_devices` and therefore already have a variable named device that points to a :class:`soco.SoCo` instance.

Getting your devices

Getting all your devices

To get all your devices use the :func:`soco.discover` function:

>>> import soco
>>> devices = soco.discover()
>>> devices
set([SoCo("192.168.0.10"), SoCo("192.168.0.30"), SoCo("192.168.0.17")])
>>> device = devices.pop()
>>> device
SoCo("192.168.0.16")

Getting any device

To get any device use the :func:`soco.discovery.any_soco` function. This can be useful for cases where you really do not care which one you get, you just need one e.g. to query for music library information:

>>> import soco
>>> device = soco.discovery.any_soco()
>>> device
SoCo("192.168.0.16")

Getting a named device

Getting a device by player name can be done with the :func:`soco.discovery.by_name` function:

>>> from soco.discovery import by_name
>>> device = by_name("Living Room")
>>> device
SoCo("192.168.1.18")

Playback control

Play, pause and stop

The normal play, pause and stop functionality is provided with similarly named methods (:meth:`~soco.core.SoCo.play`, :meth:`~soco.core.SoCo.pause` and :meth:`~soco.core.SoCo.stop`) on the :class:`~soco.core.SoCo` instance and the current state is included in the output of :meth:`~soco.core.SoCo.get_current_transport_info`:

>>> device.get_current_transport_info()['current_transport_state']
'STOPPED'
>>> device.play()
>>> device.get_current_transport_info()['current_transport_state']
'PLAYING'
>>> device.pause()
>>> device.get_current_transport_info()['current_transport_state']
'PAUSED_PLAYBACK'

More playback control with next, previous and seek

Navigating to the next or previous track is similarly done with methods of the same name (:meth:`~soco.core.SoCo.next` and :meth:`~soco.core.SoCo.previous`) and information about the current position in the queue is contained in the output from :meth:`~soco.core.SoCo.get_current_track_info`:

>>> device.get_current_track_info()['playlist_position']
'29'
>>> device.next()
>>> device.get_current_track_info()['playlist_position']
'30'
>>> device.previous()
>>> device.get_current_track_info()['playlist_position']
'29'

Seeking is done with the :meth:`~soco.core.SoCo.seek` method. Note that the input for that method is a string on the form "HH:MM:SS" or "H:MM:SS". The current position is also contained in :meth:`~soco.core.SoCo.get_current_track_info`:

>>> device.get_current_track_info()['position']
'0:02:59'
>>> device.seek("0:00:30")
>>> device.get_current_track_info()['position']
'0:00:31'

Seeing and manipulating the queue

Getting the queue

Getting the queue is done with the :meth:`~soco.core.SoCo.get_queue` method:

>>> queue = device.get_queue()
>>> queue
Queue(items=[<DidlMusicTrack 'b'Blackened'' at 0x7f2237006dd8>, ..., <DidlMusicTrack 'b'Dyers Eve'' at 0x7f2237006828>])

The returned :class:`~soco.data_structures.Queue` object is a sequence of items from the queue, meaning that it can be iterated over and its length aquired with :func:`len`:

>>> len(queue)
9
>>> for item in queue:
...     print(item.title)
...
Blackened
...and Justice for All
Eye of the Beholder
One
The Shortest Straw
Harvester of Sorrow
The Frayed Ends of Sanity
To Live Is to Die
Dyers Eve

The queue object also has :attr:`~.ListOfMusicInfoItems.total_matches` and :attr:`~.ListOfMusicInfoItems.number_returned` attributes, which are used to figure out whether paging is required in order to get all elements of the queue. See the :class:`~.ListOfMusicInfoItems` docstring for details.

Clearing the queue

Clearing the queue is done with the :meth:`~soco.core.SoCo.clear_queue` method as follows:

>>> queue = device.get_queue()
>>> len(queue)
9
>>> device.clear_queue()
>>> queue = device.get_queue()
>>> len(queue)
0