1 MOC 2 m u s i c o n c o n s o l e 3 4 http://moc.daper.net/ 5 6 7-------------------------------------------------------------------------------- 8What Is It? 9-------------------------------------------------------------------------------- 10 11MOC (music on console) is a console audio player for LINUX/UNIX designed to be 12powerful and easy to use. 13 14You just need to select a file from some directory using the menu similar to 15Midnight Commander, and MOC will start playing all files in this directory 16beginning from the chosen file. There is no need to create playlists as in 17other players. 18 19If you want to combine some files from one or more directories in one playlist, 20you can do this. The playlist will be remembered between runs or you can save 21it as an m3u file to load it whenever you want. 22 23Need the console where MOC is running for more important things? Need to close 24the X terminal emulator? You don't have to stop playing - just press q and the 25interface will be detached leaving the server running. You can attach it later, 26or you can attach one interface in the console, and another in the X terminal 27emulator, no need to switch just to play another file. 28 29MOC plays smoothly, regardless of system or I/O load because it uses the output 30buffer in a separate thread. The transition between files is gapless, because 31the next file to be played is precached while the current file is playing. 32 33Supported file formats are: MP3, Ogg Vorbis, FLAC, Musepack (mpc), Speex, Opus, 34WAVE, those supported by FFmpeg/LibAV (e.g., WMA, RealAudio, AAC, MP4), AIFF, 35AU, SVX, Sphere Nist WAV, IRCAM SF, Creative VOC, SID, wavpack, MIDI and 36modplug. 37 38Other features: 39 40 - Simple mixer 41 - Color themes 42 - Menu searching (playlist or directory) like M-s in Midnight Commander 43 - The way MOC creates titles from tags is configurable 44 - Optional character set conversion for file tags using iconv() 45 - OSS, ALSA, SNDIO and JACK output 46 - User defined keys 47 - Cache for files' tags 48 49-------------------------------------------------------------------------------- 50Documentation and The MOC Forum 51-------------------------------------------------------------------------------- 52 53This file is only a brief description of MOC, for more information is 54available on the home page (http://moc.daper.net/documentation). 55 56You can also find a discussion forum on the MOC home page. 57 58-------------------------------------------------------------------------------- 59What Software Is Required To Build It? 60-------------------------------------------------------------------------------- 61 62To build MOC from the distribution tarball you will need: 63 64 - UNIX system with POSIX threads (e.g., Linux or FreeBSD) 65 - ncurses (probably already installed in your system) 66 - C and C++ compilers (MOC is written in C, but libtool and some 67 decoder plugins require a C++ compiler) 68 - Berkeley DB (libdb) version 4 (unless configured with --disable-cache) 69 70If you are building from the SVN repository you will also need: 71 72 - Subversion (to checkout the source directory tree) 73 - Autoconf version 2.60 and the associated Automake and Libtool 74 75You should choose which of the following audio formats you wish to play and 76provide the libraries needed to support them: 77 78 - AAC - libfaad2 version 2.7 (http://www.audiocoding.com/), and 79 libid3tag (http://www.underbit.com/products/mad/) 80 - FLAC - libFLAC version 1.1 (http://flac.sourceforge.net/) 81 - MIDI - libtimidity version 0.1 (http://timidity.sourceforge.net/) 82 - modplug - libmodplug version 0.7 (http://modplug-xmms.sourceforge.net/) 83 - MP3 - libmad with libid3tag (ftp://ftp.mars.org/pub/mpeg/) 84 - Musepack (mpc) - libmpc (http://www.musepack.net/), and 85 - taglib version 1.3.1 86 (http://developer.kde.org/~wheeler/taglib.html) 87 - Ogg Vorbis - libvorbis, libogg and libvorbisfile (all version 1.0) 88 (http://www.xiph.org/ogg/), or 89 - libvorbisidec and libogg (both version 1.0) 90 (http://svn.xiph.org/trunk/Tremor) 91 - SID - libsidplay2 version 2.1.1 and libsidutils version 1.0.4 92 (http://sidplay2.sourceforge.net/) 93 - Speex - libspeex version 1.0 (http://www.speex.org/), and 94 - libogg version 1.0 (http://www.xiph.org/ogg/) 95 - WMA, RealAudio (.ra), MP4 - FFmpeg version 0.5 (http://www.ffmpeg.org/), or 96 - LibAV version 0.6.3 (http://www.libav.org/) 97 - WAVE, AU, AIFF, SVX, SPH, IRC, VOC - libsndfile version 1.0 98 (http://www.mega-nerd.com/libsndfile/) 99 - wavpack - libwavpack version 4.31 (http://www.wavpack.com/) 100 101For interfacing to the sound sub-system, you will need libraries for one or 102more of the following: 103 104 - ALSA - alsa-lib version 0.9 (http://www.alsa-project.org/) 105 - OSS - the OSS libraries (http://www.opensound.com/) 106 - BSD's SNDIO - SNDIO libraries 107 - JACK low-latency audio server - JACK version 0.4 108 (http://jackit.sourceforge.net/) 109 110For network streams: 111 112 - libcurl version 7.12.2 (http://curl.haxx.se/) 113 114For resampling (playing files with sample rate not supported by your 115hardware): 116 117 - libresamplerate version 0.1.2 (http://www.mega-nerd.com/SRC/) 118 119For librcc (fixes encoding in broken mp3 tags): 120 121 - http://rusxmms.sourceforge.net/ 122 123Note that for Debian-based distributions, you will also require any '-dev' 124suffixed versions of the packages above if building from source. 125 126The versions given above are minimum versions and later versions should also 127work. However, MOC may not yet have caught up with the very latest changes 128to library interfaces and these may cause problems if they break backwards 129compatibility. 130 131-------------------------------------------------------------------------------- 132On Which Systems Is MOC Running? 133-------------------------------------------------------------------------------- 134 135MOC is developed and tested on GNU/Linux. Sometimes test runs are made on 136other operating systems, and it is known to compile and probably work on: 137 138 - FreeBSD 139 - NetBSD 140 - OpenBSD 141 - OpenWRT 142 143There is no intention to support MOC on MS-Windows (so please don't ask). 144 145-------------------------------------------------------------------------------- 146How Do I Build and Install It? 147-------------------------------------------------------------------------------- 148 149Generic installation instruction is included in the INSTALL file. 150 151In short, if you are building from an SVN checkout of MOC (but not if you 152are building from a downloaded tarball) then you will first need to run: 153 154 autoreconf -if 155 156and then proceed as shown below for a tarball. (If you are using the 157tarball but have applied additional patches then you may also need to run 158autoreconf.) 159 160To build MOC from a downloaded tarball just type: 161 162 ./configure 163 make 164 165And as root: 166 167 make install 168 169Under FreeBSD and NetBSD (and possibly other systems) it is necessary to 170run the configure script this way: 171 172 ./configure LDFLAGS=-L/usr/local/lib CPPFLAGS=-I/usr/local/include 173 174Note that MOC and some of its supporting packages make use of GNU extensions 175to the C89 and C99 language standards. Therefore, do not set the '-std' 176option in CFLAGS to a non-GNU value; if you do, configure will fail 177unexpectedly. 178 179In addition to the standard configure options documented in the INSTALL 180file, there are some MOC-specific options: 181 182 --enable-cache=[yes|no] 183 184 Specifying 'no' will disable the tags cache support. If your 185 intent is to remove the Berkeley DB dependancy (rather than 186 simply removing the on-disk cache) then you should also either 187 build MOC without RCC support or use a librcc built with BDB 188 disabled. 189 190 --enable-debug=[yes|no|gdb] 191 192 Using 'gdb' will cause MOC to be built with options tailored to 193 use with GDB. (Note that after release 2.5 this option will be 194 split into separate debugging and logging options.) 195 196 --with-oss=[yes|no|DIR] 197 198 Where DIR is the location of the OSS include directory (and 199 defaults to '/usr/lib/oss'). 200 201 --with-vorbis=[yes|no|tremor] 202 203 Using 'tremor' will cause MOC to build against the integer-only 204 implementation of the Vorbis library (libvorbisidec). 205 206You can install MOC into its own source directory tree and run it from there 207so you do not have to install it permanently on your system. If you're just 208wanting to try it out or test some patches, then this is something you may 209wish to do: 210 211 ./configure --prefix="$PWD" --without-timidity 212 make 213 make install 214 bin/mocp -M .moc 215 216-------------------------------------------------------------------------------- 217How Do I Use It? 218-------------------------------------------------------------------------------- 219 220Run program with the 'mocp' command. The usage is simple; if you need help, 221press 'h' and/or read mocp manpage. There is no complicated command line or 222cryptic commands. Using MOC is as easy as using basic functions of Midnight 223Commander. 224 225You can use a configuration file placed in ~/.moc/config, but it's not required. 226See config.example provided with MOC. 227 228-------------------------------------------------------------------------------- 229Using Themes 230-------------------------------------------------------------------------------- 231 232Yes, there are themes, because people wanted them. :) 233 234Themes can change all colors and only colors. An example theme file with a 235exhaustive description is included (themes/example_theme) and is the 236default MOC appearance. 237 238Theme files should be placed in ~/.moc/themes/ or $(datadir)/moc/themes/ 239(e.g., /usr/local/share/moc/themes) directory, and can be selected with 240the Theme configuration options or the -T command line option (see the 241manpage and the example configuration file). 242 243Feel free to share the themes you have created. 244 245-------------------------------------------------------------------------------- 246Defining Keys 247-------------------------------------------------------------------------------- 248 249You can redefine standard keys. See the instructions in the keymap.example 250file. 251 252-------------------------------------------------------------------------------- 253How Do I Report A Problem? 254-------------------------------------------------------------------------------- 255 256Not every release is extensively tested on every system, so the particular 257configuration of software, libraries, versions and hardware on your system 258might expose a problem. 259 260If you find any problems then you should search the MOC Forum for a solution; 261your problem may not be unique. If you do find an existing topic which 262matches your problem but does not offer a solution, or the solution offered 263does not work for you and the topic appears still active, then please add your 264experience to it; it may be that additional information you can provide will 265contain the clue needed to resolve the problem. 266 267If you don't find an answer there and you installed MOC from your Linux 268distribution's repository then you should report it via your distribution's 269usual reporting channels in the first instance. If the problem is ultimately 270identified as actually being in MOC itself, it should then be reported to the 271MOC Maintainer (preferably by the distribution's MOC package maintainer). 272 273If you built MOC from source yourself or you get no resolution from your 274distribution then start a new topic on the MOC Forum for your problem or 275contact the MOC Maintainer. 276 277Before reporting a problem, you should first read this Forum post: 278 279 Linkname: How to Report Bugs Effectively 280 URL: http://moc.daper.net/node/1035 281 282and the essay it references: 283 284 Linkname: How to Report Bugs Effectively 285 URL: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html 286 287There are two things you must do if at all possible: 288 2891. Make sure you are using the current stable MOC release or, even better, 290 can reproduce it on the latest development release or SVN HEAD, and 2912. Make sure you include the version and revision information (which you 292 can obtain by running 'mocp --version'). 293 294If you do not do those two things (and don't offer a good explanation as to 295why you didn't) your problem report is likely to be ignored until such time 296as you do. 297 298-------------------------------------------------------------------------------- 299Hacking 300-------------------------------------------------------------------------------- 301 302Want to modify MOC? You're welcome to do so, and patch contributions are 303also welcome. 304 305MOC is written in C, so you must at least know this language to make simple 306changes. It is multi-threaded program, but there are places where you don't 307need to worry about that (the interface is only a single thread process). It 308uses autoconf, automake and libtool chain to generate configuration/compilation 309stuff, so you must know how to use it, for example, if you need to link to an 310additional library. 311 312The documentation for some parts of the internal API for creating decoder 313plugins (file format support) and sound output drivers can be generated using 314Doxygen (http://www.doxygen.org/). Just run the doxygen command from the MOC 315source directory. 316 317Before you change anything it is a good idea to check for the latest development 318version (check out from the Subversion repository is the best). Your changes 319might conflict with changes already made to the source or your feature might be 320already implemented. See also the TODO file as it is updated regularly and 321contains quite detailed information on future plans. 322 323If you need help, just contact MOC's Maintainer via e-mail. And if you are 324planning anything non-trivial it's a good idea to discuss your intentions 325with the MOC Maintainer once you've clarified your ideas but before spending 326too much time implementing them; it will be more productive if your work fits 327with MOC's future direction. 328 329-------------------------------------------------------------------------------- 330Who Wrote It? Where Can I Send Bug Reports, Questions or Comments? 331-------------------------------------------------------------------------------- 332 333 * Original author is Damian Pietras 334 * Current maintainer is John Fitzgerald 335 * For comments and questions see the official forum: 336 http://moc.daper.net/forum 337 * Need to report a bug? You can reach the maintainer(s) at: 338 <mocmaint@daper.net> 339 340-------------------------------------------------------------------------------- 341