README

vimmp - vim client for xmms2 and mpd
Copyright (C) 2008 Xin Wang <wxyzin@gmail.com>
Copyright (C) 2011 Brett Wilkins <brett@catalyst.net.nz>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

####################################################################

This github repository is based off a plugin hosted on vim.org, as
seen here: http://www.vim.org/scripts/script.php?script_id=2369

I have taken the liberty of updating it a bit and attaching the
GPLv3 license for good measure.

####################################################################
Requirements
============
    Vim with +python support.
    FOR XMMS2: XMMS2 with the Python interface.
    FOR MPD: MPD and python-mpd.


Installation
============
    Putting following lines into your .vimrc

        if has('python')
            py import os, sys
            py sys.path.append(os.path.expanduser("/path/to/the/vimmp/dir/"))
            pyf /path/to/main.py
        endif

    For example, I put the vimmp dir in ~/.vim, so the lines will be:

        if has('python')
            py import os, sys
            py sys.path.append(os.path.expanduser("~/.vim/vimmp"))
            pyf ~/.vim/vimmp/main.py
        endif

    Then specify what server you are using, "xmms2" or "mpd". (Although
    the script will try to guess, but it's better to set it manually.)
        let g:vimmp_server_type="xmms2"

    Also, add following map into .vimrc

        nmap <silent> <leader>x :py vimmp_toggle()<cr>

    FOR MPD USERS
    -------------
    In addtion to above settings, you also have to set the music and
    playlist directory. They should be the same as in /etc/mpd.conf. i.e.
        let g:mpd_music_directory="~/music"
        let g:mpd_playlist_directory="~/.mpd/playlists"


Usage
=====
    Use <leader>x to toggle the play window.

    Also the following key shorts are available. Most key maps start with
    c(Contrl) or l(playList).

      <space>    Play the song under cursor.
      <cr>       Same as <space>.
      cs         Stop.
      cp         Pause.
      cr         Select a repeat mode.
                 There are three modes for XMMS2: one, all, off.
                 For MPD, there are two: off, all. So there command just toggle.
      -          Decrease volume.
      =          Increase volume.
      r          Refresh window manually.
      la         Add a file or directory to playlist.
      lc         Clear the playlist.
      ld         Remove the song under cursor from current playlist.
      lf         Shuffer the list.
      ll         Load a playlist.
      ln         Create a new playlist, and save current contents to it.
      ls         Sort the playlist, by artist, title or filename.
                 Only available for XMMS2.


Customization
=============
    Specify the id3's encoding. This option is only for XMMS2, i.e
        let g:xmms_id3_encoding="gbk"

    Specify the play window's width:
        let g:xmms_window_width=30

    Specify the playlist format, default is "%artist - %title", %album
    is also avaiable.
        let g:xmms_playlist_format="%title"


Notes for MPD users
===================
    - There's only one playlist which MPD uses to play, users can only load
      other playlists' contents to that list. So the playlist name displayed
      in the status line is just the playlist's version number.
    - Currently, this plugin only support localhost mpd server.


Tips
====
    When adding music file or directory, you can use Ctrl-D to show all 
    candidates. Also, you can use arrow keys to navigate the history.