iSIZE Precoder Container on Amazon Marketplace

iSize Uncategorized

Set up iSIZE BitSave Container on Amazon Marketplace

This is a step-by-step guide to set up the iSIZE BitSave Container for Linux running on Amazon Elastic Container (ECS). The iSIZE Precoder REST API provides an interface and functionality to integrate precoding within your existing system. The API allows the creation of precoding jobs as well as poll status of jobs using standard REST clients.

REST API Description

By default, the iSIZE Precoder Container listens to port 8000 for REST commands. The REST API does not require any authentication and accepts commands via

[container_ip_addess]:[port]/[function]/[parameter]

The API is used for all the functions available below:

FunctionDescription
POST /isizeAdd a new job to queue for processing
GET /isizeGet status of all job in the queue
GET /isize/{job_ID}Get the detailed status of a single job in the queue specified by job_ID
DELETE /isize/{job_ID}Delete a job specified by job_ID
POST /codecEnable additional optional codecs

REST API function ‘add job’

This function adds precoding jobs to the queue. The JSON job details must be submitted via: POST /isize The JSON job format used is:

{ 
"input": "/isize_files/test.mp4", 
"output": "/isize_files/output/test_output.mp4",
"isize_precoding": "PRECODER_ADAPTIVE",
"isize_use_gpu": "TRUE",
"codec": "AV1",
"bitrate": "4000",
"width": "1920",
"height": "1080",
"gop": "150",
"pix_fmt": "yuv420p",
"prores_codec_profile": "PRORES_422_PROXY"
}

The details of each of the parameters are below:

ParameterRequiredDescription
inputRequiredFull path to input file available directly to container
outputRequiredOutput file path directly writable to container
isize_precodingRequiredPrecoder model to use. Accepts: PRECODER_LOW, PRECODER_BAL, PRECODER_ADAPTIVE
isize_use_gpuOptionalAvailable only on a GPU instance, otherwise queued jobs will fail. Accepts: TRUE, FALSE. Default: FALSE
codecRequiredThe codec to use. Accepts: Y4M, VP9, AV1, PRORES. With additional codec activation (see below) also accepts: H_264, H_264_M4V, MPEG2VIDEO, H_265
bitrateRequiredEncoding bitrate in kbps. Example: 5000 is 5Mbps. Ignored for codec=PRORES
widthOptionalAccepts ‘source’ or valid numerical width
heightOptionalAccepts ‘source’ or valid numerical height
gopRequiredKeyfram interval. Accepts: 1-10000
pix_fmtOptionalOutput pixel format. Accepts: yuv420p or yuv420p10le. Ignored for codec=PRORES
prores_codec_profileOptionalOnly required when codec=PRORES. Accepts: PRORES_422_PROXY, PRORES_422_LT, PRORES_422, PRORES_422_HQ, PRORES_444, PRORES_444_XQ

Returns:

HTTP return codeResponseDescription
201{“input”:”input_file”, “job_id”: created_id, “output”:”output_file”}Job successfully submitted and queued for processing
400{“input”:”input_file”, “error”: “Text description of error”}There was an error queuing the job. Please check the “error” text on how to fix this

 

REST API function ‘list jobs’

Get the list of jobs from the queue. GET /isize Returns:

HTTP return codeResponseDescription
200{“job_id”:”job_id”, “input”:”input_file”, “isize_precoding”:”isize_precoding_model_used”, “codec”:”codec_used”, “status_text”:”status_of_job”, “progress”:”progress_counter”, “start_time”:”start_time YYYY-MM-DD HH:mm:ss”, “update_time”:”update_time YYYY-MM-DD HH:mm:ss”, “end_time”:”end_time YYYY-MM-DD HH:mm:ss”}Returns blank if job queue is empty or an array of jobs. This retuns queued jobs, active jobs as well as completed jobs.

REST API function ‘list job’

Get the details of a single job from the queue. GET /isize/job_id Returns:

HTTP return codeResponseDescription
200{“job_id”:”job_id”, “input”:”input_file”, “output”:$encode_dst_url, “isize_precoding”:”isize_precoding_model_used”, “isize_use_gpu”:$encode_use_gpu, “codec”:”codec_used”, “bitrate”:”encode_bitrate_used”, “width”:”output_width”, “height”:”output_height”, “gop”:”keyframe_interval”, “pix_fmt”:”pixel_format_used”, “prores_codec_profile”:”prores_profile_used”, “status_text”:”status_of_job”, “progress”:”progress_counter”, “start_time”:”start_time YYYY-MM-DD HH:mm:ss”, “update_time”:”update_time YYYY-MM-DD HH:mm:ss”, “end_time”:”end_time YYYY-MM-DD HH:mm:ss”}Returns complete details about the job.
404{“error”:”Invalid Job ID”}The specified job ID is not valid

 

REST API function ‘delete job’

Delete an already completed job or a queued job. You can’t delete in-progress jobs. DELETE /isize/job_id Returns:

HTTP return codeResponseDescription
200{“success”:”Job Deleted”}Job deleted successfully
404{“error”:”Invalid Job ID”}The specified job ID is not valid

 

REST API function ‘enable additional codecs’

Out of the box, the iSIZE precoder supports Y4M, VP9, AV1 and PRORES codec. You can sent POST request to activate optional additional components (H_264, H_264_M4V, MPEG2VIDEO, H_265). By running the POST activate_encoders command, the below list of optional software components will be installed and activated in the container. Please note that, by running this activation command, you are accepting their corresponding licenses: x264 source & license: https://code.videolan.org/videolan/x264/ x264 config: –enable-shared –enable-pic –bit-depth=all –chroma-format=all x265 source & license: https://github.com/videolan/x265 x265 config: default (from x265/build/linux/multilib.sh) FFmpeg souce & license: https://github.com/FFmpeg/FFmpeg FFmpeg config: –disable-stripping –enable-swresample –enable-libopus –enable-libvorbis –enable-libvpx –enable-libvmaf –enable-gnutls –enable-libaom –enable-libsvtav1 –pkg-config-flags=”–static” –enable-shared –enable-gpl –enable-libx264 –enable-libx265.

The POST request to activate these optional additional components is:

POST /codec

The JSON message format used is:

{ 
"enable_codecs":"TRUE" 
}

Returns:

HTTP return codeResponseDescription
200{“success”:”Codec enabling in place. This may take up to 10 minutes. Please wait 10 minutes before sending additional requests.”}Optional additional codec support is being activated. Please wait 10 minutes before sending any new job requests. You only need to enable optional codecs once per running container.
400{“errir”:”Invalid request”}The request was not sent properly. Please recheck if the submitted JSON value enable_codec is TRUE.

 

Sample ECS configuration JSON

The JSON file below can be customized and used to setup and run iSIZE precoder engine container in ECS. Please make sure you set up appropriate volumes and mount points.

{
    "requiresCompatibilities": [
        "EC2"
    ],
    "inferenceAccelerators": [],
    "containerDefinitions": [
        {
            "name": "isize_precoder",
            "image": "<CONTAINER_PATH>",
            "memoryReservation": "20000",
            "resourceRequirements": null,
            "essential": true,
            "portMappings": [
                {
                    "hostPort": "8000",
                    "containerPort": "8000",
                    "protocol": "tcp"
                }
            ],
            "environment": null,
            "environmentFiles": [],
            "secrets": null,
            "mountPoints": [
                {
                    "sourceVolume": "isize_shared_folder",
                    "containerPath": "/isize_files",
                    "readOnly": ""
                }
            ],
            "volumesFrom": null,
            "hostname": null,
            "user": null,
            "workingDirectory": null,
            "extraHosts": null,
            "logConfiguration": null,
            "ulimits": null,
            "dockerLabels": null,
            "dependsOn": null,
            "repositoryCredentials": {
                "credentialsParameter": ""
            }
        }
    ],
    "volumes": [
        {
            "name": "isize_shared_folder",
            "host": {
                "sourcePath": "/home/ec2-user"
            }
        }
    ],
    "networkMode": null,
    "memory": "30Gb",
    "cpu": null,
    "placementConstraints": [],
    "family": "isize-task",
    "tags": []
}

Technical Support

If you need additional assistance please contact info@isize.co.