MOC(1)

📦
version 2.6.0~svn2994 · 2 versions
, in opensuse-leap 16.0

MOC(1) — Music On Console 👑🎧

✨ NAME ✨

MOC — console audio player, aka the terminal music setup that lowkey has main character energy 💅🎶

🌈 SYNOPSIS 🌈

mocp [OPTIONS] [FILE|DIR ...]

🎧 DESCRIPTION 🎧

Okay bestie, so MOC is a console audio player with a simple ncurses interface. It supports OGG, WAV, MP3 and other formats. Just run mocp, go to some directory using the menu, and press enter to start playing the file. The program will automatically play the rest of the files in the directory. Slay. 🎵✨

With no options and no file arguments, the program begins in the current directory, or in MusicDir if the StartInMusicDir option is set in the configuration file. If you give a directory on the command line, MOC will try to go there. If a playlist is given, then it is loaded. With multiple files, playlists or directories, everything will be added to the playlist recursively (including the contents of any playlist given). 🫶

Note that relative paths in playlists are resolved with respect to the directory of the playlist, or of the symlink being used to reference it. iykyk 🧚

💅 OPTIONS 💅

If an option can also be set in the configuration file, the command line overrides it (but see the -O option for the list-valued configuration file options exception). Okay? Okay. 💖

  • -D, --debug — Run MOC in debug mode. The client and server log a lot of information to debug files. Don't use this; the server log is large. This is only available if MOC was compiled without --disable-debug. 💀
  • -S, --server — Run only the server and exit. 🛰️
  • -F, --foreground — Implies -S. Run the server in foreground and log everything to stdout. ✨
  • -R NAME[:...], --sound-driver NAME[:...] — Use the specified sound driver(s). They can be OSS, ALSA, JACK, SNDIO or null (for debugging). Some of the drivers may not have been compiled in. This option is called SoundDriver in the configuration file. 🎛️
  • -m, --music-dir — Start in MusicDir (set in the configuration file). This can be also set in the configuration file as StartInMusicDir. 🎶
  • -q, --enqueue — Add files given after command line options to the queue. Don't start the interface. 🎟️
  • -a, --append — Append files, directories (recursively) and playlists given after command line options to the playlist. Don't start the interface. 📥
  • -c, --clear — Clear the playlist. 🧹
  • -p, --play — Start playing from the first item on the playlist. ▶️
  • -l, --playit — Play files given on the command line without modifying the clients' playlists. 🎧
  • -f, --next — Request playing the next song from the server's playlist. ⏭️
  • -r, --previous — Request playing the previous song from the server's playlist. ⏮️
  • -s, --stop — Request the server to stop playing. 🛑
  • -x, --exit — Bring down the server. 💥
  • -P, --pause — Request the server to pause playing. ⏸️
  • -U, --unpause — Request the server to resume playing when paused. ⏯️
  • -G, --toggle-pause — Toggle between play and pause. 🔁
  • -k [+|-]N, --seek [+|-]N — Seek forward (positive) or backward (negative) by N seconds in the file currently being played. ⏩
  • -T THEME, --theme THEME — Use a theme file. If the path is not absolute, the file will be searched for in /usr/share/moc/themes/ (depends on installation prefix), ~/.moc/themes/ and the current directory. 🎀
  • -C FILE, --config FILE — Use the specified configuration file (which must be readable) instead of the default. As this file can specify commands which invoke other applications, MOC will refuse to start if it is not owned by either root or the current user, or if it is writable by anyone other than its owner. 🔐
  • --no-config — Do not read any configuration file but use the built-in defaults. 🧼
  • -O NAME[+]=VALUE, --set-option NAME[+]=VALUE — Override configuration file option NAME with VALUE. This option can be repeated as many times as needed, and the option name is not case sensitive. Most option values are set before the configuration file is processed (which allows the new values to be picked up by substitutions); however, list-valued options are overridden afterwards (which gives the choice of whether the configured values are replaced or added to). 💫

See the example configuration file (config.example) for a description of the options available.

Examples:

-O AutoNext=no
-O messagelingertime=1 -O XTerms+=xxt:xwt
Note that MOC does not perform variable substitution as it does for values read from the configuration file. 🫡
  • -M DIR, --moc-dir DIR — Use the specified MOC directory instead of the default. This also causes the configuration file from that directory to be used. This can also be specified in the configuration file using the MOCDir option. 📁
  • -y, --sync — This copy of the interface will synchronize its playlist with other clients. This option is called SyncPlaylist in the configuration file. 🔄
  • -n, --nosync — This copy of the interface will not synchronize its playlist with other clients (see above). 🚫
  • -A, --ascii — Use ASCII characters to draw lines. (This helps on some terminals.) 🖥️
  • -i, --info — Print the information about the file currently being played. ℹ️
  • -Q FORMAT_STRING, --format FORMAT_STRING — Print information about the file currently being played using a format string. Replace string sequences with the actual information:
%state     State
%file      File
%title     Title
%artist    Artist
%song      SongTitle
%album     Album
%tt        TotalTime
%tl        TimeLeft
%ts        TotalSec
%ct        CurrentTime
%cs        CurrentSec
%b         Bitrate
%r         Rate

It is also possible to use variables from the FormatString configuration file option. 🧾

  • -e, --recursively — Alias of -a for backward compatibility. 🫶
  • -h, --help — Print a list of options with short descriptions and exit. 🙋
  • --usage — Print a synopsis of the mocp command and exit. 📜
  • -V, --version — Print the program version and exit. 🏷️
  • --echo-args — Print the POPT-interpreted command line arguments and exit. 🗣️
  • -v [+|-]N, --volume [+|-]N — Adjust the mixer volume. You can set (-v 50) or adjust (-v +10, -v -10). 🔊
  • -t OPTION[,...], --toggle OPTION[,...] / -o OPTION[,...], --on OPTION[,...] / -u OPTION[,...], --off OPTION[,...] — Followed by a list of identifiers, these will control MOC's playlist options. Valid identifiers are shuffle, repeat and autonext. They can be shortened to s, r and n respectively. Both the identifiers and short forms are case insensitive. 🎛️

Example:

-t shuffle,R,n

would toggle shuffle, repeat and autonext all at once. ✨

  • -j N{s|%}, --jump N{s|%} — Jump to some position in the current file. N is the number of seconds (when followed by an s) or the percent of total file time (when followed by a %). ⏱️

Examples: -j 10s, -j 50%

🦋 USING POPT ALIASES 🦋

MOC uses the POPT library to process its command line. This allows users to assign MOC options and arguments to an alias of their choosing. The aliases are just lines in the ~/.popt text file and have the general form:

mocp alias newoption expansion

This works as if expansion textually replaces newoption on the command line. The replacement is recursive; that is, other newoptions can be embedded in the expansion. The expansion is parsed similarly to a shell command, which allows \, ", and ' to be used for quoting. If a backslash is the final character on a line, the next line in the file is assumed to be a logical continuation of the line containing the backslash, just as in the shell. The newoption can be either a short or long option, and any syntactically valid name the user wishes to use. 🧚✨

If you add a description for the new option and/or for any argument by appending the special POPT options --POPTdesc and --POPTargs, then the option will be displayed in the output of --help and --usage. The value for these two options are strings of the form $"string". 💬

So, for example:

mocp alias --single -D --set-option autonext=no \
                         --POPTdesc=$"Play just the file selected"

would allow the user to turn on logging (-D) and override the configuration file's AutoNext option setting just by using --single as an option to the mocp command. 🔥

Sometimes you may wish to provide values to aliased options from the command line. If just one aliased option has such a value, then it's a simple matter of placing it last:

mocp alias --yours --sound-driver OSS --theme

when used like this:

mocp --yours your_theme

would result in:

mocp --sound-driver OSS --theme your_theme

But aliasing multiple options with such values means making use of the special construct !#:+ (and quoting carefully):

mocp alias -1 "-R !#:+" "-T my_theme" "-O !#:+"

when used like this:

mocp -1 OSS shuffle=yes ~/my_music

would result in:

mocp -R OSS -T my_theme -O shuffle=yes ~/my_music

There is also a ~/.popt entry which allows for the execution of a different program when the associated option is used. For this, an exec is used in place of the alias and the expansion is the program to be executed:

mocp exec --help /usr/bin/man 1 mocp \
                         POPTdesc=$"Provide the man page instead of help"

This would override the usual MOC --help output and use the system's man program to present this man page instead. 📖

Note that while ~/.popt (or /etc/popt) is the default POPT configuration file, you can nominate specific file(s) to be used instead via the MOCP_POPTRC environment variable. 🌈

🌸 ENVIRONMENT VARIABLES 🌸

okay bestie, these are the env vars MOC reads directly 💖. Some other vars might matter too — but those are for the libraries MOC leans on, not MOC itself, so don't @ me. Also, literally any environment variable can get substituted into a configuration file option value (peep the config.example file for the deets ✨).

  • ESCDELAY — an ncurses(3X) variable, and it sets the delay (in milliseconds) before ncurses treats an Esc as a standalone key instead of part of an escaped character sequence (you know, the kinda thing function keys spit out 🎹). MOC sets this to 25ms by default, which lowkey is enough for most systems, no cap.
  • HOME — tells MOC where your home directory lives 🏠. It gets used for various purposes, including the default location of the MOC directory.
  • MOCP_OPTS — whatever's in here gets prepended to the command line options before they're processed 👑. Yes, prepended. Order matters, iykyk.
  • MOCP_POPTRC — a colon-separated list of POPT configuration files that MOC loads in sequence during initialisation 📋. The rules are:
    • unset → the default POPT configuration file gets used
    • set but empty → no POPT configuration file gets loaded, periodt
    • set → the files that exist get loaded, and the ones that don't get skipped, no drama
🚨 Security check bestie: because these files can specify commands that invoke other applications, MOC will refuse to start if they're not owned by root or the current user, or if they're writable by anyone other than their owner. It's giving protective queen energy and honestly? slay.
  • TERM and WINDOW — MOC uses these to tell the difference between X-terminals, screen(1) and console terminals 🖥️. It uses the configuration file options XTerms and ScreenTerms to help make that determination.

📁 FILES 📁

  • ~/.moc — the MOC directory, where the configuration file, the socket, the pid file and other data live 🎀.
  • ~/.moc/config — the configuration file for MOC. The format is super simple; to see how to use it, look at the example configuration file (config.example) that ships with the program 📝. That example file fully describes all the configuration options, so it's a genuinely useful reference when you're using the -O option. And because this file can specify commands that invoke other applications, MOC will refuse to start if it's not owned by either root or the current user, or if it's writable by anyone other than its owner 🔒.
  • ~/.popt
  • /etc/popt — the default files POPT reads to obtain aliased options 🌀. Same deal as above: because these files can specify commands that invoke other applications, MOC will refuse to start if it's not owned by root or the current user, or if it's writable by anyone other than its owner. (Also see the MOCP_POPTRC environment variable above, bestie 👀.)
  • ~/.moc/themes
  • /usr/share/moc/themes — default directories for the theme files 💅✨.
  • /usr/share/moc/decoder_plugins — default directories for the audio decoder plugins 🎧.
  • mocp_client_log
  • mocp_server_log — client and server log files 📓. These get created in the directory where the client and server are started. (Also see the -D option.)

💀 BUGS 💀

Command line options that affect the server's behaviour (like --sound-driver) are ignored if the server is already running when you execute mocp 😭. And the user is not warned about this. Not even a little heads-up. Nothing. So if it's not doing the thing, that's probably why, ngl.

🌈 HOMEPAGE 🌈

http://moc.daper.net/ — go say hi 🦋

👑 AUTHOR 👑

  • Damian Pietras — <daper@daper.net>
  • MOC Maintainer(s) — <mocmaint@daper.net>

okay that's the whole page, you're officially a MOC girlie now 🎀✨ This was Version 2.6-alpha3, dated 16 November 2016 — iconic behaviour from the maintainers fr fr 💜🫶

📦 where this page comes from