Holger's Java API

## com.antelmann.sound
Class MP3Player

    java.lang.Object
      com.antelmann.sound.SoundPlayer
          com.antelmann.sound.MP3Player

    @ThirdParty(value="javazoom.jl")
    public class MP3Player

extends SoundPlayer

MP3Player extends SoundPlayer's capabilities to play MP3 media.
Note on 3rd party dependancy:
The MP3 capabilities in this class use the third-party class javazoom.jl.player.Player from the following library: JavaLayer from JavaZOOM (version tested here: 0.2). That class library - just like this one - is available under the GNU GPL. Go to http://www.javazoom.net/ to download the library. If the media in use is MP3, certain functionality is restricted as these functions are not easily exposed by JavaLayer. The following method will act as if no current sound was present if the current sound source is MP3:

- `setMicrosecondPosition(long microseconds)`

The method `getMicrosecondLength()` will only return a useful value, if the current sound source is a mp3 file, where the length property can be read from the file header. Finally, the JavaZOOM library does not throw an exception if the given sound source is not valid MP3 audio data when calling `load()` or `play()`. Therefore - given an invalid source of data that may in fact not be audio data at all, this player will assume that it is MP3 audio data - even if it is not. The only way this surfaces is that the `play()` method simply signals 'end of song' immediately.
To determine whether these restricitions apply to the current sound source, MP3Player contains an additional method to check whether the active sound object is in fact interpreted as MP3 (which as mentioned above doesn't mean that it is valid MP3 data).

Author:
  Holger Antelmann
See Also:
  `SoundPlayer`

Nested Class Summary

Nested classes/interfaces inherited from class com.antelmann.sound.SoundPlayer
`SoundPlayer.Listener`

Field Summary

Fields inherited from class com.antelmann.sound.SoundPlayer
`audioStream, clip, currentSoundSource, sequence, sequencer`

Constructor Summary
`MP3Player()`
`MP3Player(File file)`
`MP3Player(InputStream stream)`
`MP3Player(URL url)`

Method Summary
`void` `close()` closes the current sound.
`protected void` `finalize()`
`long` `getMicrosecondLength()` if no active sound object is present, -1 is returned; note that this doesn't return milliseconds but microseconds; also, for sampled audio data, the length may be not accurate.
`long` `getMicrosecondPosition()` returns the current microsecond position of the active sound object; returns -1 if no active sound object present
`String` `getSongInfo()` returns the info for the current sound as a String to be displayed
`String` `getSoundTypeDescription()`
`boolean` `isMP3()`
`boolean` `isPlaying()`
`protected void` `load(Object sound)` handles File and URL objects
`void` `play()` if `play()` is called on a sound that has been played through, you may have to call `stop()` before `play()` will have the effect of replaying the sound
`void` `stop()` use play() to resume playing after stop() was called

Methods inherited from class com.antelmann.sound.SoundPlayer
`addListener, beep, getCurrentSoundSource, load, load, load, load, notifyListeners, play, playAndWait, setMicrosecondPosition`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### MP3Player

    public MP3Player()
              throws SoundException

Throws:
  `SoundException`

### MP3Player

    public MP3Player(File file)
              throws SoundException

Throws:
  `SoundException`

### MP3Player

    public MP3Player(URL url)
              throws SoundException

Throws:
  `SoundException`

### MP3Player

    public MP3Player(InputStream stream)
              throws SoundException

Throws:
  `SoundException`

Method Detail

### load

    protected void load(Object sound)
                 throws SoundException

  Description copied from class: `SoundPlayer`
  handles File and URL objects

  Overrides:
    `load` in class `SoundPlayer`
  Throws:
    `SoundException`

### getSoundTypeDescription

    public String getSoundTypeDescription()

  Overrides:
    `getSoundTypeDescription` in class `SoundPlayer`

### getSongInfo

    public String getSongInfo()

  Description copied from class: `SoundPlayer`
  returns the info for the current sound as a String to be displayed

  Overrides:
    `getSongInfo` in class `SoundPlayer`

### getMicrosecondLength

    public long getMicrosecondLength()

  Description copied from class: `SoundPlayer`
  if no active sound object is present, -1 is returned; note that this doesn't return milliseconds but microseconds; also, for sampled audio data, the length may be not accurate.

  Overrides:
    `getMicrosecondLength` in class `SoundPlayer`
  See Also:
    `SoundPlayer.getMicrosecondPosition()`, `SoundPlayer.setMicrosecondPosition(long)`

### getMicrosecondPosition

    public long getMicrosecondPosition()

  Description copied from class: `SoundPlayer`
  returns the current microsecond position of the active sound object; returns -1 if no active sound object present

  Overrides:
    `getMicrosecondPosition` in class `SoundPlayer`
  See Also:
    `SoundPlayer.setMicrosecondPosition(long)`, `SoundPlayer.getMicrosecondLength()`

### isMP3

    public boolean isMP3()

### close

    public void close()

  Description copied from class: `SoundPlayer`
  closes the current sound. You can reuse the same SoundPlayer by loading a new sound with one of the `load(..)` methods

  Overrides:
    `close` in class `SoundPlayer`

### play

    public void play()

  Description copied from class: `SoundPlayer`
  if `play()` is called on a sound that has been played through, you may have to call `stop()` before `play()` will have the effect of replaying the sound

  Overrides:
    `play` in class `SoundPlayer`
  See Also:
    `SoundPlayer.stop()`

### isPlaying

    public boolean isPlaying()

  Overrides:
    `isPlaying` in class `SoundPlayer`

### stop

    public void stop()

  Description copied from class: `SoundPlayer`
  use play() to resume playing after stop() was called

  Overrides:
    `stop` in class `SoundPlayer`
  See Also:
    `SoundPlayer.play()`

### finalize

    protected void finalize()

  Overrides:
    `finalize` in class `SoundPlayer`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads