Clips
Clips represent actual video data. A clip must always be part of a playlist, so it cannot be created directly. (We will see about that...)
These are the necessary steps to create a clip with video data:
- Acquire a playlist ID (by walking the folder tree to find or create one)
- Create a new playlist item, without passing a clip_id.
- Acquire the new clip_id from the create action's response
- The clip is now accessible using the project resource, e.g. /api/projects/{project_id}/clips/{clip_id}
- (optionally) Set clip attributes using the update action
- Upload video data using the uploads resource
There is a step-by-step tutorial on how to upload a clip under 10.12 Upload if you need further assistance
Note that there is no destroy action for clips. When the last playlist reference of a clip is removed, the clip is implicitly destroyed as well. (We will also look into that.)
Attributes | |||
---|---|---|---|
id | Integer | 1 | Unique numeric identifier |
name | String | A283C002_160601_R2GJ | Clip name |
duration | Integer | 75818 | Clip duration in seconds |
framecount | Integer | 1862 | Frame count |
framerate | Integer | 25 | Frame rate |
rendered_resolutions | Hash | {"540p" => 1234, "1080p" => 2345} | Rendered resolutions and corresponding filesizes |
playlist_infos | Hash | "781944": { "name": "playlist", "folder_id": 123, "clips_count": 1, "clip_position": 2 }, "781946": { "name": "A283C002_160601_R2GJ", "folder_id": 123, "clips_count": 2, "clip_position": 1 } |
A clip can belong to multiple playlists.
Format: "playlist_id": { "name": "name of playlist", "folder_id": 123, "clips_count": 1, "clip_position": "position of clip in playlist" } |
project_id | Integer | 1 | Project ID |
reel | String | A021R1MO | Reel |
reel_number | Integer | 11 | Reel number |
scene | String | 2 | Scene |
shot | String | 134 | Shot |
circled_take | Boolean | false | Circled Take |
start_timecode | String | 00:00:00:00 | Start timecode |
take | String | 1 | Take |
thumb_image | String | https://webgate.io/media_storage-1/of_test_2851/streaming/bb85e506-1b87-4f84-b10d-3b77c789d564/thumb.jpg | URL for thumbnail 176x99 pixel |
poster_image | String | https://webgate.io/media_storage-1/of_test_2851/streaming/bb85e506-1b87-4f84-b10d-3b77c789d564/poster.jpg | URL for poster image 960x540 pixel |
updated_at | Timestamp | 2017-10-09T15:05:16.000+02:00 | last updated at |
Actions | |||
---|---|---|---|
List | GET | /projects/{project_id}/clips | Optional pagination: e.g. "?page=1&per_page=20" (both params have to be set)
Navigation links are contained in response header 'Links'; there are also headers for 'Total' and 'Per-Page' |
List with filters and sorting | POST | /projects/{project_id}/clips/filter?filters[scene][]=1 |
It is also possible to filter by part of the clip name with parameter "q":
/projects/{project_id}/clips/filter?filters%5Bscene%5D%5B%5D=1&q=clipname It is possible to filter by playlist id: /projects/{project_id}/clips/filter?filters%5Bplaylist%5D%5B%5D=782118 See here for getting possible filters: 10.10 Metadata You can sort by all fields (use "clip_name" for clip names) with "sort_by" and "direction" ("asc" or "desc", by default "asc"): /projects/{project_id}/clips/filter?sort_by=clip_name&direction=desc Optional pagination: e.g. "?page=1&per_page=20" (both params have to be set) Navigation links are contained in response header 'Links'; there are also headers for 'Total' and 'Per-Page' Download preferences To get duration and file size of the whole playlist you have to specify download_preferences: Example: download_preferences[videoheight]=540&download_preferences[fallback]=higher Allowed values for videoheight: 270,540,720,1080,2160 Allowed values for fallback: lower,higher |
Autocomplete | GET | /projects/{project_id}/clips/autocomplete?q=abc | Returns a list of matching clipnames |
List | GET | /projects/{project_id}/folders/{folder_id}/clips |
all clips in given folder; filtering and sorting can be used as in "List with filters and sorting"
Optional pagination: e.g. "?page=1&per_page=20" (both params have to be set) Navigation links are contained in response header 'Links'; there are also headers for 'Total' and 'Per-Page' |
Autocomplete | GET | /projects/{project_id}/folders/{folder_id}/clips/autocomplete?q=abc | Returns a list of matching clipnames |
Show | GET | /projects/{project_id}/clips/{id} | initiates download if Head DOES NOT contain: "Accept: application/json" |
Download | GET | /projects/{project_id}/clips/{id}.file | if Head contains: "Accept: application/file-mixed" the extension ".file" is not needed |
Stream | GET | /projects/{project_id}/clips/{id}.stream | you can set ?videoheight={270|540|720|1080|2160}, default is 540 |
Update | PUT | /projects/{project_id}/clips/{id} | necessary data: {"clip":{"name":"new clip name", ...}} |
List (Action)
Example with pagination:
GET /api/projects/6/clips?page=1&per_page=20 HTTP/1.1 Authorization: Bearer example-token Content-Type: application/json
response:
HTTP/1.1 200 OK Content-Type: application/json Link: <https://medel.webgate.io/api/projects/6/clips?page=3&per_page=20>; rel="last", <https://medel.webgate.io/api/projects/6/clips?page=2&per_page=20>; rel="next" Per-Page: 1 Total: 5 { "status": 200, "status_message": "OK", "info": "", "data": {"array":{...}} }
List with filters (Action)
You can add multiple filters on the same field by using the array syntax. For example if you want to filter for scene 1 and 2:
?filters[scene][]=1&filters[scene][]=2
List of available filters
Filter | Type |
---|---|
circled_take (true / false) | Boolean (true / false) |
episode | String |
reel | String |
reel_number | String |
scene | String |
shot | String |
shot_date | String |
take | String |
tray | String |
playlist | Integer (playlist id) |
Example:
GET /api/projects/6/clips/filter?filters[scene][]=1&filters[scene][]=2&filters[take][]=1 Authorization: Bearer example-token Content-Type: application/json
response:
HTTP/1.1 200 OK Content-Type: application/json { "status": 200, "status_message": "OK", "info": "", "data": { "hash": { "total_clips_count": 43, "duration": 2049704, "clips": [ { "checksum": null, "circled_take": "true", "created_at": "2017-10-13T15:31:25.000+02:00", "download_for_playlist_id": null, "duration": 31510, "episode": "009", "framecount": 787, "framerate": 25, "id": 833887, "name": "rbs-open-pine-30s", "playlist_infos": { "794982": { "name": "Drehtag 01", "folder_id": 75590, "clips_count": 6, "clip_position": 1 } }, "poster_image": "template/allgemein/poster_empty.jpg", "project_id": 6083, "reel": "001", "reel_number": null, "rendered_resolutions": { "720p": 11086400, "1080p": 18674364, "270p": 2073424, "540p": 5779713 }, "scene": "003", "shoot_date": "20171212", "shoot_day": "", "shot": "", "source_file_type": ".mp4", "source_filesize": 6560759, "start_timecode": "00:00:00:00", "take": "006", "thumb_image": "/images/blank.gif", "tray": "", "updated_at": "2018-01-12T17:08:40.000+01:00" } ] } } } }
Show (Action)
Adding the parameter '?mediafiles=heights' to the action, will list all the available videoheights for the particular browser. The browser is being detemined by the header "User-Agent".
Stream (Action)
This action streams rendered formats for browser view. Usually uploaded film-data is too big to stream over the internet. Therefore several formats are being automatically rendered after uploading a clip. Which formats are being automatically rendered, can be set within projects' configuration. Which format will be streamed, is being determined by which User-Agent is being used, and by setting the parameter videoheight. For example:
GET /api/projects/6/clips/1164.stream?videoheight=720 HTTP/1.1 Authorization: Bearer example-token