Release NotesUser InterfaceSystem Status
Recent API Changes
Back to All

13 February 2020

almost 5 years ago by Encoding.com Product Team #2

Advanced Multi-Source Settings

Added ability to set audio mapping parameters in source section.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required -->
    <userkey><<key>></userkey> <!-- required -->
    <action>AddMedia</action> <!-- required -->
    <source>[SourceFile1]</source> <!-- required -->
    <source>
        <url>[SourceFile2]</url>
        <url>[AdditionalSourceFile2]</url>
        <audio_stream>
            <use_stream_id>[SourceMediaAudioStreamID]</use_stream_id>
            <natural_order>[yes|no]</natural_order>
            <language>[Language]</language>
            <channel>
                <id>[OutputChannelID]</id>
                <in>
                    <id>[SourceTrackID:SourceChannelID]</id>
                    <gain>[ChannelGainLevel]</gain>
                </in>
                <in>
                    <!-- Input channel params -->
                </in>
            </channel>
            <channel>
                <!-- Audio channel params -->
            </channel>
            <normalize>[yes|no]</normalize>
            <layout>[AudioLayoutName]</layout>
        </audio_stream>
        <!-- Multiple audio streams -->
        <audio_stream>
            <!-- Audio stream params -->
        </audio_stream>
    </source>
    <source>
        <url>[SourceFile3]</url>
        <!-- Source params -->
    </source>
    <format> <!-- required -->
        <!-- Format params --> 
    </format>
</query>

{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "AddMedia",  // required
        "source": [ // required
            "[SourceFile1]", 
            {
                "url": [
                    "[SourceFile2]",
                    "[AdditionalSourceFile2]"
                ],
                "audio_stream": [
                    {
                        "use_stream_id": "[SourceMediaAudioStreamID]",
                        "natural_order": "[yes|no]",
                        "language": "[Language]",
                        "channel": [
                            {
                                "id": "[OutputChannelID]",
                                "in": [
                                    {
                                        "id": "[SourceTrackID:SourceChannelID]",
                                        "gain": "[ChannelGainLevel]"
                                    },
                                    {
                                        // Input channel params
                                    }
                                ]
                            },
                            {
                                // Audio channel params
                            }
                        ],
                        "normalize": "[yes|no]",
                        "layout": "[AudioLayoutName]"
                    }, 
                    {
                        //Audio stream params
                    }
                ]
            },
            {
                "url": "[SourceFile3]"
                // Source params
            }
        ],
        "format": { // required
            // Format params
        }
    }
}
ParameterDescriptionAllowed ValuesDefault Values
use_stream_idSpecify the source media stream ID.Set of 2 non-negative integer numbers separated by colon sign
e.g. F:S
Where
F – File index (index of <url /> param in <source /> block)
 S – Stream index in source file		none
natural_orderIf set to yes then value of <use_stream_id /> will mean number of source's audio stream, not number of stream in all type streams list.yes, nono
languageSpecify the track language.A language code in 3 lowercase letters according to ISO639-2.none
## Mapping Parameters
normalizeEnable the renormalization output track to avoid clipping noise.yes, nonone
layoutSpecify the output channels layout.One of these channel layouts:
mono — FC
stereo — FL+FR
2.1 — FL+FR+LFE
3.0 — FL+FR+FC
3.0-back — FL+FR+BC
4.0 — FL+FR+FC+BC
quad — FL+FR+BL+BR
quad-side — FL+FR+SL+SR
3.1 — FL+FR+FC+LFE
5.0 — FL+FR+FC+BL+BR
5.0-side — FL+FR+FC+SL+SR
4.1 — FL+FR+FC+LFE+BC
5.1 — FL+FR+FC+LFE+BL+BR
5.1-side — FL+FR+FC+LFE+SL+SR
6.0 — FL+FR+FC+BC+SL+SR
6.0-front — FL+FR+FLC+FRC+SL+SR
hexagonal — FL+FR+FC+BL+BR+BC
6.1 — FL+FR+FC+LFE+BC+SL+SR
6.1 — FL+FR+FC+LFE+BL+BR+BC
6.1-front — FL+FR+LFE+FLC+FRC+SL+SR
7.0 — FL+FR+FC+BL+BR+SL+SR
7.0-front — FL+FR+FC+FLC+FRC+SL+SR
7.1 — FL+FR+FC+LFE+BL+BR+SL+SR
7.1-wide — FL+FR+FC+LFE+BL+BR+FLC+FRC
7.1-wide-side — FL+FR+FC+LFE+FLC+FRC+SL+SR
octagonal — FL+FR+FC+BL+BR+BC+SL+SR
downmix — DL+DR		none
## Output Audio Channel Parameters
idSpecify the output channel ID.Channel number or one of these channel names:
FL — front left
FR — front right
FC — front center
LFE — low frequency
BL — back left
BR — back right
FLC — front left-of-center
FRC — front right-of-center
BC — back center
SL — side left
SR — side right
TC — top center
TFL — top front left
TFC — top front center
TFR — top front right
TBL — top back left
TBC — top back center
TBR — top back right
DL — downmix left
DR — downmix right
WL — wide left
WR — wide right
SDL — surround direct left
SDR — surround direct right
LFE2 — low frequency 2		none
## Input Audio Channel Parameters
idSpecify input audio channel ID.Set of 3 non-negative integer numbers separated by colon sign
e.g. F:S:C
Where
F – File index (index of <url /> param in <source /> block)
 S – Stream index in source file
* C – Channel index in audio stream		none
gainSepcify the input audio channel gain level.Float positive number from 0 to 1none

Overlay Fade In/Out

Added parameters to apply fade in and out effects for overlays.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <source>[SourceFile]</source> <!-- required-->
    <format>
        <!-- Format params -->
        <overlay>
            <overlay_start>[Overlay1StartInSeconds]</overlay_start>
            <overlay_duration>[Overlay1DurationInSeconds]</overlay_duration>
            <overlay_fade_in>[Overlay1FadeInInSeconds]</overlay_fade_in>
            <overlay_fade_out>[Overlay1FadeOutInSeconds]</overlay_fade_out>
            <!-- Video overlay params -->
        </overlay>
        <!-- ... -->
        <overlay>
            <!-- Video overlay params -->
        </overlay>
        <audio_overlay>
            <overlay_start>[Overlay1StartInSeconds]</overlay_start>
            <overlay_duration>[Overlay1DurationInSeconds]</overlay_duration>
            <overlay_fade_in>[Overlay1FadeInInSeconds]</overlay_fade_in>
            <overlay_fade_out>[Overlay1FadeOutInSeconds]</overlay_fade_out>
            <!-- Audio overlay params -->
        </audio_overlay>
        <!-- ... -->
        <audio_overlay>
            <!-- Audio overlay params -->
        </audio_overlay>
        <text_overlay>
            <overlay_start>[Overlay1StartInSeconds]</overlay_start>
            <overlay_duration>[Overlay1DurationInSeconds]</overlay_duration>
            <overlay_fade_in>[Overlay1FadeInInSeconds]</overlay_fade_in>
            <overlay_fade_out>[Overlay1FadeOutInSeconds]</overlay_fade_out>
            <!-- Text overlay params -->
        </text_overlay>
        <!-- ... -->
        <text_overlay>
            <!-- Text overlay params -->
        </text_overlay>
    </format>
</query>

{
    "query": {
        "userid": "sdf", // required
        "userkey": "sdf", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "format": {
            "overlay": [
                {
                    "overlay_start": "[Overlay1StartInSeconds]",
                    "overlay_duration": "[Overlay1DurationInSeconds]",
                    "overlay_fade_in": "[Overlay1FadeInInSeconds]",
                    "overlay_fade_out": "[Overlay1FadeOutInSeconds]"
                    // Video overlay params
                },
                {
                    // Video overlay params
                }
            ],
            "audio_overlay": [
                {
                    "overlay_start": "[Overlay1StartInSeconds]",
                    "overlay_duration": "[Overlay1DurationInSeconds]",
                    "overlay_fade_in": "[Overlay1FadeInInSeconds]",
                    "overlay_fade_out": "[Overlay1FadeOutInSeconds]"
                    // Audio overlay params
                },
                {
                    // Audio overlay params
                }
            ],
            "text_overlay": [
                {
                    "overlay_start": "[Overlay1StartInSeconds]",
                    "overlay_duration": "[Overlay1DurationInSeconds]",
                    "overlay_fade_in": "[Overlay1FadeInInSeconds]",
                    "overlay_fade_out": "[Overlay1FadeOutInSeconds]"
                    // Text overlay params
                },
                {
                    // Text overlay params
                }
            ]
        }
    }
}
ParameterDescriptionAllowed ValuesDefault Value
overlay_startSpecify the overlay's start time in seconds.Positive float value0
overlay_durationSpecify the overlay's duration in seconds.Positive float numbernone
overlay_fade_inOverlay fade-in duration in seconds.Positive float number0
overlay_fade_outOverlay fade-out duration in seconds.Positive float number0

📘

For video overlay fade in and out

If <keep_audio /> in <overlay /> set to yes <overlay_fade_in /> and <overlay_fade_out /> will be applied to audio as well.

Pre-Signed S3 URL As Destination

Added ability to use pre-signed S3 URL as destination.

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <source>[SourceFile]</source> <!-- required-->
    <format>
        <output>[OutputFormat]</output> <!-- required-->
        <destination>[DestinationPath]</destination>
    </format>
</query>

{
    "query": {
        "userid": "sdf", // required
        "userkey": "sdf", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "format": {
            "output": "[OutputFormat]", // required
            "destination": "[DestinationPath]"
        }
    }
}
Destination TypeDescription
Amazon Web Services (S3) http://[bucket].s3.amazonaws.com/[filename]?X-Amz-Algorithm=[Algorithm]&X-Amz-Credential=[Credential]&X-Amz-Date=[Date]&X-Amz-Expires=[Expires]&X-Amz-SignedHeaders=[Headers]&X-Amz-Signature=[Signature]
— Pre-signed S3 Url.

 http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&canonical_id=AWS_CANONICAL_USER_ID
— If you specify AWS canonical user ID in the URL, FULL_CONTROL on the object will be granted to the specified user.

http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&content_type=your-own/content-type
— If you specify Content type, then Amazon will add appropriate Content-type header when the object is accessed via the web.

 http://[bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]&content_disposition=attachment[;%20filename=”file.ext”]
— If you specify Content disposition, then Amazon will add appropriate Content-Disposition header when the object is accessed via the web.

http://[AWS_KEY:AWS_SECRET@][bucket].s3.amazonaws.com/[filename][?acl=public-read | authenticated-read]
— If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL.

 Also, you can add ?acl=public-read OR ?acl=authenticated-read after the filename.
This will explicitly set access rights to the saved object instead of the default settings.

http://[bucket].s3.amazonaws.com/[filename]?cache_control=[string]
— cache_control – Can be used to specify caching behavior along the request/reply chain.

 http://[bucket].s3.amazonaws.com/[filename]?expires=[string]
— expires – The date and time at which the object is no longer cacheable.

* http://[bucket].s3.amazonaws.com/[filename]?extension_content_type[[extension]]=[content\Type]
— If the output format implies multiple files (e.g. HLS) you could specify which content type to use for files with particular extension.

AWS API Gateway URL In Notifications

Added support of AWS API Gateway URL in notifications.

<?xml version="1.0"?>
<query>
    <!-- Main params -->
    <userid><<id>></userid>
    <userkey><<key>></userkey>
    <action>[Action]</action>
    <source>[SourceFile]</source>
    <notify_format>[xml|json]</notify_format>
    <notify>[NotifyURL]</notify>
    <notify_encoding_errors>[NotifyEncodingErrorURL]</notify_encoding_errors>
    <notify_upload>[NotifyUploadURL]</notify_upload>
    <notify_upload_extended>[yes|no]</notify_upload_extended>
    <notify_live_start>[NotifyLiveStartedURL]</notify_live_start>
    <qc_notify>[QCNotifyURL]</qc_notify>
    <format>
        <!-- Format params -->
    </format> 
</query>

{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "notify_format": "[xml|json]",
        "notify": "[NotifyURL]",
        "notify_encoding_errors": "[NotifyEncodingErrorURL]",
        "notify_upload": "[NotifyUploadURL]",
        "notify_upload_extended": "[yes|no]",
        "notify_live_start": "[NotifyLiveStartedURL]",
        "qc_notify": "[QCNotifyURL]",
        "format": [ // required
             {
                 // Format params
             }
        ]
    }
}
HTTP(s) URLhttps://domain.tld/path-to-endpoint
AWS API Gatewayhttps://[Key:Secret]:[ApiID].execute-api.[Region].amazonaws.com/[StageName]/
Emailmailto:[email protected]

🚧

For AWS API Gateway

Credentials in the URL can be omitted. In this case, we will use our credentials to authenticate calls to your API Gateway.

Mpeg2video codec support in MXF

<?xml version="1.0"?>
<query>
    <userid><<id>></userid> <!-- required-->
    <userkey><<key>></userkey> <!-- required-->
    <action>addMedia</action>
    <source>[SourceFile]</source> <!-- required-->
    <format> <!-- required -->
        <output>mxf</output> <!-- required -->
        <video_codec>mpeg2video</video_codec>
    </format>
</query>

{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "addMedia", // required
        "source": "[SourceFile]", // required
        "format": {
            "output": "mxf", // required
            "video_codec": "mpeg2video"
        }
    }
}
ParameterDescriptionAllowed ValuesDefault Values
video_codecDefines the codec used for your output.mxf: dvcpro, dvcpro50, dvcprohd, xdcamhd422, imx30, mpeg2video, copymxf: xdcamhd422