Show / Hide Table of Contents

    Solveig Multimedia logo


    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

    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

    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


    Copyright © Solveig Multimedia, 2009-2023

    Back to top Generated by DocFX