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 是個陣列,是這個頻道所有的影片(這裡只有一部影片),每個影片都有filepathaudio_codecidstateduration ... 等影片資訊規格的屬性(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)