The ToiMediaPlayer interface is the access point for an application to its private media player instance. Access to this interface is acquired through the ToiMediaService::createPlayerInstance() function. It is possible to create multiple private media player instances. Each application gets its own private instance of this interface for each of its media player instances.
import "ToiMediaPlayer.idl";
Public Member Functions | |
| void | open (in string url) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
| void | close () raises (TToiSessionViolationException, TToiUnavailableException) |
| void | play (in long pace) raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException) |
| void | playFromPosition (in long position, in long pace) raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiInvalidArgumentException, TToiUnavailableException) |
| void | startTimeshiftBuffering (in long maxBufferLength) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiInvalidPreconditionException, TToiOperationNotSupportedException, TToiUnavailableException) |
| void | stopTimeshiftBuffering () raises (TToiSessionViolationException, TToiInvalidPreconditionException, TToiUnavailableException) |
| void | redirectTimeshiftBuffering (in string url) raises (TToiSessionViolationException, TToiUnavailableException, TToiInvalidPreconditionException) |
| void | discardTimeshiftBuffer () raises (TToiSessionViolationException, TToiInvalidPreconditionException, TToiUnavailableException) |
| void | activateComponent (in ToiMediaPlayerBaseComponentEntry mediaComponent) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
| void | deactivateComponent (in ToiMediaPlayerBase::TToiComponentType mediaType) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
| void | setAudioChannelMode (in long streamId, in ToiMediaPlayerBase::TToiAudioChannelMode channelMode) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
| void | setParameter (in string name, in string value) raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiUnavailableException) |
| void | unsetParameter (in string name) raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiUnavailableException) |
| void ToiMediaPlayer::activateComponent | ( | in ToiMediaPlayerBaseComponentEntry | mediaComponent | ) | raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
This function selects a media component to be used. The player state is not affected.
| mediaComponent | The media component entry to be activated. |
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidArgumentException | If the component argument does not identify a valid component, an invalid argument exception is raised. |
| TToiUnavailableException | TToiUnavailableException is raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::close | ( | ) | raises (TToiSessionViolationException, TToiUnavailableException) |
This function ends the current session by stopping any playback and disconnecting from the media source. For example, if the source is a video server it ends the server session and disconnects, or if the source is a multicast channel it leaves that multicast group. If there is an ongoing timeshift on the session it will be stopped or discarded depending on the current timeshift recording configuration ToiInformationService::CFG_MEDIA_TIMESHIFT_RECORDINGPOLICY. If this function returns successfully, the player state will change to STATE_IDLE. If an exception is raised, the player state is unaffected.
| TToiSessionViolationException | If the player is in idle state a session violation exception is raised. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::deactivateComponent | ( | in ToiMediaPlayerBase::TToiComponentType | mediaType | ) | raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
This function deactivates a media component type.
| mediaType | The media component type to be deactivated. |
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidArgumentException | Raised if the component argument does not identify a valid component. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::discardTimeshiftBuffer | ( | ) | raises (TToiSessionViolationException, TToiInvalidPreconditionException, TToiUnavailableException) |
Discards the timeshift buffer and resumes live stream playback, if not already playing live. This disables further timeshift operations. If this function returns successfully, the timeshift state has changed to TIMESHIFT_STATE_INACTIVE.
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidPreconditionException | If the timeshift state is not TIMESHIFT_STATE_STOPPED or TIMESHIFT_STATE_BUFFERING_FAILED an invalid precondition exception is raised. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::open | ( | in string | url | ) | raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
This function starts a new stream session by trying to establish a connection to a media source. If this function returns successfully, the player state will change to STATE_CONNECTING. If an exception is raised, the player state is unaffected.
Depending on the success of the connection attempt to the media source, the player will make a second state transition to either STATE_PAUSED or STATE_FAILED, on success and failure, respectively. In any respect, the application will be notified with the event ToiMediaPlayerStateChangedEvent.
| url | The URL identifying the media source. The URL string may contain additional parameter information in accordance to the extended URL format. |
| TToiSessionViolationException | If the player is not in idle state at the time of the call to ToiMediaPlayer::open(), a session violation exception is raised. |
| TToiInvalidArgumentException | If the URL given as argument does not follow the extended URL format, an invalid argument exception is raised. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::play | ( | in long | pace | ) | raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException) |
This function controls playback of the stream. If this function returns successfully, the player state will change to one of four states: STATE_PLAYING, STATE_PAUSED, STATE_FASTFORWARDING, and STATE_REWINDING. Different values pace result one of these different states with the corresponding effect. In the case of pausing, it keeps the session alive, i.e. it remains connected to video servers and joined in multicast groups. If an exception is raised, the player state is unaffected.
| pace | The pace at which the position will change, given as a multiplier of normal playback times 1000. Zero will pause the stream. 1000 is normal speed (playing). Values above 1000 will result in fast forward, and below -1000 will result in rewind. This are desired paces, the actual implementation may not set the desired speed, but the different states will change according to this description. |
| TToiSessionViolationException | Raised if the player does not have an active session and will not have one soon (due to a recent call to Open) either. |
| TToiOperationNotSupportedException | If the player is in a state is which this operation is not supported, an operation not supported exception is raised. This is the case when in STATE_FAILED, for example. What is supported in which state may in other cases vary depending on which media source is used. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::playFromPosition | ( | in long | position, |
| in long | pace | ||
| ) | raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiInvalidArgumentException, TToiUnavailableException) |
This function moves the playback position of the current stream and resumes playback at the new position with the desired pace. Streams without a well defined notion of beginning and end, like multicast channels, generally do not support this operation. A position value greater than the length of the stream will be clamped.
If this function returns successfully, the player state will change to one of four states: STATE_PLAYING, STATE_PAUSED, STATE_FASTFORWARDING, and STATE_REWINDING. Different values of pace results in the different states. In the case of pausing, it keeps the session alive, i.e. it remains connected to the video server or the joined in multicast group. If an exception is raised, the player state is unaffected.
| position | The position, specified as the number of milliseconds from the beginnig of the stream, to which the playback position is to be moved. The length of the stream can be obtained by calling the ToiMediaPlayer::getStreamInfo() function. |
When playing from the timeshift buffer, the constant POSITION_LIVE can be used to stop buffer playback and start playback of the live stream.
| pace | The pace at which the position will change, given as a multiplier of normal playback times 1000. Zero will pause the stream. 1000 is normal speed (playing). Values above 1000 will result in fast forward, and below -1000 will result in rewind. This are desired paces, the actual implementation may not set the desired speed, but the different states will change according to this description. |
| TToiSessionViolationException | Raised if the player does not have an active session and will not have one soon (due to a recent call to Open) either . |
| TToiOperationNotSupportedException | If the player is in a state is which this operation is not supported, an operation not supported exception is raised. This is the case when in STATE_FAILED, for example. What is supported in which state may in other cases vary depending on which media source is used. The client may investigate this in advance by checking capabilities with ToiMediaPlayer::getCapabilities(). |
| TToiInvalidArgumentException | Raised if the position is negative. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::redirectTimeshiftBuffering | ( | in string | url | ) | raises (TToiSessionViolationException, TToiUnavailableException, TToiInvalidPreconditionException) |
Redirects the timeshift buffering to a new URL. The use case for this function is when the buffering URL need to be set or changed while playing from the timeshift buffer. If the timeshift state is TIMESHIFT_STATE_BUFFERING the buffering will stop on the current URL and then continue on the new URL. If the timeshift state is TIMESHIFT_STATE_STOPPED the buffering will just start on the new URL. The timeshift playback will continue unaffected by the redirection. If the redirection for some reason fails the player will go to live playback on the new URL. Playing from POSITION_LIVE after the redirection will also start live playback on the new URL.
Note that calling this function with high frequency will result in a fragmented buffer containing a lot of chopped pieces of content and KreaTV can not guarantee playback quality of such content. It is therefore not recommended to use this function for e.g. end user zapping.
Redirecting the timeshift buffering to a non-live media source that does not support timeshift operations will result in a timeshift state transition to TIMESHIFT_STATE_BUFFERING_FAILED with reason ToiMediaService::REASON_TIMESHIFT_BUFFER_REDIRECTED. The playback will continue to the end of the buffer.
| url | The URL identifying the new media source where the timeshift buffering should start or continue. |
| TToiSessionViolationException | Raised if the player is in STATE_IDLE. |
| TToiInvalidPreconditionException | Raised if the player is not playing from the timeshift buffer or if the timeshift recording policy is not continuous. See ToiMediaPlayerBase::isTimeshiftPlayback() and ToiInformationService::CFG_MEDIA_TIMESHIFT_RECORDINGPOLICY |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. Raised if the internal timeshift player is unavailable as the result of being linked to an active MediaRecorder for timeshift playback. |
| void ToiMediaPlayer::setAudioChannelMode | ( | in long | streamId, |
| in ToiMediaPlayerBase::TToiAudioChannelMode | channelMode | ||
| ) | raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) |
This function sets the audio channel mode for a given stream identifier. For the active stream the mode will be set instantly.
| streamId | The audio stream identifier. |
| channelMode | The audio channel mode. |
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidArgumentException | An invalid argument exception is raised if the stream identifier argument does not identify a valid audio stream or the channel mode is not supported. |
| void ToiMediaPlayer::setParameter | ( | in string | name, |
| in string | value | ||
| ) | raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiUnavailableException) |
This function sets the value of a parameter. Depending on the current state, the new value is used differently. If the function is called when in idle state, the new value is used for all sessions started after the parameter is set. If the function is called in any other state but the idle state, the new value is applied to that session only and is discarded automatically when the session ends.
| name | The name of the parameter to set. |
| value | The value to set the parameter to. |
| TToiInvalidArgumentException | The parameter name is invalid or not recognized. |
| TToiPermissionDeniedException | The application does not have permission to change the value of the parameter. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |
| void ToiMediaPlayer::startTimeshiftBuffering | ( | in long | maxBufferLength | ) | raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiInvalidPreconditionException, TToiOperationNotSupportedException, TToiUnavailableException) |
Starts background buffering of the currently viewed stream and therefore enables timeshift operations. The media player will continue to display the live stream until either pause or rewind is performed. The timeshift buffering is stopped either by an explicit call to ToiMediaPlayer::stopTimeshiftBuffering() or when the buffer is full. Timeshift operations are disabled by calling ToiMediaPlayer::discardTimeshiftBuffer(). If this function returns successfully, the timeshift state has changed to TIMESHIFT_STATE_BUFFERING. The behavior and preconditions for calling this function is different depending on the current timeshift recording policy configuration ToiInformationService::CFG_MEDIA_TIMESHIFT_RECORDINGPOLICY. The normal recording policy is more strict and only allows one sequence of calls, start->stop->discard and closing the media session will automatically discard the buffer. The continuous recording policy is more flexible and allows subsequent calls, start->stop->...->start->stop->discard. The continuous recording policy also keeps the timeshift buffer without discarding when closing the media session, making it possible for the timeshift buffer to follow a channel change.
| maxBufferLength | The maximum size of the timeshift buffer in seconds. |
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidArgumentException | If maxBufferLength is <= 0 an invalid argument exception is raised. |
| TToiInvalidPreconditionException | The preconditions is different depending on the current recording policy configuration ToiInformationService::CFG_MEDIA_TIMESHIFT_RECORDINGPOLICY. For normal timeshift recording policy the timeshift state must be TIMESHIFT_STATE_INACTIVE and the media player state must be STATE_PLAYING. The preconditions for the continuous timeshift recording policy is more loose and also allows the timeshift state to be TIMESHIFT_STATE_STOPPED, and the media player state must be STATE_PLAYING only when watching live, otherwise all other trickplay states are allowed. Any other state combination will raise an invalid precondition exception. |
| TToiOperationNotSupportedException | Raised if the current media source does not have the timeshift capability or if the current timeshift recording policy configuration ToiInformationService::CFG_MEDIA_TIMESHIFT_RECORDINGPOLICY is set to continuous but continuous timeshift is not supported. This exception is also raised if the timeshift buffering should continue on a non-discarded buffer but maxBufferLength is not the same. The timeshift capacity must remain the same until the buffer is discarded. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. Raised if the internal timeshift player is unavailable as the result of being linked to an active MediaRecorder for timeshift playback. |
| void ToiMediaPlayer::stopTimeshiftBuffering | ( | ) | raises (TToiSessionViolationException, TToiInvalidPreconditionException, TToiUnavailableException) |
Stops the timeshift buffering but preserves the content in the buffer until the function ToiMediaPlayer::discardTimeshiftBuffer() is called. The player will continue to play from the current media source. If this function returns successfully, the timeshift state has changed to TIMESHIFT_STATE_STOPPED.
| TToiSessionViolationException | If the player is in STATE_IDLE a session violation exception is raised. |
| TToiInvalidPreconditionException | If the timeshift state is not TIMESHIFT_STATE_BUFFERING an invalid precondition exception is raised. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. Raised if the internal timeshift player is unavailable as the result of being linked to an active MediaRecorder for timeshift playback. |
| void ToiMediaPlayer::unsetParameter | ( | in string | name | ) | raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiUnavailableException) |
This function restores the value of a parameter to the default. Depending on the current state, the new value is used differently. If the function is called when in idle state, all sessions started after the parameter is restored will use the default value. If the function is called in any other state but the idle state, the value is changed for that session only.
| name | The name of the parameter for which the value is to be restored to the default. |
| TToiInvalidArgumentException | The parameter name is invalid or not recognized. |
| TToiPermissionDeniedException | The application does not have permission to change the value of the parameter. |
| TToiUnavailableException | Raised if the player is temporarily unavailable due to platform resource management. |