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