Stream Smart™ REST API

Submit a new FFmpeg optimization

POST /ffmpeg

To create an optimized encoding using FFmpeg, send a POST request to /ffmpeg.

Use an FFmpegRequest to specify the FFmpeg command(s) you use to produce your desired encoded video(s). Stream Smart supports a number of FFmpeg encoding commands including:

Single-pass constant rate factor (CRF)
Single-pass variable bitrate (VBR)
Multi-pass variable bitrate

Please see the examples to the side for further details.

During optimization, Stream Smart will produce the encoded video(s) using your chosen FFmpeg command (i.e. the anchor video(s)) along with the optimized encoded video(s) (i.e. the result(s)) which have been created to achieve the same target quality using fewer bits.

Request body

application/json

FFmpegRequest

Examples

Responses

201 Created

Body

application/json

FFmpegResponse

Ex. 1

Ex. 2

Ex. 3

FFmpeg using VBR

curl -X POST "http://localhost/ffmpeg"  \
 -H "Content-Type: application/json"  \
 -d '{
    "title": "Tears of Steel",
    "config": {
        "inputLocation": {
            "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
            "storageLocation": {
                "type": "S3",
                "name": "reference-assets"
            }
        },
        "encodes": [
            {
                "commands": [
                    "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
                ],
                "outputLocation": {
                    "path": "example/output/path/encoded_video.mp4",
                    "storageLocation": {
                        "type": "S3",
                        "name": "reference-assets"
                    }
                }
            }
        ]
    }
}'

FFmpeg using multipass VBR

curl -X POST "http://localhost/ffmpeg"  \
 -H "Content-Type: application/json"  \
 -d '{
    "title": "Tears of Steel",
    "config": {
        "inputLocation": {
            "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
            "storageLocation": {
                "type": "S3",
                "name": "reference-assets"
            }
        },
        "encodes": [
            {
                "commands": [
                    "ffmpeg -i {INPUT_LOCATION} -passlogfile {TEMP_FILE_1} -fps_mode cfr -s 1920x1080 -aspect 1.778 -pix_fmt yuv420p -y -f mp4 -movflags +faststart -profile:v high -preset slow -pass 1 -vcodec libx264 -bf 0 -refs 4 -b:v 8000k -maxrate:v 12000k -bufsize:v 18000k -minrate:v 8000k -tune animation -x264opts rc-lookahead=48:keyint=96:stitchable=1 -keyint_min 48 -g 96 -force_key_frames \\"expr:eq(mod(n,48),0)\\" -an -sn -dn -map_chapters -1 -hide_banner -loglevel info -nostdin -copyts -start_at_zero -max_delay 0 -max_muxing_queue_size 1024 -an /dev/null",
                    "ffmpeg -i {INPUT_LOCATION} -passlogfile {TEMP_FILE_1} -fps_mode cfr -s 1920x1080 -aspect 1.778 -pix_fmt yuv420p -y -f mp4 -movflags +faststart -profile:v high -preset slow -pass 2 -vcodec libx264 -bf 0 -refs 4 -b:v 8000k -maxrate:v 12000k -bufsize:v 18000k -minrate:v 8000k -tune animation -x264opts rc-lookahead=48:keyint=96:stitchable=1 -keyint_min 48 -g 96 -force_key_frames \\"expr:eq(mod(n,48),0)\\" -an -sn -dn -map_chapters -1 -hide_banner -loglevel info -nostdin -copyts -start_at_zero -max_delay 0 -max_muxing_queue_size 1024 -an {OUTPUT_LOCATION}"
                ],
                "outputLocation": {
                    "path": "example/output/path/encoded_video.mp4",
                    "storageLocation": {
                        "type": "S3",
                        "name": "reference-assets"
                    }
                }
            }
        ]
    },
    "ssimwaveInternal": {
        "lastStep": "scoreoptimized"
    }
}'

FFmpeg using single command CRF

curl -X POST "http://localhost/ffmpeg"  \
 -H "Content-Type: application/json"  \
 -d '{
    "title": "Tears of Steel",
    "config": {
        "inputLocation": {
            "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
            "storageLocation": {
                "type": "S3",
                "name": "reference-assets"
            }
        },
        "encodes": [
            {
                "commands": [
                    "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \\"ref=3:bframes=3:b_adapt=2:keyint=48:keyint_min=48:scenecut=0\\" -profile:v high -level:v 4.1 -preset slow -crf 23 -b:v 4000k -maxrate 6000k -bufsize 8000k -an {OUTPUT_LOCATION}"
                ],
                "outputLocation": {
                    "path": "example/output/path/encoded_video.mp4",
                    "storageLocation": {
                        "type": "S3",
                        "name": "reference-assets"
                    }
                }
            }
        ]
    }
}'

Customized configuration for the FFmpeg encoder.

Object

Example:

{
    "inputLocation": {
        "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
        "storageLocation": {
            "type": "S3",
            "name": "reference-assets"
        }
    },
    "encodes": [
        {
            "commands": [
                "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
            ],
            "outputLocation": {
                "path": "example/output/path/encoded_video.mp4",
                "storageLocation": {
                    "type": "S3",
                    "name": "reference-assets"
                }
            }
        }
    ]
}

inputLocation

ReferenceAsset

Used to specify details about the location and name of the reference asset to be optimized.

encodes

Array

An array of FFmpeg encoding commands to apply to the given reference asset and output locations in which to store the encoded videos.

Object

commands

Array of string

The FFmpeg encoding commands to apply to the given reference asset. Within each command, you reference the input location of the reference asset using {INPUT_LOCATION} and the output location of the encoded video using {OUTPUT_LOCATION}.

Example:

[
    "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
]

outputLocation

OutputLocation

The output location in which to store the encoded videos.

string

Types: FFmpegRequest

Represents the body of a request sent to the /ffmpeg endpoint.

Object

Example:

{
    "title": "Tears of Steel",
    "config": {
        "inputLocation": {
            "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
            "storageLocation": {
                "type": "S3",
                "name": "reference-assets"
            }
        },
        "encodes": [
            {
                "commands": [
                    "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
                ],
                "outputLocation": {
                    "path": "example/output/path/encoded_video.mp4",
                    "storageLocation": {
                        "type": "S3",
                        "name": "reference-assets"
                    }
                }
            }
        ]
    }
}

title

string

The title of the content being optimized.

Example:

Tears of Steel

config

FFmpegConfig

Captures the FFmpeg configuration, principally the FFmpeg enconding command(s).

ssimwaveInternal

SSIMWAVEInternal

An optional object used to capture various configuration options that apply to the optimization algorithms. Please consult your Stream Smart representative for more details on the applicability of this object for your use case.

Methods: Submit a new FFmpeg optimization

Types: FFmpegResponse

The location to save the output optimized asset(s) to.

Object

Example:

{
    "path": "example/output/path/encoded_video.mp4",
    "storageLocation": {
        "type": "S3",
        "name": "reference-assets"
    }
}

path

string required

Path in which to store the video file(s).

Example:

example/output/path/encoded_video.mp4

storageLocation

StorageLocation required

The location that the specified video is stored at.

Types: FFmpegConfig

Object

Example:

{
    "x1": 30,
    "x2": 50,
    "y1": 1,
    "y2": 2.5
}

x1

number

Default:

30

x2

number

Default:

50

y1

number

Default:

0

y2

number

Default:

2.5

Types: SSIMWAVEInternal

Represents the reference or mezzanine video asset in the system and is the source for the encoding operation.

Object

Example:

{
    "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
    "storageLocation": {
        "type": "S3",
        "name": "reference-assets"
    }
}

key

string required

The full key for the video file in the StorageLocation

Example:

sources/tearsofsteel/tearsofsteel_4k.mov

storageLocation

StorageLocation required

The location of the specified video.

Types: FFmpegConfig

An object that can be used to capture various configuration options that apply to the optimization algorithms. Please consult your Stream Smart representative for more details on the applicability of this object for your use case(s).

Object

Example:

{
    "qualityDelta": {
        "x1": 30,
        "x2": 50,
        "y1": 1,
        "y2": 2.5
    },
    "rateControlOverride": [
        ""
    ],
    "segmentScoreMethod": "persecondslidingwindowminimum",
    "scoreMetric": "eps",
    "lastStep": "stitch",
    "copyEncodeLocation": "",
    "bandingQualityDelta": {
        "x1": 65,
        "x2": 85,
        "y1": 8,
        "y2": 4
    },
    "displayDevice": "oled65c9pua",
    "optimizationMode": {
        "type": "bitrate-savings",
        "config": {}
    }
}

qualityDelta

QualityDelta

Acceptable delta in quality from the anchor encode

Default:

{
    "x1": 30,
    "x2": 50,
    "y1": 0,
    "y2": 2.5
}

rateControlOverride

Array of string

Override dynamically chosen Rate Control values with this list

Default:

[
]

segmentScoreMethod

string

Enumeration:

averagepersecondminimum

average

persecondslidingwindowminimum

Default:

persecondslidingwindowminimum

scoreMetric

string

Enumeration:

eps

vmaf

svs

Default:

eps

lastStep

string

Enumeration:

encode

score

stitch

scoreoptimized

Default:

stitch

copyEncodeLocation

string

bandingQualityDelta

Object

x1

number

Default:

65

x2

number

Default:

85

y1

number

Default:

8

y2

number

Default:

4

displayDevice

string

Default:

oled65c9pua

optimizationMode

Object

type

string

Enumeration:

bitrate-savings

target-quality

Default:

bitrate-savings

config

Object

Types: FFmpegRequest

This specifies a storage location for a video asset.

Object

Example:

{
    "type": "S3",
    "name": "reference-assets"
}

type

StorageLocationType required

The type of storage being used (ie: S3)

Example:

S3

name

string required

The name of the S3 bucket

Example:

reference-assets

Types: OutputLocation ReferenceAsset

The type of storage to use.

string

Enumeration:

S3

Amazon S3

Example:

S3

Types: StorageLocation

Represents the response from a succesful POST to the /ffmpeg endpoint.

All of

Example:

{
    "title": "Tears of Steel",
    "config": {
        "inputLocation": {
            "key": "sources/tearsofsteel/tearsofsteel_4k.mov",
            "storageLocation": {
                "type": "S3",
                "name": "reference-assets"
            }
        },
        "encodes": [
            {
                "commands": [
                    "ffmpeg -r 24 -i {INPUT_LOCATION} -pix_fmt yuv420p -color_primaries bt709 -color_trc bt709 -colorspace bt709 -color_range mpeg -c:v libx264 -x264-params \"ref=3:bframes=3:b_adapt=2:keyint=50:keyint_min=50:scenecut=0:stitchable=1\" -profile:v high -level:v 4.1 -b:v 5000k -maxrate 6250k -bufsize 10000k -r 24 -vf scale=1920x1080 -an {OUTPUT_LOCATION}"
                ],
                "outputLocation": {
                    "path": "example/output/path/encoded_video.mp4",
                    "storageLocation": {
                        "type": "S3",
                        "name": "reference-assets"
                    }
                }
            }
        ]
    },
    "id": "04a2e841-9c9e-4f50-9f9f-4a8b847f5b3e"
}

FFmpegRequest

Object

id

string

The UUID that represents the analysis that was done as part of the optimization process.

Example:

04a2e841-9c9e-4f50-9f9f-4a8b847f5b3e

Methods: Submit a new FFmpeg optimization