Media Service

The Media Service allows applications to handle media content for different purposes, most importantly, for playback. It connects to the media source and automatically uses the appropriate hardware resources to fetch, decode and, optionally, decrypt the media.

Depending on the purpose, applications use the Media Service to create different software resources:

• Media Player

A Media Player allows applications to open and manage media playback sessions. This includes operations such as play, stop, jumping to a position, fastforward, pause and rewind, although the operations actually available may vary depending on the media source.

See the Video element documentation for information about how to display media.

An application can use the Media Service to create a Media Player by calling createPlayerInstance(). If successful, the Media Service will create a Media Player instance, assign it to the application and return a ToiMediaPlayer object that the application can use to control the Media Player. When the Media Player is no longer needed it must be released by calling releaseInstance()

• Media Session

A Media Session represents media that is currently being processed by the Media Service. Every time an application uses a software resource such as the Media Player to open a playback session, the Media Service assigns a Media Session to it, which is identified by a sessionId.

The purpose of a Media Session is mostly informative and can be useful to applications that do not have access to the Media Player that is managing the playback session. See the Media Session section for more information.

The objects returned by the Media Service are proxies, providing an interface for the application to access the corresponding resource instances. A proxy object has an independent life cycle and should not be confused with the resource instance it represents.

Configuration

In any playback session there are always several elements to consider:

• Stream Sources The different media sources and network protocols used to fetch the media, such as UDP or HTTP.
• Stream Formats The different media stream formats or containers that hold the media, such as MPEG Transport Stream.
• Content Encodings The format in which the media is encoded, such as AAC or H.264
• Conditional Access The encryption systems used to protect the media from unauthorized access.

In order to enable support for a particular source, stream format, encoding or CA system the appropriate protocol, container and license IIPs must be added to the boot image. For example, a possible configuration could include the following IIPs:

kreatv-license-hls
kreatv-option-mediasource-hls[:<parameter-list>]
kreatv-option-mediasource-container-ts
kreatv-license-decode-audio-aac
kreatv-license-decode-video-h264
kreatv-option-ca-verimatrix[:<parameter-list>]

Some IIPs may require additional configuration in the form of parameters, specified at build time. See the IIP reference for a list of the available IIPs and their descriptions.

The Media Service automatically selects which elements to use to successfully decode the content. No explicit indication is needed from the application at run time.

Media Player

A Media Player instance always has a well defined state. Depending on its state, the Media Player responds differently to commands from the application.

Two Fundamental State Machines

The Media Player state is a combination of the states in two separate state machines. One of the state machines is primarily controlled by the application and the other is primarily controlled by events on the network. They are not completely independent since application actions may affect the network and the network may affect what the application is allowed to do, but for the sake of simplicity it helps to think of them as independent of each other.

The Media Player state machine has the following states:

• STATE_IDLE
• STATE_CONNECTING
• STATE_PAUSED
• STATE_PLAYING
• STATE_FASTFORWARDING
• STATE_REWINDING
• STATE_FAILED

STATE_PAUSED, STATE_PLAYING, STATE_REWINDING and STATE_FASTFORWARDING are collectively referred to as Playback states.

The Media Player never enters STATE_IDLE without being explicitly told by the application. If an error occurs with the network connection, and that error is determined to be fatal to the communication with the server, the Media Player enters STATE_FAILED, which gives the application an opportunity to clean up on its side.

The state machine controlled by events on the network has two states only:

• No Data In this state there is no data to read. There are several possible reasons for this: no stream has been started, playback of the selected stream cannot be started for some reason, problems on the network cause the stream to be delivered late or not at all. Whatever happens, intentionally or unintentionally, that cause interrupts in the stream delivery triggers a transition to this state.
• Data Available In this state stream data is available at the expected pace.

See ON_DATA_AVAILABLE and ON_STATE_CHANGED

Unreachable States

Some of the states may not be reachable by the Media Player, depending on the stream source or format. For example, a media stream received over a multicast channel cannot be put in the STATE_REWINDING state, since the Media Player has no control of the transmission of the stream. Its only option is to play the stream as it is received from the network, or stop playing it completely.

When a state transition is not possible, the application is notified in one of two ways, depending on the latency involved to get that information from the stream source. The application must always be prepared to handle both mechanisms:

• ToiOperationNotSupportedException thrown from the play() method when the Media Player knows right away that the operation cannot be completed successfully.
• ON_STATE_CHANGED event emitted at a later stage when the media player has found out that the state transition was not possible. In this case the Media Player state jumps back to the last state that was valid.

Capabilities

Ongoing sessions have a number of capabilities that indicate which operations are possible at any given time. These capabilities are represented by a bit mask, and can be obtained by calling getCapabilities()

For example, the absence of the capability CAPABILITY_FASTFORWARD means that the media source does not support fastforward, and requests to enter that state will fail.

Changes in capabilities after a session has started are notified with the ON_CAPABILITIES_CHANGED event.

How to use it

A typical playback session starts by calling open() with the media source URL, which will set the state to STATE_CONNECTING. When the connection to the media source has been established the state will change to STATE_PAUSED and at that point the application can call play() with the desired pace.

The pace argument of play() specifies how many milliseconds of media will be played per second. A pace of 1000 means regular playback, 0 means pause, a negative value means rewind and a value higher than 1000 means fastforward.

The resulting pace may be different than the requested pace, depending on the limitations of the stream source and other factors.

When the application wants to terminate the playback session, it calls close()

Positioning

Some media sources support positioning, which is indicated to the application by CAPABILIY_GETPOSITION. If this capability is present, then it is possible for the application to obtain the current playback position by calling getPositionInfo() or to be notified about changes in the playback position by the event ON_POSITION_STATUS_CHANGED.

The information provided by the Media Player about the position includes also the valid range and the playback pace. See ToiPositionInfo.

If CAPABILITY_SETPOSITION is present, then it is also possible for the application to specify the desired playback position by calling playFromPosition()

Stream Information

The information about the stream being processed by the Media Player can be obtained by calling getStreamInfo(). This information includes a description of all the media components (audio, video, etc) that are part of the stream.

The information about the current stream can also be obtained by the ON_SESSION_STREAM_INFO_CHANGED event, which is emitted at three different occasions: right after start of playing a stream, when the stream information changes and when changing active video or audio stream.

Media Player Parameters

The Media Player Parameters are a tool for providing information or fine-tuning the operation of a Media Player instance. Each Media Player instance has its own set of parameters that are applied to every new streaming session started by it.

The parameters are set either by using setParameters() or by specifying an extended URL in open(). If the setParameters() method is called in STATE_IDLE, the change affects the default value of the parameter for that particular media player instance. The default value is the value that will be applied to a new streaming session, in case the parameter is not explicitly defined in the URL argument to the open() method. If the setParameters() method is called in any other state but STATE_IDLE, the change affects the current session only.

Some parameters can also be set at build time by the kreatv-option-streamer-config IIP or at runtime by an Infocast server. This is described in Media Player configuration.

Media Session

Calling openSession() with the sessionId of an existing session will return a ToiMediaSession object for the application to access the corresponding Media Session instance. The sessionId can be obtained by listening to ON_SESSION_STATE_CHANGED.

When an application is not interested in a Media Session anymore it must release it by calling releaseInstance(). This action does not close the underlying session, which can only be done by the owner of the Media Player by calling close()

Stream Information

A Media Session provides information about the stream that is being processed. See getUrl() and getStreamInfo()

Applications can be notified about changes in the stream by the ON_SESSION_STREAM_INFO_CHANGED event.

Type

The Media Session type indicates for what purpose the media is being processed. The type is represented by a bit mask, and the value can be obtained by calling getType()

States

The Media Session has its own state machine, different from the Media Player. The possible states are:

• STATE_CLOSED
• STATE_CONNECTING
• STATE_FAILED
• STATE_RUNNING

The current state can be obtained by calling getState() or by listening to the ON_SESSION_STATE_CHANGED event.

Media Parameters

Every Media Session has a set of parameters accesible by calling getParameters(). Some of them can be used to fine-tune certain configuration options and can be set by setParameters(). Changes in parameters are notified by the ON_PARAMETER_CHANGED event.

See the list of available parameters for more information.