The Kaltura Player abstracts the need to retrieve direct access to the video file, and handles the various aspects of the video playback including multi-bitrate, choosing the correct codec and streaming protocols, DRM, Access Control and more. Often applications need a direct URL for downloading the raw media file for purposes such as streaming outside of the Kaltura Player, processing the video data (such as video analysis or transcriptions) and more. In cases where you need to access the playback stream directly, or just a link to download the video file, you will need to consider the target playback devices, any security protocols applied to your Kaltura account and video, and then call the suitable API methods. The following will guide developers of using the playManifest API call to retrieve specific transcoded video flavors from a Kaltura account.
The playManifest API
The playManifest is a redirect action source code, whose purpose is to direct media player applications to the desired video stream.
The playManifest features return the following types:
- A redirect to video file for [progressive download (http://en.wikipedia.org/wiki/Progressive_download) or an M3U8 stream descriptor for Apple HTTP Streaming, aka HLS.
- An XML response in the form of a MPEG-DASH Media Presentation Description (MPD).
- An XML response in the form of Flash Media Manifest File.
Retrieving a URL for a Video Stream
To retrieve a specific video flavor:
Make sure you have the Partner ID and Entry ID on hand, and then call the playManifest API using the following URL: [serviceUrl]/p/[YourPartnerId]/sp/0/playManifest/entryId/[YourEntryId]/format/[StreamingFormat]/protocol/[Protocol]/flavorParamId/[VideoFlavorId]/ks/[ks]/video.[ext].
Next, replace the following parameters:
|serviceUrl||The base URL to the Kaltura Server|
|YourPartnerId||Your Kaltura account publisher ID (this can be retrieved from the Publisher Account Settings page in the KMC).|
|YourEntryId||The Id of the media entry you’d like to retrieve.|
|StreamingFormat||See the list of available formats in the table below. This parameter is optional and defaults to /format/url.|
|Protocol||Whether video is to be delivered over HTTP or HTTPS. See the list of available protocols below for additional options. This parameter is optional and defaults to /format/http.|
|VideoFlavorId||The Id of the video flavor you want to download. If supported by the streaming format, multiple flavors may be comma separated.|
|ks||A valid Kaltura Session. This parameter is only required when the media entry has an Access Control defined to limit anonymous access to the media.|
|ext||The file extension of the video you wish to retrieve (for example, mp4 if the video flavor is an MPEG4 filem, or flv if the video flavor is an FLV file).|
Available Service URLs (Public / SaaS)
|Protocol + Domain||Description|
|https://cdnapisec.kaltura.com||Secure HTTPS Request. (recommended)|
|http://cdnapi.kaltura.com||Standard HTTP Request.|
Available Playback Formats
|applehttp||HTTP Live Streaming (HLS) Streaming.|
|hds||Adobe HTTP Dynamic Streaming. Not available for all Kaltura accounts.|
|rtmp||Real Time Messaging Protocol (RTMP). Recommended only for Live, or special use cases.|
|rtsp||Real Time Streaming Protocol (RTSP). For legacy devices, such as older Blackberry and Nokia phones.|
|hdnetworkmanifest||Akamai HDS delivery. Available only for accounts with Akamai delivery.|
|hdnetwork||Akamai Proprietary Delivery Protocol. Available only for accounts with Akamai delivery. (deprecated)|
Available Protocol Parameters
|http||http Redirect and streaming URLs make use of the HTTP protocol. (Default)|
|https||https Redirect and streaming URLs make use of the HTTPS protocol.|
|rtmp||rtmpe||rtmpt||rtmpte||(RTMP Streaming only) Streaming Server Base URL make use of the specified protocol (RTMP, RTMPE, RTMPT, or RTMPTE).|
Note: The playManifest API is not a standard part of the Kaltura API v3, it is a direct URL request that retrieves the specific binary video file from Kaltura. The response to the playManifest URL is the actual video file of the requested entry flavor.
Note: The playManifest API does not require a KS unless the media entries were specifically setup with Access Control profiles to limit anonymous access to the media. If the media entry does have Access Control profiles assigned, a KS (Kaltura Session) must be specfied when calling the playManifest URL.
What is the Distinction between flavorParamId and flavorId?
- flavorParamId represents the transcoding parameters that are used to generate a flavor. For example, all HD flavors in an account will usually have the same flavorParamId (across different entries)
- flavorId is the identifier of a specific video file, for example, the HD flavor will have a different flavorId for each entry that has an HD flavor.
When to You use each Flavor?
- If the flavorIds for the specific entry are known (e.g., the application is doing a flavorAsset.list with entryIdEqual), then use flavorId/flavorIds.
- If the flavorIds are not known (e.g., the application would like to build a URL to the HD flavor, but does not want to perform flavorAsset.list) use flavorParamId/flavorParamIds.
Considerations of Access Control and Entitlements
It is important to note that Kaltura entries can be set for private or protected modes, where access is only allowed when providing a valid admin Kaltura Session.
For best practice, to retrieve the download URL for an entry, use the following steps:
- Locate the ID of the desired video flavor (see below Video Flavor Id).
- Call the
Below is a PHP code sample for retrieving the download URL of a web-playable flavor for a desired entry ID:
Video Flavor ID
The VideoFlavorId parameter determines which video flavor the API will return as download. This parameter has various options, depending on the Kaltura server deployment and publisher account.
The following lists few of the conventional flavor IDs:
Note:Note: Only flavor id 0 (zero) is static and the same across Kaltura editions. The following list are common flavor Ids on the Kaltura SaaS edition, but note flavors change and upgraded often (improved quality, new codecs, etc.) - Use this list for example purposes.
- The original uploaded video (before transcoding) = 0
- iPhone / Android (mp4) = 301951
- iPad (mp4) = 301971
- Nokia/Blackberry (3gp) = 301991
- Other devices (mp4) = 301961
The correct flavor IDs (per account and Kaltura edition) can be retrieved using one of the following ways:
- Visiting the KMC Settings > Transcoding Profiles.
- Making an API call to the ConversionProfile.list action.
>Retrieving Streaming URL for Mobile Applications
To retrive streaming URL for mobile applications, use the following guidelines:
- For Apple iPad devices – get all the flavors (marked ready) that have the tag ‘ipadnew’ and build the following URL:
- For Apple iPhone devices – get all the flavors (marked ready) that have the tag ’iphonenew’ tag and build the following URL:
- For Android devices that support HLS – get all the flavors (marked ready) that have the tag ’iphonenew’ tag (excluding audio-only flavors where width, height & framerate fields equal to zero) and build the following URL:
- For Android devices that do not support HLS – get a single video flavor that has the ‘iPhoneNew’ tag and build the following URL:
Retrieving the Currently Playing Video URL using the Player JS API
To retrieve the URL of the video that is being played in the player, use the following player call: