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".