From c4d01c72f0172be7fa36993deb68f78eea3bf2bb Mon Sep 17 00:00:00 2001 From: Determinant Date: Wed, 5 Nov 2014 00:37:34 +0800 Subject: add readme --- README.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..41eec45 --- /dev/null +++ b/README.rst @@ -0,0 +1,57 @@ +mpd_trigger: Execute whatever you want when MPD (Music Player Daemon) changes its state +======================================================================================= + +:Author: Ted Yin +:Address: ted.sybil@gmail.com + +What Is This? +------------- +I'd like to let a notification pop up whenever MPD is playing or paused. +However, disappointing enough, I failed to find any existing programs/scripts +to achieve this little but convenient functionality. Although there is +mpd-hiss_, it has quite a number of dependencies and is written in Python with +several separated files. I think such a simply little desire should not be as +complicated as this. Even though I love programming in Python, that project +still need to polished to be flexible and easy to deploy (But it is a good +project anyway). Being different from it, this project tends to lightweight and +simple but as extensible as it can, but in the end, should be simple. After +all, a simple task deserves a simple solution. Now the code is written in C in +a single file and highly portable. It uses "patterns" to generate a command +once MPD state is being changed and pipe it into a pre-selected shell. During +the execution, it consumes few resources and imposes little overhead. + +How to Use? +----------- +First, compile it by invoking ``make``. The only executable file is +``mpd_trigger``. You could run ``./mpd_trigger -h`` to read the help. A typical +example is as follow (execute in bash): + +:: + + ./mpd_trigger 192.168.248.130 -p 6600 -e "echo 'Hey, {title} is {state}!'" + +Then play a song. Besides diagnostic outputs, you should find the output of +executing that ``echo`` command. + +You may have noticed something like ``{title}`` which is actually a pattern +representing the title of the song is to be filed in that place. +``mpd_trigger`` currently support two kinds of patterns: + +- Information patterns: ``{title}``, ``{artist}``, ``{album}``, ``{track}``, + ``{state}``, ``{elapsed_time}``, ``total_time``, ``{elapsed_pct}`` +- Conditional pattern: ``{str_to_check?stringa:stringb}`` which checks whether + ``str_to_check`` is an empty string, if it is ``stringa`` is chosen, + otherwise ``stringb``, note that the surrounding braces are removed. + + +For Mac OS X users, after installing a tool called ``terminal-notifier``, try +the following command: + +:: + + ./mpd_trigger -e 'terminal-notifier -title "{title}: {state} ({elapsed_pct}%)" -subtitle "{artist}" -message "{album} @ {track?{track}:unknown track}" -sender com.apple.iTunes' + +Finally, it is worth mentioning that patterns can be nested, for example a part +of the pattern in last example ``{track?{track}:unkown track}`` makes use of such technique. + +.. _mpd-hiss: https://github.com/ahihi/mpd-hiss -- cgit v1.2.3-70-g09d2