README.rst 4.06 KB
Newer Older
Kaliko Jack's avatar
Kaliko Jack committed
1
2
3
==============
python-musicpd
==============
J. Alexander Treuman's avatar
J. Alexander Treuman committed
4

Kaliko Jack's avatar
Kaliko Jack committed
5
6
Getting python-musicpd
----------------------
J. Alexander Treuman's avatar
J. Alexander Treuman committed
7

Kaliko Jack's avatar
Kaliko Jack committed
8
The latest release of python-musicpd can be found at
Kaliko Jack's avatar
Kaliko Jack committed
9
http://pypi.python.org/pypi/python-musicpd.
J. Alexander Treuman's avatar
J. Alexander Treuman committed
10
11
12
13
14
15
16
17


Getting the latest source code
------------------------------

If you would instead like to use the latest source code, you can grab a copy
of the development version from git by running the command:

Kaliko Jack's avatar
Kaliko Jack committed
18
  git clone git://git.kaliko.me/python-musicpd.git
J. Alexander Treuman's avatar
J. Alexander Treuman committed
19
20
21
22
23


Installing from source
----------------------

Kaliko Jack's avatar
Kaliko Jack committed
24
To install python-musicpd from source, simply run the command::
J. Alexander Treuman's avatar
J. Alexander Treuman committed
25

Kaliko Jack's avatar
Kaliko Jack committed
26
  python3 setup.py install
J. Alexander Treuman's avatar
J. Alexander Treuman committed
27
28

You can use the `--help` switch to `setup.py` for a complete list of commands
Kaliko Jack's avatar
Kaliko Jack committed
29
and their options.  See the `Installing Python Modules`_ document for more details.
J. Alexander Treuman's avatar
J. Alexander Treuman committed
30
31
32
33
34


Using the client library
------------------------

Kaliko Jack's avatar
Kaliko Jack committed
35
The client library can be used as follows::
J. Alexander Treuman's avatar
J. Alexander Treuman committed
36

Kaliko Jack's avatar
Kaliko Jack committed
37
38
39
40
41
42
    client = musicpd.MPDClient()       # create client object
    client.connect('localhost', 6600)  # connect to localhost:6600
    print client.mpd_version           # print the mpd version
    print client.cmd('one', 2)         # print result of the command "cmd one 2"
    client.close()                     # send the close command
    client.disconnect()                # disconnect from the server
J. Alexander Treuman's avatar
J. Alexander Treuman committed
43
44
45

A list of supported commands, their arguments (as MPD currently understands
them), and the functions used to parse their responses can be found in
Kaliko Jack's avatar
Kaliko Jack committed
46
`doc/commands.txt`.  See the `MPD protocol documentation`_ for more
47
details.
J. Alexander Treuman's avatar
J. Alexander Treuman committed
48
49

Command lists are also supported using `command_list_ok_begin()` and
Kaliko Jack's avatar
Kaliko Jack committed
50
51
`command_list_end()` ::

Kaliko Jack's avatar
Kaliko Jack committed
52
53
54
55
    client.command_list_ok_begin()       # start a command list
    client.update()                      # insert the update command into the list
    client.status()                      # insert the status command into the list
    results = client.command_list_end()  # results will be a list with the results
J. Alexander Treuman's avatar
J. Alexander Treuman committed
56

Kaliko Jack's avatar
Kaliko Jack committed
57
58
Provide a 2-tuple as argument for command supporting ranges (cf. `MPD protocol documentation`_ for more details).
Possible ranges are: "START:END", "START:" and ":" ::
Kaliko Jack's avatar
Kaliko Jack committed
59
60
61
62
63
64
65
66
67

    # An intelligent clear
    # clears played track in the queue, currentsong included
    pos = client.currentsong().get('pos', 0)
    # the 2-tuple range object accepts str, no need to convert to int
    client.delete((0, pos))
    # missing end interpreted as highest value possible, pay attention still need a tuple.
    client.delete((pos,))  # purge queue from current to the end

Kaliko Jack's avatar
Kaliko Jack committed
68
69
70
71
72
73
74
75
A notable case is the `rangeid` command allowing an empty range specified
as a single colon as argument (i.e. sending just ":")::

    # sending "rangeid :" to clear the range, play everything
    client.rangeid(())  # send an empty tuple

Empty start in range (i.e. ":END") are not possible and will raise a CommandError.

J. Alexander Treuman's avatar
J. Alexander Treuman committed
76
77

Commands may also return iterators instead of lists if `iterate` is set to
Kaliko Jack's avatar
Kaliko Jack committed
78
`True`::
J. Alexander Treuman's avatar
J. Alexander Treuman committed
79

Kaliko Jack's avatar
Kaliko Jack committed
80
81
82
    client.iterate = True
    for song in client.playlistinfo():
        print song['file']
J. Alexander Treuman's avatar
J. Alexander Treuman committed
83

84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
Each command have a *send\_<CMD>* and a *fetch\_<CMD>* variant, which allows to
send a MPD command and then fetch the result later.
This is useful for the idle command::

    >>> client.send_idle()
    # do something else or use function like select()
    # http://docs.python.org/howto/sockets.html#non-blocking-sockets
    # ex. select([client], [], [])
    >>> events = client.fetch_idle()

    # more complex use for example, with glib/gobject:
    >>> def callback(source, condition):
    >>>    changes = client.fetch_idle()
    >>>    print changes
    >>>    return False  # removes the IO watcher

    >>> client.send_idle()
    >>> gobject.io_add_watch(client, gobject.IO_IN, callback)
    >>> gobject.MainLoop().run()
J. Alexander Treuman's avatar
J. Alexander Treuman committed
103

Kaliko Jack's avatar
Kaliko Jack committed
104
105
Contacting authors
------------------
J. Alexander Treuman's avatar
J. Alexander Treuman committed
106

Kaliko Jack's avatar
Kaliko Jack committed
107
You can contact the original author by emailing J. Alexander Treuman
Kaliko Jack's avatar
Kaliko Jack committed
108
<jat⊘spatialrift.net>.  He can also be found idling in #mpd on
J. Alexander Treuman's avatar
J. Alexander Treuman committed
109
irc.freenode.net as jat.
Kaliko Jack's avatar
Kaliko Jack committed
110

Kaliko Jack's avatar
Kaliko Jack committed
111
The current maintainer can be found on xmpp chat room <kaliko.me⊘conf.azylum.org>
Kaliko Jack's avatar
Kaliko Jack committed
112
113
114
115
or you can contact him by email/xmpp <kaliko⊘azylum.org>.

 .. _Installing Python Modules: http://docs.python.org/3/install/
 .. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/