.TH CMUS 1 31/01/2010 cmus .nh .ad l .SH NAME cmus \- C* Music Player .SH SYNOPSIS cmus [\fBoptions\fR] .SH DESCRIPTION cmus is a small ncurses based music player. It supports various output methods by output\-plugins. cmus has completely configurable keybindings and can be controlled from the outside via \fBcmus\-remote\fR(1). .SH OPTIONS \-\-listen ADDR .RS Listen to ADDR (UNIX socket) instead of \fI$CMUS_SOCKET\fR or \fI$XDG_RUNTIME_DIR/cmus\-socket\fR. ADDR is either a UNIX socket or host[:port]. .RE .RS \fBWARNING\fR: Using host[:port] is insecure even with password! It might be useful though in LAN if you want multiple local users to able to control cmus. Never make cmus listen to the internet. .RE .RS NOTE: Don't use this option to run multiple instances as same user. That would corrupt the track metadata cache. .RE \-\-passwd PASSWD .RS Set the password for TCP/IP connections. Must be set if you are listening from host[:port]. Used in conjunction with \-\-listen. .RE \-\-plugins .RS List available plugins and exit. .RE \-\-show\-cursor .RS Keep cursor always visible. This is useful for screen readers. .RE \-\-help .RS Display usage information and exit. .RE \-\-version .RS Display version information and exit. .RE .SH VIEWS There are 7 views in cmus. Press keys 1\-7 to change active view. Library view (1) .RS Display all tracks in so\-called \fBlibrary\fR. Tracks are sorted artist/album tree. Artist sorting is done alphabetically. Albums are sorted by year. .RE Sorted library view (2) .RS Displays same content as view 1, but as a simple list which is automatically sorted by user criteria. .RE Playlist view (3) .RS Displays editable playlists with optional sorting. .RE Play Queue view (4) .RS Displays queue of tracks which are played next. These tracks are played before anything else (i.e. the playlist or library). .RE Browser (5) .RS Directory browser. In this view, music can be added to either the library, marked playlist or queue from the filesystem. .RE Filters view (6) .RS Lists user defined filters. .RE Settings view (7) .RS Lists keybindings, unbound commands and options. Remove bindings with \fBD\fR or \fBdel\fR, change bindings and variables with \fBenter\fR and toggle variables with \fBspace\fR. .RE .SH COMMAND LINE Everything in cmus is implemented as commands which can be typed at command line or bound to a key. To enter command mode type \fB:\fR. To execute a command press \fBENTER\fR or to cancel press \fBESC\fR or \fBCTRL\-C\fR. Use up/down arrows to browse command history. Use \fBTAB\fR to complete commands and parameters, you can tab complete almost anything. You don't need to type full command names if the command is unambiguous (no other commands starting with the same characters). Examples: .RS .nf # add files, short for ':add ~/music' :a ~/music # change output plugin :set output_plugin=oss # start playing # you could just press 'x' which is the default # binding for this command :player\-play # clear current view (library, playlist or play queue) :clear .fi .RE .SH SEARCHING Search mode works like the command mode, to enter search mode press \fB/\fR and then type the search words and press \fBENTER\fR. Press \fBn\fR to search next or \fBN\fR to search previous match using the same search words. Type \fB?\fR to search backwards. In views 1\-4 words are compared to artist, album and title tags. Type \fB//WORDS\fR or \fB??WORDS\fR to search only artists/albums in view 1 or titles in views 2\-4. If the file doesn't have tags words are compared to filename without path. Searching works in views 5\-7 too and its logic should be pretty obvious. .SH PLAYLIST EDITING .SS Selecting Tracks Editing commands affect the currently marked tracks or if there are no marked tracks the currently selected track (or selected artist/album in view 1). Mark selected track by pressing \fBSPACE\fR. Marked tracks appear with a gray background. You can only mark tracks in the list views (2\-4). .SS Copying Tracks Between Views You can copy marked or selected tracks from views 1\-5. .TP \fBa\fR copy tracks to the library (1\-2) .TP \fBy\fR copy tracks to the marked playlist (3) .TP \fBe\fR append tracks to the play queue (4) .TP \fBE\fR prepend tracks to the play queue (4) .SS Moving Tracks In views 2\-4 you can move tracks within the list. Note that moving is disabled if the view is auto\-sorted (see \fBlib_sort\fR and \fBpl_sort\fR options). Pressing \fBp\fR moves marked tracks to the position immediately after the selected track. \fBP\fR moves them to the position immediately before the selected track. If there are no marked tracks then the selected track is moved down (\fBp\fR) or up (\fBP\fR). NOTE: Changing active filters reloads view 2 so it isn't a good idea to manually order tracks in the view. .SS Removing Tracks Press \fBD\fR or \fBdelete\fR to remove marked or selected tracks in the current view (1\-4). The tracks will be removed immediately from the view without asking for confirmation. In the browser and filters views the same keys are used to remove a file or filter (will ask for confirmation). .SH STATUS LINE Right hand side of the status line (second row from the bottom, black text on a grey background) consists of the following fields: .nf aaa_mode & play_sorted & play_library | continue follow repeat shuffle .fi NOTE: \fBaaa_mode\fR and \fBplay_sorted\fR will be displayed only if \fBplay_library\fR is \fBtrue\fR because these are meaningless when playing the playlists (view 3). Pressing \fBm\fR, \fBo\fR, \fBM\fR, \fBC\fR, \fBr\fR and \fBs\fR keys should make it easier to understand what all those fields mean. See CONFIGURATION OPTIONS section for more information about these options. .SH KEYBINDINGS Here's list of default keybindings. See \fBunbind\fR and \fBbind\fR commands in the COMMANDS section. .SS Common Context .nf q quit \-i ^C echo Type :quit to exit cmus. I echo {} b player\-next c player\-pause x player\-play z player\-prev v player\-stop ^L refresh / search\-start ? search\-b\-start n search\-next N search\-prev \&. seek +1m l, right seek +5 , seek \-1m h, left seek \-5 m toggle aaa_mode C toggle continue M toggle play_library o toggle play_sorted r toggle repeat ^R toggle repeat_current t toggle show_remaining_time s toggle shuffle f toggle follow F push filter L push live\-filter u update\-cache 1 view tree 2 view sorted 3 view playlist 4 view queue 5 view browser 6 view filters 7 view settings ! push shell ] vol +0 +1 [ vol +1 +0 +, = vol +10% } vol \-0 \-1 { vol \-1 \-0 \- vol \-10% enter, mlb_click_selected win\-activate E win\-add\-Q a win\-add\-l y win\-add\-p e win\-add\-q G, end win\-bottom down, j, mouse_scroll_down win\-down p win\-mv\-after P win\-mv\-before tab win\-next ^F, page_down win\-page\-down ^B, page_up win\-page\-up ^E win\-scroll\-down ^Y win\-scroll\-up D, delete win\-remove i win\-sel\-cur space win\-toggle g, home win\-top k, up, mouse_scroll_up win\-up .fi .SS Browser Context .nf space win\-activate backspace browser\-up i toggle show_hidden u win\-update .fi .SH LIBRARY VIEW SORTING The library view (the tree\-like one; not the sorted library view, for which the sorting is controlled by the user by setting lib_sort \- see \fICONFIGURATION OPTIONS\fR), is sorted automatically by cmus using the information found in the tagging information provided by the audio files. Generally, in the library view cmus uses three levels of sorting: the first level would be the artist name, the second one the album and finally the actual track. At first, cmus checks if the "filename" looks like an URL, if it does, the item is given the special artist and album name \fB\fR. If it is a file, it is checked if the artist and album tags are set. If not, cmus assigns the special name \fB\fR for the unset tag. As the first level, cmus sorts alphanumerically by the value of the artist tag. ( and will be used as if they where normal names.) If a special sorting tag is available, it's value will be used instead. For album names, alphanumerical sorting is not the primary method, though. To decide, how the second level should be sorted, cmus looks at the date of the first track of each album. Sorting is done from young to old. Of course, if one artist happens to have more then one album from one year, alphanumerical sorting will be used after sorting by date. If the date header is not set, the album will be placed on top of the list (in fact, the internal integer value for unset album tags is \-1). The method for third sorting level (the track) is very similar to album sorting. First two numerical values are checked (discnumber and tracknumber). If sorting is still ambiguous, sorting will be done alphanumerically by the value of the track's \fIfilename\fR (not track name!). For simple albums, that is it. There is a special case, though. Albums, that feature various artists, also known as samplers or compilations. If a track belongs to a compilation is again decided by the existence and value of special tagging information. First, it is checked if cmus should use a special artist name (e.g.: \fI'Fatboy Slim'\fR for a DJ set). If so, that one will be used instead of the real artist name. If that special name tag is not set, cmus checks if another tag is set. If that is the case, the album will be given the special artist name \fB\fR. Albums filed under \fB\fR are sorted alphanumerically by album name instead of by date. That way, you do not end up with compilation tracks scattered around your library view. The problem with compilation tagging is, that there is no generic tag or method, that can be regarded as a standard across all different formats, supported by cmus. For mp3, the special\-name tag would be the id3v2 \fBTPE2\fR frame. The mark\-as\-compilation tag is the \fBTCMP\fR frame (which is a user defined id3v2.3 frame, used at least by amarok and apple's iTunes[tm]). For vorbis style tags (for example in ogg vorbis and flac files), the special\-name tag is \fBALBUMARTIST\fR and the mark\-as\-compilation tag is \fBCOMPILATION\fR. Vorbis tags names are case insensitive. .SH COMMANDS This section describes cmus' commands. You can bind a key to any of these commands, put these commands to configuration files and execute them in command mode. Also cmus\-remote uses these commands in its protocol. Optional parameters are in brackets, obligatory parameters in angle brackets and default key bindings in parenthesis. add [\-l] [\-p] [\-q] [\-Q] .RS Add file/dir/url/playlist to the specified view or the current view. .TP \-l add to library .TP \-p add to playlist .TP \-q add play queue .TP \-Q prepend to play queue .RE .RS URL is a Shoutcast stream (http://...) or a CDDA URL (cdda://...) (see \fBPLAYING AUDIO DISCS\fR). .RE .RS Supported playlist: plain, .m3u, .pls. .RE bind [\-f] .RS Add a key binding. .TP \-f overwrite existing binding .RE .RS Use tab to expand contexts, keys and commands. Command is any command listed in this section. .RE .RS Valid key contexts .RS common, library (1\-2), playlist (3), queue (4), browser (5), filters (6) .RE .RE .RS There's one context for each view. Common is a special context on which bound keys work in every view. .RE .RS You can override specific keys in common context for a view. For example \fBi\fR selects the current track in views 1\-3 but in browser it is overridden to toggle showing of hidden files. .RE browser\-up (\fBbackspace\fR) .RS Change to parent directory in browser view (5). This command only makes sense to be bound to the \fBbrowser\fR key context although it's possible to use this even if browser view is not active. .RE cd [directory] .RS Changes the current working directory. Changes the directory displayed in browser view too. .RE clear [\-l] [\-p] [\-q] .RS Remove all tracks from the specified view or the current view. .TP \-l clear library .TP \-p clear playlist .TP \-q clear play queue .RE colorscheme .RS Change color scheme. Color schemes are found in \fI/usr/share/cmus/\fR or \fI$XDG_CONFIG_HOME/cmus/\fR and have .theme filename extension. .RE echo ... .RS Display arguments on the command line. .RE .RS If the arguments contain \fB{}\fR it is replaced with file name of the first selected track. .RE .RS NOTE: unlike with \fBrun\fR the \fB{}\fR is replaced with only the first selected filename. .RE .RS Default bindings: .RE .RS .RS .nf common I echo {} common ^C echo Type :quit to exit cmus. .fi .RE .RE factivate ... .RS Select and activate the given user defined filters (displayed in the filters view). Filter names are separated by spaces. This command is mostly useful when bound to a key, to change active filters very quickly. If no arguments given then all filters are unactivated. .RE .RS If you prefix a filter name with "!" then the filter value is negated before activation. .RE filter .RS Use this command when you want to temporarily filter contents of the library views without having separately define (fset) and activate the filter. The filter is not saved. .RE fset = .RS Define (or replace existing) filter and add it to filters view (6). .RE invert .RS Invert the marking of tracks in playlist and queue views. See \fBmark\fR and \fBunmark\fR. .RE live\-filter .RS Use this command when you want to temporarily filter contents of the library views without having separately define (fset) and activate the filter. The filter is not saved. .RE load [\-l] [\-p] .RS Load a playlist to the specified view or to the current view. .TP \-l load to library views .TP \-p load to playlist view .RE lqueue [NUM] .RS Queue NUM (default 1) random albums from the library. See also \fBtqueue\fR. .RE mark .RS Mark tracks in playlist and queue view by using a filter expression. .RE pl\-create .RS Creates a new playlist. .RE pl\-export .RS Exports the currently selected playlist. .RE pl\-import [filename] .RS Imports a playlist into the playlist view. The argument can be omitted in the browser view. .RE pl\-rename .RS Renames the selected playlist. .RE player\-next (\fBb\fR) .RS Skip to the next track. .RE player\-pause (\fBc\fR) .RS Toggle pause. .RE player\-pause\-playback .RS Pause if currently playing. .RE player\-play [filename] (\fBx\fR) .RS Play the given track, or, if none is specified, [re]play the current track from the beginning. .RE player\-prev (\fBz\fR) .RS Skip to the previous track. .RE player\-stop (\fBv\fR) .RS Stop playback. .RE prev\-view .RS Go to previously used view. .RE left\-view .RS Go to view "to the left" of current one, e.g. view 4 \-> view 3. .RE right\-view .RS Go to view "to the right" of current one, e.g. view 3 \-> view 4. .RE push .RS Enter command mode with the command line pre\-set to text. Example: .RE .RS .RS bind common w push filter artist= .RE .RE .RS Text can contain spaces and even trailing spaces will be honored. This command can only be bound to a key but not used in the command line directly. .RE pwd .RS Prints the current working directory. .RE quit [\-i] (\fBq\fR, \fB:wq\fR) .RS Exit cmus. .TP \-i ask before exiting .RE raise\-vte .RS Raise the virtual terminal emulator window. Works only in X session. .RE rand .RS Randomizes (shuffles) the tracks in the library, playlist or queue view. .RE refresh (\fB^L\fR) .RS Redraw the terminal window. .RE run .RS Run command for the marked tracks OR the selected one if none marked. .RE .RS By default file names are appended to the command. If the command contains \fB{}\fR it is replaced with list of filenames. .RE .RS NOTE: In view 1 you can run a command for all files in the selected album or artist. .RE save [\-e] [\-l] [\-L] [\-p] [\-q] [file] (\fB:w\fR) .RS Save the specified view's or the current view's contents to a playlist file. In extended mode (\-e), also save metadata. .TP \-l save library views .TP \-L save filtered library views .TP \-p save playlist view .TP \-q save queue view .RE .RS If no filename given the old filename is used. "\-" outputs to stdout (works only remotely). .RE search\-next (\fBn\fR) .RS If a search pattern has been entered before, search forward for the next match in the current view. See \fBSEARCHING\fR above. .RE search\-prev (\fBN\fR) .RS If a search pattern has been entered before, search backwards for the previous match in the current view. See \fBSEARCHING\fR above. .RE seek [+\-]([mh] | [HH:]MM:SS) .RS Seek to absolute or relative position. Position can be given in seconds, minutes (m), hours (h) or HH:MM:SS format where HH: is optional. .RE .RS Seek 1 minute backward .RS :seek \-1m .RE .RE .RS Seek 5 seconds forward .RS :seek +5 .RE .RE .RS Seek to absolute position 1h .RS :seek 1h .RE .RE .RS Seek 90 seconds forward .RS :seek +1:30 .RE .RE .RS Default bindings: .RE .RS .RS .nf common , :seek \-1m common . :seek +1m common l :seek +5 common h :seek \-5 common right :seek +5 common left :seek \-5 .fi .RE .RE set