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:

  1. Acquire a playlist ID (by walking the folder tree to find or create one)
  2. Create a new playlist item, without passing a clip_id.
  3. Acquire the new clip_id from the create action's response
  4. The clip is now accessible using the project resource, e.g. /api/projects/{project_id}/clips/{clip_id}
  5. (optionally) Set clip attributes using the update action
  6. 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://webgate.io/api/projects/6/clips?page=3&per_page=20>; rel="last", <https://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

A note on Watermarks

Watermarks are not managed by the API at the moment. Standard watermarks are being added with rendering mediafiles (streamable representations of a clip). If you want to change the watermark, or suddenly cannot stream files, please refer to the webpage and change things there.

Example:

Updating a clip's name by sending a json/body:

PUT /api/projects/6/clips/1164 HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json

data: {"clip":{"name":"Example Clip"}}

response:

HTTP/1.1 204 No Content

The action "Show" with extension .file on the id, downloads the file with a 302 redirect. If you are using tools like curl, you need to specifically enable them for redirects. With curl, e.g., it would be the switch "-L".

Downloading works also with adding "Accept:application/file-mixed" to the header of the HTTP request.

Example:

Downloading a clip with setting an "Accept"-header:

GET /api/projects/6/clips/1164.file HTTP/1.1
Authorization: Bearer example-token
Accept: application/file-mixed

response:

HTTP/1.1 302 "Redirecting to Sourcefile"