Update documentation

[python-musicpdaio.git] / doc / source / tutorial.rst

diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
index 31cbde9d51ed4f798c9ec362cbdd236cb28e0822..95e69488c895c9bbe913ff3d1ab99ca36920abbe 100644 (file)
--- a/doc/source/tutorial.rst
+++ b/doc/source/tutorial.rst
@@ -23,9 +23,68 @@ For now the code is in early development stage. No releases are made.
 Getting started
 ----------------
 
+.. index:: single: command; searchadd
+
+**Connect, clear the queue, add tracks**
+
+.. sourcecode:: python
+
+   import mpdaio
+
+   client = mpdaio.MPDClient()
+   await client.ping()         # Plain connection test
+   print(client.version)       # Prints MPD's protocol version
+   print(await client.clear()) # Clears the current queue
+   # Add all tracks from artist "Amon Tobin"
+   print(await client.searchadd('(Artist == "Amon Tobin")'))
+   await client.play()
+   await client.setvol(60)
+   print(await client.currentsong())
+   await client.close()        # Finally close connection
+
+.. index:: single: command; password
+
+**Using a specific host, port and a password.**
+
+The password is sent when a connection is made, no need to explicitly send the
+password command.
+
+.. sourcecode:: python
+
+   client = mpdaio.MPDClient(host='example.org', port='6601', password='53(237')
+   await client.ping()
+
+**Wrapping some commands in a python script**
 
 .. literalinclude:: tutorial/tutorial-00.py
 
+.. index:: single: command; albumart
+
+**Fetch album art for the given track**
+
+The logic is similar with `readpicture` command.
+
+.. sourcecode:: python
+
+   client = mpdaio.MPDClient()
+   # Looking for cover art in 'Tool/2001-Lateralus/'
+   track = 'Tool/2001-Lateralus/09-Tool - Lateralus.flac'
+   aart = await cli.albumart(track, 0)
+   received = int(aart.get('binary'))
+   size = int(aart.get('size'))
+   with open('/tmp/cover', 'wb') as cover:
+       # aart = {'size': 42, 'binary': 2051, data: bytes(...)}
+       cover.write(aart.get('data'))
+       while received < size:
+           aart = await cli.albumart(track, received)
+           cover.write(aart.get('data'))
+           received += int(aart.get('binary'))
+       if received != size:
+           print('something went wrong')
+   await cli.close()
+
+Cf. `MPD protocol documentation`_ for more binary responses.
+
 
 Concurrency
 -----------
@@ -33,4 +92,5 @@ Concurrency
 .. literalinclude:: tutorial/tutorial-01.py
 
 
+.. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/
 .. vim: spell spelllang=en