doc/manual.rst

   1 ==============================
   2 CMus - C\* Music Player Manual
   3 ==============================
   4
   5 .. contents::
   6
   7 Command Line Options
   8 ==========================
   9
  10 See ``cmus --help`` for more information.
  11
  12 Remote Control
  13 ==============
  14
  15 CMus can be controlled via UNIX-socket using ``cmus-remote`` command. This is
  16 very useful feature because it allows you control CMus without having to
  17 switch to the desktop where CMus window is.
  18
  19 See ``cmus-remote --help`` for more information.
  20
  21 Views
  22 =====
  23
  24 There are 6 views in cmus:
  25
  26 * Artist/Album/Track Tree View (1)
  27 * Shuffle List (2)
  28 * Sorted List (3)
  29 * Play Queue (4)
  30 * Directory Browser (5)
  31 * Filter View (6)
  32
  33 To switch between the views use keys '1' - '5'. Views 1-3 display current
  34 playlist.  View 3 can be sorted (see sort_ option).
  35
  36 View 4 displays play queue. Tracks in the play queue are played first and
  37 removed from the queue immediately after playing starts. After last track from
  38 play queue has been played CMus starts playing tracks in the playlist.
  39
  40 View 5 allows you to browse filesystem, add tracks to playlist, enqueue
  41 tracks, delete files and even play tracks directly from the browser.  You can
  42 also 'cd' into a playlist.
  43
  44 View 6 displays user defined `Playlist Filters`_.
  45
  46 Normal Mode
  47 ==========================
  48
  49 Global Keys (Views 1-6)
  50 --------------------------
  51
  52 =================  ===========
  53 Key                Description
  54 =================  ===========
  55 F1                 show help window
  56 z                  skip back in playlist
  57 x                  play
  58 c                  pause
  59 v                  stop
  60 b                  skip forward in playlist
  61 C                  toggle continue
  62 r                  toggle repeat
  63 m                  toggle playlist mode (all, artist, album)
  64 p                  toggle play mode (tree (view 1), shuffle (view 2), sorted (view 3))
  65 t                  toggle time elapsed/remaining
  66 Q                  quit
  67 :                  enter command mode
  68 left, h            skip 5 seconds back in song
  69 right, l           skip 5 seconds forward in song
  70 1                  switch to artist/album/track tree view
  71 2                  switch to shuffle view
  72 3                  switch to sorted view
  73 4                  switch to play queue view
  74 5                  switch to directory browser view
  75 6                  switch to filters view
  76 up, k              move up
  77 down, j            move down
  78 page up, ctrl-b    move page up
  79 page down, ctrl-f  move page down
  80 home, g            go to top of the window
  81 end, G             go to bottom of the window
  82 \-                 volume down
  83 +, =               volume up
  84 {                  left channel down
  85 }                  right channel down
  86 [                  left channel up
  87 ]                  right channel up
  88 =================  ===========
  89
  90 Playlist Keys (Views 1-3)
  91 --------------------------
  92
  93 =======  ===========
  94 Key      Description
  95 =======  ===========
  96 del, D   remove selected artist, album or track from playlist
  97 e        append selected artist, album or track to the play queue
  98 E        prepend selected artist, album or track to the play queue
  99 i        jump to current track
 100 u        remove non-existent files from playlist and update tags for changed files
 101 enter    play selected track
 102 space    show/hide albums for the selected artist
 103 tab      switch window in the artist+album/track view
 104 =======  ===========
 105
 106 Play Queue Keys (View 4)
 107 --------------------------
 108
 109 =======  ===========
 110 Key      Description
 111 =======  ===========
 112 del, D   remove selected track from the queue
 113 =======  ===========
 114
 115 Directory Browser Keys (View 5)
 116 -------------------------------
 117
 118 =========  ===========
 119 Key        Description
 120 =========  ===========
 121 del, D     remove selected file
 122 a          add file/directory to playlist
 123 e          append selected file/directory to the play queue without adding to playlist
 124 E          prepend selected file/directory to the play queue without adding to playlist
 125 i          toggle showing of hidden files
 126 enter      cd to selected directory/playlist or play selected file
 127 backspace  cd to parent directory
 128 =========  ===========
 129
 130 Filter View Keys (View 6)
 131 -------------------------
 132
 133 =======  ===========
 134 Key      Description
 135 =======  ===========
 136 del, D   remove selected filter
 137 space    select/unselect filter
 138 enter    apply selected filters
 139 =======  ===========
 140
 141 Command Mode
 142 ==========================
 143
 144 Press ':' any time to enter command mode. The command mode works much like
 145 VIM_'s command mode.  Tabulator expansion works for files/dirs, commands and
 146 options. There's command history too (up/down arrow keys). Press 'ESC' to
 147 leave command mode and return to `Normal Mode`_.
 148
 149 You don't have to type whole command name if it is unambiguous.  For example
 150 ``:a some-file.mp3``.
 151
 152 Commands
 153 --------------------------
 154
 155 Use the ``:set`` command to set options.
 156
 157 ===============================  ===========
 158 Command                          Description
 159 ===============================  ===========
 160 :add dir/file/playlist/url       Add dir/file/playlist/url to playlist. This command can be used to join playlists.
 161 :bind context key command        Define keybinding (See `Keybindings`_).
 162 :cd [directory]                  Change directory.  Default directory is ``$HOME``.
 163 :clear                           Clear playlist.
 164 :enqueue\ dir/file/playlist/url  Add dir/file/playlist/url to the play queue.
 165 :filter [value]                  Set temporary playlist filter. If no value is given filtering is disabled.
 166 :fset name=value                 Add or replace filter
 167 :load filename                   Clear playlist and then load a new one. Simple one track/line lists and .pls playlists are supported.
 168 :run command                     Execute command for the currently selected files (See `Running Programs`_).
 169 :save [filename]                 Save playlist.  Default filename is the last used one.
 170 :seek [+-]POS                    Seek top POS (seconds). POS can be suffixed with 'm' (minutes) or 'h' (hours).
 171 :set OPTION=VALUE                Set option (See Options_).
 172 :shuffle                         Reshuffle playlist.
 173 :unbind context key              Remove keybinding.
 174 ===============================  ===========
 175
 176 Options
 177 --------------------------
 178
 179 ======================  ===========
 180 Option                  Description
 181 ======================  ===========
 182 output_plugin           output plugin (alsa, arts, oss)
 183 buffer_seconds          size of player buffer in seconds (1-10)
 184 confirm_run             confirm :run with >1 files (true/false)
 185 dsp.\*, mixer.\*        output plugin options (use tab to cycle through all possible options)
 186 color\_\*               user interface colors (See `User Interface Colors`_)
 187 format_current          format of the line showing currently played track
 188 format_playlist         format of text in views 2-4
 189 format_title            format of terminal window title
 190 format_track_win        format of text in track window (view 1)
 191 altformat\_\*           format strings used when file has no tags
 192 _`sort`                 comma separated list of sort keys for the sorted view (3). Valid keys: artist, album, title, tracknumber, discnumber, date, genre, filename)
 193 status_display_program  script to run when player status changes (See `Status Display`_)
 194 ======================  ===========
 195
 196 Format Characters
 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 =========  ===========
 200 Character  Description
 201 =========  ===========
 202 %a         artist
 203 %l         album
 204 %D         disc number
 205 %n         track number
 206 %t         title
 207 %g         genre
 208 %y         year
 209 %d         duration
 210 %f         path and filename
 211 %F         filename
 212 %=         start align right (use at most once)
 213 %%         literal '%'
 214 =========  ===========
 215
 216 You can use printf style formatting (width, alignment, padding).
 217
 218 Examples
 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 ::
 222
 223         :set format_trackwin= %02n. %t (%y)%= %d
 224         :set format_current= %n. %-30t %40F (%y)%= %d
 225
 226 To see current value of an option type ``:set option=<TAB>``.
 227
 228 ID3 Tags
 229 ========
 230
 231 Some MP3s encode tags using different character set than specified in the
 232 frame. In other words those MP3s are broken but because this is so common
 233 problem cmus has an option (mad.charset) to change character set used for those broken MP3s.
 234
 235 You need to edit ``~/.config/cmus/config`` manually, this can't be set using
 236 ``:set`` command. Default value is ISO-8859-1.
 237
 238 ::
 239
 240         mad.charset = "cp1251"
 241
 242 **Note:** If you change this option you need to remove
 243 ``~/.cache/cmus/trackdb.*`` files because they contain tags encoded in the old
 244 character set.
 245
 246 Searching
 247 =========
 248
 249 =======  ===========
 250 Key      Description
 251 =======  ===========
 252 /WORDS   search forward
 253 ?WORDS   search backward
 254 //WORDS  search forward (see below)
 255 ??WORDS  search backward (see below)
 256 /        search forward for the latest used pattern
 257 ?        search backward for the latest used pattern
 258 n        search next
 259 N        search previous
 260 =======  ===========
 261
 262 WORDS is list of words separated by spaces.  Search is case insensitive and
 263 works in every view.
 264
 265 In views 1-4 words are compared to artist, album and title tags.  Use
 266 //WORDS and ??WORDS to search only artists/albums in view 1 or titles in
 267 views 2-4.  If the file doesn't have tags words are compared to filename
 268 without path.
 269
 270 In view 5 words are compared to filename without path.
 271
 272 Streaming
 273 =========
 274
 275 CMus supports Shoutcast/Icecast streams (Ogg and MP3).  To add stream
 276 to playlist use ``:add`` command or ``cmus-remote``.
 277
 278 ::
 279
 280         :add http://example.com/path/to/stream
 281
 282 _`Playlist Filters`
 283 ===================
 284
 285
 286 Add filters using ``:fset`` command, select filters with `space` and then
 287 apply selected filters by pressing `enter`.  Only tracks matching the
 288 activated filters will be shown in the playlist (views 1-3).  Filters do not
 289 change the actual playlist content, i.e.  ``:save`` command will still save
 290 all tracks to playlist file whether they are visible or not.
 291
 292 ========  =======  ===========
 293 Filter    Type     Description
 294 ========  =======  ===========
 295 filename  string   filename or URI
 296 artist    string
 297 album     string
 298 title     string
 299 genre     string   music genre
 300 date      integer  year
 301 duration  integer  seconds
 302 stream    boolean  true if track is a stream
 303 tag       boolean  true if track has tags
 304 ========  =======  ===========
 305
 306 Strings are case insensitive. ``?`` matches exactly one character and ``*``
 307 zero or more characters.  To match literal '?' or '*' you need to escape it
 308 with backslash ('\\?' and '\\*', to get literal backslash use '\\\\').
 309
 310 Integers are non-zero and -1 means the value is not set.  For example
 311 ``date=-1`` tests if date is not set.
 312
 313 ========  ===========
 314 Type      Comparators
 315 ========  ===========
 316 boolean   none (filter name itself has value true or false)
 317 integer   <, <=, =, >=, >, !=
 318 string    =, !=
 319 ========  ===========
 320
 321 Filters are separated with ``&`` (and) or ``|`` (or). Parenthesis can be used
 322 to group expressions and ``!`` (not) inverts expression value.
 323
 324 Filter names are case sensitive and can contain only these characters:
 325 ``a-zA-Z0-9_-``
 326
 327 Sometimes you may want to set temporary playlist filter which you only use
 328 once (you don't want to add it to the filter list).  Use ``:filter`` to set
 329 temporary filter or disable filtering if no argument given.
 330
 331 Examples
 332 --------
 333
 334 ::
 335
 336         :fset ogg=filename="*.ogg"
 337
 338         # use the filter above, user defined filters are like booleans
 339         :fset ogg-rock=ogg&genre="*rock*"
 340
 341         # not 80s music unless artist is Iron Maiden
 342         :fset foo=!(date>=1980&date<1990)|artist="iron maiden"
 343
 344         # regular files, not streams
 345         :fset files=!stream
 346
 347         # temporarily filter ogg files or streams
 348         # 'ogg' is user defined filter (see above)
 349         :filter ogg|stream
 350
 351         # disable any filters
 352         :filter
 353
 354 Running Programs
 355 ================
 356
 357 You can execute external commands for the currently selected files by
 358 executing ``:run command``.  Playlist view (1, 2 or 3) must be active when
 359 running commands.  In view 1 you can run any command for files of the selected
 360 track, album or artist.  In views 2 and 3 command is executed for the only
 361 selected file, of course. CMus will ask confirmation if there are more than
 362 one selected files unless ``confirm_run`` is ``false``.
 363
 364 ``{}`` in the command is replaced with the selected files. If the command
 365 doesn't contain ``{}`` the selected files are automatically appended to the
 366 command.  `/bin/sh` compatible quoting are supported (single/double quotes and
 367 escaping with ``\``).
 368
 369 Both stdout and stderr are redirected to /dev/null and stdin is closed so you
 370 can't run interactive text mode programs.  GUI programs should work just fine.
 371
 372 Examples
 373 --------
 374
 375 These examples assume that view 1 is active and the selected album contains
 376 only files `file1.ogg` and `file2.ogg`.
 377
 378 ::
 379
 380         # rm -f file1.ogg file2.ogg
 381         :run rm -f
 382
 383         # tagger -uniq -date 2004 file1.ogg file2.ogg
 384         :run tagger -uniq -date 2004
 385
 386         # cp file1.ogg file2.ogg /tmp
 387         :run cp {} /tmp/
 388
 389
 390 Status Display
 391 ==========================
 392
 393 CMus can run external program which can be used to display player status on
 394 desktop background (using root-tail for example), panel etc.
 395
 396 For example if you use WMI_ you can write a script that displays currently
 397 playing file on the wmi statusbar using wmiremote command::
 398
 399         :set status_display_program=cmus-status-display
 400
 401 To disable status display set ``status_display_program`` to empty string.
 402
 403 Example Script (cmus-status-display)
 404 ------------------------------------
 405
 406 ::
 407
 408         #!/bin/bash
 409         #
 410         # cmus-status-display
 411         #
 412         # Usage:
 413         #   in cmus command ":set status_display_program=cmus-status-display"
 414         #
 415         # This scripts is executed by cmus when status changes:
 416         #   cmus-status-display key1 val1 key2 val2 ...
 417         #
 418         # All keys contain only chars a-z. Values are UTF-8 strings.
 419         #
 420         # Keys: status file url artist album discnumber tracknumber title date
 421         #   - status (stopped, playing, paused) is always given
 422         #   - file or url is given only if track is 'loaded' in cmus
 423         #   - other keys/values are given only if they are available
 424         #
 425
 426         output()
 427         {
 428                 # write status to /tmp/cmus-status (not very useful though)
 429                 echo "$*" >> /tmp/cmus-status 2>&1
 430
 431                 # WMI (http://wmi.modprobe.de/)
 432                 #wmiremote -t "$*" &> /dev/null
 433         }
 434
 435         while [[ $# -ge 2 ]]
 436         do
 437           eval _$1=\"$2\"
 438           shift
 439           shift
 440         done
 441
 442         if [[ -n $_file ]]
 443         then
 444                 output "[$_status] $_artist - $_album - $_title ($_date)"
 445         elif [[ -n $_url ]]
 446         then
 447                 output "[$_status] $_title"
 448         else
 449                 output "[$_status]"
 450         fi
 451
 452
 453 User Interface Colors
 454 ==========================
 455
 456 Change ``color_*`` options to customize colors.
 457
 458 Example::
 459
 460         :set color_statusline_bg=4
 461
 462 **Tip:** type ``:set color_<tab>`` to cycle through all color option
 463 variables.
 464
 465 Colors
 466 --------------------------
 467
 468 ======  =====
 469 Value   Color
 470 ======  =====
 471 -1      default color. use this if you want transparency
 472 0       black
 473 1       red
 474 2       green
 475 3       brown (or yellow)
 476 4       blue
 477 5       magenta
 478 6       cyan
 479 7       gray
 480 8       dark gray
 481 9       bright red
 482 10      bright green
 483 11      bright yellow
 484 12      bright blue
 485 13      bright magenta
 486 14      bright cyan
 487 15      white
 488 16-255  more colors, not supported by every terminal
 489 ======  =====
 490
 491 **Note:** On terminals supporting only 16 colors you can use colors 8-15 for
 492 foreground only.
 493
 494 ==============  ==============
 495 Terminal Type   Number of Colors Supported
 496 ==============  ==============
 497 gnome-terminal  16
 498 rxvt-unicode    88
 499 xterm           256
 500 GNU Screen      as many as the terminal inside which screen is running
 501 ==============  ==============
 502
 503 Keybindings
 504 ===========
 505
 506 Use `:bind context key command` to bind a key and `:unbind context key` to
 507 remove existing keybinding.  Use tab to cycle through contexts, keys and
 508 functions.
 509
 510 =============  ==============
 511 Context        Description
 512 =============  ==============
 513 browser        Directory browser
 514 common         All views
 515 filters        Filters view
 516 playlist       Views 1-3
 517 play_queue     Play Queue
 518 =============  ==============
 519
 520
 521 Functions Common for All Views
 522 ------------------------------
 523
 524 ========================  ==============
 525 Function                  Description
 526 ========================  ==============
 527 help
 528 next
 529 pause
 530 play
 531 prev
 532 quit
 533 search_next
 534 search_prev
 535 seek_backward
 536 seek_forward
 537 stop
 538 toggle_continue
 539 toggle_play_mode
 540 toggle_playlist_mode
 541 toggle_remaining_time
 542 toggle_repeat
 543 view_1
 544 view_2
 545 view_3
 546 view_4
 547 view_5
 548 view_6
 549 vol_down
 550 vol_left_down
 551 vol_left_up
 552 vol_right_down
 553 vol_right_up
 554 vol_up
 555 win_activate_next         toggle active window in view 1
 556 win_bottom                goto bottom
 557 win_down                  scroll down one row
 558 win_page_down             scroll down one page
 559 win_page_up               scroll up one page
 560 win_top                   goto top
 561 win_up                    scroll up one row
 562 ========================  ==============
 563
 564 Functions for Playlist Views (1-3)
 565 ----------------------------------
 566
 567 ========================  ==============
 568 Function                  Description
 569 ========================  ==============
 570 expand_artist             toggle showing albums for selected artist
 571 play_selected             play selected track
 572 queue_append              append to play queue
 573 queue_prepend             prepend to play queue
 574 remove                    remove artist/album/track from play queue
 575 select_current            jump to currently playing file
 576 update                    remove non-existent files from playlist and update tags for changed files
 577 ========================  ==============
 578
 579 Functions for Play Queue View (4)
 580 ---------------------------------
 581
 582 ========================  ==============
 583 Function                  Description
 584 ========================  ==============
 585 remove                    remove selected track from queue
 586 ========================  ==============
 587
 588 Functions for Directory Browser (5)
 589 -----------------------------------
 590
 591 ========================  ==============
 592 Function                  Description
 593 ========================  ==============
 594 add                       add selection to playlist
 595 cd_parent                 cd ..
 596 enter                     enter directory/playlist or play file
 597 queue_append              append to play queue
 598 queue_prepend             prepend to play queue
 599 reload                    reload directory
 600 remove                    remove selected file
 601 toggle_show_hidden        toggle showing hidden files
 602 ========================  ==============
 603
 604 Functions for Filters View (6)
 605 ------------------------------
 606
 607 ========================  ==============
 608 Function                  Description
 609 ========================  ==============
 610 activate                  activate selected filters
 611 delete_filter             delete filter
 612 toggle_filter             select / deselect filter
 613 ========================  ==============
 614
 615 Examples
 616 --------
 617
 618 ::
 619
 620         # make control-h toggle showing hidden files
 621         :bind browser ^H toggle_show_hidden
 622
 623         # remove binding for F1 key (help by default)
 624         :unbind common F1
 625
 626
 627 Files
 628 ==========================
 629
 630 ~/.config/cmus/config
 631   configuration options
 632
 633 ~/.config/cmus/filters
 634   playlist filters
 635
 636 ~/.config/cmus/keybindings
 637   keybindings
 638
 639 ~/.config/cmus/playlist.pl
 640   automatically saved playlist
 641
 642 ~/.cache/cmus/trackdb.dat, ~/.cache/cmus/trackdb.idx
 643   cached tags
 644
 645 ~/.cache/cmus/ui_curses_cmd_history
 646   command mode history
 647
 648 ~/.cache/cmus/ui_curses_search_history
 649   search mode history
 650
 651 You can override location of these files by setting ``XDG_CONFIG_HOME`` and/or
 652 ``XDG_CACHE_HOME`` environment variables.
 653
 654 Bugs
 655 ==========================
 656
 657 If you configured cmus with ``DEBUG=2`` then debugging information will be
 658 written to ``/tmp/cmus-debug`` file. After a crash last lines of these files
 659 should contain useful information.
 660
 661 Using GDB
 662 --------------------------
 663
 664 Run ``gdb cmus core`` and type ``backtrace`` to see at which line cmus
 665 crashed.
 666
 667 Author
 668 ==========================
 669
 670 Timo Hirvonen <tihirvon AT gmail.com>
 671
 672 .. _VIM: http://www.vim.org
 673 .. _WMI: http://wmi.modprobe.de