1Interacting with Quod Libet
2===========================
3
4
5In Python
6---------
7
8Quod Libet supports :ref:`plugins written in Python <PluginDev>`. These
9plugins can interact with songs more directly than the other interfaces,
10changing or reading metadata using dict-like !AudioFile objects. The plugin
11interface has not yet stabilized, although we do not expect it to change
12drastically in the future.
13
14
15The Unix Way
16------------
17
18
19Querying the player
20^^^^^^^^^^^^^^^^^^^
21
22Quod Libet writes information about the current song to
23``~/.quodlibet/current``. The file is in key=value form. Key values are in
24UTF-8, except for the ``~filename`` key, which has unknown encoding (but
25will point to the file being played when interpreted as a sequence of bytes).
26
27There is a ``--print-playing`` option which can use the same syntax as the
28RenamingFiles interface to print information about the current song:
29``quodlibet --print-playing '<artist> - <tracknumber~title>'``
30
31``quodlibet --status`` provides player state information. The first word
32will be either *playing*, *paused*, or *not-running*, followed by
33
34 * the selected View,
35 * volume setting (0.0 - 1.0)
36 * Playback order & repeat settings
37 * Current song progress (0.0 - 1.0)
38
39
40Controlling the player
41^^^^^^^^^^^^^^^^^^^^^^
42
43Quod Libet understands a number of command line arguments to control a running player. For a full list, see the man page.
44
45  * ``--next``, ``--previous``, ``--play``, and ``--pause`` should
46    be self-explanatory; ``--play-pause`` toggles pause on and off.
47  * ``--volume n`` sets the volume to anywhere between 0 (muted) or
48    100 (full volume)
49  * ``--seek <time>`` seeks within the current song.
50  * ``--query <search text>`` searches in your library
51    (if the current browser supports it).
52  * ``--play-file <filename>`` plays that file or directory.
53
54Quod Libet can also be controlled via a `FIFO
55<https://en.wikipedia.org/wiki/Named_pipe>`_ , ``~/.quodlibet/control``. To see
56how the command-line arguments map to FIFO commands, refer to
57``process_arguments()`` in
58https://github.com/quodlibet/quodlibet/blob/master/quodlibet/quodlibet/cli.py;
59as a simple example::
60
61    # Sets volume to 50%
62    echo volume 50 > ~/.quodlibet/control
63
64
65Integration with third party tools
66----------------------------------
67
68
69Quod Libet in Conky
70^^^^^^^^^^^^^^^^^^^
71
72`Conky <https://github.com/brndnmtthws/conky>`_ is a lightweight system
73monitor for X. It includes builtin objects for many popular music players, but
74not quodlibet (yet).  That doesn't mean you can't use conky with quodlibet.
75After installing conky, add the following to your```~/.conkyrc`` file::
76
77    ${if_existing /<path to your home directory>/.quodlibet/current}
78    ${exec quodlibet --print-playing "<artist>"}
79    ${scroll 50 ${exec quodlibet --print-playing "<title~album>"}  }
80    ${endif}
81
82
83will display the current artist on one line with a scrolling display of
84song title and album on the next line.  Conky will only attempt to display
85this information if quodlibet is playing.
86
87
88eSpeak: Speech Synthesizer
89^^^^^^^^^^^^^^^^^^^^^^^^^^
90
91You can use `eSpeak <http://espeak.sourceforge.net/>`_ to hear the current
92playing title.
93
94::
95
96    quodlibet --print-playing "<~~people~title>" | espeak -s 120  -v $(quodlibet --print-playing "<language|<language>|en>")
97
98In this example Quod Libet will use the value of the language tag to tell
99eSpeak which language/voice to use for the specific title (Use ``espeak
100--voices``` to get a list of all available languages).
101
102You can also lower the volume during speaking::
103
104    VOL=$(echo $(quodlibet --status | head -n1 | cut -d\  -f3)*100 | bc)
105    quodlibet --volume=$(echo $VOL/3 | bc)
106    quodlibet --print-playing "<~~people~title>" | espeak -s 120 -v $(quodlibet --print-playing "<language|<language>|en>")
107    quodlibet --volume=$(echo $VOL/1 | bc)
108