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 **Using a specific host, port and a password.**
  48
  49 The password is sent when a connection is made, no need to explicitly send the
  50 password command.
  51
  52 .. sourcecode:: python
  53
  54    client = mpdaio.MPDClient(host='example.org', port='6601', password='53(237')
  55    await client.ping()
  56
  57 **Wrapping some commands in a python script**
  58
  59 .. literalinclude:: tutorial/tutorial-00.py
  60
  61 .. index:: single: command; albumart
  62
  63 **Fetch album art for the given track**
  64
  65 The logic is similar with `readpicture` command.
  66
  67 .. sourcecode:: python
  68
  69    client = mpdaio.MPDClient()
  70    # Looking for cover art in 'Tool/2001-Lateralus/'
  71    track = 'Tool/2001-Lateralus/09-Tool - Lateralus.flac'
  72    aart = await cli.albumart(track, 0)
  73    received = int(aart.get('binary'))
  74    size = int(aart.get('size'))
  75    with open('/tmp/cover', 'wb') as cover:
  76        # aart = {'size': 42, 'binary': 2051, data: bytes(...)}
  77        cover.write(aart.get('data'))
  78        while received < size:
  79            aart = await cli.albumart(track, received)
  80            cover.write(aart.get('data'))
  81            received += int(aart.get('binary'))
  82        if received != size:
  83            print('something went wrong')
  84    await cli.close()
  85
  86 Cf. `MPD protocol documentation`_ for more binary responses.
  87
  88
  89 Concurrency
  90 -----------
  91
  92 .. literalinclude:: tutorial/tutorial-01.py
  93
  94 .. vim: spell spelllang=en