help.txt

 Vimpc Help

 Vimpc is an mpd client based around the vi/vim text editors.
 It features normal and command (plus searching) modes of operation.
 Motion will be very familiar to vi users however playback might not.
 In addition different windows/tabs may behave differently to others, please
 see the specific section for each tab if unsure.

 To access this help again type :help

 NORMAL MODE:
 --------------------------------------------------
   Default key mappings for normal vimpc operation.
   Note: count is always an optional parameter.

 MOTION:
   [count] k, Up            | scroll up [count]
   [count] j, Down          | scroll down [count]
   [count] Pg Up, Ctrl+u    | scroll up by [count] half pages
   [count] Pg Dn, Ctrl+d    | scroll down by [count] half pages
   [count] Ctrl+f           | scroll down by [count] pages
   [count] Ctrl+b           | scroll up by [count] pages
   [count] Ctrl+y           | scroll down a line, maintain selection
   [count] Ctrl+e           | scroll up a line, maintain selection
           Home             | scroll to the top
           End              | scroll to the bottom
           %                | scroll to a random line
   [count] f                | scroll to the currently playing song + [count]
   [count] F                | scroll to the currently playing song - [count]
   [count] gg               | scroll to the top, or to the line [count]
   [count] G                | scroll to the bottom, or the line [count]
   [count] H                | select the top visible line + [count]
   [count] M                | select the middle visible line
   [count] L                | select the bottom visible line - [count]
   [count] z<Enter>         | selected line (or [count]) to display at the top
   [count] zt               | selected line (or [count]) to display at the top
   [count] z.               | selected line (or [count]) to display in centres
   [count] zz               | selected line (or [count]) to display in centres
   [count] z-               | selected line (or [count]) to display at the bottom
   [count] zb               | selected line (or [count]) to display at the bottom
   [count] .                | repeat the last normal mode action [count] times


 WINDOWS/TABS:
           W                | open a window selection window
           q                | closes the current window
   [count] gt               | next window/tab, or to window/tab number [count]
   [count] gT               | previous window/tab, or back [count] windows/tabs
           Alt+<number>     | change to the given window/tab number

           ZZ               | quit vimpc
           ZQ               | quit vimpc

 MARKS:
           m<Key>           | set a mark called <Key>
                            | this mark will hold the tab and line combination
           '<Key>           | jump to mark named <Key>
           `<Key>           | as above
           g'<Key>          | as above
           g`<Key>          | as above

   Default marks are created for a - z. These marks will allow you to
   instantly jump to the first entry in the current window that begins
   with the corresponding letter. ie. 'A will jump to the first entry
   starting with A. (browse, directory, library and list windows only)


 PLAYING (ALSO SEE PLAYLIST):
   [count] ^, I             | skip to the start of the currently playing song
   [count] <                | skip to the previous song
   [count] >                | skip to the next song
   [count] [                | skip to the previous artist
   [count] ]                | skip to the next artist
   [count] {                | skip to the previous album
   [count] }                | skip to the next album

   [count] +                | increase volume
   [count] -                | decrease volume

           space            | toggle pause on/off or start playing
           s, backspace     | stop playback

           C                | toggle consume
           T                | toggle crossfade
           R                | toggle random
           E                | toggle repeat
           S                | toggle single

 SEARCHING:
           /<exp>           | searches forward for <exp> (regular expression)
           ?<exp>           | searches backward for <exp> (regular expression)
   [count] n                | scroll to next result
   [count] N                | scroll to previous result

 SEARCH FLAGS:
           \c               | if in search expression, disables case sensitivity
           \C               | if in search expression, enables case sensitivity


 WINDOWS/TABS
 --------------------------------------------------

 ALL WINDOWS:

   Unless specified otherwise in the specific window sections,
   all windows will perform the following operations for the keys below.

           A                | add all songs in window to the playlist
           D                | delete all songs in window from the playlist
           X                | delete all songs from the selected line to the end
           v, V             | enter visual selection mode
           o                | go to the other end of the visual selection
           gv               | reselect the last visual selected songs
           gp               | scroll forward to a song that is in the playlist
           gP               | scroll backward to a song that is in the playlist

   In addition to these keys some windows have window specific bindings as below.

 PLAYLIST:
   Window showing the songs currently in the mpd playlist. Songs will
   be played in the order that they are listed on this window.

           A                | add all songs to the playlist
   [count] d, del           | delete songs
   [count] h, Left          | seek back [count] seconds
   [count] l, Right         | seek forward [count] seconds
           P                | paste songs that were deleted/cut
           e                | information about selected song
           y                | lyrics for selected song
   [count] Ctrl+a           | move song down [count]
   [count] Ctrl+x           | move song up [count]
   [count] gm               | move song to position [count]
           <Enter>          | play the selected song

 BROWSE:
   The browse window shows every single song in the mpd database. It is
   default sorted according to the songformat

   [count] a                | add songs to playlist
   [count] d, del           | delete songs
           e                | information about selected song
           y                | lyrics for selected song
           <Enter>          | append the song to the playlist and play it

 LISTS:
   Shows the playlists that have been saved into mpd's playlist directory.
   As well as playlists in the mpd music directory (based on "playlists"
   setting).

   [count] a                | add the list's contents to playlist
   [count] d, del           | delete the list's contents from playlist
           x                | delete the list itself
           e                | view the list's contents
           <Enter>          | play the currently selected list

 LIBRARY:
   The library window is a heirachy of artist/album/song form.

   By default only the artists are shown but these can be expanded
   or collapsed using the left and right keys.

   Any file which does not have an artist tag will show up under
   "Unknown Artist", likewise no album tag causes "Unknown Album".
   Albums with multiple artists will show up under "Various Artists"

   Note: if you want to show the album by default as well, then
         use the setting "expand-artists"

   [count] a                | add song, album or artist to playlist
   [count] d, del           | delete song, album, artist from playlist
           h, Left          | collapse selection
           l, Right         | expand selection
           zc               | collapse selection
           zo               | expand selection
           e                | view artist/album songs in a new window
           y                | lyrics for selected song
           <Enter>          | clear playlist, add song/album/artist and play it

 DIRECTORY:
   Filesystem navigation of music.

   [count] a                | add songs to playlist
   [count] d, del           | delete songs from the playlist
           h, Left          | go up one directory
           l, Right         | change into selected directory
           e                | information about selected song
           y                | lyrics for selected song
           <Enter>          | append the song to the playlist and play it
                            | or navigate into the selected directory

 OUTPUTS:
   Lists all the available mpd outputs.

           a                | enable the selected output
           A                | enable all outputs
           d                | disable the selected output
           D                | disable all outputs
           <Enter>          | toggle the selected output

 SONGINFO:
   More detailed information about a particular song,
   this window is opened by selecting a song and pressing 'e'.

           a                | add song to the playlist
           d                | delete song from playlist
           <Enter>          | append the song to the playlist and play it


 COMMAND/EX MODE
 --------------------------------------------------

   Similar to command/ex mode in vi/vim.
   Command mode is entered with the ':' key.

   Multiple commands can be specified if they are separated with ';'
    i.e :consume on; play 1

   NOTE: Any commands prefixed in this help with:
           '*' support tab completion
           '@' support a line number, range or both


   :<command>               | executes the command <command>
                            | the full command does not need to be given
                            | provided it is a unique match
                            | ie :con does not work
                            | as it could be :console or :connect
                            | but :conn will call the :connect command
   :<number>                | go to line number <number>


 RANGES:
   :<number><command>       | go to the line number <number> then execute command
   :<no1>,<no2><command>    | perform the command over range <no1> to <no2>


 EDITING:
   A number of keyboard shortcuts are available when typing in
   command mode.

   Ctrl+b, Home             | go to start of line
   Ctrl+e, End              | go to end of the line
   Ctrl+h, Backspace        | delete previous character
   Ctrl+u                   | clear from cursor position to start
   Ctrl+w                   | clear from cursor position to start of previous word
   Shift+Left               | move to previous word
   Shift+Right              | move to next word


 CONNECTING:
   connect [host] [port]    | connects to [host] [port] or to the default
   connect <path>           | connect to a socket at <path>
   disconnect               | disconnect from host
   password <password>      | authenticate to mpd using <password>
   reconnect                | reconnect to host last connected to

 DATABASE:
   update [path]            | perform a database update
   rescan [path]            | force an update including songs without changes

 PLAYBACK:
   pause                    | toggle between pause/play
 @ play <position>          | play the song at <position> in playlist
   stop                     | stop playback

   next [count]             | skip forward [count] songs
   previous [count]         | skip backward [count] songs

   volume [0-100]           | set the volume

   seek <time>              | seek to <time>, where <time> is of the form
                            |    <mm:ss>, <:ss>, or <ss>
   seek+ <time>             | seek forward <time>
   seek- <time>             | seek backward <time>

   consume [on/off]         | toggles consume, or sets on/off
   crossfade [0-10]         | toggles crossfade, or sets crossfade time
   random [on/off]          | toggles random, or sets on/off
   repeat [on/off]          | toggles repeat, or sets on/off
   single [on/off]          | toggles single, or sets on/off

 PLAYLIST:
 @ add                      | add the selected songs to the playlist
 * add <uri>                | add a song/directory/stream using the given <uri>
   addall                   | add all songs to the playlist
 @ delete [pos1] [pos2]     | delete selected songs, songs at [pos1], or [pos1] to [pos2]
   deleteall                | delete all songs in the playlist
   localadd <path>          | if connected via a filesystem socket, adds a song using <path>
   move <pos1> <pos2>       | move song from <pos1> to <pos2>
   shuffle                  | shuffle the playlist
   swap <pos1> <pos2>       | swap songs in <pos1> and <pos2>

 * edit <name>              | load the playlist <name>
 * load <name>              | load the playlist <name>
   save <name>              | save the current playlist <name>
   toplaylist <name>        | save contents of window/tab to playlist <name>
   write <name>             | save the current playlist <name>

 FIND:
   find[!] <search>         | search database and display results in new window
   findartist[!] <search>   | search database in artist tag only
   findalbum[!] <search>    | search database in album tag only
   findgenre[!] <search>    | search database in genre tag only
   findsong[!] <search>     | search database in title tag only

   Note: Appending a ! to any search term will automatically add the songs to
   the playlist rather than creating a new window.

 OUTPUTS:
 @ disable [id/name]        | enable selected output or id <id> or name <name>
 @ enable [id/name]         | disable selected output or id <id> or name <name>
 @ toggle [id/name]         | disable selected output or id <id> or name <name>

 TAG EDITTING:
 @ s/<match>/<re>/<opt>     | replace tags in the selected or range of songs
                            | if they match "<match>", if so <match>
                            | is replaced with <re>, the replace is only
                            | for the songs' tag based on option <opt>
                            | where <opt> =
                            |    a for artist tag
                            |    b for album tag
                            |    t for title tag
                            |    n for track tag
                            | Note: a blank <match> entry is treated the same
                            | as a <match> entry of of ".*"
                            |
                            | ie :1,6s//The Smiths/a
                            | will set the artist tag to "The Smiths" for the
                            | first 6 songs in the current window
                            |
 @ substitute               | same as above

 SEARCHING:
   nohlsearch               | temporarily turn off search highlights
                            | until the next search is performed

 WINDOWS/TABS:
   Note: Specifying a line number on the following commands will cause
         the window to open on that line number

 @ browse                   | open browse window
 @ console                  | open console window (see CONSOLE section)
 @ directory                | open directory window
 @ help                     | open help window (this one)
 @ library                  | open library window
 @ lists                    | open the lists window
 @ outputs                  | open outputs window
 @ playlist                 | open playlist window
 @ windowselect             | open window selection window

   tabfirst                 | navigate to the first window/tab
   tablast                  | navigate to the last window/tab
   tabnext                  | navigate to the next window/tab
   tabprevious              | navigate to the previous window/tab
   tabmove <location>       | move the current tab to <location> (first is 0)
   tabhide [tabname]        | hide the current tab (or [tabname]) from the tab bar
   tabrename <tabname>      | rename the current tab to <tabname>
   tabrename <n1> <n2>      | rename tab <n1> to <n2>

   quit[!]                  | if only one tab then quit, otherwise close the tab
   quitall[!]               | quit vimpc
                            | Note: if ! is appended to quit, playback is stopped
   redraw                   | redraws the window

 CONSOLE:
   !mpc <arguments>         | execute mpc with the given <arguments>
                            | the result is output in the console window
   clear                    | clears the console window
   echo <string>            | echos the given string to the console window

 CONFIGURATION:
   alias <name> <commands>  | create an alias <name> which executes the commands
                            | each command may be seperated by ;
                            | i.e :alias hello echo "hello"; echo "world";
   map                      | show the current mappings
   map <newkeys> <keys>     | create a mapping from <keys> to <otherkeys>
                            | see later section "MAPPING KEYS"
   unmap <keys>             | remove the mapping of <keys>

   tmap <tab> <keys> <keys> | create a mapping for the tab named <tab> only
   tunmap <tab> <keys>      | unmap keys for the tab named <tab>
   wmap <newkeys> <keys>    | create a mapping for the current window only
   wunmap <keys>            | unmap keys for the current window

   set                      | show the currently enabled settings and their values
 * set <setting>            | sets a configurable setting, see SETTINGS section

 HIGHLIGHTING:
   hi <prop> <bg> <fg>      | highlight a property with colors
                            | standard 16 term colors are available
                            | and specified as default, red, green, etc.
                            | for bold colors use the prefix bold_
                            | Ex: hi status default bold_white

   Properties:
   --------------------------
   song     - Songs
   id       - Song IDs
   dir      - The directory string in :directory mode
   current  - The current song
   tab      - Tabs
   progress - Progress bar window
   match    - Songs matched by a search string
   partial  - Artists/albums that are partially in the playlist
   full     - Artists/albums that are fully in the playlist
   pager    - The color of the text in the settings pager window
   status   - The statusline
   error    - Errors

 MISCELLANEOUS:
   normal <input>           | execute <input> as if it were entered in normal mode
   sleep <seconds>          | do nothing for <seconds> seconds


 MAPPING KEYS
 --------------------------------------------------

 Any key combination can be mapped to any other key combination
 including to ex mode commands.

 To create a map, the command :map is used which will map the
 first key combination provided to the second one.

 i.e. :map FF :browse<C-M>gg/
      :map @ :set add next<C-M>a:set add end<C-M>

 This will make the input "FF" change to the browse tab, go to the
 first line and then enter search mode. And the input "@" will set the
 add position to "next" then add the selected song then set the
 add position to "end".

 All ex mode or search commands you want to execute must be
 terminated with <C-M>, <Return> or <Enter> otherwise
 you will stay in that mode, instead.

 If you want to make a key do nothing map it to <Nop>

 i.e :map <Down> <Nop>

 Mappable Keys:
 ----------------------------

 As well as regular ascii keys other keyboard keys and
 the mouse can be mapped and are described below.

    <Down>, <Left>          | Directional keys
    <Right>, <Up>           | Directional keys
    <Space>                 | Spacebar
    <PageUp>, <PageDown>    | Page up and down
    <Home>, <End>           | Home and End
    <C-x>                   | Ctrl+x
    <A-x>                   | Alt+x
    <Enter>                 | Enter key
    <Return>                | Return key
    <BS>                    | Backspace key
    <Tab>                   | Tab key
    <Del>                   | Delete key
    <lt>                    | Less than symbol '<'
    <sc>                    | Semicolon symbol ';'
    <F1>, <F2>, etc         | Function keys
    <ScrollWheelUp>         | Scroll Wheel up
    <ScrollWheelDown>       | Scroll Wheel down
    <LeftMouse>             | Since left mouse click
    <2-LeftMouse>           | Double left mouse click
    <RightMouse>            | Single right mouse click
    <2-RightMouse>          | Double right mouse click


 PRINT FORMATS
 -------------------------------------------------

 The song and library formats used to print the songs can be set using
 the settings songformat and libraryformat respectively. The formatting
 of these strings is based upon those of ncmpcpp.

    %a    - Artist or AlbumArtist (based on albumartist setting)
    %A    - Artist or AlbumArtist, but swap "The Band" to "Band, The"
    %r    - Artist
    %R    - Artist, but swap "The Band" to "Band, The"
    %m    - AlbumArtist
    %M    - AlbumArtist, but swap "The Band" to "Band, The"
    %b    - Album
    %B    - Album, but swap "The Album" to "Album, The"
    %t    - Song title
    %d    - Date
    %y    - Year
    %n    - Track number
    %N    - Track number zero padded to two digits
    %c    - Disc number
    %l    - Duration
    %f    - Filename/URI

    $Axx  - Align following parts at xx% from the left of the screen
    $R    - Begin right alignment
    $E    - Add ellipsis for trimmed text (must be before right align)
    $H    - Toggle highlight color off/on
    {,}   - Will only display contents between { and } if not empty
    \|     - Alternative to use if prior entry is blank

The setting songfillchar is used to fill up space due to alignment when
rendering a song. The default setting is ' '.

 Examples:
    The default song format is: "{%a - %t}\|{%f}$E$R $H[$H%l$H]$H"
    This displays artist - title if they both exist otherwise
    displays the filename and displays the duration aligned
    to the right. The $H ensures that [ and ] will not change
    color when that song is highlighted.

    The default library format is: "$H[$H%l$H]$H {%t}\|{%f}$E$R "
    This displays the duration, again not highlighting [ and ]
    followed by a space, then either the song title or if that
    is empty the filename.


 MOUSE SUPPORT
 --------------------------------------------------

 Mouse support can be enabled using :set mouse

 The mouse can be used to change between tabs by clicking on
 on the name of the tab. Or to select an item within a window
 by clicking on it. Double clicking an item will generally
 do whatever <Enter> would do by default on that item.
 Double clicking on a blank part of the tab bar will
 open the window selection window.

 The behaviour of the mouse can also be modified using
 the :map command. See section (MAPPING KEYS).

 SETTINGS
 --------------------------------------------------

 To print all settings values you can specify :set with no arguments.
 Or to print a particular setting you can use :set <setting>?

 i.e. :set
         shows a window displaying all settings
      :set colour?
         will print either "colour" or "nocolour" to the screen

 All on/off settings can be prefixed with "no", to disable the setting,
 or postfixed with "!" which will toggle the setting.

 i.e. :set nocolour
         turns colour support off
      :set progressbar!
         will toggle the progressbar on or off

 Value settings are not toggled on and off but hold an actual
 string/number value.

 All settings support tab completion.

   On/Off Settings:
   -----------------------
   albumartist          | use the albumartist in preference to artist
   autolyrics           | automatically fetch lyrics as the songs change
   autoscroll           | automatically scroll playlist when songs change
   autoscrolllyrics     | estimate to scroll lyrics as percents of song complete
   autoupdate           | automatically update mpd after tag changes
   browsenumbers        | display id numbers next to songs in the browse window
   colour               | enable or disable colours
   expand-artists       | when enabled, expand to artist by default in library
   groupignorethe       | group artists like "xyz" and "the xyz" in the library
   hlsearch             | highlight search results
   ignorecase           | case insensitive searching
   incsearch            | search for results as you are typing
   listallmeta          | download all meta information to construct the library
   local-music-dir      | location on the client computer of music files
   lyricstrip           | regular expression to strip from title for lyric search
   mouse                | turn mouse support on
   polling              | poll mpd for status updates rather than using idle mode
   playlistnumbers      | display id numbers next to songs in the playlist
   playonadd            | if mpd is stopped start playing when a song is added
   progressbar          | whether or not to show the progress bar
   reconnect            | automatically reconnect if the connection drops
   scrollonadd          | scroll down one line after adding a song
   scrollondelete       | scroll down one line after deleting a song
   scrollstatus         | scroll song titles in the status line
   seekbar              | mouse click on progress bar causes a seek
   searchwrap           | wrap search results when using n/N
   showlists            | include playlists in the directory window
   showpath             | show the current path in the directory window
   showpercent          | show the current percentage in the progress bar
   singlequit           | :q and :quit will quit vimpc, not close active tab
   smartcase            | if capital in search pattern, enable case sensitivity
   songnumbers          | display id numbers next to songs in other windows
   sortignorecase       | ignore case when sorting
   sortignorethe        | ignore the prefix 'the' when sorting
   sortalbumdate        | sort albums in the library by date
   stoponquit           | automatically stop playback when vimpc is quit
   tabbar               | whether or not to show the tab bar
   timeremaining        | display the time remaining rather than elapsed
   windownumbers        | display the number next to the window in the tab bar

   Value Settings:
   ----------------------
   add <where>          | set where to add songs to the playlist
                        | either "end" or "next" (defaults to end)
   libraryformat <fmt>  | set the format to print songs in the library
                        | set PRINT FORMATS section
   albumformat <fmt>    | set the format to print albums in the library
                        | set PRINT FORMATS section
   playlists <option>   | set which playlists to include in the lists window
                        | "mpd", "files" or "all" (defaults to mpd)
   songformat <fmt>     | set the format to print songs
                        | set PRINT FORMATS section
   sort <option>        | sort the browse window based on the songformat or
                        | the order of the library, options are either
                        | "format" or "library" (defaults to format)
   timeout <seconds>    | sets the timeout in seconds when connecting
                        | to use the default MPD_TIMEOUT environment
                        | variable, set this to 0 (defaults to 15)
   window <window>      | sets the window that will start with focus
   windows <windows>    | comma seperated list of windows to be shown at startup


 CONFIGURATION FILE
 --------------------------------------------------

 The config file $XDG_CONIFG_HOME/vimpc/vimpcrc is a file containing vimpc commands
 (without the preceeding : ). These commands can change mpd settings
 such as "consume on" as well as vimpc specific settings
 like "set nocolour".