MOC
                      m u s i c  o n  c o n s o l e

                          http://moc.daper.net/


--------------------------------------------------------------------------------
What Is It?
--------------------------------------------------------------------------------

MOC (music on console) is a console audio player for LINUX/UNIX designed to be
powerful and easy to use.

You just need to select a file from some directory using the menu similar to
Midnight Commander, and MOC will start playing all files in this directory
beginning from the chosen file.  There is no need to create playlists as in
other players.

If you want to combine some files from one or more directories in one playlist,
you can do this.  The playlist will be remembered between runs or you can save
it as an m3u file to load it whenever you want.

Need the console where MOC is running for more important things?  Need to close
the X terminal emulator?  You don't have to stop playing - just press q and the
interface will be detached leaving the server running.  You can attach it later,
or you can attach one interface in the console, and another in the X terminal
emulator, no need to switch just to play another file.

MOC plays smoothly, regardless of system or I/O load because it uses the output
buffer in a separate thread.  The transition between files is gapless, because
the next file to be played is precached while the current file is playing.

Supported file formats are: MP3, Ogg Vorbis, FLAC, Musepack (mpc), Speex, Opus,
WAVE, those supported by FFmpeg/LibAV (e.g., WMA, RealAudio, AAC, MP4), AIFF,
AU, SVX, Sphere Nist WAV, IRCAM SF, Creative VOC, SID, wavpack, MIDI and
modplug.

Other features:

  - Simple mixer
  - Color themes
  - Menu searching (playlist or directory) like M-s in Midnight Commander
  - The way MOC creates titles from tags is configurable
  - Optional character set conversion for file tags using iconv()
  - OSS, ALSA, SNDIO and JACK output
  - User defined keys
  - Cache for files' tags

--------------------------------------------------------------------------------
Documentation and The MOC Forum
--------------------------------------------------------------------------------

This file is only a brief description of MOC, for more information is
available on the home page (http://moc.daper.net/documentation).

You can also find a discussion forum on the MOC home page.

--------------------------------------------------------------------------------
What Software Is Required To Build It?
--------------------------------------------------------------------------------

To build MOC from the distribution tarball you will need:

  - UNIX system with POSIX threads (e.g., Linux or FreeBSD)
  - ncurses (probably already installed in your system)
  - C and C++ compilers (MOC is written in C, but libtool and some
    decoder plugins require a C++ compiler)
  - Berkeley DB (libdb) version 4 (unless configured with --disable-cache)

If you are building from the SVN repository you will also need:

  - Subversion (to checkout the source directory tree)
  - Autoconf version 2.60 and the associated Automake and Libtool

You should choose which of the following audio formats you wish to play and
provide the libraries needed to support them:

  - AAC - libfaad2 version 2.7 (http://www.audiocoding.com/), and
          libid3tag (http://www.underbit.com/products/mad/)
  - FLAC - libFLAC version 1.1 (http://flac.sourceforge.net/)
  - MIDI - libtimidity version 0.1 (http://timidity.sourceforge.net/)
  - modplug - libmodplug version 0.7 (http://modplug-xmms.sourceforge.net/)
  - MP3 - libmad with libid3tag (ftp://ftp.mars.org/pub/mpeg/)
  - Musepack (mpc) - libmpc (http://www.musepack.net/), and
                   - taglib version 1.3.1
                     (http://developer.kde.org/~wheeler/taglib.html)
  - Ogg Vorbis - libvorbis, libogg and libvorbisfile (all version 1.0)
                 (http://www.xiph.org/ogg/), or
               - libvorbisidec and libogg (both version 1.0)
                 (http://svn.xiph.org/trunk/Tremor)
  - SID - libsidplay2 version 2.1.1 and libsidutils version 1.0.4
          (http://sidplay2.sourceforge.net/)
  - Speex - libspeex version 1.0 (http://www.speex.org/), and
          - libogg version 1.0 (http://www.xiph.org/ogg/)
  - WMA, RealAudio (.ra), MP4 - FFmpeg version 0.5 (http://www.ffmpeg.org/), or
                              - LibAV version 0.6.3 (http://www.libav.org/)
  - WAVE, AU, AIFF, SVX, SPH, IRC, VOC - libsndfile version 1.0
                                         (http://www.mega-nerd.com/libsndfile/)
  - wavpack - libwavpack version 4.31 (http://www.wavpack.com/)

For interfacing to the sound sub-system, you will need libraries for one or
more of the following:

  - ALSA - alsa-lib version 0.9 (http://www.alsa-project.org/)
  - OSS - the OSS libraries (http://www.opensound.com/)
  - BSD's SNDIO - SNDIO libraries
  - JACK low-latency audio server - JACK version 0.4
                                    (http://jackit.sourceforge.net/)

For network streams:

  - libcurl version 7.12.2 (http://curl.haxx.se/)

For resampling (playing files with sample rate not supported by your
hardware):

  - libresamplerate version 0.1.2 (http://www.mega-nerd.com/SRC/)

For librcc (fixes encoding in broken mp3 tags):

  - http://rusxmms.sourceforge.net/

Note that for Debian-based distributions, you will also require any '-dev'
suffixed versions of the packages above if building from source.

The versions given above are minimum versions and later versions should also
work.  However, MOC may not yet have caught up with the very latest changes
to library interfaces and these may cause problems if they break backwards
compatibility.

--------------------------------------------------------------------------------
On Which Systems Is MOC Running?
--------------------------------------------------------------------------------

MOC is developed and tested on GNU/Linux.  Sometimes test runs are made on
other operating systems, and it is known to compile and probably work on:

  - FreeBSD
  - NetBSD
  - OpenBSD
  - OpenWRT

There is no intention to support MOC on MS-Windows (so please don't ask).

--------------------------------------------------------------------------------
How Do I Build and Install It?
--------------------------------------------------------------------------------

Generic installation instruction is included in the INSTALL file.

In short, if you are building from an SVN checkout of MOC (but not if you
are building from a downloaded tarball) then you will first need to run:

	autoreconf -if

and then proceed as shown below for a tarball.  (If you are using the
tarball but have applied additional patches then you may also need to run
autoreconf.)

To build MOC from a downloaded tarball just type:

	./configure
	make

And as root:

	make install

Under FreeBSD and NetBSD (and possibly other systems) it is necessary to
run the configure script this way:

	./configure LDFLAGS=-L/usr/local/lib CPPFLAGS=-I/usr/local/include

Note that MOC and some of its supporting packages make use of GNU extensions
to the C89 and C99 language standards.  Therefore, do not set the '-std'
option in CFLAGS to a non-GNU value; if you do, configure will fail
unexpectedly.

In addition to the standard configure options documented in the INSTALL
file, there are some MOC-specific options:

	--enable-cache=[yes|no]

	  Specifying 'no' will disable the tags cache support.  If your
	  intent is to remove the Berkeley DB dependancy (rather than
	  simply removing the on-disk cache) then you should also either
	  build MOC without RCC support or use a librcc built with BDB
	  disabled.

	--enable-debug=[yes|no|gdb]

	  Using 'gdb' will cause MOC to be built with options tailored to
	  use with GDB.  (Note that after release 2.5 this option will be
	  split into separate debugging and logging options.)

	--with-oss=[yes|no|DIR]

	  Where DIR is the location of the OSS include directory (and
	  defaults to '/usr/lib/oss').

	--with-vorbis=[yes|no|tremor]

	  Using 'tremor' will cause MOC to build against the integer-only
	  implementation of the Vorbis library (libvorbisidec).

You can install MOC into its own source directory tree and run it from there
so you do not have to install it permanently on your system.  If you're just
wanting to try it out or test some patches, then this is something you may
wish to do:

	./configure --prefix="$PWD" --without-timidity
	make
	make install
	bin/mocp -M .moc

--------------------------------------------------------------------------------
How Do I Use It?
--------------------------------------------------------------------------------

Run program with the 'mocp' command.  The usage is simple; if you need help,
press 'h' and/or read mocp manpage.  There is no complicated command line or
cryptic commands.  Using MOC is as easy as using basic functions of Midnight
Commander.

You can use a configuration file placed in ~/.moc/config, but it's not required.
See config.example provided with MOC.

--------------------------------------------------------------------------------
Using Themes
--------------------------------------------------------------------------------

Yes, there are themes, because people wanted them. :)

Themes can change all colors and only colors.  An example theme file with a
exhaustive description is included (themes/example_theme) and is the
default MOC appearance.

Theme files should be placed in ~/.moc/themes/ or $(datadir)/moc/themes/
(e.g., /usr/local/share/moc/themes) directory, and can be selected with
the Theme configuration options or the -T command line option (see the
manpage and the example configuration file).

Feel free to share the themes you have created.

--------------------------------------------------------------------------------
Defining Keys
--------------------------------------------------------------------------------

You can redefine standard keys.  See the instructions in the keymap.example
file.

--------------------------------------------------------------------------------
How Do I Report A Problem?
--------------------------------------------------------------------------------

Not every release is extensively tested on every system, so the particular
configuration of software, libraries, versions and hardware on your system
might expose a problem.

If you find any problems then you should search the MOC Forum for a solution;
your problem may not be unique.  If you do find an existing topic which
matches your problem but does not offer a solution, or the solution offered
does not work for you and the topic appears still active, then please add your
experience to it; it may be that additional information you can provide will
contain the clue needed to resolve the problem.

If you don't find an answer there and you installed MOC from your Linux
distribution's repository then you should report it via your distribution's
usual reporting channels in the first instance.  If the problem is ultimately
identified as actually being in MOC itself, it should then be reported to the
MOC Maintainer (preferably by the distribution's MOC package maintainer).

If you built MOC from source yourself or you get no resolution from your
distribution then start a new topic on the MOC Forum for your problem or
contact the MOC Maintainer.

Before reporting a problem, you should first read this Forum post:

   Linkname: How to Report Bugs Effectively
        URL: http://moc.daper.net/node/1035

and the essay it references:

   Linkname: How to Report Bugs Effectively
        URL: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

There are two things you must do if at all possible:

1. Make sure you are using the current stable MOC release or, even better,
   can reproduce it on the latest development release or SVN HEAD, and
2. Make sure you include the version and revision information (which you
   can obtain by running 'mocp --version').

If you do not do those two things (and don't offer a good explanation as to
why you didn't) your problem report is likely to be ignored until such time
as you do.

--------------------------------------------------------------------------------
Hacking
--------------------------------------------------------------------------------

Want to modify MOC?  You're welcome to do so, and patch contributions are
also welcome.

MOC is written in C, so you must at least know this language to make simple
changes.  It is multi-threaded program, but there are places where you don't
need to worry about that (the interface is only a single thread process).  It
uses autoconf, automake and libtool chain to generate configuration/compilation
stuff, so you must know how to use it, for example, if you need to link to an
additional library.

The documentation for some parts of the internal API for creating decoder
plugins (file format support) and sound output drivers can be generated using
Doxygen (http://www.doxygen.org/).  Just run the doxygen command from the MOC
source directory.

Before you change anything it is a good idea to check for the latest development
version (check out from the Subversion repository is the best).  Your changes
might conflict with changes already made to the source or your feature might be
already implemented.  See also the TODO file as it is updated regularly and
contains quite detailed information on future plans.

If you need help, just contact MOC's Maintainer via e-mail.  And if you are
planning anything non-trivial it's a good idea to discuss your intentions
with the MOC Maintainer once you've clarified your ideas but before spending
too much time implementing them; it will be more productive if your work fits
with MOC's future direction.

--------------------------------------------------------------------------------
Who Wrote It?  Where Can I Send Bug Reports, Questions or Comments?
--------------------------------------------------------------------------------

	* Original author is Damian Pietras
	* Current maintainer is John Fitzgerald
	* For comments and questions see the official forum:
	              http://moc.daper.net/forum
	* Need to report a bug?  You can reach the maintainer(s) at:
	                 <mocmaint@daper.net>

--------------------------------------------------------------------------------

Preamble
---
This document is meant to give you an overview on the idea of having a
parametric equalizer for sound enhancement and how you can create your
own presets.  Also the interaction with the equalizer in MOC is described.

I would like to improve this document to make it more usable; so if you
have any comments and/or ideas feel free to contact me.

- Hendrik Iben (hiben<at>tzi(dot)de)


Content
---
0. Document History
1. Motivation
2. Usage
3. Preset Format
4. Creating Presets
5. TODO
6. References


0. Document History
---
07.09.2008 - Initial version
15.03.2011 - Reformatted


1. Nuts and Bolts / Motivation for Implementing the Equalizer
---
The equalizer is an implementation of a biquadratic peaking equalizer
filter looked up from the Audio EQ Cookbook[1].

It happens to be a parametric equalizer and this means that, different
from other equalizer implementations, the number of bands* is not fixed.
When I started the idea of implementing the equalizer I looked around
in the source of other audio playback software and found that a lot of
them are recycling the code used by the famous XMMS[2] audio player.
I also would have liked to recycle the code but I decided against it
for two reasons:

The first reason is that there is almost no documentation on the algorithm
used.  Maybe the signal processing folks have fun finding out what makes
this thing work but I was totally lost.  So I decided that I wanted to
*know* what I am doing if I do it.

As for the second reason, the code used by XMMS is totally optimized for
integer arithmetic.  There is no problem with this in general but I had
the goal of implementing something that was as accurate as I could and
I wanted to use floating point arithmetic.

So I am no signals processing guy, but I have -- I think -- a solid
understanding of the matter.  I sat down and started to read about
equalizing, audio processing and signal theory in general.  After some
time I found a mathematical description and a C implementation of
biquadratic filters in the Audio Cookbook.  I made an implementation of
the XMMS equalizer and the biquadratic filter using Octave[3] to compare
the outcome of both filters.  I was a bit surprised how different filters
can be but in the end succeeded (?) in finding a quite good biquadratic
filter set that would produce results not unlike the XMMS equalizer.

Although I did not use the XMMS-code I think that people will be more
happy to accept this equalizer if they can use their presets with it.
There is some conversion needed, but it's a straightforward process.
I converted all presets provided by XMMS into presets for this mixer.
They should be available at [4].

* A band is a chosen center frequency where a filter has most impact.
  If you look at WinAmp / XMMS / Beep Media Player you will find that
  they settled on a common set of 10 bands.


2. Using the Equalizer
---
The default keys for the equalizer are:

'e' - Refresh equalizer
'E' - Toggle equalizer (on/off)
'k' - Select next preset
'K' - Select previous preset

Each of these actions results in a message displayed in the message area.
This message will be overridden by the next action.


3. Preset Format
---
Presets for the equalizer are to be placed in a directory called 'eqsets'
in MOC's home directory (e.g., $HOME/.moc/eqsets).  There is no convention
for the filename, but it will serve as the name in the selection process.

File format in pseudo EBNF:

  EQSET
  ((<CF> <BW> <AMP>)|(0 <PREAMP>))*

  CF:     Center frequency (sane values are from ~20 to ~20000).
  BW:     Bandwith in Octaves.  This defines how fast the bands
          influence vanishes over the frequencies.
  AMP:    Amplification factor (in dB) to apply to the band.
  PREAMP: Specifies an amplification factor applied before equalizing.

So a valid equalizer set would be:

  # this is a comment
  EQSET
  # amplify audio by 1.4dB
  0 1.4
  # damp frequencies at 100Hz by -4dB, filter bandwidth 1.5 octaves
  100   1.5 -4
  # amplify frequencies at 4000Hz by 2dB, filter bandwidth 1.5 octaves
  4000  1.5 2

There is no order to stick to when specifying frequencies.


4. Creating Your Own Presets
---
For a start you should have a look at the converted presets[4].  The
bandwidths used in the conversion have been extracted by taking a look
at the filters signal response (implementation and analysis in Octave).
I tried to do this as accurately as possible but I don't know if I made
a mistake.  They sound correct though... :-)

You might note that there is never a positive amplification factor in
the presets although there are in the original preset.  The reason for
this is that I used the maximum amplification in the preset as zero
amplification and adjusted the other values accordingly.

In general, when creating a preset get used to the following idea: Do not
amplify the frequencies you want but damp those that are of no interest.
This has the same effect but avoids clipping and this equalizer type seems
to be very prone to clipping.  Also be very careful with pre-amplifying
the audio for the same reason.

With that said, the next confusing thing is the bandwidth definition.
Every band needs a defined bandwidth in octaves where the bandwidth
defines where the filter's effect has been reduced by 3dB*.  This means
that if you define a band at 1000Hz with a bandwidth of 1.5 octaves and
an amplification of -10dB, at 353.6Hz** and at 2828.4Hz the amplification
will be reduced to -7dB.

If unsure, stay in between 1.0 and 2.0.  Just keep in mind that if two
bands overlap you might get an undesired amplification.

When designing presets, just save the preset and select it in MOC.  After
each change press the refresh key (default 'e').  This will re-create the
equalizer reflecting your changes.

If your preset is not found, have a look at the output of MOC's server
thread.  Parsing errors are emitted there.

*  3dB is commonly used for bandwidth.  -3dB equals about 70.7% of
   original amplification.
** 353.6 =~ 1000*(2^-1.5), 2828.4 =~ 1000*(2^1.5)


5. TODO
---
- The equalizer is currently not optimized in any way.

- It converts all sound data into floating point values to perform the
  equalization and converts them back afterwards.  A better approach
  would be either to provide integer algorithms for equalization or to
  leave the audio data in floating point format.

- There is no sorting for the presets; their order is defined by reading
  the directory content.

- Maybe it would be nice to add a name to the preset different from the
  filename.


6. References
---
[1] Cookbook formulae for audio EQ biquad filter coefficients
    http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt
[2] X Multimedia System
    http://www.xmms.org/
[3] GNU Octave
    http://www.gnu.org/software/octave/
[4] Converted WinAmp / XMMS Equalizer sets
    http://www.informatik.uni-bremen.de/~hiben/moc/eqsets.tar.gz