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