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