HTML5 Video Editor Integration API

Registration

To make custom integration with your serivce it is required to register a developer account to get an apiKey and configure integration options:

callBackUrl to receive events that are performed by the user while using the editor. See CallBack events for details
Provide custom API urls for media files. See Custom URLs specification and Generate media info for details
- fetchFileUrl to fetch media information
- mediaTabContentUrl to fetch media files to display at media tab,
- fetchThumbnailUrl to fetch media file’s thumbnail to display at timeline
outputS3Bucket to upload output results to Amazon S3 Bucket. See S3 bucket configuration for details

Before open the editor's session for specific user use Create user session API to get the session’s id

To open an editor use the following url:

https://smarteditingonline.solveigmm.com/?session_id=<id>

Custom URLs specification

To provide custom media files within the user's session, the urls specified during developer registration should be implemented at developer server.

The urls should be configured to respond with the ‘Access-Control-Allow-Origin’ header with the value where the editor is running and 'Access-Control-Allow-Headers' 'content-type'

All request contain an Authorization header:

"Authorization": <auth_token>

auth_token - the token that was assigned to user's session at apiAuthToken

fetchFileUrl

The fetchFileUrl is used to get media information.

Request:

GET 
fetchFileUrl/<fileId>

Parameters:

fileId- the media file's id

Response:

JSON encoded object dev_media_file_entry_object :

{     
  "id":<string>,
  "previewUrl":<string_url>,
  "name":<string>,
  "filetype":<string>,
  "mediaType":<string>,
  "duration":<number>,
  "size":<number>,
  "width":<number>,
  "height":<number>,
  "thumbnail":<base64_encoded_png_image>,
  "audioTracks":[<string>, <string>]
}

id - defines file id

previewUrl - url for playing media file

name - defines file name of entry

filetype - defines file's type, could be: "mp4", "mov", "mp3", "png","m4a","jpg","mxf", "folder", "webm"

mediaType - defines entry media type, could be: "video", "audio", "image"

duration - is duration in 100ns units,

size - file size in bytes,

width, height- is video resolution in pixels of source media

thumbnail- is png image converted to base64 encoded string.

audioTracks - array of audio tracks names

mediaTabContentUrl

The mediaTabContentUrl is used to get media tab content.

Request:

GET 
mediaTabContentUrl?start_number=<number>&count=<number>&filter=<string>&sort_field=<string>&sort_order=<string>&search=<string>

Parameters:

start_number- the start number of first element in requested media list

count - the max count of requested entries

filter - defines filter by mediaType (optional, could be comma separated combination of multiple items)

sort_field - defines sort field

name - by name of the file
createTime - by creation time (default)
size - by size
duration - by duration

sort_order - defines order in which entries should be sorted(optional)

asc - ascending
desc - descending (default)

search - defines search string that will be applied to entries(optional)

Response:

{
 "total_count":<number>,
 "entries":[ 
    <dev_media_file_entry_object>,
    <dev_media_file_entry_object>,
    <dev_media_file_entry_object>,
    <dev_media_file_entry_object>,    
  ]
}

Description:

total_count - defines total count of files
entries - An array of dev_media_file_entry_object

fetchThumbnailUrl

The fetchThumbnailUrl is used to get a single thumbnail in order to display it at timeline.

Request:

GET
fetchThumbnailUrl?id=<fileId>&time=<number>

Parameters:

id- the media file’s id

time - the thumnbail’s time in 100ns units

Response:

JSON encoded object

{
  "data":<base64_encoded_png_image>
}

Description:

data - is png image converted to base64 encoded string.

Generate media info

The media file information required for customized urls implementation could be prepared in advance.

Generate media info API

Use existing html5editor backend server to generate media info.

All request should contain an Authorization header:

"Authorization": <valid_api_key>

valid_api_key - the valid api developer's key

Create media info task

Request:

POST
/api/task/mediainfo

Request Body:

{
  "originalUrl": <valid_file_url>
  "previewUrl": <valid_file_url> (optional)
}

Description:

originalUrl - file's url of the orignal media file

previewUrl - file's url of the preview media file that supported by browser

Response:

{
  "id": <taskId>
}

Get media info

Request:

GET
/api/task/mediainfo/<taksId>

Response:

Status 202 - The media file processing is in progress

Status 200 - The media file was processed

JSON mediainfo object:

{     
  "info":{
    "name":<string>,
    "filetype":<string>,
    "mediaType":<string>,
    "duration":<number>,
    "size":<number>,
    "width":<number>,
    "height":<number>,
    "thumbnail":<base64_encoded_png_image>,
    "previewUrl":<string_url>,
    "audioTracks":[<string>, <string>]
    },
  "thumbnails":[{
    "time":<number>,
    "data":<base64_encoded_png_image>
  }]
}

Description:

info - should be used to implement fetchFileUrl, and mediaTabContentUrl. The fields description at dev_media_file_entry_object.

thumbnails - should be used to implement fetchThumbnailUrl

Generate media info locally

The local installed docker container(provided on demand) helps to generate media info locally

S3 Bucket configuration

To upload output results to Amazon S3 Bucket outputS3Bucket should be configured with the following fields:

s3_bucket_object:

{
    "awsBucketName":<string>,
    "awsEndPoint":<string>,
    "awsAccessKey":<string>,
    "awsSecreteKey":<string>,
}

The example permission policy configuration for Amazon is the following:

{
    "Version": "2012-10-17",
    "Statement": [       
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::<bucketName>"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::<bucketName>/*"
            ]
        }
    ]
}

CallBack events

The editor sends POST requests with JSON object body to the callback url that was specified during developer registration.

Common event structure

{
  "type": <string>,
  "userData": <string>,
  "apiAuthToken": <string>
  "payload": <object>
}

type - the event type

userData - the data that was passed at user’s session registration

apiAuthToken - the apiAuthToken that was passed at user’s session registration

payload- contains event dependant fields

Check event at callbackUrl

Each event’s POST request contains the Authorization header that is set to the unique_user_session_id that was created by Registration api ("/api/users"). You can use it to restrict posting of unauthorised data to callback.

Project created

Called when the user created new project

type: project_create

payload:

{
  "projectId":<unique_project_id>,
  "thumbnail":<base64_image_string>
}

Project updated

Called when the user make some changes to project

type: project_update

payload:

{
  "projectId":<unique_project_id>,
  "thumbnail":<base64_image_string>
}

Render project started

Called when the user starts project rendering

type: render_start

payload:

{
  "projectId":<unique_project_id>,
}

Render project completed

Called when the project rendering completed

type: render_complete

payload:

{
  "projectId":<unique_project_id>,
  "downloadUrl":<output_file_url>,
  "error":<error_message>
}

HTML5 Video Editor - Backend Server API

Authorization

auth_token is used to identify user in API requests,

Backend uses WebSocket connection associated with auth_token in order to track if the user is online.

For the new connection auth_token is created as follow (JS):

const client = new WebSocket('ws://backendHost:backendPort/websocket')
  client.onopen = () => {
    const authToken = Date.now().toString()
    client.send(JSON.stringify({
      type: 'user_event',
      payload: { authToken },
    }))
  }
  client.onmessage = message => {
    const dataFromServer = JSON.parse(message.data)
    if (dataFromServer.type === 'ping') {
      client.send(JSON.stringify({
        type: 'pong',
      }))
    }
  }

Create user

Request:

POST /api/users

Request Body:

userObject:

{
  "name": <string>, 
  "data": <string>,
  "apiKey":<string>
  "apiAuthToken": <string>
}

Description:

All properties are optional

name - name of the user

data - custom user’s data

apiKey - associates the user with the the developer's profile

apiAuthToken - used as Authorization header with custom urls overriden by developer's profile (should be used with apiKey)

Response:

JSON encoded object:

{
  "id": <string>
}

Description:

id - users’s id

Update existing user

Request:

PATCH /api/users/<id>

Request Body:

userObject as for create user request

Response:

JSON encoded object:

{
  "id": <string>
}

Description:

id - users’s id

Get user data

Request:

GET /api/users/<id>

Parameters:

id - user’s id

Response:

{
  "name": <string>
  "data": <string>
}

Get media files list

Request:

GET /api/mediafiles?start_number=0&count=20&filter=video&sort_field=createTime&sort_order=asc&search=abc&folder=<id>&auth_token=<valid_token>

Parameters:

start_number- the start number of first element in requested media list

count - the max count of requested entries

filter - defines applied filter to all files by types could be video, audio, image, folder, voiceover(optional, could be comma separated combination of multiple items)

sort_field - defines sort field

name - by name of the file
createTime - by creation time (default)
size - by size
duration - by duration

sort_order - defines order in which entries should be sorted(optional)

asc - ascending
desc - descending (default)

search - defines search string that will be applied to entries(optional)

folder - defines the folder with to get files from(optional)

auth_token - user’s auth_token

Response:

{
 "total_count":4,
 "entries":[ 
    <media_file_entry_object>,
    <media_file_entry_object>,
    <media_file_entry_object>,
    <media_file_entry_object>,    
  ]
}

Description:

total_count - defines total count of files
entries - An array of media_file_entry_objects

Get information on media file

Used to get information on single media file

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request:

GET 
/api/mediafiles/<id>

Parameters:

id- media file id

Response:

JSON encoded media_file_entry_object object:

{     
  "id":<string>,
  "name":<string>,
  "type":<string>,
  "filetype":<string>,
  "mediaType":<string>,
  "duration":<number>,
  "size":<number>,
  "width":<number>,
  "height":<number>,
  "thumbnail":<base64_encoded_png_image>,
  "previewUrl":<string_url>,
  "originalUrl"::<string_url>,
  "audioTracks":[<string>,<string>],
  "status":<string>,
  "progress":<number>,
  "error": <media_error_description_object>,
  "taskId": <string>,
  "categoryId":<string>,
  "moodId":<string>
}

id - defines file id

name - defines file name of entry

type - defines entry type, could be "test", "uploaded", "url", "output"

test - test file available to all users
uploaded - files that was uploaded by user
url - file is imported from url
output - files that was exported/rendered

filetype - defines entry type, could be: "mp4", "mov", "mp3", "png","m4a","jpg","mxf", "folder", "webm"

mediaType - defines entry media type, could be: "video", "audio", "image"

duration - is duration in 100ns units,

size - file size in bytes,

width, height- is video resolution in pixels of source media

thumbnail- is png image converted to base64 encoded string.

previewUrl - url for playing media file

originalUrl - url for original media file. In case of using proxy file for previewUrl

audioTracks - array of audio tracks names

status- defines media file status if some operation is in progress, could be

render - status for project output file that is rendering now
upload - status for media file that user is uploading now
import - status for media file that is importing from url now
convert - status for media file that is converting now
prepare_thumbnails - status for media file that is involved in thumbnails building process.
ready- status indicates that on media file there will no further operations expected

progress- determine progress of the current stage

error - determine error description JSON object <media_error_description_object>

taskId - determine id of render task used for output files (optional)

categoryId - category id of the media file, used with audio library files (optional)

moodId - mood id of the media file, used with audio library files (optional)

Media error description object

media_error_description_object:

{     
  "type": <error_type>,
  "message": <text>,
  "title": <error_title>,
}

error_type could be:

exceeded_file_size - Exceeded single file size limit
exceeded_per_user_size - Exceeded per user size limit
low_disk_space - low disk space on server
unsupported_media - media file is not supported
internal_server_error - Internal server error
not_found - media file not found
used_in_projects - media file is used in projects

text- contains error description

error_title - the error title

Get status on media file

Used to get status on media_file_entry_object

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request:

GET 
/api/mediafile/status?&id="1233f2"

Parameters:

id - media file id

Response:

JSON encoded object

{     
  "status":"upload",
  "progress":90,
  "error": <media_error_description_object>
}

Delete media file

Used to delete media_file_entry_object

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request:

DELETE
/api/mediafiles/<id>?force=1

Parameters:

id - media file id

force - ignore error

Response:

{
  "error": <[media_error_description_object](#media_error_description_object)>
}

Working with folders

Create folder

Creates new folder with specified name

Request:

POST /api/folders

Headers:

"Authorization": "valid_auth_token"

valid_auth_token - was received on authorization

Request Body:

{
  "name": "folder_name"
  "folder": "folder_id"
}

Description:

name - the name of the folder,

folder - the folder’s id to create new folder in

Response:

JSON encoded object

{
  "id":"2sdv342s8834"
}

Delete folder

Removes folder with all it’s content recursively with subfolders

Request:

DELETE
/api/folders/<id>?force=1

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

id - folder’s id

force - ignore error

Response:

{
  "error": <media_error_description_object>
}

Update folder name

Request:

PATCH
/api/folders/<id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

<id>- requested folder id

Request Body:

{
  "name": <folder_new_name>,
}

Description:

name- name of the folder. Optional

Response:

JSON encoded object:

{}

Move media file(s), folders to another folder

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request:

PUT
/api/folders/<id>/entries

Parameters:

<id>- requested folder id

Request Body:

{
  "files": [],
  "folders": [],
}

Description:

files - an array of file ids to move to folder ( Optional)

folders- an array of folder ids to move to folder ( Optional)

NOTE: in case case of moving files to root folder /api/folders/root/entries should be used

Get audio library files list

Fetches list of audio library files. To initiate audio library files fetch process use /api/import/audiolib_json sort_field

Request:

GET /api/audiolib_files?type=music&start_number=0&count=20&sort_field=createTime&sort_order=asc&search=abc&category_id=<id>&mood_id=<id>

Parameters:

start_number - the start number of first element in requested media list

count - the max count of requested entries

type - selects the list of specific type could be:

music- audio tracks with music composition (default)
sound - audio samples of specific sounds or noises

category_id - optional field to filter by specific category

mood_id - optional field to filter by specific mood

sort_field - defines sort field

name - by name of the file (default)
createTime - by creation time

sort_order - defines order in which entries should be sorted(optional)

asc - ascending (default)
desc- descending

search - defines search string that will be applied to entries(optional)

Response:

Response is the same as for api /api/mediafiles

Get information on audio library file

Used to get information on audio library file

Request:

GET 
[/api/audiolib_files/<id>](#Get_information_on_media_file "/api/audiolib_files/<id>")

Response:

Response is the same as /api/mediafiles/

Get categories list for audio library files

Fetches list of existing categories

Request:

GET /api/audiolib_files/categories?type=music

Parameters:

type - field to define type of the list could be:

music - audio tracks with music composition (default)
sound - audio samples of specific sounds or noises

Response:

JSON array describing media_file_entry_object's:

{
  "entries":[ 
   <auidolib_category_object>,
             <auidolib_category_object>,
   <auidolib_category_object>,
   <auidolib_category_object>,	
  ],
}

<auidolib_category_object> is JSON object

{
  "id": <unique_id>
  "name": <category_name>
  "entriesCount": 20
}

Get Moods list for audio library files

Fetches list of existing categories

Request:

GET /api/audiolib_files/moods?type=music

Parameters:

type - field to define type of the list could be:

music - audio tracks with music composition (default)
sound - audio samples of specific sounds or noises

Response:

JSON array describing media_file_entry_object's:

{
  "entries":[ 
    <auidolib_mood_object>,
             <auidolib_mood_object>,
    <auidolib_mood_object>,
    <auidolib_mood_object>,	
  ],
}

<auidolib_mood_object> is JSON object

{
  "id": <unique_id>
  "name": <mood_name>
  "entriesCount": 20
}

Thumbnails for clip on timeline

To get thumbnails for the clip on timeline from prepared database of thumbnails use

cached=true parameter in request

if cached=false thumbnails will be generated in real time

To get list of thumbnails for the media file with step and requested count

Request:

GET
/api/clip_thumbnails?id=0&start_time=10000000&step=5000000&count=20&cached=true

Parameters:

id- the media file’s id ( see /api/mediafiles)

start_time - the time in 100ns units for the start time

step - the time in 100ns units time step

count - count of requested thumbnails

cached - should get thumbnails from prepared database

Response:

JSON encoded object

{
 "status":"",
 "thumbnails":[
    {
      time:0
      data:"base64_encoded_png_image"
    },
    {
      time:5000000
      data:"base64_encoded_png_image"
    }
  ]
}

Description:

status - contains error message, empty string means operation success,

thumbnails - an array of thumbnails objects,

time - thumbnail time in 100ns units,

data - base64_encoded_png_image

Get single thumbnail

Request:

GET
/api/clip_thumbnail?id=0&time=10000000

Parameters:

id- the media file’s id ( see /api/mediafiles)

time - thumnbail’s time in 100ns units

Response:

JSON encoded object

{
  "data":<base64_encoded_png_image>
}

Description:

data - is png image converted to base64 encoded string.

Editing task

Create new task

Editing Task is passed via POST request the request body should contain json object with XTL format task

Request:

POST
/api/task/editing

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request Body:

{
  "xtl_task": <valid_xtl_task_string>
}

Description:

auth_token - User gets this token after authorization

Example of xtl_task:

<timelines version="2">
  <timeline>
    <group >
      <track video="1" audio="1" accuracy="frame">
        <clip src="media_file_id" start="00:00:01:00" stop="00:00:06:00" timeFormat="time10ms" />
        <clip src="media_file_id" start="00:00:07:00" stop="00:00:12:00" timeFormat="time10ms" />
      </track>
    </group>
  </timeline>
</timelines>

Response:

JSON encoded object

{
  "taskId":"2sdv342s8834"
  "fileId": "output_23234234234.mp4"
  "error":  <error_description_message>
}

Description:

taskId - an id of newly created task

fileId - identifies output Media File

error - contains error description (optional)

Editing task operation status

To get task’s status use GET request

Request:

GET
/api/task/editing?id=<task_id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

id- requested task’s id

Response:

JSON encoded object

{
  "id":<task_id>,
  "progress":50,
  "status":"running",
  "error": <engine_error_description_object>,
  "outputUrls":[
    "http://35.234.23.3/output_files/43234/32343/name.mp4"
  ]
}

Description:

id - an id of task
progress - task progress in percent
status- string description of current task status could be:

running - task is running
completed - task was successful completed
aborted - task was aborted by user or error message
downloading - downloading media files before trimming (in case of “url” file types)
uploading - uploading saved result (e.g. to amazon bucket)

error - task’s Engine error description object
outputUrls - links to output media file(s)

Engine error description object

engine_error_description_object:

{     
  "type": <type>,
  "message": <message>,
  "code": <code>,
}

type - could be:

engine_error - Edit engine error
download_error - unable to download input media
upload_error - upload error

message - contains error description
code - internal engine error code

Stop editing task

To stop task use DELETE request

Request:

DELETE
/api/task/editing?id=<task_id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

id- requested task’s id

Response: JSON encoded object

{
  "status":"",
}

Projects

Create new project

Project passed via POST request the request body should contain json object with project’s data

Request:

POST
/api/projects

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request Body:

{
  "name": <project_name>, 
  "data": <project_data>,
  "thumbnail": <base_64_string>,
  "createTime": <unix_timestamp_ms>
}

Description:

name- name of the project.

data - actual project’s data.

thumbnail - the project thumbnail

createTime - the project createTime (Optional). If not set the backend time will be used

Response:

JSON encoded object:

{
  "id": "B7pAdG3HJUZ25uJkwuuVcQH6Hkndx6gARcV76EV4"
}

Description:

id - project’s id

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Update existing project

Request:

PATCH
/api/projects/<id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

<id>- requested project id

Request Body:

{
  "name": <project_name>,
  "data": <project_data>,
  "thumbnail": <base64_string>, 
  "modifTime":<unix_timestamp_ms>
}

Description:

name- name of the project. Optional

data - actual project’s data. Optional

thumbnail - thumbnail for the project. Optional

modifTime - project’s modification time. Optional. If not set the backend time will be used.

Response: JSON encoded object:

{}

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Get existing project’s data

To get project’s data use GET request

Request:

GET
/api/projects/<id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

<id> - requested project id

Response:

JSON encoded <project_object>:

{
  "id":<project_id>,
  "data":<project_data>,
  "name":<project_name>,
  "createTime":<unix_timestamp>,
  "modifTime":<unix_timestamp>,
  "thumbnail": <base64_string>
}

Description:

id - an id of the project

data - actual project’s data

name - name of the project

createTime - project’s creation time

modifTime - last project’s modification time

thumbnail - thumbnail for the project

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Get projects list

Request:

GET /api/projects?start_number=0&count=20&data=0&search=abc

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

start_number - the start number of first element in requested project list

count - the max count of requested entries

data - fill <project_object>’s data field for non zero value

search - defines search string that will be applied to entries(optional)

Response:

JSON array describing media_file_entry_object’s:

{
 "total_count":4,
 "entries":[ 
        <project_object>,
        <project_object>,
        <project_object>,
        <project_object>,    
        ],
}

Description:

total_count - defines total count of files
The project_object description could be found in /api/project

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Delete project

Used to delete project

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request:

DELETE
/api/projects/<id>

Parameters:

id - project id

Response:

{}

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Actions history

The action history is saved at backend to keep project’s changes between autosave intervals and ability to restore the changes if the user disconnected between autosave intervals. The order of POST requests will define the order of the entries returned by GET The total actions count for the project configured by ACTION_HISTORY_DEPTH (default value 1000) backend variable. Exceeding this count will remove earlier actions. The actions are linked to the project, removing the project removes all actions related to it.

Create new action

Action passed via POST request the request body should contain json object with action’s data. On new action all action with canceled=”true” field will be removed, before posting action that will remove canceled actions the project should be in sync.

Request:

POST
/api/actions

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request Body:

{
  "id": <action_id>,  
  "project": <project_id>,
  "name": <action_name>, 
  "data": <action_data>,
  "createTime": <unix_time_ms>,
}

Description:

id - action’s id

projectId- project’s id to which action belongs to

name - the name of the action

data - the action data

createTime- the action’s createTime (Optional). If not set the backend time will be used

Response:

JSON encoded object:

{
  "id": "1632798732"
}

Description:

id - actions’id

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Undo Redo action

In order to undo/redo action, the “canceled” field should be updated.

Request:

PATCH
/api/actions/<id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

<id>- requested action id

Request Body:

{
  "modifTime": <unix_time_ms>    
  "canceled": true
}

Description:

canceled- true means action was undoed false action is active

modifTime - the time of modification. If not set backend time will be used

Response:

JSON encoded object:

{}

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Get actions list

Request:

GET /api/actions?project=<valid_project_id>

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Parameters:

project - the project id that actions belongs to

Response:

JSON array describing media_file_entry_object’s:

{
  "entries":[ 
      <action_object>,
      ],
}

Description:

The action object:

{
  "id": <action_id>,   
  "name": <action_name>, 
  "data": <action_data>,
  "canceled": <boolean>,
  "createTime": <unix_time_ms>
  "modifTime": <unix_time_ms>
}

id - action id.

name - name of the action.

data - actual action’s data.

canceled - "true" - action was canceled (undo operation was done), "false" - action is active

createTime - action’s creation time unix time in ms

modifTime - action’s modification time unix time in ms

The entries are in the order that they were POSTed.

Error Codes:

400 - bad request

404 - no user or no project with id found

500 - internal server error

Overlay image upload

For editing with text overlays or image overlay it’s required to put image data of rendered text or image to use it in editing task, it will be automatically deleted after user disconnected.

Request:

POST
/api/overlay_img

Headers:

"Authorization": <valid_auth_token>

valid_auth_token - was received on authorization

Request Body:

{
  "data":"base64_encoded_png_image"
}

Description:

data - base64 encoded_png_image

Response: JSON encoded object

{
  "status":"",
  "id":<overlay_img_id>,
}

status - contains error message, empty string means operation success,

id - an id of overlay_img

Local media upload

Create an upload session on response upload_session_id will be available. The upload session is valid within 24 hours. Upload media file parts with specifying upload_session_id. The progress of current session could be gotten via upload_session_id

Create an upload session

Headers:

"Authorization": <valid_auth_token>

Request:

POST
/api/upload/media

Request Body:

{
  "size":12345
  "name":"my media.mp4"
  "folder":"folder_id"
}

Description:

valid_auth_token - User gets this token after authorization

size - is number of bytes of file data, which will be transferred in subsequent requests

folder - destination folder’s id (optional)

Response:

JSON encoded object

{
  "id":<upload_session_id>,
}

id - an id of uploaded media

Error Codes:

400 - bad request

404 - no user found

500 - internal server error

507 - Upload limit exceeded error

514 - Unsupported media

Put media file parts to upload session

Headers:

"Authorization": <valid_auth_token>
"Content-Length": <chunk_size>
"Content-Range": bytes <range_start>-<range_end>/<total_size>
"Content-Type": "application/octet-stream"

Request:

PUT
/api/upload/media?id=<upload_session_id>

Request Body:

<binary_data>

Description:

valid_auth_token - User gets this token after authorization

chunk_size - number of bytes in the current chunk

<range_start>-<range_end>/<total_size> - show which bytes in the file you upload. For example, Content-Range: bytes 0-524287/2000000 shows that you upload the first 524,288 bytes (256 x 1024 x 2) in a 2,000,000 byte file ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range )

Response:

Status 200 - the media file was uploaded
Status 206 - more data expected

Use the Range header in the response to determine where to start the next chunk. The header contains information on which bytes the server has received. Do not assume that the server received all bytes sent in the previous request.

For example, Range bytes=0-524287 - means that server has received the first 524,288 bytes ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range )

Status 5xx - upload request was interrupted

Import media by URL

Initiates process of importing media by url at backend side.

Create an url import request

Headers:

"Authorization": <valid_auth_token>

Request:

POST
/api/import/media/url

Request Body:

{
  "url":"https://example.com/file.mp4"
  "folder":"folder_id"
}

Description:

valid_auth_token - User gets this token after authorization

folder - destination folder’s id (optional)

Response:

JSON encoded object

{
  "id":<imported_media_id>,
}

id - an id of imported media

Error Codes:

400 - bad request

404 - no user found

500 - internal server error

Import AWS bucket

Initiates process of importing media by aws bucket credentials at backend side.

Create an aws bucket import request

Headers:

"Authorization": <valid_auth_token>

Request:

POST
/api/import/media/awsbucket

Request Body:

{
  "awsAccessKey":<key>,
  "awsSecreteKey":<secrete>,
  "awsBucketName":<bucket_name>,
}

Description:

valid_auth_token - User gets this token after authorization

awsAccessKey, awsSecreteKey, awsBucketName - Credentials to access aws bucket.

Response:

JSON encoded object

{
  "id":<awsbucket_id>,
  "error":<error description>,
}

id - an id of imported aws_bucket

error - description if present

Error Codes:

400 - bad request

404 - no user found

500 - internal server error

Import audio library files from json list

Initiates process of fetching audio library files using json list. The json list’s absolute path is set by env variable AUDIOLIB_JSON_LIST (default uses /var/www/smm_cloud_editor_v2/audioLib.json) The media absolute path is configured by AUDIOLIB_FILES_DIR env variable

The example of audioLib.json:

{
    "entries": [
        {
            "name": "Bubble_G_Funk_Remastered.mp3",
            "relativePath": "Bubble_G_Funk_Remastered.mp3",
            "category": "Electro",
            "type": "music"
        },
        {
            "name": "cats.mp3",
            "relativePath": "cats.mp3",
            "category": "animals",
            "type": "sound"
        },
    ]
}

Create an audio library files import request

Initiate importing process. To get the progress and errors use GET

Request:

POST
/api/import/audiolib_json

Response:

JSON encoded object

{
}

Error Codes:

500 - internal server error

Get an audio library files import process status

Request:

GET
/api/import/audiolib_json

Response:

JSON encoded object

{
  "processedCount": 1
  "totalCount": 256
  "error":<error description>,
}

error - contains error description if present

processedCount - contains count of files already handled

total count - contains total number of files

Error Codes:

500 - internal server error

Import Project

Create an import session

Creates import project session on response the id of the new project will be available

Headers:

"Authorization": <valid_auth_token>

Request:

POST
/api/upload/project

Request Body:

{
  "size":12345
  "name":"edlproject.zip"
  "fps":29.97
  "createFolder":true
}

Description:

valid_auth_token - User gets this token after authorization

size - is number of bytes of file data, which will be transferred in subsequent requests

name - the name of the uploaded project file (optional)

fps - the fps that will be used at the import stage e.g. for edl that is required(optional)

сreateFolder - import media files to the folder with the project name or to root media (optional)

Response:

JSON encoded object

{
  "id":<project_id>,
}

id - an id of the new project

Error Codes:

400 - bad request

500 - internal server error

Put project file parts to import session

Headers:

"Authorization": <valid_auth_token>

"Content-Length": <chunk_size>

"Content-Range": bytes <range_start>-<range_end>/<total_size>

"Content-Type": "application/octet-stream"

Request:

PUT
/api/upload/project?id=<project_id>

Request Body:

<binary_data>

Description:

valid_auth_token - User gets this token after authorization

chunk_size - number of bytes in the current chunk

<range_start>-<range_end>/<total_size> - show which bytes in the file you upload.

For example, Content-Range: bytes 0-524287/2000000 shows that you upload the first 524,288 bytes (256 x 1024 x 2) in a 2,000,000 byte file ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range )

Response:

Status 200 - the media file was uploaded

Status 206 - more data expected

For example Range bytes=0-524287 - means that server has received the first 524,288 bytes ( https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range )

Status 5xx - upload request was interrupted

Get import project session progress and status

Headers:

"Authorization": <valid_auth_token>

Request:

GET
/api/upload/project?id=<project_id>

Response:

JSON encoded object

{
  "stage": <import_project_stage>,
  "progress": 0
  "error": "error description"
}

Description:

import_project_stage - the status of the import process, could be:

"upload" - the data is uploading now
"unpack" - the data is unpacking
"import_media" - import media files
"ready" - the import process completed

progress - the progress value of the current stage

error - error description if present

Cancel import project session

Headers:

"Authorization": <valid_auth_token>

Request:

DELETE
/api/upload/project?id=<project_id>

Response:

JSON encoded object

{}

Voiceover recording

Voiceover is implemented using kurento media server

Create voiceover recording session

Creates webrtc connection and start sending voice data to server

Headers:

"Authorization": <valid_auth_token>

Request:

POST
/api/voiceovers

Request Body:

{
  "sdpOffer":<sdp_offer>
  "iceCandidates":<array_of_local_ice_candidates>
}

Description:

offer - SDP offer string created by browser webRtcPeer.generateOffer

iceCandidates - local ice candidates array gathered by browser

Response:

JSON encoded object

{
  "id":<new_voiceover_id>
  "sdpAnswer": <remote_sdp_answer>
  "iceCandidates": <array_of_remote_ice_candidates }
}

Error Codes:

500 - internal server error

Start voiceover recording

Start record voiceover data to file

Headers:

"Authorization": <valid_auth_token>

Request:

PUT
/api/voiceovers/<id>

Request Body:

{
  "name": <the file name for_recording>
}

Description:

id - recording id

name - new recording file name (optional) , the backend will set name automatically if missing

Response:

JSON encoded object

{
  error: <error description>
}

error - Error description if present

Error Codes:

500 - internal server error

Stop and delete voiceover recording session

Headers:

"Authorization": <valid_auth_token>

Request:

DELETE
/api/voiceovers/<id>?keepRecording=1

Description:

id - recording id

keepRecording - flag determines keeping media file recorded during the session

Response:

JSON encoded object

{
}

Error Codes:

500 - internal server error

Statistics

Get backend live statistics.

Request:

GET
/api/stat

Response:

JSON encoded object

{
  "activeUsersCount":1,
  "activeBuildThumbsTasksCount":0,
  "activeRenderTasksCount":1,
  "activeImportFromURLTasksCount":0,
  "activeImportFromLocalDriveCount":0
}

Description:

activeUsersCount - Count of active user

activeBuildThumbsTasksCount - Count of active build timeline thumbnails tasks

activeRenderTasksCount - Count of active render tasks

activeImportFromURLTasksCount- Count of files that are downloading from url now

activeImportFromLocalDriveCount - Count of files that are uploading from local drive now

Backend version

Request:

GET
/api/version

Response:

JSON encoded object

{
  "version":"1.0.2006.18",
}

Description

Version string contains 1 - major, 0 - minor, 20 - year, 06 - month, 18 - day