Doc/cmus.txt

   1 @title CMUS 1 05/11/2006 cmus
   2
   3 @h1 NAME
   4
   5 cmus - C\* Music Player
   6
   7
   8 @h1 SYNOPSIS
   9
  10 cmus [*options*]
  11
  12
  13 @h1 DESCRIPTION
  14
  15 cmus is a small ncurses based music player.  It supports various output
  16 methods by output-plugins. It has got completely configurable keybindings and
  17 it can be controlled from the outside via *cmus-remote*(1).
  18
  19 @h1 OPTIONS
  20
  21 --listen ADDR
  22         Listen to ADDR (UNIX socket) instead of `/tmp/cmus-$USER`.
  23         ADDR is either a UNIX socket or host[:port].
  24
  25         *WARNING*: Using host[:port] is insecure even with password!
  26         It might be useful though in LAN if you want multiple local users to
  27         able to control cmus.  Never make cmus listen to the internet.
  28
  29         NOTE: Don't use this option to run multiple instances as same user.
  30         That would corrupt the track metadata cache.
  31
  32 --plugins
  33         List available plugins and exit.
  34
  35 --show-cursor
  36         Keep cursor always visible.  This is useful for screen readers.
  37
  38 --help
  39         Display usage information and exit.
  40
  41 --version
  42         Display version information and exit.
  43
  44
  45 @h1 VIEWS
  46
  47 There are 7 views in cmus.  Press keys 1-7 to change active view.
  48
  49 Library view (1)
  50         Display all tracks in so-called *library*. Tracks are sorted
  51         artist/album tree.  Artist sorting is done alphabetically. Albums are
  52         sorted by year.
  53
  54 Sorted library view (2)
  55         Displays same content as view 1, but as a simple list which is
  56         automatically sorted by user criteria.
  57
  58 Playlist view (3)
  59         Displays editable playlist with optional sorting.
  60
  61 Play Queue view (4)
  62         Displays queue of tracks which are played next. These tracks are
  63         played before anything else (i.e. the playlist or library).
  64
  65 Browser (5)
  66         Directory browser.  In this view, music can be added to either the
  67         library, playlist or queue from the filesystem.
  68
  69 Filters view (6)
  70         Lists user defined filters.
  71
  72 Settings view (7)
  73         Lists keybindings, unbound commands and options.  Remove bindings with
  74         *D* or *del*, change bindings and variables with *enter* and toggle
  75         variables with *space*.
  76
  77 @h1 COMMAND LINE
  78
  79 Everything in cmus is implemented as commands which can be typed at command
  80 line or bound to a key.  To enter command mode type *:*.  To execute a command
  81 press *ENTER* or to cancel press *ESC*.  Use up/down arrows to browse command
  82 history.  Use *TAB* to complete commands and parameters, you can tab complete
  83 almost anything.  You don't need to type full command names if the command is
  84 unambiguous (no other commands starting with the same characters).
  85
  86 Examples:
  87
  88         @pre
  89         # add files, short for ':add ~/music'
  90         :a ~/music
  91
  92         # change output plugin
  93         :set output_plugin=oss
  94
  95         # start playing
  96         # you could just press 'x' which is the default
  97         # binding for this command
  98         :player-play
  99
 100         # clear current view (library, playlist or play queue)
 101         :clear
 102         @endpre
 103
 104
 105 @h1 SEARCHING
 106
 107 Search mode works like the command mode, to enter search mode press */* and
 108 then type the search words and press *ENTER*.  Press *n* to search next or *N*
 109 to search previous match using the same search words.  Type *?* to search
 110 backwards.
 111
 112 In views 1-4 words are compared to artist, album and title tags. Type
 113 *//WORDS* or *??WORDS* to search only artists/albums in view 1 or titles in
 114 views 2-4. If the file doesn't have tags words are compared to filename
 115 without path.
 116
 117 Searching works in views 5-7 too and its logic should be pretty obvious.
 118
 119 @h1 LIBRARY VIEW SORTING
 120
 121 The library view (the tree-like one; not the sorted library view, for which
 122 the sorting is controlled by the user by setting lib_sort - see `CONFIGURATION
 123 OPTIONS`), is sorted automatically by cmus using the information found in the
 124 tagging information provided by the audio files.
 125
 126 Generally, in the library view cmus uses three levels of sorting: the first
 127 level would be the artist name, the second one the album and finally the
 128 actual track.
 129
 130 At first, cmus checks if the "filename" looks like an URL, if it does, the
 131 item is given the special artist and album name *<Stream>*.
 132
 133 If it is a file, it is checked if the artist and album tags are set. If not,
 134 cmus assigns the special name *<No Name>* for the unset tag.
 135
 136 As the first level, cmus sorts alphanumerically by the value of the artist
 137 tag. (<Stream> and <No Name> will be used as if they where normal names.)
 138
 139 For album names, alphanumerical sorting is not the primary method, though.
 140 To decide, how the second level should be sorted, cmus looks at the date of
 141 the first track of each album. Sorting is done from young to old. Of course,
 142 if one artist happens to have more then one album from one year,
 143 alphanumerical sorting will be used after sorting by date.
 144
 145 If the date header is not set, the album will be placed on top of the list (in
 146 fact, the internal integer value for unset album tags is -1).
 147
 148 The method for third sorting level (the track) is very similar to album
 149 sorting. First two numerical values are checked (discnumber and tracknumber).
 150 If sorting is still ambiguous, sorting will be done alphanumerically by the
 151 value of the track's `filename` (not track name!).
 152
 153 For simple albums, that is it. There is a special case, though. Albums, that
 154 feature various artists, also known as samplers or compilations.
 155
 156 If a track belongs to a compilation is again decided by the existence and
 157 value of special tagging information. First, it is checked if cmus should use
 158 a special artist name (e.g.: `'Various Artists'`). If so, that one will be used
 159 instead of the real artist name.
 160
 161 If that special name tag is not set, cmus checks if another tag is set.
 162 If that is the case, the album will be given the special artist name
 163 *<Compilations>*.
 164
 165 That way, you do not end up with compilation tracks scattered around your
 166 library view.
 167
 168 The problem with compilation tagging is, that there is no generic tag or
 169 method, that can be regarded as a standard across all different formats,
 170 supported by cmus.
 171
 172 For mp3, the special-name tag would be the id3v2 *TPE2* frame. The
 173 mark-as-compilation tag is the *TCMP* frame (which is a user defined id3v2.3
 174 frame, used at least by amarok and apple's iTunes[tm]).
 175
 176 For vorbis style tags (for example in ogg vorbis and flac files), the
 177 special-name tag is *ALBUMARTIST* and the mark-as-compilation tag is
 178 *COMPILATION*. Vorbis tags names are case insensitive.
 179
 180 @h1 PLAYLIST EDITING
 181
 182 @h2 Selecting Tracks
 183
 184 Editing commands affect the currently marked tracks or if there are no marked
 185 tracks the currently selected track (or selected artist/album in view 1).
 186
 187 Mark selected track by pressing *SPACE*.  Marked tracks appear with a gray
 188 background.  You can only mark tracks in the list views (2-4).
 189
 190 @h2 Copying Tracks Between Views
 191
 192 You can copy marked or selected tracks from views 1-5.
 193
 194 @li *a*
 195 copy tracks to the library (1-2)
 196
 197 @li *y*
 198 copy tracks to the playlist (3)
 199
 200 @li *e*
 201 append tracks to the play queue (4)
 202
 203 @li *E*
 204 prepend tracks to the play queue (4)
 205
 206 @h2 Moving Tracks
 207
 208 In views 2-4 you can move tracks withing the list. Note that moving is
 209 disabled if the view is auto-sorted (see *lib_sort* and *pl_sort* options).
 210
 211 Pressing *p* moves marked tracks to the position immediately after the
 212 selected track.  *P* moves them to the position immediately before the
 213 selected track.  If there are no marked tracks then the selected track is
 214 moved down (*p*) or up (*P*).
 215
 216 NOTE: Changing active filters reloads view 2 so it isn't a good idea to
 217 manually order tracks in the view.
 218
 219 @h2 Removing Tracks
 220
 221 Press *D* or *delete* to remove marked or selected tracks in the current view
 222 (1-4).  The tracks will be removed immediately from the view without asking
 223 for confirmation.  In the browser and filters views the same keys are used to
 224 remove a file or filter (will ask for confirmation).
 225
 226
 227 @h1 STATUS LINE
 228
 229 Right hand side of the status line (second row from the bottom, black text on
 230 a grey background) consists of the following fields:
 231
 232 @pre
 233 aaa_mode & play_sorted & play_library | continue repeat shuffle
 234 @endpre
 235
 236 NOTE: *aaa_mode* and *play_sorted* will be displayed only if *play_library* is
 237 *true* because these are meaningless when playing the playlist (view 3).
 238
 239 Pressing *m*, *o*, *M*, *C*, *r* and *s* keys should make it easier to
 240 understand what all those fields mean.
 241
 242 See CONFIGURATION OPTIONS section for more information about these options.
 243
 244
 245 @h1 KEYBINDINGS
 246
 247 Here's list of default keybindings.  See *unbind* and *bind* commands in the
 248 COMMANDS section.
 249
 250
 251 @h2 Common Context
 252 @pre
 253 ^C             echo Type :quit<enter> to exit cmus.
 254 I              echo {}
 255 b              player-next
 256 c              player-pause
 257 x              player-play
 258 z              player-prev
 259 v              player-stop
 260 ^L             refresh
 261 n              search-next
 262 N              search-prev
 263 .              seek +1m
 264 l, right       seek +5
 265 ,              seek -1m
 266 h, left        seek -5
 267 m              toggle aaa_mode
 268 C              toggle continue
 269 M              toggle play_library
 270 o              toggle play_sorted
 271 r              toggle repeat
 272 ^R             toggle repeat_current
 273 t              toggle show_remaining_time
 274 s              toggle shuffle
 275 u              update-cache
 276 1              view tree
 277 2              view sorted
 278 3              view playlist
 279 4              view queue
 280 5              view browser
 281 6              view filters
 282 7              view settings
 283 ]              vol +0 +1
 284 [              vol +1 +0
 285 +, =           vol +10%
 286 }              vol -0 -1
 287 {              vol -1 -0
 288 -              vol -10%
 289 enter          win-activate
 290 E              win-add-Q
 291 a              win-add-l
 292 y              win-add-p
 293 e              win-add-q
 294 G, end         win-bottom
 295 down, j        win-down
 296 p              win-mv-after
 297 P              win-mv-before
 298 tab            win-next
 299 ^F, page_down  win-page-down
 300 ^B, page_up    win-page-up
 301 D, delete      win-remove
 302 i              win-sel-cur
 303 space          win-toggle
 304 g, home        win-top
 305 k, up          win-up
 306 @endpre
 307
 308 @h2 Browser Context
 309 @pre
 310 backspace      browser-up
 311 i              toggle show_hidden
 312 u              win-update
 313 @endpre
 314
 315 @h1 COMMANDS
 316
 317 This section describes cmus' commands.  You can bind a key to any of these
 318 commands, put these commands to configuration files and execute them in
 319 command mode.  Also cmus-remote uses these commands in its protocol.
 320
 321 Optional parameters are in brackets, obligatory parameters in angle brackets
 322 and default key bindings in parenthesis.
 323
 324 add [-l] [-p] [-q] [-Q] <file|dir|url|playlist>
 325         Add file/dir/url/playlist to the specified view or the current view.
 326
 327         @li -l
 328         add to library
 329
 330         @li -p
 331         add to playlist
 332
 333         @li -q
 334         add play queue
 335
 336         @li -Q
 337         prepend to play queue
 338
 339         URL is a Shoutcast stream (http://...).
 340
 341         Supported playlist: plain, .m3u, .pls.
 342
 343 bind [-f] <context> <key> <command>
 344         Add a key binding.
 345
 346         @li -f
 347         overwrite existing binding
 348
 349         Use tab to expand contexts, keys and commands.  Command is any command
 350         listed in this section.
 351
 352         Valid key contexts
 353                 common, library (1-2), playlist (3), queue (4), browser (5),
 354                 filters (6)
 355
 356         There's one context for each view.  Common is a special context on
 357         which bound keys work in every view.
 358
 359         You can override specific keys in common context for a view.  For
 360         example *i* selects the current track in views 1-3 but in browser it
 361         is overridden to toggle showing of hidden files.
 362
 363 browser-up (*backspace*)
 364         Change to parent directory in browser view (5). This command only
 365         makes sense to be bound to the *browser* key context although it's
 366         possible to use this even if browser view is not active.
 367
 368 cd [directory]
 369         Changes the current working directory.  Changes the directory
 370         displayed in browser view too.
 371
 372 clear [-l] [-p] [-q]
 373         Remove all tracks from the specified view or the current view.
 374
 375         @li -l
 376         clear library
 377
 378         @li -p
 379         clear playlist
 380
 381         @li -q
 382         clear play queue
 383
 384 colorscheme <name>
 385         Change color scheme.  Color schemes are found in `/usr/share/cmus/` or
 386         `~/.cmus/` and have .theme filename extension.
 387
 388 echo <arg>...
 389         Display arguments on the command line.
 390
 391         If the arguments contain *{}* it is replaced with file name of the
 392         first selected track.
 393
 394         NOTE: unlike with *run* the *{}* is replaced with only the first
 395         selected filename.
 396
 397         Default bindings:
 398
 399                 @pre
 400                 common  I   echo {}
 401                 common  ^C  echo Type :quit<enter> to exit cmus.
 402                 @endpre
 403
 404 factivate <user-defined-filter>...
 405         Select and activate the given user defined filters (displayed in the
 406         filters view).  Filter names are separated by spaces.  This command is
 407         mostly useful when bound to a key, to change active filters very
 408         quickly.  If no arguments given then all filters are unactivated.
 409
 410         If you prefix a filter name with "!" then the filter value is negated
 411         before activation.
 412
 413 filter <filter-expression>
 414         Use this command when you want to temporarily filter contents of the
 415         library views without having separately define (fset) and activate the
 416         filter.  The filter is not saved.
 417
 418 fset <name>=<filter-expression>
 419         Define (or replace existing) filter and add it to filters view (6).
 420
 421 invert
 422         Invert the marking of tracks in playlist and queue views. See *mark*
 423         and *unmark*.
 424
 425 load [-l] [-p] <playlist>
 426         Load a playlist to the specified view or to the current view.
 427
 428         @li -l
 429         load to library views
 430
 431         @li -p
 432         load to playlist view
 433
 434 lqueue [NUM]
 435         Queue NUM (default 1) random albums from the library. See also
 436         *tqueue*.
 437
 438 mark <filter-expression>
 439         Mark tracks in playlist and queue view by using a filter expression.
 440
 441 player-next (*b*)
 442         Skip to the next track.
 443
 444 player-pause (*c*)
 445         Toggle pause.
 446
 447 player-play (*x*)
 448         If stopped, start playing the current song; if already playing seek to
 449         beginning of the current song.
 450
 451 player-prev (*z*)
 452         Skip to the previous track.
 453
 454 player-stop (*v*)
 455         Stop playback.
 456
 457 prev-view
 458         Go to previously used view.
 459
 460 quit
 461         Exit cmus.
 462
 463 refresh (*^L*)
 464         Redraw the terminal window.
 465
 466 run <command>
 467         Run command for the marked tracks OR the selected one if none marked.
 468
 469         By default file names are appended to the command.  If the command
 470         contains *{}* it is replaced with list of filenames.
 471
 472         NOTE: In view 1 you can run a command for all files in the selected
 473         album or artist.
 474
 475 save [-l] [-p] [file]
 476         Save the specified view's or the current view's contents to a playlist
 477         file.
 478
 479         @li -l
 480         save library views
 481
 482         @li -p
 483         save playlist view
 484
 485         If no filename given the old filename is used.
 486
 487 search-next (*n*)
 488         If a search pattern has been entered before, search forward for the
 489         next match in the current view.  See *SEARCHING* above.
 490
 491 search-prev (*N*)
 492         If a search pattern has been entered before, search backwards for the
 493         previous match in the current view.  See *SEARCHING* above.
 494
 495 seek [+-](<num>[mh] | [HH:]MM:SS)
 496         Seek to absolute or relative position.  Position can be given in
 497         seconds, minutes (m), hours (h) or HH:MM:SS format where HH: is
 498         optional.
 499
 500         Seek 1 minute backward
 501                 :seek -1m
 502
 503         Seek 5 seconds forward
 504                 :seek +5
 505
 506         Seek to absolute position 1h
 507                 :seek 1h
 508
 509         Seek 90 seconds forward
 510                 :seek +1:30
 511
 512         Default bindings:
 513
 514                 @pre
 515                 common  ,      :seek -1m
 516                 common  .      :seek +1m
 517                 common  l      :seek +5
 518                 common  h      :seek -5
 519                 common  right  :seek +5
 520                 common  left   :seek -5
 521                 @endpre
 522
 523 set <option>=<value>
 524         Set value of an option. See *OPTIONS*.
 525
 526 set <option>
 527         Display option value.  Vim compatible *set <option>?* is also
 528         supported.
 529
 530 showbind <context> <key>
 531         Show key binding.
 532
 533 shuffle
 534         Reshuffle the shuffle lists for both library and playlist views.
 535
 536 source <filename>
 537         Read and execute commands from <filename>.
 538
 539 toggle <option>
 540         Toggle value of a toggle-able option (all booleans and tristate
 541         *aaa_mode*).
 542
 543 tqueue [NUM]
 544         Queue NUM (default 1) random tracks from the library. See also
 545         *lqueue*.
 546
 547 unbind [-f] <context> <key>
 548         Remove a key binding. Use tab to cycle through bound keys.
 549
 550         -f
 551                 Don't throw an error if the binding is not known
 552
 553 unmark
 554         Unmark all tracks (see *mark*).
 555
 556 update-cache
 557         Update track metadata cache (~/.cmus/cache).
 558
 559 view <name or 1-7>
 560         Switches active view.
 561
 562 vol [+-]NUM[%] [[+-]NUM[%]]
 563         Set, increase or decrease volume.
 564
 565         If you give *vol* just one argument it changes both channels.  Two
 566         values make it possible to change the left and right channel
 567         independently.
 568
 569         To increase or decrease volume prefix the value with *-* or *+*,
 570         otherwise value is treated as absolute volume.
 571
 572         Both absolute and relative values can be given as percentage units
 573         (suffixed with *%*) or as internal values (hardware may have volume in
 574         range 0-31 for example).
 575
 576         Default bindings:
 577
 578                 @pre
 579                 common  =  :vol +10%
 580                 common  +  :vol +10%
 581                 common  -  :vol -10%
 582                 common  [  :vol +1 +0
 583                 common  ]  :vol +0 +1
 584                 common  {  :vol -1 -0
 585                 common  }  :vol -0 -1
 586                 @endpre
 587
 588 win-activate (*enter*)
 589         In views 1-3 start playing the selected track.  In view 5 start
 590         playing the selected track or change to the selected directory.  In
 591         view 6 activate the selected filters.  In settings view (7) change
 592         binding or variable.
 593
 594 win-add-l (*a*)
 595         Add the currently marked or selected track(s) (views 3-4), or the
 596         currently selected file or directory (view 5) to the library.
 597
 598         Analogous to *:add -l*
 599
 600 win-add-p (*y*)
 601         Add the currently marked or selected track(s) (views 1-2, 4), or the
 602         currently selected file or directory (view 5) to the playlist.
 603
 604         Analogous to *:add -p*
 605
 606 win-add-Q (*E*)
 607         Prepend the currently marked or selected track(s) (views 1-3), or the
 608         currently selected file or directory (view 5) to the play queue.
 609
 610         Analogous to *:add -Q*
 611
 612 win-add-q (*e*)
 613         Add the currently marked or selected track(s) (views 1-3), or the
 614         currently selected file or directory (view 5) to the play queue.
 615
 616         Analogous to *:add -q*
 617
 618 win-bottom (*G*, *end*)
 619         Goto bottom of the current window.
 620
 621 win-down (*j*, *down*)
 622         Goto down one row in the current window.
 623
 624 win-mv-after (*p*)
 625         If no tracks are marked, move the selected track down one row. If any
 626         tracks are marked, move the marked tracks after the currently selected
 627         track.  This command works in unsorted playlist and play queue view.
 628
 629 win-mv-before (*P*)
 630         If no tracks are marked, move the selected track up one row. If any
 631         tracks are marked, move the marked tracks before the currently
 632         selected track.  This command works in unsorted playlist and play
 633         queue view.
 634
 635 win-next (*tab*)
 636         Activate next window.  Only relevant in view 1.
 637
 638 win-page-down (*^F*, *page_down*)
 639         Goto down one page in the current window.
 640
 641 win-page-up (*^B*, *page_up*)
 642         Goto up one page in the current window.
 643
 644 win-remove (*D*, *delete*)
 645         Remove the selected entry.  For tracks no confirmations are made.  For
 646         files (view 5), filters (view 6) and bindings (view 7) user has to
 647         confirm the action.
 648
 649 win-sel-cur (*i*)
 650         Select the current track (position in library or playlist, not
 651         necessarily same as the currently playing track).  Works only in views
 652         1-3, does nothing in other views.
 653
 654 win-toggle (*space*)
 655         Expand albums in library view (1), mark tracks in views 2-4, toggle
 656         selection of a filter in view 6, toggle variable value in view 7.
 657
 658 win-top (*g*, *home*)
 659         Goto top of the current window.
 660
 661 win-up (*k*, *up*)
 662         Goto up one row in the current window.
 663
 664 win-update (*u*)
 665         Checks the modification time of the files in the library, and updates
 666         metadata for changed files.  Removes non-existent files from the
 667         library.
 668
 669         Reloads contents of directory in the browser view.
 670
 671         Only works in views 1-2 and 5, does nothing in other views.
 672
 673
 674 @h1 CONFIGURATION OPTIONS
 675
 676 This section describes cmus' options that can be altered with the *set* and
 677 *toggle* commands. Default values are in parenthesis, possible values in
 678 brackets.
 679
 680 auto_reshuffle (false)
 681         Reshuffle playlist when end of shuffle list is reached.
 682
 683 aaa_mode (all) [all, artist, album]
 684         Defines what tracks should be played in the library view.  Not used in
 685         the other views. For example if set to *artist* the player behaves
 686         like there were only the files of the currently playing artist in the
 687         library.
 688
 689 altformat_current [`Format String`]
 690         Alternative format string for the line displaying currently playing
 691         track.
 692
 693 altformat_playlist [`Format String`]
 694         Alternative format string for the list views (2-4).
 695
 696 altformat_title [`Format String`]
 697         Alternative format string for terminal title.  NOTE: not all
 698         terminals support changing window title.
 699
 700 altformat_trackwin [`Format String`]
 701         Alternative format string for the tree view's (1) track window.
 702
 703 buffer_seconds (10) [1-20]
 704         Size of player buffer in seconds.
 705
 706 color_cmdline_bg (default) [`Color`]
 707         Command line background color.
 708
 709 color_cmdline_fg (default) [`Color`]
 710         Command line foreground color.
 711
 712 color_error (lightred) [`Color`]
 713         Color of error messages displayed on the command line.
 714
 715 color_info (lightyellow) [`Color`]
 716         Color of informational messages displayed on the command line.
 717
 718 color_separator (blue) [`Color`]
 719         Color of the separator line between windows in view (1).
 720
 721 color_statusline_bg (gray) [`Color`]
 722         Status line background color.
 723
 724 color_statusline_fg (black) [`Color`]
 725         Status line foreground color.
 726
 727 color_titleline_bg (blue) [`Color`]
 728         Background color of the line displaying currently playing track.
 729
 730 color_titleline_fg (white) [`Color`]
 731         Foreground color of the line displaying currently playing track.
 732
 733 color_win_bg (default) [`Color`]
 734         Window background color.
 735
 736 color_win_cur (lightyellow) [`Color`]
 737         Color of currently playing track.
 738
 739 color_win_cur_sel_bg (blue) [`Color`]
 740         Background color of the selected row which is also the currently
 741         playing track in active window.
 742
 743 color_win_cur_sel_fg (lightyellow) [`Color`]
 744         Foreground color of the selected row which is also the currently
 745         playing track in active window.
 746
 747 color_win_dir (lightblue) [`Color`]
 748         Color of directories in browser.
 749
 750 color_win_fg (default) [`Color`]
 751         Window foreground color.
 752
 753 color_win_inactive_cur_sel_bg (gray) [`Color`]
 754         Background color of the selected row which is also the currently
 755         playing track in inactive window.
 756
 757 color_win_inactive_cur_sel_fg (lightyellow) [`Color`]
 758         Foreground color of the selected row which is also the currently
 759         playing track in inactive window.
 760
 761 color_win_inactive_sel_bg (gray) [`Color`]
 762         Background color of selected row in inactive window.
 763
 764 color_win_inactive_sel_fg (black) [`Color`]
 765         Foreground color of selected row in inactive window.
 766
 767 color_win_sel_bg (blue) [`Color`]
 768         Background color of selected row in active window.
 769
 770 color_win_sel_fg (white) [`Color`]
 771         Foreground color of selected row in active window.
 772
 773 color_win_title_bg (blue) [`Color`]
 774         Background color of window titles (topmost line of the screen).
 775
 776 color_win_title_fg (white) [`Color`]
 777         Foreground color of window titles (topmost line of the screen).
 778
 779 confirm_run (true)
 780         Ask for confirmation before executing *:run*
 781
 782 continue (true)
 783         Continue playing after current track finishes.
 784
 785 format_current [`Format String`]
 786         Format string for the line displaying currently playing track.
 787
 788 format_playlist [`Format String`]
 789         Format string for the list views (2-4).
 790
 791 format_title [`Format String`]
 792         Format string for terminal title.
 793
 794         NOTE: not all terminals support changing window title.
 795
 796 format_trackwin [`Format String`]
 797         Format string for the tree view's (1) track window.
 798
 799 id3_default_charset (ISO-8859-1)
 800         Default character set to use for ID3v1 and broken ID3v2 tags.
 801
 802         NOTE:  This is used only if the tag is not valid UTF-8.
 803
 804 lib_sort (artist album discnumber tracknumber title filename) [`Sort Keys`]
 805         Sort keys for the sorted library view (2).
 806
 807 output_plugin [alsa, arts, oss, sun]
 808         Name of output plugin.
 809
 810 pl_sort () [`Sort Keys`]
 811         Sort keys for the playlist view (3).  Empty value disables sorting and
 812         enables manually moving tracks.
 813
 814 play_library (true)
 815         Play tracks from the library instead of playlist.
 816
 817 play_sorted (false)
 818         Play tracks from the library in the sorted view (2) order instead of
 819         tree view (1) order.  Used only when play_library is true.
 820
 821 repeat (false)
 822         Repeat after all tracks played.
 823
 824 repeat_current (false)
 825         Repeat current track forever.
 826
 827 replaygain (false)
 828         Enable Replay Gain.
 829
 830 replaygain_limit (true)
 831         Use replay gain limiting when clipping.
 832
 833 replaygain_preamp (6.0)
 834         Replay gain preamplification in decibels.
 835
 836 show_hidden (false)
 837         Display hidden files in browser.
 838
 839 show_remaining_time (false)
 840         Display remaining time instead of elapsed time.
 841
 842 shuffle (false)
 843         Play in shuffled order.  Shuffle works in the library views (1-2) and
 844         playlist view (3).
 845
 846 softvol (false)
 847         Use software volume control.
 848
 849         NOTE: You should probably set this to false when using *ao* as
 850         *output_plugin* to output to wav files.
 851
 852 softvol_state (100 100)
 853         Used to save left and right channel values for software volume
 854         control.  Two integers in range 0..100 separated by a space.  This
 855         option is not usually changed directly since *vol* command does same
 856         thing if *softvol* is true.
 857
 858 status_display_program () [command]
 859         This command, if not empty, is run every time cmus' status changes.
 860         It can be used to display currently playing track on desktop
 861         background or panel for example.  See
 862         `/usr/share/doc/cmus/examples/cmus-status-display`.
 863
 864 @h2 Colors
 865
 866 Color is integer in range -1..255.
 867
 868 The following color names are recognized:
 869
 870 Terminal's default color, -1
 871         default
 872
 873 Fg & bg, 0..7
 874         black, red, green, yellow, blue, magenta, cyan, gray
 875
 876 Fg, 8..15
 877         darkgray, lightred, lightgreen, lightyellow, lightblue, lightmagenta,
 878         lightcyan, white
 879
 880 @h2 Format Strings
 881
 882 Format strings control display of tracks in library, playlist and play queue
 883 views.
 884
 885 NOTE: *altformat_\** options are used when there are no tags available.
 886
 887 Special Characters:
 888
 889         %a
 890                 artist
 891         %l
 892                 album
 893         %D
 894                 disc number
 895         %n
 896                 track number
 897         %t
 898                 title
 899         %g
 900                 genre
 901         %c
 902                 comment
 903         %y
 904                 year
 905         %d
 906                 duration
 907         %f
 908                 path and filename
 909         %F
 910                 filename
 911         %=
 912                 start align right (use at most once)
 913         %%
 914                 literal *%*
 915
 916 You can use printf style formatting (width, alignment, padding). To see
 917 current value of an option type *:set option=<TAB>*.
 918
 919 Examples:
 920
 921         @pre
 922         :set format_trackwin= %02n. %t (%y)%= %d
 923         :set format_current= %n. %-30t %40F (%y)%= %d
 924         @endpre
 925
 926 @h2 Sort Keys
 927
 928 Sort option (lib_sort, pl_sort) value is space separated list of the following
 929 sort keys:
 930
 931         artist, album, title, tracknumber, discnumber, date, genre, comment, filename
 932
 933
 934 @h1 PLUGIN OPTIONS
 935
 936 dsp.alsa.device
 937         PCM device for ALSA plugin, usually "default".
 938
 939 mixer.alsa.channel
 940         Mixer channel for ALSA Plugin, usually "pcm", "master" or "headphone".
 941         To see all possible values run "alsamixer" or "amixer".
 942
 943 mixer.alsa.device
 944         Mixer device for ALSA plugin, usually "default".
 945
 946 dsp.ao.buffer_size
 947         Buffer size, default is 8192 but you may want to try bigger values if
 948         you experience buffer under-runs.
 949
 950 dsp.ao.driver
 951         Output driver for libao plugin.  Example values: "alsa09", "esd",
 952         "irix", "oss", "sun", "aixs", "wav".
 953
 954         NOTE: of the file output drivers only "wav" is supported.
 955
 956 dsp.ao.wav_counter
 957         Counter used for making filename.  Used only if *dsp.ao.driver* is
 958         "wav".  For example if this is 1 and *dsp.ao.wav_dir* is "/home/user"
 959         then PCM data is outputted to "/home/user/01.wav".  This counter is
 960         incremented every time playback is stopped.
 961
 962         NOTE: you probably want to set *continue* to *false* (press *C*),
 963         otherwise playback is not stopped between tracks and all PCM data is
 964         outputted to one wav file (useful if you want to join files).  Also
 965         unsetting shuffle and repeat might be good idea.
 966
 967 dsp.ao.wav_dir
 968         Output directory for libao plugin, default is your home directory.
 969         Used only if *dsp.ao.driver* is "wav".
 970
 971 dsp.oss.device
 972         PCM device for OSS plugin, usually /dev/dsp.
 973
 974 mixer.oss.channel
 975         Mixer channel for OSS Plugin, "pcm" or "master".
 976
 977 mixer.oss.device
 978         Mixer device for OSS plugin, usually /dev/mixer.
 979
 980 dsp.sun.device
 981         PCM device for Sun plugin, usually /dev/audio.
 982
 983 mixer.sun.channel
 984         Mixer channel for Sun Plugin, usually "master".
 985
 986 mixer.sun.device
 987         Mixer device for Sun plugin, usually /dev/mixer.
 988
 989
 990 @h1 FILTERS
 991
 992 Filters are used mostly for filtering contents of library views (1 & 2).
 993 Filters do not change the actual library content, i.e. *:save* command will
 994 still save all tracks to playlist file whether they are visible or not.
 995
 996 @h2 Syntax
 997
 998 Filter expression is list of built-in filters or user defined filters
 999 separated with *&* (and) or *|* (or).  Parenthesis can be used group
1000 subexpressions and *!* negates result of the expression following it.
1001
1002 @h2 Strings
1003
1004 *filename*, *artist*, *album*, *title*, *genre*, *comment*
1005
1006 Comparators: *=* and *!=* (not equal)
1007
1008 @h2 Integers
1009
1010 *discnumber*, *tracknumber*, *date* (year), *duration* (seconds)
1011
1012 Comparators: *<*, *<=*, *=*, *>=*, *>*, *!=*
1013
1014 @h2 Booleans
1015
1016 *tag* (true if track has tags), *stream* (true if track is a stream)
1017
1018 @h2 Defining Filters
1019
1020 Filters can be defined with *fset* command.  User defined filters appear in
1021 the filters view (6).
1022
1023 Create a new filter which name is *ogg* and value *filename="\*.ogg"*
1024         :fset ogg=filename="\*.ogg"
1025
1026 Filter ogg and mp3 files from the 90s. Note the use of user defined filter
1027 *ogg*
1028         :fset 90s-ogg-mp3=date>=1990&date<2000&(ogg|filename="\*.mp3")
1029
1030 @h2 Activating Filters
1031
1032 *factivate* changes visible contents of the library (views 1-2).
1033
1034 Activate user defined filters *ogg* and *missing-tags*
1035         :factivate ogg missing-tags
1036
1037 Like above but negate value of *ogg* filter.
1038         :factivate !ogg missing-tags
1039
1040 Alternatively you can select the filters by pressing *space* in view 6 and
1041 then activate the selected filters by pressing *enter*.
1042
1043 @h2 Throw-away Filters
1044
1045 *filter* command is useful when you want to use a filter only once and not
1046 save it.  It changes visible contents of the library (views 1-2) and
1047 unactivates all filters in the filters view.
1048
1049 Filter all rock (anything with *rock* in genre tag) music from 80s-
1050         :filter date>=1980&genre="\*rock\*"
1051
1052 @h2 Selecting Tracks Matching a Filter
1053
1054 Mark (select) all tracks with duration less than 2 minutes
1055         :mark duration<120
1056
1057 This command works in views 2-4.
1058
1059
1060 @h1 FILES
1061
1062 cmus reads its configuration from 3 different places.
1063
1064 `~/.cmus/autosave`
1065         This is the first file cmus loads.  cmus saves its state on exit to
1066         this file so you shouldn't edit it.
1067
1068 `/usr/share/cmus/rc`
1069         If the autosave file didn't exist, this file is read instead.
1070
1071 `~/.cmus/rc`
1072         Static config file. This file is read immediately after the autosave
1073         file, and is never modified by cmus.  You can override auto-saved
1074         settings in this file.  This file is not limited to options, it can
1075         contain other commands too.
1076
1077 @h2 Color Schemes
1078
1079 There are some color schemes (\*.theme) in `/usr/share/cmus`.  You can switch
1080 them using the *:colorscheme* command.  You can put your own color schemes to
1081 ~/.cmus.
1082
1083 @h2 Examples
1084
1085 Example status display script (See *status_display_program* option) can be
1086 found in `/usr/share/doc/cmus/examples`.
1087
1088
1089 @h1 BUGS
1090
1091 After a crash last lines of `/tmp/cmus-debug` (or $TMPDIR/cmus-debug) might
1092 contain useful information.  The file exists only if you configured cmus with
1093 maximum debug level (*./configure DEBUG=2*).
1094
1095 Feature requests and bug reports should go to the cmus-devel mailing list:
1096         http://lists.sourceforge.net/lists/listinfo/cmus-devel
1097
1098
1099 @h1 SEE ALSO
1100
1101 *cmus-remote*(1)
1102
1103
1104 @h1 AUTHORS
1105
1106 cmus was mainly written by Timo Hirvonen <tihirvon\@gmail.com>.  Other
1107 contributers are listed in the `AUTHORS` file.
1108
1109 This man page was written by Frank Terbeck <ft\@bewatermyfriend.org>,
1110 Timo Hirvonen <tihirvon\@gmail.com>, and Clay Barnes <clay.barnes\@gmail.com>.