This API function allows you to set the media information for a Clip, in the database.
support, ws.webtv, api, clips, set_media_info, media
GET vars specific to this request:
Var | Value | Description |
go | clips | The API section |
do | set_media_info | The API action |
iq | Clip ID | Clip ID |
Resulting Request URL:
The resulting request URL would be similar to this (don't forget to append the required info: key, timestamp, salt and signature):
https://....../api.php?go=clips&do=set_media_info&iq={clip_id}&{required information}
*** Each type of Clip requires a different set of media ***
"Standard" Clip case (Clip type 0)
NOTES:
1. The media files must already be in the storage location, according to the Configuration > Video > Storage
- In the case of using local storage, the files must have been uploaded to the uploads/movies folder.
- In the case of AWS, the files must have been uploaded to the corresponding S3 bucket.
- In the case of external server (FTP), the files must have been uploaded to the FTP location.
2. Since this API call will only associate new info in the datebase, it will not handle file deletion/replacement. If you are assigning media to a quality, it will replace any previous assignment but the previous files won't be deleted or replaced from the storage location; therefore, you must manage those tasks in another procedure you must implement.
Var | Value | Description |
*** Single-bitrate media *** | ||
id_quality | (int) Quality ID | [Required] The ID of the quality to which you are associating the media. NOTE: You can use the config > get_video_qualities API call to get the quality list. |
vod_flash | (string) MP4 video file name | Name of the .mp4 file to be played back when using the Flash video player. |
vod_html5_h264 | (string) MP4 video file name | Name of the .mp4 file to be played back when using the HTML5 video player. |
vod_html5_webm | (string) WebM video file name | [Only if WebM is enabled] Name of the .webm file to be played back when using the HTML5 video player. |
The following fields only apply when the Store extension is present and "Trailer" is enabled for the Clip. | ||
vod_flash_trailer | (string) MP4 video file name | Name of the .mp4 file to be played back when using the Flash video player. |
vod_html5_h264_trailer | (string) MP4 video file name | Name of the .mp4 file to be played back when using the HTML5 video player. |
vod_html5_webm_trailer | (string) WebM video file name | [Only if WebM is enabled] Name of the .webm file to be played back when using the HTML5 video player. |
NOTE: Do not provide the URL to the videos, only the file names. |
"StreamClip VOD" case (Clip type 1)
NOTES:
- For more info regarding media support and protocols, check the StreamClip VOD tutorial.
- For more info on how to associate media when using Amazon S3/CloudFront, check the this tutorial.
- For more info on how to associate media when using CloudFront signed URLs, check the this tutorial.
- For more info on how to associate media when using URLs with tokens (using an external tokenizer script), check the this tutorial.
Var | Value | Description |
*** Multi-bitrate media *** (The multi-bitrate media is not associated to a particular quality) |
||
mbr_flash | (string) HLS or F4M URL | The Multi-Bitrate URL for Flash (can be F4M or HLS/.m3u8) |
mbr_html5 | (string) HLS or DASH URL | The Multi-Bitrate URL for HTML5 (HLS/.m3u8 or DASH/.mdp) |
*** Single-bitrate media *** | ||
id_quality | (int) Quality ID | [Required for assigning single-bitrate media] The ID of the quality to which you are associating the media. NOTE: You can use the config > get_video_qualities API call to get the quality list. |
vod_flash | (string) MP4 video file URL | URL of the .mp4 file/stream to be played back when using the Flash video player. |
vod_html5_h264 | (string) MP4 video file URL | URL of the .mp4 file to be played back when using the HTML5 video player. |
vod_html5_webm | (string) WebM video file URL | [Only if WebM is enabled] URL of the .webm file to be played back when using the HTML5 video player. |
The following fields only apply when the Store extension is present and "Trailer" is enabled for the Clip. | ||
vod_flash_trailer | (string) MP4 video file URL | URL of the .mp4 file/stream to be played back when using the Flash video player. |
vod_html5_h264_trailer | (string) MP4 video file URL | URL of the .mp4 file to be played back when using the HTML5 video player. |
vod_html5_webm_trailer | (string) WebM video file URL | [Only if WebM is enabled] URL of the .webm file to be played back when using the HTML5 video player. |
"StreamClip Live" case (Clip type 2)
NOTE: For more info regarding media support and protocols, check the StreamClip Live tutorial.
Var | Value | Description |
*** Multi-bitrate media *** (The multi-bitrate media is not associated to a particular quality) |
||
mbr_flash | (string) HLS or F4M URL | The Multi-Bitrate URL for Flash (can be F4M or HLS/.m3u8) |
mbr_html5 | (string) HLS or DASH URL | The Multi-Bitrate URL for HTML5 (HLS/.m3u8 or DASH/.mdp) |
*** Single-bitrate media *** | ||
id_quality | (int) Quality ID | [Required for assigning single-bitrate media] The ID of the quality to which you are associating the media. NOTE: You can use the config > get_video_qualities API call to get the quality list. |
live_flash | (string) MP4 live stream URL | URL of the live stream (RTMP or HLS) |
live_ios | (string) MP4 live stream URL | URL of the live stream (HLS) |
live_rtsp | (string) MP4 live stream URL | URL of the live stream (RTSP) |
dash | (string) MP4 live stream URL | URL of the live stream (DASH) |
The following fields only apply when the Store extension is present and "Trailer" is enabled for the Clip. | ||
vod_flash_trailer | (string) → | Read "standard" Clip case |
vod_html5_h264_trailer | (string) → | Read "standard" Clip case |
vod_html5_webm_trailer | (string) → | Read "standard" Clip case |
"EmbedClip" case (Clip type 3)
NOTE: For more info about how this Clip type works, check the EmbedClip tutorials.
Var | Value | Description |
id_quality | (int) Quality ID | [Required for assigning single-bitrate media] The ID of the quality to which you are associating the media. NOTE: You can use the config > get_video_qualities API call to get the quality list. |
embed_flash | (string) Embed code for Flash | HTML embed code (or supported video site URL) used in the case of Flash video player. |
embed_html5 | (string) Embed code for HTML5 | HTML embed code (or supported video site URL) used in the case of HTML5 video player. |
The following fields only apply when the Store extension is present and "Trailer" is enabled for the Clip. | ||
vod_flash_trailer | (string) → | Read "standard" Clip case |
vod_html5_h264_trailer | (string) → | Read "standard" Clip case |
vod_html5_webm_trailer | (string) → | Read "standard" Clip case |
"Auto-Encoding" Clip case (Clip type 4)
NOTES:
[For more info about how this Clip type works, read the Auto-Encoding Clip tutorial]
1. The source media file must have been uploaded to the uploads/movies folder.
2. [In the case of associating the resulting files] The resulting media files must already be in the storage location, according to the Configuration > Video > Storage
- In the case of using local storage, the files must have been uploaded to the uploads/movies folder.
- In the case of AWS, the files must have been uploaded to the corresponding S3 bucket.
- In the case of external server (FTP), the files must have been uploaded to the FTP location.
3. Since this API call will only associate new info in the datebase, it will not handle file deletion/replacement. If you are assigning media to a quality, it will replace any previous assignment but the previous files won't be deleted or replaced from the storage location; therefore, you must manage those tasks in another procedure you must implement.
Var | Value | Description |
*** Encoding source *** (The encoding source is not associated to a particular quality) |
||
encoding_source | (string) Video file name | Name of the file which is used for encoding the resulting qualities. |
*** Single-bitrate media *** (In the case of associating the resulting files, check the "standard" Clip case) |
||
NOTE: Do not provide the URL to the videos, only the file names. |
If the request was successful, you'll receive a response containing:
• ok: If the media was successfully set.
Example:
{ "ok": "The Clip media was correctly set" }
If the request failed (for example, if the Clip ID is invalid), you'll receive a response like the following:
{ "error": "CLIP_NOT_FOUND", "error_long": "It was not possible to find a Clip with the supplied ID" }
Possible Error Messages
Besides the general errors, this request can return the following errors:
• REQUEST_ERROR | Invalid Clip ID:
The Clip ID is not valid.
• REQUEST_ERROR | Invalid Quality ID:
The Quality ID is not valid.
• CLIP_NOT_FOUND | It was not possible to find a Clip with the supplied ID:
The Clip was not found.
• MODIFICATION_ERROR_MBR | It was not possible to set the Multi-Bitrate media for the Clip
• MODIFICATION_ERROR_ENCODING_SOURCE | It was not possible to set the encoding_source the Clip
• MODIFICATION_ERROR_MEDIA | It was not possible to set the Clip media
Preparing GET and POST data.
// The GET vars $GET_VARS = array( "go" => "clips", "do" => "set_media_info", "iq" => 700 ); // The POST vars $POST_VARS = array( // setting media for quality ID 1 on a standard clip... "id_quality" => 1, "vod_flash" => "myvideo.mp4", "vod_html5_h264" => "myvideo.mp4", "vod_html5_webm" => "myvideo.webm" );
Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***
// Collect the API Base URL and Credential info $API_URL = "https://www.mywebtvdomain.tv/api.php"; $API_KEY_ID = "1b323a1cb879fd4e66530fbad07a32ee"; $API_SHARED_SECRET = "MWIzMjNhMWNiODc5ZmQ0ZTY2NTMwZmJhZDA3YTMyZWViOTQ3MDJiOGM2ZTU2NjE3"; // keep this safe!!! // Generating salt and timestamp $salt = md5(mt_rand()); $timestamp = time(); $signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true)); // Generating the validation signature // - Default method: using base64_encode(hash_hmac(...)) $signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true)); // comment this line if using the next method // - Simplified method - available since v60: using md5(). // This method requires the variable $API_SIGNATURE_GENERATION_MODE = 1; in the config/Config.inc.php file. // $signature = md5($salt."-".$timestamp."-".$API_SHARED_SECRET); // you must "uncomment" this line when using the simplified method // Append the timestamp, salt, key and signature to the GET vars $GET_VARS["timestamp"] = $timestamp; // UTC timestamp $GET_VARS["salt"] = $salt; $GET_VARS["key"] = $API_KEY_ID ; // The API Key ID: This is public and is used by the API to identify the application; $GET_VARS["signature"] = $signature; // Create the request URL. Please note that if you do not use PHP buit in function // to create the HTTP query then don't forget to URL encode the values $REQUEST_URL = $API_URL."?".http_build_query($GET_VARS); // The previous will build an URL like .../api.php?go=api_subject&do=api_action&etc... // Create a new cURL resource and set the appropriate options $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $REQUEST_URL); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HEADER, false); curl_setopt($ch, CURLOPT_POSTFIELDS, $POST_VARS); // If your PHP host does not have a valid SSL certificate, you will need to turn off SSL // Certificate Verification. This is dangerous (!), and should only be done temporarily // until a valid certificate has been installed curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); // Turns off verification of the SSL certificate. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // Turns off verification of the SSL certificate. // Sending the request to the API $response = curl_exec($ch); // Processing the response if (!$response) { echo 'API call failed'; } else { print_r(json_decode($response,true)); }