FAQ.- Last updated July 17th 2001

Check for the latest version online at : http://media.tangent.org/faq.html


  1. So what is mod_mp3?

  2. Where do I get it from?

  3. What sort of license does it have?

  4. How can I make suggestions for it?

  5. How can I report a bug?

  6. How do I install it?

  7. How do I use it?

  8. What are the directives?

  9. XMMS is just sitting here doing nothing.

  10. What protocols are being supported?

  11. Can I write my own interface to it?

  12. What are the different flags I can give op ?

  13. Will this work with Apple's OSX?

  14. So what is up with Apple's Itunes?

  15. So what are streams?

  16. Will this work with SSL?

  17. My build is dieing with apxs=255?

  18. So what about Vorbis support?

  19. I am getting a sync error from the client, what does that mean?

  20. Apache is loading very slowly.

  21. What is this RSS thing, and where can I find a perl/php class to handle it.

  22. What does the information in the logs mean ?

  23. Do I have to use a virtual host for this?

  24. What is the future?

So what is mod_mp3?

Appendix A. MP3 httpd.conf Examples

This turns apache into your basic RIAA hating, but every college student loving mp3 streaming server. It can play from a list of files, either straight through or randomly. It can also be used to cache mp3's into memory and have the server operate entirely from memory. Enjoy, groove, mp3s not included.


Where do I get it from?

You can get it from either here via the web or here via ftp.

What sort of license does it have?

You are pretty much free to use it as you please. Check out the License file with the distribution for more details. (Its very BSD like)

How can I make suggestions for it?

Send email to brian@tangent.org.


How can I report a bug?

Enter your bug here(BROKE!). You are better off going to http://media.tangent.org/submit.pl. Just submit a bug. This works best right now.


How do I install it?

Read the INSTALL file that comes along with the module.


How do I use it?

Listen 8000
<VirtualHost www.example.com:8000>
ServerName www.exampe.com
MP3Engine On
MP3CastName "Brian's Tunes"
MP3Genre "Much, nutty"
MP3 /export/mp3
MP3 /tmp/madonna.mp3
MP3 /tmp/cows.mp3
MP3Random On
#Increase this if your connections are timing out
Timeout 1200
ErrorLog /usr/local/apache/logs/music_error_log
</VirtualHost>
Make sure you also enable Listen for port 80 if you are also running a regular webserver. Also, keep in mind that while I set mine up with VirtualHosts, you could just as easily use Directory, or Location directives. You could run as many streams out of a single host as you want.


So what are the directives?

  • MP3 - Either a filename or directory filled with mp3s (it recurses into subdirectories)
  • MP3Engine - Turn on the streaming mp3 server.
  • MP3CastName - Name of your server
  • MP3Genre - Genre that will be sent to the client
  • MP3Random - Tells mod_mp3 to randomly dish out music
  • MP3Stream - I am not useable yet.
  • MP3Loop - Causes requests to loop thrugh the music requested indefinetly.
  • MP3LimitPlayConnections - Limit the number of play requests possible.
  • MP3ReloadRequest - When enabled this causes mod_mp3 to reload all of playlists/files/directories for each request.
  • MP3Playlist - This takes a file filled with mp3 filenames and loads the filename into mod_cgi list (most MP3 player's playlists are in this format)
  • MP3Cache - Tells mod_mp3 to cache all of the files to memory instead of getting them at request time from disk. This can take up a lot of memory but is quite a bit faster if you are expecting a large load. This directive must come first if used.
  • MP3DefaultOperation - You can use this to send a different default output than just straight MP3. The different options are: rss, m3u, m3u2, pls, pls2, list, select. It will also take a second option with can be a regular expression to match browsers with.
  • MP3Allow - When turned on, only files that are matched with a regular expression given with this directive will load. So "MP3Allow *.mp3" would only load file that ended with .mp3.
  • MP3Deny - Same as MP3Allow but it denies files by filenames.


    • XMMS is just sitting here doing nothing.

    Look at the example, you probably don't have your virtualhost defined correctly.


    What protocols are being supported?

    Whatever I can get my hands on. Right now that means just Icecast and Shoutcast. Shout is full supported and ice is coming along nicely. We can also do the headers for Ogg files.


    Can I write an interface for it?

    Yes. The idea is to let other people write the interface for mod_mp3. To enable this a couple of hooks have been added. You can find a list of the contents to a server by doing a http://example.com:8000/?op=rss. If you want, you can this grab songs based on the ID of the song (which is the filename MD5'ed). An examle is: http://avenger.tangent.org:8080/?op=play&song=475c47c405940fde1737e8bc85f65760&song=7777e58678fcc5fcc96d449b4951ebd1

    This was just a start, there is a mailing list for the interface, as I get an idea about what people want, more will be added


    What are the different flags I can give op ?

  • ?op=select : lets you search, but also lists ALL the songs, on the bottom of the list, you can selct individual songs, and play them.. (make your own playlist, search for songs, etc).
  • ?op=rdf : listing in RDF format Version 1.0
  • ?op=rss : listing in RSS format Version 0.91
  • ?op=m3u : Makes a playlist in m3u format, and sends it to you, if you have the proper settings with mime-types this would/could load up winamp for you with the entire collectionas a playlist.
  • ?op=m3u2 : different format of the playlist.
  • ?op=pls : Winamp playlist
  • ?op=pls2 : Another playlist format
  • ?op=list: List in RSS version 0.91
  • ?op=play : Plays songs randomly.
  • ?op=reload : Tells the server to reload all of its playlists.
  • ?op=index : Shows the index page, if you have one set in your document root for this host. (NOTE, index can be replaced by anything that is not mentioned above, i.e it could be ?op=blowupafghasnistan).

    • Will this work with Apple's OSX?

    Several people have written in and said that it will. If I get a binary I will put it up for people to download and use. Which has been happening. Keep in mind though that until someone sends me a copy of OSX (I own a Mac) I won't be actively testing it.


    So what is up with Apple's Itunes?

    In theory it supports the shout protocol, but in reality it seems to ignore file names found in the stream.


    So what are streams?

    A cute idea. Look through the mail archives for the mailing lists for more info. This is not completly supported yet.


    Will this work with SSL?

    According to people on the mailing list, it will work just fine. Trick is you need a player that can do SSL. You can either do this by tunneling or I am told by using IE with some native player.


    My build is dieing with apxs=255?

    You are not going to like the answer to this. Basically at some point you have either installed multiple copies of Apache or somehow munged your current copy. Do this: "apxs -g -n example; cd example; make". Did that work? If it didn't your copy of Apache is munged.


    So what about Vorbis support?

    Go look at this articles.


    I am getting a sync error from the client, what does that mean?

    Check that you are not accidently loading any files that may not be mp3's. That is the normal culprit **July 18th 2001** As of this writing, mod_mp3 will load all files in your directory right now, so if you have .LOGs or .mpeg etc in your directory it will load it, and dish them to your player, when you get to that error, just hit next, or press stop and then play.


    Apache is loading very slowly.

    You have some crazy sized music collection I take it? And you are just point Apache at the directory and waiting for it to start right? Well, it will, but it is going to take a while. I would suggest using a playlist instead. You can generate one with "find /export/mp3 | grep -i "\.mp3" > /tmp/playlist"


    What is this RSS thing, and where can I find a perl/php class to handle it?

    You can find out information on RSS at . There is a perl class on CPAN called XML::RSS that will parse RSS. For PHP look at this http://nwow.org/rssparse-0.4.tar.gz


    What does all the info in the logs mean ?

    [16/Jul/2001:22:36:19 -0400] fc62362bf4cd1a8602bbf170409b8d04 7652fcbd1077f4ffa58ba36d10c8d9d4 Pharoahs
    This is what you see in your MP3Log file,
  • the stuff in the [] is pretty self explanatory.
  • The second string is the transaction id of the player
  • The third string is the MD5 of the file being streamed for that player
  • The fourth string is the ID3 Name or filename if there is no id3 tag for that file.

    Do I have to use a virtual host for this?

    No, not at all. You can put directives in the root of your httpd.conf or even put them in a directory (you could also technically put them in a .htaccess file, but that would be pretty horrible for performance).


    So what is the future?

    World domination? Complete online server that would make any radio station drool. Support for more than just mp3. You name it, I am open to ideas. The big thing for me is that I want to give people a voice. Just like apache opened up the web for anyone to publish thoughts and ideas that they have, I want this module to extend that same philosphy to the online airwaves. The FCC is never going to make community radio a reality, hopefully this will give people an alternative.

    Ok, now that that soap box bit is over, the idea is to create a server which can be controlled by other applications. Let people write good interfaces and not worry about the actual protocols and methods of delivery.

    Appendix A. MP3 httpd.conf Examples

    Simple

    Listen 8000
    <VirtualHost avenger.tangent.org:8000>
    ServerName avenger.tangent.org
    MP3Engine On
    MP3CastName "Brian's Tunes"
    MP3Genre "Much, nutty"
    MP3 /export/mp3
    MP3DefaultOperation select
    Timeout 1200
    ErrorLog /usr/local/apache/logs/music_error_log
    </VirtualHost>

    Ogg

    Listen 8001
    <VirtualHost avenger.tangent.org:8001>
    ServerName avenger.tangent.org
    MP3Engine On
    MP3CastName "Brian's Tunes"
    MP3Genre "Much, nutty"
    MP3 /export/ogg
    MP3MimeType audio/x-ogg
    ErrorLog /usr/local/apache/logs/music_error_log
    Timeout 1200
    </VirtualHost>

    Advanced

    # The mod_mp3 virtual host.
    # Do not just make-up any name here for the ServerName directive.
    # Use real, valid, host names from the DNS.
    # Increase the timeout if you have large length mpeg files.
    # Timeout of zero means no timeout.
    <VirtualHost 123.456.789.101>
    ServerName music.example.com
    ServerAdmin webmaster@example.com
    ErrorLog /var/log/httpd-error.log
    SetEnvIfNoCase User-Agent mozilla is_a_browser

    <IfDefine !is_a_browser>
    Timeout 0
    </IfDefine>

    <IfDefine is_a_browser>
    DocumentRoot /usr/home/webmaster/mp3_interface_html
    </IfDefine>

    # Toggle the MP3 module On/Off.
    MP3Engine On

    # Control the number of connections to mod_mp3.
    # Upload speed divided by bitrate is the rule of thumb.
    # example with DSL 768/768 line, and mp3 w/128 bitrate:
    # floor((768000 - 10%) / 128000) = 5
    # Remember that about 5% to 15% of your bandwidth is consumed by overhead.
    # and since 90% of a stream is not so good, we round-down, and get five.
    # Your mileage may vary.
    MP3LimitPlayConnections 2

    # Name this radio station.
    MP3CastName "mod_mp3 radio"

    # Give your Station a format type (aka Classical, Electronic, rock'n'roll, etc.).
    MP3Genre "various"

    # Multiple MP3 directives are allowed.
    # Rule of thumb dictates you not use the MP3 direcctive when using a MP3Playlist.
    MP3 "/data/mp3z"

    # This can increase the performance on large collections, but not dramatically.
    # It is a good idea to avoid using this with the MP3 directive,
    # unless you know what your doing.
    #MP3Playlist /data/playlist.m3u

    # Toggle the stream mode On/Off
    # This doens't work at the moment.
    # When enabled, you should comment-out any MP3, or MP3Playlist directives.
    #MP3Stream On

    # Randomize (aka shuffle) the mod_mp3 internal playlist for playback.
    #MP3Random On

    # The Default Operation is referring to the url string passed to mod_mp3.
    # The default is to simply play mp3s from the internal list.
    # Available paramaters are: rss, m3u, m3u2, pls, pls2, list, and select.
    # The following example uses the select option only if a browser connects.
    # You dont' really need this if you plan to write an interface. See the DocumentRoot above.

    <IfDefine is_a_browser>
    MP3DefaultOperation select
    </IfDefine>
    </VirtualHost>
    </IfModule>