MP3 STATION Although I have tested this software on all the computers I could get my hands on I really need some feedback. So if you are reading here you are probably trying to use this software, please tell me any difficulty you encounter along with any problems the software suffers. Index 1.0 LICENCE TERMS 2.0 DESCRIPTION AND FEATURES 3.0 REQUIREMENTS 4.0 INSTALLATION 5.0 USING THE SOFTWARE 6.0 PLAYLISTS 7.0 UTILITY 1.0 LICENCE TERMS MP3 STATION A LIRC-aware, plain text, Linux/Unix toolset for managing mp3 playback with as little user interaction as possible. It was built to handle mp3 playback in a car. Copyright (C) 2003 David Rao This file is part of MP3 STATION. MP3 STATION is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. MP3 STATION is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with MP3 STATION; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA If you have any doubts about what is written above please read the important information in the COPYING file. You should find this file in the project root. In this project I have used code/ideas from other GPL projects. Many thanks to: Russell Marks for the mixer stuff I used from rexima (ver. 1.2), Michael Hipp for the helping to efficiently reduce mpg123 framestatus printing. 2.0 DESCRIPTION AND FEATURES A plain text Linux/Unix toolset for managing mp3 playback in a car with as little user interaction as possible. N.B. It was not made to be better or fancier than any other mp3 player or front-end, but instead it attempts to implement some features that are not commonly found without the need of GUI. This means that you can use your old P75 portable with 8Mb ram to do the job ! MP3 STATION is composed of 2 parts: a server (cm3s) and a client The server is responsible for: a) starting mpg123 in remote control mode and talking to it through 2 pipes (a command pipe from which mpg123 reads commands and a status pipe on which mpg123 writes status info and where clients can write commands that cm3s server part will interpret) b) telling mpg123 what to do and responding adequately when it finishes playing a track c) accept commands from an arbitrary client that writes to status pipe optionally client can get some additional information from cm3s via ipc messages The reason why pipes were chosen instead of sockets is because even a shell script can very easyly write to a pipe, it is therefor possible to write your own client with a simple bash script. The client is a simples software that is responsible for track management and playlist loading. Anyone can rewrite a better client if they like as long as they use the commands that cm3s understands. (look at STATUS and cm3s.proto) The ipc messages can be safely ignored because they are automatically removed from cm3s if there is no client reading them. N.B. The server part has good functionality even without the client part, and can actually be started without ant client present. Actually the client I wrote will not be of any use until the server is started because it will hang until something opens the stat pipe for reading. The main features of this project are: 1) Restart of last playlist at last played track even if list was randomized if cm3s is started with no options. 2) Configurable behavior to start last track from last played frame. 3) Configurable behavior to start from last track or the one after. 4) Transparent loading of directories as if they are regular playlists containing all the files that have mp3 or MP3 extension as long as they are not in a subdirectory named "no_autoplay" case insensitive. 5) Transparent recompilation of playlists generated from directories when directory content changes. 6) Optionally start plaback at a given track (0 is first track). 7) Optionally repeat playlist until new one is loaded (this is the actual default behavior). 8) Optionally reverse the order of a playlist. 9) Keep a repository of all the playlists that have been played (and relative last played track) so that when you reload the playlist by default you start alt the last played track. 10)A simple ncurses client for communicating with cm3s that includes a mixer (if your platform support it, look at the output of configure to see if you are going to get mixer capabilities). 11)A simple integrated parallel client (for the moment it will only work with linux). 12)All programs run under a non privileged user (set during configure process). 13)Load defaults from a ini like configuration file. The search path is: ~/.cm3s.ini (user home directory) /etc/cm3s.ini 14)Manage cm3s with an InfraRed Remote control (see the README.remote) 3.0 REQUIREMENTS In order to compile and use the software you need: A) autoconf (only if you did not get the configure script) B) make (I use gnu make all the time) C) c compiler (project was developed with gcc and optimizer in makefile is set to do best with gcc if you are not using gcc you might haveto change manually something in Makefile) D) ncurses or curses E) mpg123 or mpg321. mpg321 is a free drop-in replacement of mpg123, it may not be as good as the original software but it has some interesting features, on the other hand mpg123 is very light and fast and also producess less power supply disturbance and minimizes some other problems. F) audio device supported by mpg321 (since stdout will be used by the remote control feature) G) I use some features of gnu getopt that may not be present on other getopt implementations (sparc does not even seem to have getopt.h at all) but I have made some effort to work this around H) For some timing functions I use ither nanosleep or RTC is is not essential but it would be good to have at least one avalible. I) If you intend to use an InfraRed remote control you may also need Lirc 4.0 INSTALLATION 4.1 Quick Installation guide This is a general installation procedure tha will work perfectl on linux but may have some trouble with other platfoems. You may take a look at README.platform for specifit platform installation issues. For the moment installation is very simple .... # ./configure [options] The configure script should do everything for you correctly but you may like to check manually Makefile. # ./configure --help should give you all options you need. Before you start building the binaries you might like to take a look at the Makefile to see if everything suits your system. Values that are user changeable have suitable comments, all the rest should be correctly set by the configure script. # make doinst N.B. the actual installation requires you to be root. If the the final user that will own the package already exists you could try installing from that user. This is dew to the way I set the process id to the owner of the package (set user on execution) The autoconf, configure and make should work under any user. make doinst will: 1) remove any stale executable and object files (equivalent to make clean) 2) compile everything and strip programs (equivalent to make all) 3) put them in place for you (equivalent to make install) If you like you can take a look at what is being compiled before installing. Try: # ./configure [options] # make clean # make # make install make clean will remove all stale binaries and object files from source tree. NB you do not need to do this if you use make doinst because it does it for you. make distclean will also remove the configure script, if you do this you will need to run autoconf. If you intend to use InfraRed remote control you will also need to install lirc. See README.remote for further details. 4.2 More Installation Details Most developement of this project has been done with Linux on x86 platform and gcc 3.2, so if this is your case chances are that the configure script has done for you all that needs to be done so you probably do not need to read this. If on the other hand you fall into any of these categories: your machine is not x86 based (or you have some strange cpu like winchip ...), you are not using linux, you do not have gcc compiler (or you hane a version prior to 3.1 of gcc); chances are that configure is not doing all that could be done or even worst it is not doing enough to get you going. For eg if you have a system like : linux, gcc 2.95, via C3 cpu configure might fail to detect properly your cpu (it could detect i686) this will let you build binaries ok ... but when you try to run them you are going to get an illegal instruction error. In this case all you can do is set manually the correct parameter in the Makefile see README.viac3 for this issue. 4.3 CPU Detection Configure uses a set ov scripts for detecting your cpu depending on your machine architecture and operating syste. These scripts, amongs others are in the scripts directory. In particula the ones for detecting cpu have the following nomenclature: get_cpu. where a is a single letter that stands for machine architecture in short i for Intel d for Digital alpha architecture s for sun If you need to add more architectures you will also haveto edit manually configure.ac and run automake OS statds for the full string returned by uname -s as operating system name. If you need to add more os you may do so without modifying anithing else. These scripts all display at prompt the detected cpu. If the cpu is undetected and there is a compatibe ancestor they should return that ancestor (like i386 for the x86 famyly), if there is no compatible ancestor they return nothing. You can run them safely to see what they do. If you have a processor that you know to have tuning options that is not detected by the script you can modify the script in order to detect it correcly. (I know for sure that k6, k7 thunderbird, duron, celeron are missing and will therefor be detected as i386, if you have one of these please tell me the /proc/cpuinfo entry for them) 4.4 Preinstallation Script (used by make install) Another set of scripts used during the installation process are the preinstall. These are run by the make install (or doinst) By default make install first looks for preinstall. , if it does not find one it will try to run preinstall.sh. What this script should do is to add a group and user as specifird in the arguments. For eg preinstall.Linux pippo users should create a group users and create a user pippo whose group is users on a linux system. I have found that the way adduser,useradd, groupadd .... etc work are very platform dependent, so if there is not one for your system and the default preinstall.sh does not do the job for you, feel free to write one that works (you will not haveto change any other script if you use the preinstall. nomenclature) 5.0 USING THE SOFTWARE cm3s -h will give you all the help you need (I hope). Look at the example of the .cm3s.ini file in the Doc directory. By default cm3s has verbosity level =1 which produces some interesting information, if you set verbosity to anything >1 you will get a lot of information that is only useful if you need to debug. Even if you start cm3s with verbosity =0 you could get some output. If you want to discard all output you should start with something like # cm3s >/dev/null Depending on your platform and on the player that is being used cm3s may not be able to start at boot time (by rc ) so you may haveto use cm3s_boot (witch does not drop root privileges and does not set owner on execution). These problems should now be solved if not check that perms on /dev/dsp look loke: crw-rw-rw- 1 root sys 14, 3 Jul 18 1994 /dev/dsp Personally I have a line in my rc.local that tests the existence of bothe cm3s executable and mp3 directory tree, if thye are bothe present then I start the software. for egample: [ -x /usr/local/bin/cm3s -a -d /mp3 ] && /usr/local/bin/cm3s /mp3 It is also handy to use rexima to set your audio levels to something sensable ! Client is a totally iterative user interface. (you should start client after having started cm3s, if not it will just hang untill you do so) While running client you can try pressing h for help on the running mode, if I have coded any help you will get something in the bottom part of the window. In any case client has 3 modes for now 1)playback managing mode 2)playlist loading mode 3)mixer mode in mode 1 e,esc exits from client leaving cm3s to continue playback b toggle playlist order (forward or reverse) i show id3 tag of current track p toggle pause playback q quits client and cm3s r randomize current playlist R toggle randome mode b toggle playlist order (forward or backwards) l go to playlist loading mode m go to the mixer menu UParrow replay previous track DOWNarrow skip to next track LEFTarrow restart playing current track RIGHTarrow skip to next track PG_UP go back as many tracks as can fit on the upper window PG_DOWN skip forward as many tracks as can fit on the upper window in mode 2 e exits from load mode and go back to playback managing mode UParrow scroll up DOWNarrow scroll down LEFTarrow move one directory up RIGHTarrow descend in to directory (does nothing on files) ENTER load selected file (or directory) in mode 3 there is very little help because it works just like rexima. Actuall what you see is a modified and crippled version of rexima embedded in the client. 5.1 CONFIGURING THE SOFTWARE Client is a totally interactive software so it does not need any configuration. Cm3s itself was made to be nearly totaly indipendent and therefor can be configured to behave in different ways. By default cm3s first looks for a configuration file in user's home directory (~/.cm3s.ini) if that file does not exist it the looks for a system wide one in /etc/cm3s.ini . Most things that can be instructed via command line options can also be configured in cm3s.ini . Also keep in mind that command line options have a preceeding importance over any configured options. For the moment cm3s understands the following syntax: paremeter = value This is a list of valid parameters and what the expected value should be: mp3_base_directory = absolute (abs.) path to a directory default_playlist = abs. path to a real playlyst or a directory temporary_directory = abs. path to directory where temporary files will be written log_file = abs. path to file where you want logging to be written run_as_daemon = true/false (anything different will be regarded as false) play_in_random_mode = true/false reverse_playlist_order = true/false repeat_playlist = true/false save_frame = true/false #start next overrides save_frame start_next = true/false audio_buffer = size in kilobytes master_vol = master vlolume in mono/stereo in abslolute/offset notation pcm_vol = audio device mixer level in mono/stereo in abslolute/offset notation spc_port = io of port on which spc is atached (0x378 for lpt1) Volume settings can be ither mono (if your eqipment is stereo this means bothe chanels will be set to the same level) master_vol = 50 which is the same as master_vol = 50,50 if your hardware is stereo On the other hand the volume can me set relatively to present volume, (in this case the setting must be mono) master_vol = +1 in which case the vomule will be increased of 1% from present setting. The names of the parameters should be self explanatory, if not you can look at the cm3s.ini example. If that is still not enough you can ask me ;-) . 6.0 PLAYLISTS For cm3s playlists can be either actual text files containing absolute path to mp3 files (one line per file) and comments or directories. A playlist should contain at least one playable file, and can be as big as the biggest memory block that malloc can allocate (difficult to work out exactly how big that is on a running system). A comment can only begin at the start of a line and end at the end of the line A comment is initiated by the character "#" and will be terminated by the character new line (\n for printf, ^M, 13 or 0x0d as acii value). If the first line of a playlist is a comment it is a special reserved comment. It contains the random seed of the list (0 means none) and where the playlist was originated from. This is an example of a playlist witch has not been randomized generated from /mnt/usb_hd/mp3/artist #0 /mnt/usb_hd/mp3/artist /mnt/usb_hd/mp3/artist/track1.mp3 /mnt/usb_hd/mp3/artist/track2.mp3 /mnt/usb_hd/mp3/artist/track3.mp3 /mnt/usb_hd/mp3/artist/track4.mp3 /mnt/usb_hd/mp3/artist/track5.mp3 /mnt/usb_hd/mp3/artist/track6.mp3 /mnt/usb_hd/mp3/artist/track7.mp3 /mnt/usb_hd/mp3/artist/track8.mp3 /mnt/usb_hd/mp3/artist/track9.mp3 /mnt/usb_hd/mp3/artist/track10.mp3 /mnt/usb_hd/mp3/artist/track11.mp3 Playlists can contain relative paths in very restrictive cases (so be warned) the paths may only be relative to where cm3s was started, so unless you intend to start cm3s always from the same point you should avoid using relative paths in your playlists. In future I'll probably add a feature that will allow paths to be relative to where the playlist is located. cm3s actually creates a playlist when it loads transparently a directory. It does basically the same thing if you load a single file through a client, it will create a playlist containing a single track. Keep in mind that loading a single mp3 file at cm3s start wight not work, cm3s was written for handling playlists and not for playing single files; there are other programs that can play a single mp3 file more efficiently. 7.0 UTILITY Here are some Usefull stuff I'm currently using on my MP3 Station. Rexima: actually the text console client has a crippled and modified version of rexima embedded in it. Note that acpi is now stable in kernel 2.4 whch makes a very good and practical alternative to spo, sled and cppb. Sled: this is very handy, you can shutdown your MP3 Station at a touch of a button without the need of a keyboard or monitot. I have a modified version of sled, that I call SPO (Serial Power Off) that makes better use of the two LEDs and has more reliable button logic. You can download it amongst the other misc downloads at: https://sourceforge.net/project/showfiles.php?group_id=76280 and you can see some pictures of the finished job on the MP3 STATION project homepage http://cm3s.sourceforge.net Cppb: this is the next step to spo (and sled). It's targhet is to have a unique button to turn on and shutdown your car pc gust like the button on your car stereo. It is avalible, just like spo, amongst the misc downloads at: https://sourceforge.net/project/showfiles.php?group_id=76280 . Soon I'll also place some screenhots of this project too.