Larry's comments in red, like this.  
In general, this looks very good -- I think you did a great job anticipating the questions users are going to ask.

I'd add one other note for Web server administrators: Be sure that when your server delivers an MPEG Audio Layer 3 file, it has the MIME type audio/mpeg.  This is the default Apache configuration.

Important! This file is primarily intended for support gurus, not end-users, as it contains some instructions involving file copying, renaming, et cetera. Questions 1 - 4 in particular should only be used under supervision. -tb
 
 

0. What should happen when I try to play an MP3 stream?

When you click on an MP3 stream, on a site with MIT course materials, you should see a rectangular dialog with three buttons: Play From Network, Save First, and Cancel. Normally you want Play From Network, which is the default. Selecting either Play From Network or Save First will begin the download and show you the MP3 control panel (if you save first, it'll take a while).

If you don't see the initial dialog, you should read the first four questions below, which contain procedures for getting it to work.

If you do see that dialog, but have problems playing the MP3 or with the control panel, skip to questions 5 and higher, which are information-only.

If you're trying to play non-Athena MP3's, please see question 14.

I think we should be careful about characterizing the source of the MP3 as "Athena" and "non-Athena" -- maybe call it "from an MIT web server" and "from outside of MIT".  The e-reserves server, for example, is really a Libraries project and not part of Athena.

Also, perhaps it's worth stating in the intro that this only pertains to the Athena-supported Netscape browser, and not MSIE or Netscape on PCs, etc.
 
 
 
 

1. When I click on a MP3 link, I am prompted for a location to save the file.
or
2. When I click on an MP3 link, Netscape says it doesn't know what to do with this type and asks me to decide.

Sounds like you're missing a mime type. Netscape doesn't know what to do with an MP3, so it's either assuming you want to save it to a file or asking you what to do with it.

Netscape on Athena has global mime-types files which contain "standard settings" for things like MP3 streams, audio files, et cetera. But if you have local versions of those files, the local ones will be used instead ... and may contain incorrect settings.

So first we have to make sure those local files aren't the problem. We'll get them out of the way by renaming them. Exit Netscape if it's running and then enter the following commands:

cd ~
mv .mime.types .mime.types.local
mv .mailcap .mailcap.local

If you get "cannot access" for either of the latter two commands, it means you didn't have that file to begin with. If you get it for both of the latter two commands, see the next question.

After entering the commands above, launch Netscape and see if the MP3 player behaves properly. When clicking on an MP3 stream, you should see a box with three buttons as described at the top of this page.

If Netscape is still asking to do the wrong thing, see the next question.

If Netscape is now doing the right thing, go to question four to figure out what to do about those local files we renamed.
 
 

3. Okay, I should be using the global mime-types now, but I still don't get the correct prompt for the MP3 player.

Hmm. Netscape should be reading those global files, but we've seen at least one case where it refused to. Let's try copying the globals to your home directory, shall we?

First, exit Netscape if you're running it.

Then enter these commands (exactly as shown, including capitalization):

add infoagents
cd ~
cp /mit/infoagents/share/Netscape/@sys/mailcap .mailcap
cp /mit/infoagents/share/Netscape/@sys/mime.types .mime.types

Now start Netscape, click on an MP3 link, and see if you get the correct dialog as described at the top of the page.

(If it still doesn't work, you've stumped us - report the problem and someone will have to look at it in person.)

Add a "mailto" link here or instructions on running sendbug(?) perhaps? 
 
 

4. It's working now, but I had settings I wanted in my local mime-types files and I need them back.

I'm not going to give precise instructions here, because if you have local mime-types files with settings you want to keep, you already know how to edit them, don't you? (If you didn't add items to your local mime-types file yourself for a known, specific reason, then you should probably stick to the global settings.)

You'll need to restore the .mailcap.local and .mime.types.local files you made to their correct names. Then you'll need to edit them to add the correct lines for the Athena MP3 player.

As usual, Netscape should not be running when you do this!

Your .mailcap file needs the following lines. The strange formatting below is so the lines will scroll instead of wrap, so you can see that each is a single line, with no carriage return. Be careful of spacing and punctuation. Also, if the file has an audio/* handler in it, these lines should be inserted before that line in the file.

Your .mime.types file needs the following line, which is much simpler.

audio/mpeg mp3

Once these lines have been added, Netscape should play MP3s correctly from your local settings.
 
 

5. The stream seems to be playing - the timer digits are changing - but I don't hear anything.

Well, if you're on a cluster machine, the sound may be disabled (and you should be listening to this with headphones).

Press the "Audio Controls" button on the MP3 control panel. The system's audio control app will appear.

(It may fall "behind" the Netscape window when it does, especially if there is a color or other X error, which happens on Suns a lot. Minimize windows and you'll see it lurking back there.)

Turn down the volume so you don't deafen yourself, and then click the Speaker button (for a quick test only, unless you're in private) or the Headphone button. If there's a Mute option, make sure that's off.

See the man pages for audiocontrol (on an Athena Sun) or audiopanel (on an Athena SGI) for more information, may want to add links to:
 http://web.mit.edu/answers/workstations/ws_headphones.html 
 http://web.mit.edu/answers/sgi/sgi.disks/sgi_cdrom_audioctrl.html 
 
 

6. Oops! I downloaded the MP3 file instead of streaming it. What's the difference, and where did that huge file go? Do I need to delete it?

No. It's in a temporary area and should vanish with no anguish, unless you're putting Netscape's cache/temporary files in the wrong place. When you download the file (Save First), you get the whole thing before you can play it; when you stream it (Play From Network), you play it as it loads. Either way, it vanishes once it's played.
 
 

7. I hit the Stop or Quit button and the playback stopped, but the control panel stayed around for a while.

It's normal for the panel to linger for several seconds. (In fact, it's deliberate, to give you time to read the "Done" message.) If it's longer than a minute, just close the control panel yourself; it's probably gotten confused.

Maybe at this point a  quick guide to the control GUI is in order.  I guess it would be ideal if I add it to the GUI itself under "Help", but it's really pretty self-explanatory; the audio control UIs don't have any useful help, either..
So, here's my first cut at a guide:

The  Athena MPEG-player control panel has the following components:
1. "Playing:" message, shows the song title if that is available.  Due to the way MP3 files are typically delivered by Web servers, this will often say only "Streaming input" since no identification is available.
2. Below that is the "Elapsed time" counter, showing how many minutes and seconds of audio have actually been played.
3. The next line is a row of control buttons, which are explained below. 
4. The "Status:" message shows you what the player is doing.  It is typically either "PLaying", meaning audio material is playing; "Paused", meaning you have clikced the Pause control to momentarily stop the playback, and "Done", meaning there is no more matierlal to play.  When it says "Done" the, only useful thing you can do is quit; normally the GUI exits automatically about 5 seconds after the status changes to Done, anyway.
5. The window below the status line is for diagnostic messages. If there is any trouble with the MP3 player, the diagnostics will appear here, so you can transcribe them in a bug report.

MPEG Player GUI Controls:
1. Play/Pause button: clicking this toggles the state between playing and paused, just like the familiar "Pause" control on audio tape and CD playback devices.  Note that since the workstation's audio hardware buffers some data head of what it is playing, "Pause" may not take effect for a second or two while the buffer runs out.
2. Stop: Stops playback and finishes the stream.  Since this player is constructed to play a stream of data over the network, there is no way to "rewind" it and start again, so the Stop control aborts and finishes the playback.  The GUI will usually disappear automatically about 5 seconds after stopping.
3. Quit: This is the same as "Stop" except it also exits the GUI immediately.
4. Stay: Toggles the "stay" state of the window.  Normally, "stay" is off and the window disappears automatically after playback finishes.  The only reason you should want to keep it around is if there are diagnostic messages you need to use for troubleshooting (or to transcribe for a bug report).  If "stay" is on, the window stays open until you explicitly click Quit (or press ^C or ^Q over the window).
5. Audio Controls: Clicking here brings up your workstation's audio control panel.  If there is already an audio panel open, don't use this button since it always creates a new one!  Use your window manager to bring the existing panel to the foreground if you have one.
 

8. I hit the Stop or Quit button, the control panel's gone now, but Netscape itself is still loading the file.

This happens a lot. Netscape's ignoring the "we're done now" messages from the MP3 handler. It's safe to press Netscape's Stop button.

Yup, I'd go so far as to say, this happens every time.  It's a bug in Netscrape, work around it by hitting the traffic light.
 
 

9. What's the point of the "Stay" checkbox?

Diagnostic only. If you happen to get an error, the stream stops; unfortunately this means the control panel goes away. The checkbox keeps it around long enough for you to read the error (so you can tell us about it). Don't use it unless you're having problems.
 
 

10. I pressed Quit and an error appeared: "EOF in pipe to mpg123, maybe it died?"

At the moment this is apparently normal. Stop and Quit effectively do the same thing, but Stop is the recommended way to exit. (Actually, letting the stream play itself out is the recommended way to exit. See question 15.)
 
 

11. Pause doesn't pause immediately.

No, it can't. The player has to play whatever is in the buffer before it can pause.
 
 

12. Why isn't there a Rewind button?

Streaming media doesn't rewind. Play it again, Sam.
 
 

13. No matter what MP3 I play, the control panel never shows any identifying information, only "Streaming input" at the top.

This is a problem with Apache's ability to handle streaming media. The ID information is at the end of the MP3 stream, not the beginning, and therefore we can't get at it until after we've already played it! So, for now, all MP3s are generic "streaming input."

This isn't peculiar to Apache, actually, it's an inherent problem with any Web server sending an MP3 file as a stream -- MP3's dont even necessarily _have_ metadata, and if they do it's at the end.  What other sites do is use a different protocol entirely to deliver an MP3 to a special external player..

Other MP3 sites have stumbled over this very same problem and have a tendency to "wrap" their MP3s - sending a link to the stream rather than the stream itself - in order to first send the ID information. Which brings us to our next question ....
 
 

14. I was trying to play a non-Athena MP3 and all I got was the "End of input" message, nothing else happened.

You were probably actually getting an MP3 URL - the location of a stream, not the stream itself. Apparently most of the big MP3 sites "wrap" their streams this way (see the question above), and our MP3 handler doesn't know how to deal with these URLs. Yet. So you can't play them. You can only play direct MP3 streams.

Please bear in mind that an MP3 player is in the infoagents locker only for the purpose of playing official course materials, and therefore all MP3 playback outside MIT is "non-supported" anyway.

Maybe the way to put this is "playback of MP3s originating from outside of MIT is not supported."

15. I tried to play a stream and got an error from Netscape about 'stdin'. Now every time (or almost every time) I play a stream, I get this error.

This is a bug in Netscape. Downloading the file (Save File) instead of playing it from the network seems to cure it, but that's a drastic solution. Exiting Netscape and restarting it should also work. To make this happen less often, don't Stop streams in the middle if you can avoid it.
Well, I wouldn't say "drastic" :-) but maybe just "downloading the file once seems to cure it, but so does exiting Netscape and launching a new one."
 

16. What systems does the Athena MP3 player run on?

Suns and SGIs have been supported and tested. A player has been installed for Linux systems but has not, as of this writing, been tested.

There's an equally untested i386-netbsd version too, actually!
 
 

7 Feb 2000 - Todd Belton