de.enough.polish.multimedia
Class AudioPlayer

java.lang.Object
  de.enough.polish.multimedia.AudioPlayer

All Implemented Interfaces:

android.media.MediaPlayer.OnCompletionListener, android.media.MediaPlayer.OnPreparedListener, PlayerListener

public class AudioPlayer
extends Object
implements PlayerListener, android.media.MediaPlayer.OnCompletionListener, android.media.MediaPlayer.OnPreparedListener

Plays back audio files - at the moment this is only supported for MIDP 2.0 and devices that support the MMAPI and for Android devices.

Copyright Enough Software 2006 - 2009

Author:

Robert Virkus, j2mepolish@enough.de

Field Summary

Fields inherited from interface javax.microedition.media.PlayerListener

CLOSED, DEVICE_AVAILABLE, DEVICE_UNAVAILABLE, DURATION_UPDATED, END_OF_MEDIA, ERROR, STARTED, STOPPED, VOLUME_CHANGED

Constructor Summary

AudioPlayer()
Creates a new audio player with no default content type and no caching.

AudioPlayer(boolean doCachePlayer)
Creates a new audio player with no default content type.

AudioPlayer(boolean doCachePlayer, String contentType)
Creates a new audio player with no listener

AudioPlayer(boolean doCachePlayer, String contentType, PlayerListener listener)
Creates a new audio player

AudioPlayer(String contentType)
Creates a new audio player without caching and with no listener.

Method Summary

void	cleanUpPlayer() Closes and deallocates the player.
static String	getAudioType(String type, String protocol) Helper function for getting a supported media type.
Player	getPlayer() Returns the original player.
PlayerListener	getPlayerListener() Retrieves the currently registered player listener.
int	getVolumeLevel() Gets the volume using a linear point scale with values between 0 and 100.
boolean	isMuted() Detects the the player is currently muted
boolean	isPlaying() Determines if the audio player is currently playing music
static boolean	isSupportedAudioType(String type, String protocol) Determines whether the given audio format is supported by this device for the specified protocol.
void	onCompletion(android.media.MediaPlayer mp) Informs the audio player about a finished media on Android devices.
void	onPrepared(android.media.MediaPlayer p)
void	play() Plays back the last media again.
void	play(InputStream in) Plays the media taken from the specified input stream with the content type specified in the constructor.
void	play(InputStream in, String type) Plays the media taken from the specified input stream.
void	play(String url) Plays the media taken from the specified URL with the content type specified in the constructor.
void	play(String url, String type) Plays the media taken from the specified URL.
void	playerUpdate(Player p, String event, Object data)
void	prepare(String url) This method is part of a two-phase playback.
void	setMute(boolean mute) Mutes the player or restores the previous volume level
void	setPlayerListener(PlayerListener listener) Sets a player listener, replacing any previously registered listener.
void	setVolumeLevel(int j2MeLevel) Sets the volume using a linear point scale with values between 0 and 100.
void	stop()
void	streamMp3s(String[] filenames) This method will play the files with the filenames given in the parameter one after the other.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AudioPlayer

public AudioPlayer()

Creates a new audio player with no default content type and no caching.

AudioPlayer

public AudioPlayer(boolean doCachePlayer)

Creates a new audio player with no default content type.

Parameters:

doCachePlayer - caches the player even though the end of the media is reached

AudioPlayer

public AudioPlayer(String contentType)

Creates a new audio player without caching and with no listener.

Parameters:

contentType - the type of the referenced media, this is being resolved to the phone's expected type automatically. You can, for example, use the type "audio/mp3" and this method resolves the type to "audio/mpeg3", if this is expected by the device.

AudioPlayer

public AudioPlayer(boolean doCachePlayer,
                   String contentType)

Creates a new audio player with no listener

Parameters:

doCachePlayer - caches the player even though the end of the media is reached

contentType - the type of the referenced media, this is being resolved to the phone's expected type automatically. You can, for example, use the type "audio/mp3" and this method resolves the type to "audio/mpeg3", if this is expected by the device.

AudioPlayer

public AudioPlayer(boolean doCachePlayer,
                   String contentType,
                   PlayerListener listener)

Creates a new audio player

Parameters:

doCachePlayer - caches the player even though the end of the media is reached

contentType - the type of the referenced media, this is being resolved to the phone's expected type automatically. You can, for example, use the type "audio/mp3" and this method resolves the type to "audio/mpeg3", if this is expected by the device.

listener - an optional PlayerListener

Method Detail

stop

public void stop()

setPlayerListener

public void setPlayerListener(PlayerListener listener)

Sets a player listener, replacing any previously registered listener.

Parameters:

listener - the new listener or null

getPlayerListener

public PlayerListener getPlayerListener()

Retrieves the currently registered player listener.

Returns:

the current player listener

streamMp3s

public void streamMp3s(String[] filenames)
                throws IOException

This method will play the files with the filenames given in the parameter one after the other. This method is only available for the Android platform at the moment.

Parameters:

filenames - Must not be null and no array element must be null. Each filename must start with 'file://'. Normally you want to access files under the directory 'System.getProperty("fileconn.dir.private")'.

Throws:

IOException

play

public void play(String url,
                 String type)
          throws MediaException,
                 IOException

Plays the media taken from the specified URL.

Parameters:

url - the URL of the media

type - the type of the referenced media, this is being resolved to the phone's expected type automatically. You can, for example, use the type "audio/mp3" and this method resolves the type to "audio/mpeg3", if this is expected by the device.

Throws:

MediaException - when the media is not supported

IOException - when the URL cannot be resolved

play

public void play(InputStream in,
                 String type)
          throws MediaException,
                 IOException

Plays the media taken from the specified input stream.

Parameters:

in - the media input

type - the type of the referenced media, this is being resolved to the phone's expected type automatically. You can, for example, use the type "audio/mp3" and this method resolves the type to "audio/mpeg3", if this is expected by the device.

Throws:

MediaException - when the media is not supported

IOException - when the input cannot be read

play

public void play(String url)
          throws MediaException,
                 IOException

Plays the media taken from the specified URL with the content type specified in the constructor.

Parameters:

url - the URL of the media

Throws:

MediaException - when the media is not supported

IOException - when the URL cannot be resolved

play

public void play(InputStream in)
          throws MediaException,
                 IOException

Plays the media taken from the specified input stream with the content type specified in the constructor.

Parameters:

in - the media input

Throws:

MediaException - when the media is not supported

IOException - when the input cannot be read

play

public void play()
          throws MediaException

Plays back the last media again. This can only be used when doCachePlayer is set to true in the constructor

Throws:

MediaException - when the player cannot be started

See Also:

AudioPlayer(boolean), AudioPlayer(boolean, String), AudioPlayer(boolean, String, PlayerListener), AudioPlayer(String)

getPlayer

public Player getPlayer()

Returns the original player.

Returns:

the original player, this can be null when no audio has been played back so far.

getAudioType

public static String getAudioType(String type,
                                  String protocol)

Helper function for getting a supported media type.

Parameters:

type - the type like "audio/mp3"

protocol - the protocol, when null is given the content type will be returned for any protocol

Returns:

the type supported by the device, for example "audio/mpeg3" - null when the given type is not supported by the device.

isSupportedAudioType

public static boolean isSupportedAudioType(String type,
                                           String protocol)

Determines whether the given audio format is supported by this device for the specified protocol.

Parameters:

type - the type like "audio/mp3"

protocol - the protocol, when null is given the content type will be returned for any protocol

Returns:

true when the given audio type is supported

isPlaying

public boolean isPlaying()

Determines if the audio player is currently playing music

Returns:

true when audio is played back

playerUpdate

public void playerUpdate(Player p,
                         String event,
                         Object data)

Specified by:

playerUpdate in interface PlayerListener

cleanUpPlayer

public void cleanUpPlayer()

Closes and deallocates the player.

getVolumeLevel

public int getVolumeLevel()

Gets the volume using a linear point scale with values between 0 and 100. 0 is silence; 100 is the loudest useful level that this VolumeControl supports. If the given level is less than 0 or greater than 100, the level will be set to 0 or 100 respectively. When setLevel results in a change in the volume level, a VOLUME_CHANGED event will be delivered through the PlayerListener.

Returns:

the volume level between 0 and 100 or -1 when the player is not initialized

setVolumeLevel

public void setVolumeLevel(int j2MeLevel)

Sets the volume using a linear point scale with values between 0 and 100. 0 is silence; 100 is the loudest useful level that this VolumeControl supports. If the given level is less than 0 or greater than 100, the level will be set to 0 or 100 respectively. When setLevel results in a change in the volume level, a VOLUME_CHANGED event will be delivered through the PlayerListener.

Parameters:

j2MeLevel - the volume level between 0 and 100

isMuted

public boolean isMuted()

Detects the the player is currently muted

Returns:

true when the player is muted

setMute

public void setMute(boolean mute)

Mutes the player or restores the previous volume level

Parameters:

mute - true when the player should be muted, false when the previous volume level should be restored

onCompletion

public void onCompletion(android.media.MediaPlayer mp)

Informs the audio player about a finished media on Android devices.

Specified by:

onCompletion in interface android.media.MediaPlayer.OnCompletionListener

Parameters:

mp - the media player (should be the same as this.mediaPlayer)

onPrepared

public void onPrepared(android.media.MediaPlayer p)

Specified by:

onPrepared in interface android.media.MediaPlayer.OnPreparedListener

prepare

public void prepare(String url)
             throws IOException

This method is part of a two-phase playback. The first phase is to prepare the content, the second phase plays it. This way gaps in the playback of subsequent contents are minimized. This method will only prepare the audio content given by the url. You can play this content with the play() method. This method is only available on android at the moment.

Parameters:

url -

Throws:

IOException