API Documentation
API Documentation
Click-AP provides a RESTful API for communicating with Yakitory clients. The following describes the API.
我們提供 RESTful API 的方式來讓各種不同的Apps 控制 Yakitory , 包含影片上傳、進行編碼、轉換、完成通知,到個別影片音訊、視訊規格查詢,影片列表回傳都是透過 API 就可以完成。我們把 API 呼叫的過程作成 GIF , 希望能幫助說明。
Before we start, You must prepare access key, It's a random string for the Yakitory to verify identity.
在開始使用 API 前需取得 access key ,它是API 金鑰,它是一加密字串,讓我們在操控 Yakitory 時確認有管理權限。
Videos
Getting information about all videos(取得在串流伺服器中的其中一部影片)
Web service URL:
http://your-yakitory-server.edu.tw/api/clients/:id/videos
Arguments:
access_key - the clients given access_key, required for authentication.
Example Response:
If authentication is successful, the following JSON is return:
{"videos":["{\"filepath\":\"http://moodle.mcu.edu.tw/yaki_videos/10/銘傳Moodle_LTI架構.wmv\",
\"audio_codec\":\"aac\",\"video_bitrate\":\"1736\",\"thumbnail_filename\":\"Movie_LTI_thumb.jpg\",\"audio_sample_rate\":\"44100\",\"client_id\":\"1\",
\"thumbnail_filepath\":\"http://moodle.mcu.edu.tw/yaki_videos/10/銘傳Moodle_LTI架構_thumb.jpg\",\"error_msg\":null,
\"container\":\"mov,mp4,m4a,3gp,3g2,mj2\",\"video_codec\":\"mpeg4\",\"width\":\"640\",\"fps\":\"29\",\"id\":\"10\",\"state\":\"completed\",
\"height\":\"480\",\"duration\":\"15580\",\"filename\":\"/medias/4/銘傳Moodle_LTI架構.wmv\"}"]}
JSON 的結果,videos 是個陣列,是這個頻道所有的影片(這裡只有一部影片),每個影片都有filepath 、audio_codec 、id 、state 、duration ... 等影片資訊規格的屬性(attribute),在
Video
Getting information about a particular video
Web service URL:
http://your-yakitori-server.edu.tw/api/clients/:id/videos/:video_id
Arguments:
access_key - the clients given access_key, required for authentication.
Example Response:
If authentication is successful, the following JSON is return:
{"video":"{\"filepath\":\"https://moodle.ntust.edu.tw/yaki_videos/10/Moodle小幫手.mov\",\"audio_codec\":\"aac\",
\"video_bitrate\":\"1736\",\"audio_sample_rate\":\"44100\",\"thumbnail_filename\":\"Moodle小幫手_thumb.jpg\",
\"thumbnail_filepath\":\"https://moodle.ntust.edu.tw/yaki_videos/10/Moodle小幫手_thumb.jpg\",\"client_id\":\"1\",
\"container\":\"mov,mp4,m4a,3gp,3g2,mj2\",\"error_msg\":null,
\"encodings\":[{\"filepath\":\"https://moodle.ntust.edu.tw/yaki_videos/10/Moodle小幫手_HD.m3u8\",
\"started_encoding_at\":\"Mon Mar 01 21:56:07 -0500 2010\",\"video_id\":\"10\",\"finished_encoding_at\":\"Mon Mar 01 21:56:09 -0500 2010\",
\"client_id\":\"1\",\"profile_id\":\"1\",\"id\":\"10\",\"state\":\"completed\",\"filename\":\"Moodle小幫手_HD.flv\"}],\"video_codec\":\"mpeg4\",
\"width\":\"640\",\"fps\":\"30\",\"id\":\"10\",\"filename\":\"/medias/4/Moodle小幫手.mov\",\"duration\":\"15580\",\"height\":\"480\",
\"state\":\"completed\"}"}
upload(上傳影片)
Upload a video to Yakitory
Web service URL:
http://your-yakitori-server.edu.tw/api/clients/:id/videos/upload
Arguments:
access_key - the clients given access_key, required for authentication.
Example:
curl(使用 curl):
curl -i -XPOST -F 'access_key=5zgn7mdttnysynwd' 'http://yakitory/api/clients/5/videos/upload' -F 'filepath=@Movie1.mp4'
ASP.NET WebClient (使用 C# - WebClient):
System.Net.WebClient oWeb = new System.Net.WebClient();
oWeb.Headers.Add("Content-Type", "application/x-www-form-urlencoded")
NameValueCollection parameters = new NameValueCollection();
parameters.Add("access_key", "5zgn7mdttnysynwd");
oWeb.QueryString = parameters;
var responseBytes = oWeb.UploadFile("http://yakitory/api/clients/5/videos/upload", "Movie1.mp4");
string response = Encoding.ASCII.GetString(responseBytes);
Example Response:
{"video":"{\"filepath\":\"/Public/data/tmp_uploads/0000000001_Movie1.mov\",
\"audio_codec\":null,\"video_bitrate\":null,\"thumbnail_filename\":null,\"audio_sample_rate\":null,\"client_id\":\"5\",\"thumbnail_filepath\":null,
\"error_msg\":null,\"container\":null,\"video_codec\":null,\"width\":null,\"fps\":null,\"id\":\"31\",\"state\":\"queued\",\"height\":null,\"duration\":null,
\"filename\":\"Movie1.mov\"}"}
Notifications
Yakitori can be configured to notify the client making the encoding request once all encodings for a video are complete. By setting a clients Notification URL, you tell Yakitory that this client should be notified. Once all encodings for a video are complete, Yakitory will send a notification to a URL configured for the client. The notification is a JSON object in the following format:
{
"video_thumbnail": "https://www.moodle.com.tw/yakitory_videos/34/Movie_1_original_thumb.jpg",
"video_id": "34",
"encodings": [
{
"state": "completed",
"id": 34,
"filename": "Movie_LTI_HD"
}
],
"video_state": "completed"
}
以 PHP(or Moodle) 為例:
<?php
function var_error_log( $object=null ){
ob_start(); // start buffer capture
var_dump( $object ); // dump the values
$contents = ob_get_contents(); // put the buffer into a variable
ob_end_clean(); // end capture
return $contents;
}
$videodata = json_decode( file_get_contents('php://input') );
file_put_contents('streamvideo.txt', var_error_log( $videodata));
接收後物件( streamvideo.txt ) 的結果如下:
object(stdClass)[1]
'video_id' = string '54' (length=2)
'video_state' = string 'completed' (length=9)
'video_thumbnail' = string 'data/tmp_videos/54/智慧大師課程移轉5_thumb.jpg' (length=54)
'encodings' =
array (size=2)
0 =
object(stdClass)[2]
'id' = int 77
'container' = string 'flv' (length=3)
'filename' = string '智慧大師課程移轉5_HD.flv' (length=32)
'filepath' = string 'data/tmp_videos/54/智慧大師課程移轉5_HD.flv' (length=51)
'state' = string 'completed' (length=9)
1 =
object(stdClass)[3]
'id' = int 78
'container' = string 'ts' (length=2)
'filename' = string '智慧大師課程移轉5_-%d.ts' (length=32)
'filepath' = string 'data/hls/54/智慧大師課程移轉5.m3u8' (length=42)
'state' = string 'completed' (length=9)