Difference between revisions of "Cmus"

From ArchWiki
Jump to: navigation, search
(Configuration)
m (See also: add link to 3rd party scripts and status display programs)
 
(18 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 +
[[Category:Multimedia players]]
 +
[[ja:Cmus]]
 
[[sr:Cmus]]
 
[[sr:Cmus]]
[[Category:Player]]
 
 
[http://cmus.sourceforge.net/ cmus] ''(C* MUsic Player)'' is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings.
 
[http://cmus.sourceforge.net/ cmus] ''(C* MUsic Player)'' is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings.
  
=Installation=
+
== Installation ==
[[pacman|Install]] {{Pkg|cmus}}, available in the [[Official Repositories]].
+
  
Alternatively, there is also a development version available in the [[AUR]] called {{AUR|cmus-git}}.
+
[[Install]] the {{Pkg|cmus}} package, or {{AUR|cmus-git}} for the development version.
  
= Configuration =
+
=== Using cmus with alsa ===
To configure cmus start it and switch to the configuration tab by pressing {{Keypress|7}}. Now you can see a list of default keybindings. Select a field in the list with the arrow keys and press{{Keypress|Enter}} to edit the values. You can also remove bindings with {{Keypress|D}} or {{Keypress|del}}. To edit unbound commands and option variables scroll down in the list to the relevant section. Variables can also be toggled instead of edited with {{Keypress|space}}. Cmus allows changing the color of nearly every interface element. You can prefix colors with "light" to make them appear brighter and set attributes for some text elements.
+
When using cmus with [[Advanced Linux Sound Architecture]] the default configuration does not allow playing music. What you might encounter when trying to start cmus is a blank terminal line with no output whatsoever. To fix it, create a new config file and set the following variables
 +
{{hc|~/.config/cmus/rc|2=
 +
set output_plugin=alsa
 +
set dsp.alsa.device=default
 +
set mixer.alsa.device=default
 +
set mixer.alsa.channel=Master
 +
}}
  
== Using cmus whith alsa ==
+
==Usage==
When using cmus with [[Advanced Linux Sound Architecture]] the default configuration does not allow playing music. To fix it change three variables, set {{ic|dsp.alsa.device}} to {{ic|default}} , set {{ic|mixer.alsa.channel}} to {{ic|Master}} and set {{ic|mixer.alsa.device}} to {{ic| default}}.
+
 
+
=Usage=
+
 
Cmus comes with a great reference manual.
 
Cmus comes with a great reference manual.
 
  $ man cmus  
 
  $ man cmus  
Line 20: Line 23:
 
  $ man cmus-remote
 
  $ man cmus-remote
  
== Starting Cmus ==
+
=== Starting Cmus ===
  
 
To start cmus, type:
 
To start cmus, type:
Line 27: Line 30:
 
When you first launch cmus it will open to the album/artist tab.
 
When you first launch cmus it will open to the album/artist tab.
  
== Adding Music ==
+
=== Adding Music ===
Press {{Keypress|5}} to switch to the file-browser tab so we can add some music.
+
Press {{ic|5}} to switch to the file-browser tab so we can add some music.
Now, use the arrow keys ({{Keypress|up}}, {{Keypress|down}}), {{Keypress|Enter}} and {{Keypress|Backspace}} to navigate to where you have audio files stored. Alternatively, you may use the vim bindings ({{Keypress|k}}, {{Keypress|j}}) to navigate up and down through your music.
+
Now, use the arrow keys ({{ic|up}}, {{ic|down}}), {{ic|Enter}} and {{ic|Backspace}} to navigate to where you have audio files stored. Alternatively, you may use the vim bindings ({{ic|k}}, {{ic|j}}) to navigate up and down through your music.
  
To add music to your cmus library, use the arrow keys to highlight a file or folder, and press {{Keypress|a}}. When you press {{Keypress|a}} cmus will move you to the next line down (so that it is easy to add a bunch of files/folders in a row) and start adding the file/folder you pressed {{Keypress|a}} in to your library. This may take a bit if you added a folder with a lot of music in it. As files are added, you will see the second time in the bottom right go up. This is the total duration of all the music in the cmus library.
+
To add music to your cmus library, use the arrow keys to highlight a file or folder, and press {{ic|a}}. When you press {{ic|a}} cmus will move you to the next line down (so that it is easy to add a bunch of files/folders in a row) and start adding the file/folder you pressed {{ic|a}} in to your library. This may take a bit if you added a folder with a lot of music in it. As files are added, you will see the second time in the bottom right go up. This is the total duration of all the music in the cmus library.
 
{{Note|cmus does not move, duplicate or change your files. It just remembers where they are and caches the metadata (duration, artist, etc.)}}
 
{{Note|cmus does not move, duplicate or change your files. It just remembers where they are and caches the metadata (duration, artist, etc.)}}
 
{{Note|Cmus automatically saves your settings, library and everything when you quit.}}
 
{{Note|Cmus automatically saves your settings, library and everything when you quit.}}
  
== Playing Tracks ==
+
=== Playing Tracks ===
Press {{Keypress|1}} to go to the simple library view. Use the ({{Keypress|up}} and {{Keypress|down}} arrow keys (or {{Keypress|k}}, {{Keypress|j}}) to select a track you'd like to hear, and press {{Keypress|Enter}} to play it. Here's some keys to control play:
+
Press {{ic|1}} to go to the simple library view. Use the {{ic|up}} and {{ic|down}} arrow keys (or {{ic|k}}, {{ic|j}}) to select an artist and album you would like to hear. Pressing {{ic|space}} on the artist name will collapse or expand the albums it contains. Switch between list of tracks and artist/album view by pressing {{ic|Tab}} and press {{ic|Enter}} to play the selected track. Here is some keys to control the playback:
:Press {{Keypress|c}} to pause/unpause
+
:Press {{ic|c}} to pause/unpause
:Press {{Keypress|right}}/{{Keypress|left}} (or {{Keypress|h}}, {{Keypress|l}}) arrow keys to seek by 10 seconds
+
:Press {{ic|right}}/{{ic|left}} (or {{ic|h}}, {{ic|l}}) arrow keys to seek by 10 seconds
:Press {{Keypress|<}}/{{Keypress|>}} seek by one minute
+
:Press {{ic|<}}/{{ic|>}} seek by one minute
  
== Keybindings ==
+
=== Keybindings ===
 
See the configuration section on how to change keybindings.
 
See the configuration section on how to change keybindings.
  
== Remote Control ==
+
==Tabs==
 +
There are 7 tabs in cmus.  Press keys {{ic|1}}-{{ic|7}} to change active tab.
 +
 
 +
=== Library tab (1) ===
 +
Display all tracks in so-called '''library'''. Tracks are sorted artist/album tree.  Artist sorting is done alphabetically. Albums are sorted by year.
 +
 
 +
=== Sorted library tab (2) ===
 +
Displays same content as view, but as a simple list which is automatically sorted by user criteria.
 +
 
 +
=== Playlist tab (3) ===
 +
Displays editable playlist with optional sorting.
 +
 
 +
=== Play Queue tab (4) ===
 +
Displays queue of tracks which are played next. These tracks are played before anything else (i.e. the playlist or library).
 +
 +
=== Browser (5) ===
 +
Directory browser.  In this tab, music can be added to either the library, playlist or queue from the filesystem.
 +
 
 +
=== Filters tab (6) ===
 +
Lists user defined filters.
 +
 
 +
=== Settings tab (7) ===
 +
Change settings. See configuration for further information.
 +
 
 +
== Configuration ==
 +
To configure cmus start it and switch to the configuration tab by pressing {{ic|7}}. Now you can see a list of default keybindings. Select a field in the list with the arrow keys and press{{ic|Enter}} to edit the values. You can also remove bindings with {{ic|D}} or {{ic|del}}. To edit unbound commands and option variables scroll down in the list to the relevant section. Variables can also be toggled instead of edited with {{ic|space}}. Cmus allows changing the color of nearly every interface element. You can prefix colors with "light" to make them appear brighter and set attributes for some text elements.
 +
 
 +
=== Remote Control ===
 
Cmus can be controlled externally through a unix-socket with {{ic|cmus-remote}}. This makes it easy to control playback through an external application or key-binding.
 
Cmus can be controlled externally through a unix-socket with {{ic|cmus-remote}}. This makes it easy to control playback through an external application or key-binding.
  
One such usage of this feature is to control playback in Cmus with the XF86 keyboard events. The following script when run will start Cmus in an xterm terminal if it isn't running, otherwise it will will toggle play/pause:
+
One such usage of this feature is to control playback in Cmus with the XF86 keyboard events. The following script when run will start Cmus in an xterm terminal if it is not running, otherwise it will will toggle play/pause:
  
{{bc|<nowiki>
+
{{bc|1=
 
#!/bin/sh
 
#!/bin/sh
#
 
# Author: Dennis Hodapp
 
# Filename: cplay
 
# Requires: cmus
 
#
 
# Tests if cmus is running and starts it if it isn't.
 
# Else it toggles play/pause.
 
 
# This command will break if you rename it to
 
# This command will break if you rename it to
 
# something containing "cmus".
 
# something containing "cmus".
  
TERMINAL=/usr/bin/xterm
+
if ! pgrep cmus ; then
SHELL=/bin/sh
+
   xterm -e cmus
 
+
if ! ps aux | grep -w "cmus$" | grep -v grep > /dev/null ; then
+
   $TERMINAL -e $SHELL -c cmus & > /dev/null
+
 
else
 
else
 
   cmus-remote -u
 
   cmus-remote -u
 
fi
 
fi
</nowiki>}}
+
}}
  
 
To use the previous script in [[Openbox]], copy the code above into a file {{ic|~/bin/cplay}}. Make the file executable using {{ic|chmod +x ~/bin/cplay}}. Next edit {{ic|~/.config/openbox/rc.xml}} and change the following key-bindings to look like this:
 
To use the previous script in [[Openbox]], copy the code above into a file {{ic|~/bin/cplay}}. Make the file executable using {{ic|chmod +x ~/bin/cplay}}. Next edit {{ic|~/.config/openbox/rc.xml}} and change the following key-bindings to look like this:
Line 78: Line 98:
 
     <keybind key="XF86AudioPlay">
 
     <keybind key="XF86AudioPlay">
 
       <action name="Execute">
 
       <action name="Execute">
         <command>cplay</command>
+
         <command>cmus-remote -u</command>
 
       </action>
 
       </action>
 
     </keybind>
 
     </keybind>
Line 94: Line 114:
 
</nowiki>}}
 
</nowiki>}}
  
Now when you use the {{ic|XF86AudioPlay}} key on your keyboard, cmus will open up. If it's opened already it will then start playing. Using the XF86AudioNext and XF86AudioPrev keys will change tracks.
+
Now when you use the {{ic|XF86AudioPlay}} key on your keyboard, cmus will open up. If it is opened already it will then start playing. Using the XF86AudioNext and XF86AudioPrev keys will change tracks.
  
=Tabs=
+
== See also ==
There are 7 tabs in cmus.  Press keys {{Keypress|1}}-{{Keypress|7}} to change active tab.
+
 
+
== Library tab (1) ==
+
Display all tracks in so-called '''library'''. Tracks are sorted artist/album tree.  Artist sorting is done alphabetically. Albums are sorted by year.
+
 
+
== Sorted library tab (2) ==
+
Displays same content as view, but as a simple list which is automatically sorted by user criteria.
+
 
+
== Playlist tab (3) ==
+
Displays editable playlist with optional sorting.
+
 
+
== Play Queue tab (4) ==
+
Displays queue of tracks which are played next. These tracks are played before anything else (i.e. the playlist or library).
+
+
== Browser (5) ==
+
Directory browser.  In this tab, music can be added to either the library, playlist or queue from the filesystem.
+
 
+
== Filters tab (6) ==
+
Lists user defined filters.
+
 
+
== Settings tab (7) ==
+
Change settings. See configuration for further information.
+
  
=Links=
+
* [https://github.com/cmus/cmus Git Repository]
# [http://gitorious.org/cmus Git Repository]
+
* [https://cmus.github.io/ Website]
# [http://cmus.sourceforge.net/ Website]
+
* [https://github.com/cmus/cmus/wiki User submitted scripts]

Latest revision as of 17:26, 26 July 2016

cmus (C* MUsic Player) is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings.

Installation

Install the cmus package, or cmus-gitAUR for the development version.

Using cmus with alsa

When using cmus with Advanced Linux Sound Architecture the default configuration does not allow playing music. What you might encounter when trying to start cmus is a blank terminal line with no output whatsoever. To fix it, create a new config file and set the following variables

~/.config/cmus/rc
set output_plugin=alsa
set dsp.alsa.device=default
set mixer.alsa.device=default
set mixer.alsa.channel=Master

Usage

Cmus comes with a great reference manual.

$ man cmus 
$ man cmus-tutorial
$ man cmus-remote

Starting Cmus

To start cmus, type:

$ cmus

When you first launch cmus it will open to the album/artist tab.

Adding Music

Press 5 to switch to the file-browser tab so we can add some music. Now, use the arrow keys (up, down), Enter and Backspace to navigate to where you have audio files stored. Alternatively, you may use the vim bindings (k, j) to navigate up and down through your music.

To add music to your cmus library, use the arrow keys to highlight a file or folder, and press a. When you press a cmus will move you to the next line down (so that it is easy to add a bunch of files/folders in a row) and start adding the file/folder you pressed a in to your library. This may take a bit if you added a folder with a lot of music in it. As files are added, you will see the second time in the bottom right go up. This is the total duration of all the music in the cmus library.

Note: cmus does not move, duplicate or change your files. It just remembers where they are and caches the metadata (duration, artist, etc.)
Note: Cmus automatically saves your settings, library and everything when you quit.

Playing Tracks

Press 1 to go to the simple library view. Use the up and down arrow keys (or k, j) to select an artist and album you would like to hear. Pressing space on the artist name will collapse or expand the albums it contains. Switch between list of tracks and artist/album view by pressing Tab and press Enter to play the selected track. Here is some keys to control the playback:

Press c to pause/unpause
Press right/left (or h, l) arrow keys to seek by 10 seconds
Press </> seek by one minute

Keybindings

See the configuration section on how to change keybindings.

Tabs

There are 7 tabs in cmus. Press keys 1-7 to change active tab.

Library tab (1)

Display all tracks in so-called library. Tracks are sorted artist/album tree. Artist sorting is done alphabetically. Albums are sorted by year.

Sorted library tab (2)

Displays same content as view, but as a simple list which is automatically sorted by user criteria.

Playlist tab (3)

Displays editable playlist with optional sorting.

Play Queue tab (4)

Displays queue of tracks which are played next. These tracks are played before anything else (i.e. the playlist or library).

Browser (5)

Directory browser. In this tab, music can be added to either the library, playlist or queue from the filesystem.

Filters tab (6)

Lists user defined filters.

Settings tab (7)

Change settings. See configuration for further information.

Configuration

To configure cmus start it and switch to the configuration tab by pressing 7. Now you can see a list of default keybindings. Select a field in the list with the arrow keys and pressEnter to edit the values. You can also remove bindings with D or del. To edit unbound commands and option variables scroll down in the list to the relevant section. Variables can also be toggled instead of edited with space. Cmus allows changing the color of nearly every interface element. You can prefix colors with "light" to make them appear brighter and set attributes for some text elements.

Remote Control

Cmus can be controlled externally through a unix-socket with cmus-remote. This makes it easy to control playback through an external application or key-binding.

One such usage of this feature is to control playback in Cmus with the XF86 keyboard events. The following script when run will start Cmus in an xterm terminal if it is not running, otherwise it will will toggle play/pause:

#!/bin/sh
# This command will break if you rename it to
# something containing "cmus".

if ! pgrep cmus ; then
  xterm -e cmus
else
  cmus-remote -u
fi

To use the previous script in Openbox, copy the code above into a file ~/bin/cplay. Make the file executable using chmod +x ~/bin/cplay. Next edit ~/.config/openbox/rc.xml and change the following key-bindings to look like this:

Note: Make sure there are no conflicting keybindings in rc.xml
~/.config/openbox/rc.xml
  <keyboard>
    <keybind key="XF86AudioPlay">
      <action name="Execute">
        <command>cmus-remote -u</command>
      </action>
    </keybind>
    <keybind key="XF86AudioNext">
      <action name="Execute">
        <command>cmus-remote -n</command>
      </action>
    </keybind>
    <keybind key="XF86AudioPrev">
      <action name="Execute">
        <command>cmus-remote -r</command>
      </action>
    </keybind>
  </keyboard>

Now when you use the XF86AudioPlay key on your keyboard, cmus will open up. If it is opened already it will then start playing. Using the XF86AudioNext and XF86AudioPrev keys will change tracks.

See also