doc/source/tutorial.rst

   1 .. _tutorial:
   2
   3 Tutorials
   4 =========
   5
   6 Install
   7 -------
   8
   9 For now the code is in early development stage. No releases are made.
  10
  11 .. code:: bash
  12
  13    # Use a virtualenv
  14    python -m venv .../path/to/my/venv
  15    . .../path/to/my/venv/bin/activate
  16    pip install git+https://codeberg.org/MusicPlayerDaemon/python-musicpdaio.git@main
  17
  18
  19 .. todo::
  20
  21    Updating a previous installation via `pip install git+https`.
  22
  23 Getting started
  24 ----------------
  25
  26 .. index:: single: command; searchadd
  27
  28 **Connect, clear the queue, add tracks**
  29
  30 .. sourcecode:: python
  31
  32    import mpdaio
  33
  34    client = mpdaio.MPDClient()
  35    await client.ping()         # Plain connection test
  36    print(client.version)       # Prints MPD's protocol version
  37    print(await client.clear()) # Clears the current queue
  38    # Add all tracks from artist "Amon Tobin"
  39    print(await client.searchadd('(Artist == "Amon Tobin")'))
  40    await client.play()
  41    await client.setvol(60)
  42    print(await client.currentsong())
  43    await client.close()        # Finally close connection
  44
  45 .. index:: single: command; password
  46
  47 **musicpdaio** tries to come with sane defaults, then running
  48 :py:class:`mpdaio.MPDClient` with no explicit argument will try default values
  49 to connect to MPD. Cf. :ref:`reference` for more about
  50 :ref:`defaults<default_settings>`.
  51
  52 **Using a specific host, port and a password.**
  53
  54 The password is sent when a connection is made, no need to explicitly use the
  55 password command. In the following code a client is constructed with a password argument, then when the ping method is called:
  56  * the client fetch a connection from the pool
  57  * then a password command is sent with the password
  58  * finally the ping command is sent.
  59
  60 .. sourcecode:: python
  61
  62    client = mpdaio.MPDClient(host='example.org', port='6601', password='53(237')
  63    await client.ping()
  64
  65 **Wrapping some commands in a python script**
  66
  67 .. literalinclude:: tutorial/tutorial-00.py
  68
  69 .. index:: single: command; albumart
  70
  71 **Fetch album art for the given track**
  72
  73 The logic is similar with `readpicture` command.
  74
  75 .. sourcecode:: python
  76
  77    client = mpdaio.MPDClient()
  78    # Looking for cover art in 'Tool/2001-Lateralus/'
  79    track = 'Tool/2001-Lateralus/09-Tool - Lateralus.flac'
  80    aart = await cli.albumart(track, 0)
  81    received = int(aart.get('binary'))
  82    size = int(aart.get('size'))
  83    with open('/tmp/cover', 'wb') as cover:
  84        # aart = {'size': 42, 'binary': 2051, data: bytes(...)}
  85        cover.write(aart.get('data'))
  86        while received < size:
  87            aart = await cli.albumart(track, received)
  88            cover.write(aart.get('data'))
  89            received += int(aart.get('binary'))
  90        if received != size:
  91            print('something went wrong')
  92    await cli.close()
  93
  94 Cf. `MPD protocol documentation`_ for more binary responses.
  95
  96
  97 Concurrency
  98 -----------
  99
 100 .. literalinclude:: tutorial/tutorial-01.py
 101
 102 .. vim: spell spelllang=en