javax.telephony.media
Interface Player

All Superinterfaces:

CoderConstants, MediaConstants, PlayerConstants, Resource, ResourceConstants

All Known Subinterfaces:

TTSPlayer

public interface Player

extends Resource, PlayerConstants

Defines methods for playing media data into a Terminal. A Player extracts data from a media data object (MDO) (which supplies a stream of media to be played), transcodes the data as necessary for the telephony network, and streams the resultant data out to that network.

The play() method accepts one or an array of Strings which identify the media streams to be played. Each media stream may be encoded by any coder type supported by this player resource.

A Player may optionally support additional processing features. These features define parameters and runtime controls that affect operation of an ongoing play operation. The presence of these features is indicated by a true value for the following attributes:

Attribute:	indicates the ability to:
a_Pause	pause and resume in place
a_Speed	change the playback speed
a_Volume	increase and decrease the volume
a_Jump	jump forward and backward while playing

Each of these is explained in the Attributes section.

In addition to the play() method, a number of RTC actions may affect the operation of the player. These can be invoked through Run Time Control RTC actions, or by the pausePlayer(), resumePlayer(), stopPlayer() jumpPlayer(), adjustPlayerVolume(), adjustPlayerSpeed() methods.

Coding types for data objects are defined in CoderConstants.

The MDO to be played is identified by its String name. The String name is an identifier that may be interpreted as a path or URL (URI) for the MDO.

Note: The format of the String that identifies an MDO is not defined by this release of specification [although it will be compatible with that used in the ContainerService]. The vendor-specific implementation of the MediaService (for example, the vendor of the server or resource) shall define the supported String formats.

For example, an implementation may support URLs or File pathnames; in which case an application could use Strings of the form: "file://node/dir/name" or "dir/dir/name" or "container/container/dataobject".

If the MDO identifier is a file pathname, it is interpreted in the logical filename-space of the server. Applications and their prompts need to be installed with correct pathnames.

Operation:

Player States:

The following is the state diagram for a player.

The Player has three states: Idle, Active, and Paused.

In the Idle state, the Player is performing no coding or transmit operations. The state transitions to the Active or Paused state when the play() method starts. The state of the Player after play() starts is determined by the Boolean value of the parameter p_StartPaused. The state transitions to Active if p_StartPaused is false. The state transitions to Paused if p_StartPaused is true.

In the Paused state, the player is not transmitting the media stream. It retains its place in the MDO being played, and resumes from the same place when the RTC action, rtca_Resume is received.

In the Active state, the Player is busy, actively transmitting the media stream from a MDO to its output media stream (the Terminal). The Player continues in this state until it reaches the end of the MDO list or until RTC actions tell it to pause or stop. In the Active state, the Player may receive RTC commands to change the speed or volume of the play operation. It may also receive commands to jump forward or backward in the MDO.

If a new play() is attempted while the Player is Active, the result is determined by the value of the p_IfBusy parameter. The alternative values for p_IfBusy are:

• v_Queue: This play is queued (default). It is played when the previous plays have completed.
• v_Stop: The current play and any queued plays are stopped, (with event qualifier q_Stop). This play begins immediately.
• v_Fail: This play fails, with (getError() == e_Busy)

Player Attributes

Attribute a_Pause

If the attribute Player.a_Pause is true, then the Player supports the pause and resume operations.

• rtca_Pause sets the player state to Paused and onPause is invoked if ev_Pause is enabled in p_EnabledEvents.
• rtca_Resume sets the player state to Active, continues to play the stream from it current offset, and onResume is invoked if ev_Resume is enabled in p_EnabledEvents.

If the value of attribute a_Pause is false, then then the effects of the RTC actions, parameters, and methods discussed in this section are not defined.

Attribute a_Speed

A MDO has a "normal" speed at which its data is to be played. The RTC actions discussed in this section may change the speed up or down. The playback speed achieved by these actions is called the adjusted speed.

The units by which speed may be adjusted are percentage change from the normal speed.

If the attribute Player.a_Speed is true, then the player supports the following features:

• The rtca_SpeedUp and rtca_SpeedDown RTC actions cause the playback speed to be adjusted up or down respectively. The amount of change is governed by the parameter p_SpeedChange, in units of percentage change from the normal speed.
• If the current playback speed is not at the default normal value, the rtca_ToggleSpeed RTC action changes the speed to the normal value. If the current playback speed is at the default normal value, the rtca_ToggleSpeed RTC action changes the speed to the last adjusted value.
• If a RTC action would result in setting the speed beyond the maximum or minimum allowed values, the command/action is ignored. If a RTC action would result in no change to the playback speed (e.g., changing speed to normal when the speed is already normal, toggling the speed when no adjustment had been made to the speed), the action is ignored.
• The event ev_Speed is delivered to PlayerListener.onSpeedChange. This event may be enabled or disabled by the p_EnabledEvents parameter.

If the value of attribute a_Speed is false, then then the effects of the RTC actions, parameters, and methods discussed in this section are not defined.

Attribute a_Volume

A MDO has a "normal" default volume at which its data is to be played. The RTC actions discussed in this section may change the volume up or down. The playback volume achieved by these actions is called the adjusted volume. Local regulatory restrictions may limit the levels to which volume may be adjusted. It is the responsibility for the client application to ensure that it does not adjust the volume so as to exceed those levels.

The units by which volume may be adjusted are measured in dB from the normal volume.

If the value of attribute a_Volume is true then the Player supports the following features:

• The rtca_VolumeUp and rtca_VolumeDown RTC actions cause the playback volume to be adjusted one quantum up or down respectively. The size of the quantum is governed by the parameter p_VolumeChange, measured in dB from the normal volume.
• If the current playback volume is not at the default normal value, the rtca_ToggleVolume RTC action changes the volume to the normal value. If the current playback volume is at the default normal value, the rtca_ToggleVolume RTC action changes the volume to the last adjusted value.
• The event ev_Volume is delivered to PlayerListener.onVolumeChange. This event may be enabled or disabled by the p_EnabledEvents parameter.

If an RTC action would result in no change to the playback volume (e.g., changing volume to normal when the volume is already normal, toggling the volume when no adjustment had been made to the volume), then the command/action is ignored. Likewise, when the volume is already at its maximum or minimum value, RTC actions that attempt to set it beyond the limit are ignored.

If the value of attribute a_Volume is false, then the effects of the RTC actions, parameters, and methods discussed in this section are not defined.

Attribute a_Jump

A Player has a "current location" within a MDO when in the Active or Paused state. The location and the granularity of changing that location depends on the coder type; being determined by the sample rate and whether the coder is "stateful". For simple Pulse Code Modulation (PCM) coders the location is reported and changed in millisecond units (rounded to the sample rate).

If a player resource supports a_Jump attribute, then the following features are supported:

• The rtca_JumpForward and rtca_JumpBackward RTC actions change the current location one quantum forward or backward respectively. The quantum is set by the parameter p_JumpTime.
• The rtca_JumpStartMDO and rtca_JumpEndMDO RTC actions change the current location to the start or the end of the current MDO.
• The rtca_JumpForwardMDOs and rtca_JumpBackwardMDOs RTC actions change the current location to the beginning of the MDO that is n MDOs ahead or behind the current MDO in the play list respectively. The value n is set by the parameter p_JumpMDOIncrement.
• The rtca_JumpStartMDOList and rtca_JumpEndMDOList RTC actions change the current location to the beginning or end respectively of the list of MDOs being played.

A Jump method or RTC action that goes past the end of the current MDO continues into the next MDO in the MDO list if the coders for the MDOs support the same time increment. If the next MDO in sequence has a different coder type, the current location is set to the beginning of that MDO.

If the value of attribute a_Jump is false, then the effects of the RTC actions, parameters, and methods discussed in this section are not defined.

Since:

JTAPI-1.3

Fields inherited from interface javax.telephony.media.ResourceConstants

e_Disconnected, FOREVER, q_Disconnected, q_RTC, rtcc_Disconnected, rtcc_TriggerRTC, v_Forever

Fields inherited from interface javax.telephony.media.MediaConstants

e_OK, q_Duration, q_Standard, q_Stop

Fields inherited from interface javax.telephony.media.PlayerConstants

a_Coder, a_DictionaryList, a_Jump, a_LoadedDictionary, a_Pause, a_SapiOptions, a_Speed, a_Volume, e_Busy, ev_ActivateDictionary, ev_AdjustSpeed, ev_AdjustVolume, ev_Jump, ev_LoadDictionary, ev_Marker, ev_Pause, ev_Play, ev_Resume, ev_Speed, ev_Stop, ev_UnloadDictionary, ev_Volume, p_CoderTypes, p_EnabledEvents, p_IfBusy, p_JumpMDO, p_JumpMDOIncrement, p_JumpMSCIncrement, p_JumpSentence, p_JumpTime, p_JumpWord, p_MaxDuration, p_SpeedChange, p_StartPaused, p_VolumeChange, q_Duration, q_EndOfData, rtca_JumpBackwardMDOs, rtca_JumpBackwardMSCs, rtca_JumpBackwardSentences, rtca_JumpBackwardTime, rtca_JumpBackwardWords, rtca_JumpEndMDO, rtca_JumpEndMDOList, rtca_JumpEndMSC, rtca_JumpEndMSCList, rtca_JumpEndSentence, rtca_JumpForwardMDOs, rtca_JumpForwardMSCs, rtca_JumpForwardSentences, rtca_JumpForwardTime, rtca_JumpForwardWords, rtca_JumpStartMDO, rtca_JumpStartMDOList, rtca_JumpStartMSC, rtca_JumpStartMSCList, rtca_JumpStartSentence, rtca_NormalSpeed, rtca_NormalVolume, rtca_Pause, rtca_Resume, rtca_SpeedDown, rtca_SpeedUp, rtca_Stop, rtca_ToggleSpeed, rtca_ToggleVolume, rtca_VolumeDown, rtca_VolumeUp, rtcc_PlayComplete, rtcc_PlayStarted, v_Class, v_Fail, v_Queue, v_Stop

Fields inherited from interface javax.telephony.media.CoderConstants

v_24kADPCM, v_32kADPCM, v_44kADPCM, v_48k8BitLinear, v_48kALawPCM, v_48kMuLawPCM, v_64k8BitLinear, v_64kALawPCM, v_64kMuLawPCM, v_88k8BitLinear, v_88kALawPCM, v_88kMuLawPCM, v_ADPCM_24k, v_ADPCM_32k, v_ADPCM_44k, v_ADSI, v_ALawPCM_48k, v_ALawPCM_64k, v_ALawPCM_88k, v_ASCII, v_Linear8Bit_48k, v_Linear8Bit_64k, v_Linear8Bit_88k, v_MuLawPCM_48k, v_MuLawPCM_64k, v_MuLawPCM_88k, v_TDD

Method Summary

PlayerEvent	adjustPlayerSpeed(Symbol adjustment) Adjusts the speed of the current play function.
PlayerEvent	adjustPlayerVolume(Symbol adjustment) Adjusts the volume the current play function.
PlayerEvent	jumpPlayer(Symbol jump) Jump forward or backward within a sequence of MDOs during a play.
PlayerEvent	pausePlayer() Pause the current play.
PlayerEvent	play(java.lang.String[] streamIDs, int offset, RTC[] rtc, java.util.Dictionary optargs) Play a sequence of MDOs (Media Data Objects) identified by the streamIDs.
PlayerEvent	play(java.lang.String streamID, int offset, RTC[] rtc, java.util.Dictionary optargs) Play a single MDO (Media Data Object) named by streamID.
PlayerEvent	resumePlayer() Resume the current play.
PlayerEvent	stopPlayer() Stop the current play.

Method Detail

play

public PlayerEvent play(java.lang.String[] streamIDs,
                        int offset,
                        RTC[] rtc,
                        java.util.Dictionary optargs)
                 throws MediaResourceException

Play a sequence of MDOs (Media Data Objects) identified by the streamIDs. This sequence of MDOs is called the "MDO list".

This method returns when the MDO list is completely played, or when the playing has been stopped. (Player Pause does not cause this method to return.) Play returns a PlayerEvent. The condition that caused the play to stop is included in the completion event. RTC actions can alter the course of the play without the intervention of the application. Optional arguments can alter the characteristics of the play.

Exceptions are thrown if pre- or post- conditions are not satisfied

Pre-conditions:

1. a Player resource is configured
2. all MDOs are playable

Post-conditions:

1. As indicated by getQualifier():
   • q_EndOfData: All MDOs named in this MDO list have been played.
   • q_Stop: play was stopped by the stop() method or because (p_IfBusy=v_Stop)
   • q_RTC: play was stopped by Player.rtca_Stop

Parameters:

streamIDs - a String[] naming the MDO list to be played.

offset - number of milliseconds into the MDO list at which play is to start, offset may span several items in streamIDs.

rtc - Array of RTC that effect this play.

optargs - a Dictionary of optional arguments.

Returns:

a PlayerEvent when the operation is complete (or queued).

Throws:

MediaResourceException - if requested operation fails.

DisconnectedException - if Terminal is disconnected.

play

public PlayerEvent play(java.lang.String streamID,
                        int offset,
                        RTC[] rtc,
                        java.util.Dictionary optargs)
                 throws MediaResourceException

Play a single MDO (Media Data Object) named by streamID. Equivalent to play() with a String[] of length one, containing the given streamID.

Parameters:

streamID - a String naming the MDO to be played.

offset - int number milliseconds into the MDO at which play is to start.

rtc - Array of RTC that effect this play.

optargs - a Dictionary of optional arguments.

Returns:

a PlayerEvent when the operation is complete (or queued).

Throws:

MediaResourceException - if requested operation fails.

DisconnectedException - if Terminal is disconnected.

adjustPlayerSpeed

public PlayerEvent adjustPlayerSpeed(Symbol adjustment)
                              throws MediaResourceException

Adjusts the speed of the current play function.

Parameter adjustment specifies the type of speed adjustment desired.

• rtca_SpeedUp - speed up by p_SpeedChange
• rtca_SpeedDown - slow down by p_SpeedChange
• rtca_ToggleSpeed - toggle between normal and adjusted speed.
• rtca_NormalSpeed - set to normal speed

This is functionally equivalent to the RTC actions.

Note: the value of p_SpeedChange is in units of percent deviation from normal.

Note: this is functionally equivalent to the RTC actions, except that it generates a Completion Event instead of a non-transactional Event.

Parameters:

adjustment - an RTC Symbol specifying the type of change.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if speed cannot be adjusted

adjustPlayerVolume

public PlayerEvent adjustPlayerVolume(Symbol adjustment)
                               throws MediaResourceException

Adjusts the volume the current play function.

Parameter adjustment specifies the type of volume adjustment desired.

• rtca_VolumeUp - volume up by p_VolumeChange
• rtca_VolumeDown - volume down by p_VolumeChange
• rtca_ToggleVolume - toggle between normal and adjusted volume
• rtca_NormalVolume - set to normal volume

This is functionally equivalent to the RTC actions.

Note: the value of p_VolumeChange in in units of dB from the normal volume.

Note: this is functionally equivalent to the RTC actions, except that it generates a Completion Event instead of a non-transactional Event.

Parameters:

adjustment - an RTC Symbol specifying the type of change.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if volume cannot be adjusted

jumpPlayer

public PlayerEvent jumpPlayer(Symbol jump)
                       throws MediaResourceException

Jump forward or backward within a sequence of MDOs during a play.

Parameter jump specifies the type of jump desired. It is one of the rtca_Jump<Type><Units> Symbols.

For example: rtca_JumpForwardTime.

This is functionally equivalent to the Jump RTC actions, except that it generates a Completion Event instead of a non-transactional Event.

Parameters:

jump - a Symbol specifying the type of jump.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if the jump cannot be done

pausePlayer

public PlayerEvent pausePlayer()
                        throws MediaResourceException

Pause the current play.

This is functionally equivalent to rtca_Pause, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if pause cannot be done

resumePlayer

public PlayerEvent resumePlayer()
                         throws MediaResourceException

Resume the current play.

This is functionally equivalent to rtca_Resume, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if resume cannot be done

stopPlayer

public PlayerEvent stopPlayer()
                       throws MediaResourceException

Stop the current play.

This is functionally equivalent to rtca_Stop, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a PlayerEvent when the operation completes

Throws:

MediaResourceException - if stop cannot be done