MPE-Streaming

(this article assumes that you've already setup a working MPExtended environment, as described in the getting started article. It also assumes that you get how the JSON interface works and can make a simple method call.)

Basic operations

When using the JSON API there is one significant difference with the other APIs: some methods don't use the /json/ suffix, but instead the /stream/ suffix. This are all methods which don't return JSON but return data instead. You can find which method uses what in the API documentation. First try if your setup works by testing GetServiceDescription().

Access to the actual data streams over the SOAP API is experimental at the momen, and not detailed here. 

Each stream has an identifier. The client can choose this identifier freely, but it should be unique across all clients that use the streaming service. Each stream is also associated with a transcoder profile. This specifies what kind of stream is created, and how: which transcoder, codecs and container is used. These are defined in the StreamingProfiles.xml configuration file. Note that not all profiles do support all modes of operation. HTTP Live Streaming for example is only supported when that's explicitly declared in the configuration.

The process of setting up transcoding is a bit more complicated then what's needed. This is due to historical implementation reasons, but also allows us for greater flexibility in the future. First you initialize a stream with the InitStream method. You can select a media source with the type, provider and itemId parameters. The clientDescription parameter is pure informational. This method should return true. Then, you start the stream with StartStream. Specify the transcoder profile you want with the profileName parameter (you can get a list of profiles with GetTranscoderProfiles). StartStream blocks until the transcoding has started; this may take up to 30 seconds. It returns an URL to the stream.

When the user is done watching the stream, you have to kill it off, else the transcoding will continue running and use unnecessary CPU cycles. This is done with the FinishStream method.

HTTP Live Streaming

Note: this is untested at the moment.

The basic procedure is exactly the same for normal streaming, except that you need a transcoder profile that supports HTTP Live Streaming (currently this are only the FFMpeg HTTP Live Test and VLC HTTP Live Test profiles), and that the StartStream method returns the URL to the playlist. Segments are usually around 10 seconds long.

Extracting image stills

It is possible to extract image stills from a media file with the ExtractImage method (for example to show as placeholder for loading video). With the position parameter you can seek in the file (it's in seconds).  The returned image is an JPEG image. If you want smaller images you can let it resize the image with the ExtractImageResized method.

Selecting subtitle and audio language

MPExtended defaults to using no subtitles and the first audio stream. If you need to select other streams, you can use the StartStreamWithStreamSelection method. It has two additional parameters - audioId and subtitleId. With the GetMediaInfo method you can a list of all available audio, video and subtitles streams, along with their languages and IDs. Make sure to pass the ID of the streams and not their Index. External subtitles are also reported by GetMediaInfo, but they usually have incorrect Language information. Selecting an invalid subtitle stream will result in no subtitles, while selecting an invalid audio stream will result in the first one. Subtitles are hardcoded into the video.

Seeking

It is possible to seek in a stream. Because there is no standard protocol for this, we invented our own. First stop the playing of the video (i.e. abort the request on the URL returned by StartStream). Then you can seek to another place in the video with, again, the StartStream method, but this time with the position parameter set to the new position in seconds. Make sure to use the same identifier as your previous stream.

Note that at the moment this basically starts a whole new transcoding. For this reason it may be quite slow - up to 30 seconds. This will change in the future (and that's why it's important to do it this way instead of finishing the stream and starting a new one). Seeking in live TV is not supported.

Streaming live TV

While the general process is the same, there are a few differences when streaming live TV:

• When calling InitStream, use the channel ID as itemId.
• You can leave the provider parameter always out, but sending a value along doesn't hurt.
• When calling GetMediaInfo, use the identifier of a running stream as itemId, not the channel ID. You need to start a stream to be able to get the media info. Starting a timeshifting through the TAS won't work. 
• Stream selection probably doesn't work
• Extracting images doesn't work (and neither are TV logos supported)