Source Media Locations

A source media file must be specified only for AddMedia and AddMediaBenchmark actions.

Media Sources can be specified in a number of ways:

  • As a valid URL (simple string).
  • As a more complex set of parameters such as several URLs, and audio and video stream mapping parameters.
  • Blank Frame insertion.
<?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>
        <!-- Source params -->
    </source>
    <source>
        <!-- Blank Frames params -->
    </source>
    <format> <!-- required -->
        <!-- Format params --> 
    </format>
</query>
{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "AddMedia",  // required
        "source": [ // required
            "[SourceFile1]", 
            {
                "url": "[SourceFile2]"
                // Source params
            },
            {
                // Blank Frames params
            }
        ],
        "format": { // required
            // Format params
        }
    }
}

Supported source media locations.

Source Location

Request Format

HTTP(s) Server

• http(s)://[user[:password]@]hostname[:port]/[path]/[filename]

FTP / SFTP Server

FTP is likely to only work with servers that support passive mode and appropriate firewall settings. We strongly recommend SFTP instead of FTP.

• ftp://[user[:password]@]hostname[:port]/[path]/[filename][?passive=yes]
• sftp://[user[:password]@]hostname[:port]/[path]/[filename]

Amazon Web Services (S3)

• http(s)://[bucket].s3.amazonaws.com/[filename]
• http(s)://[AWS_KEY:[email protected]][bucket].s3.amazonaws.com/[filename]
• http(s)://[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 NOTE: URL must be signed for GET.
• http(s)://[bucket].s3.amazonaws.com/[filename]?assume_role=[AssumedRoleUser]
— Assume Role for the specified user.

Rackspace CloudFiles

• http(s)://[RS_USER:[email protected]]storage.cloudfiles.com/[path]/[filename]
• http(s)://storage4.clouddrive.com/v1/MossoCloudFS_cea19775-aa94-4d78-8da9-1a7b4bbbd548/container_name/file.ext?auth-token=c2633419-7b79-3d58-8417-d63666dddfd5 — Virtual URL for Cloud Files. Sample below with authentication tomdashken.

Aspera Server

• fasp://[user[:password]@]hostname[:port]/[path]/[filename]

Microsoft Azure Blob

• http(s)://[access_key]@[account].blob.core.windows.net/[container]/[path]
• http(s)://[account].blob.core.windows.net/[container]/[path]?sig=[Signature]&se=[SignedExpiry]&sv=[SignedVersion]&sp=[SignedPermissions]&sr=[SignedResource]

OpenStack Cloud Storage

• http(s)://[user[:password]@]storage.[region].oraclecloud.com/v1/[service-endpoint]/[container]/[object] — Oracle cloud storage:
• swift://[user[:password]@]hostname[:port]/v1/[tenant]/[container]/[object] – Swift tempauth(v1)
• swift://[user[:password]@]hostname[:port]/v2.0/[tenant]/[container]/[object] – Swift identity (v2)

RTMP

• rtmp://[user[:password]@]hostname[:port]/[path]

S3 NetApp

• s3://[KEY[:SECRET]@]hostname[:PORT]/[path]

Pre-Signed Amazon AWS S3 URL query parameters

Parameter

Description

X-Amz-Algorithm

Signature algorithm.

X-Amz-Credential

Access Key and Scope

X-Amz-Date

Signature date in format "yyyyMMddTHHmmssZ"

X-Amz-Expires

Expiration time in seconds

X-Amz-SignedHeaders

Headers list separated with ";" sign

X-Amz-Signature

Signature hash

Pre-Signed Microsoft Azure Blob URL query parameters

Parameter

Description

sig

Signature hash

se

Signature expiration date in one of the ISO 8601 UTC formats

sv

Signature service version

sp

Permitted operations on the signed blob resource. Permissions may be combined.

sr

Signed blob resource type

👍

For FTP URL.

Adding ?passive=yes to the FTP URL forces transfer use Passive Mode for FTP.
The default is no, but this can be specified explicitly with ?passive=no.

Parameter ?disable-epsv in source URL disables extended passive mode.

👍

For Amazon S3

  • If you don't specify an AWS key/secret, the object must have READ permission for AWS user
    1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869 (or for all users).
    See Amazon S3 ACL for details.

  • If you need your S3 files to be accessed with your own AWS credentials, add your AWS key/secret to the URL. If you use the Access key and Secret key, they must be distinctly URL encoded. For example, if your Key and the Secret are:

    1ZG3YAKJ8W0VOA9L7WT6lQT5MsQLirc8owb:SxX/9EhU4M+QarasFelQ0v2M

First, we must URL encode the Secret as it contains special characters: ':' , '/', and '+'. The URL encoded Secret is now:

lQT5MsQLirc8owb%3ASxX%2F9EhU4M%2BQarasFelQ0v2M

You should NOT URL encode the colon between Key and Secret nor the '@' after them. So, the destination URL will be:
http://1ZG3YAKJ8W0VOA9L7WT6:lQT5MsQLirc8owb%3ASxX%2F9EhU4M%[email protected]/v/encoded/

Keep in mind the above URL encoding requirements are in addition to the full XML/JSON document urlencode when POSTing the request to our API.

  • Using specific S3 endpoints:
    To use specific endpoint replace ‘s3.amazonaws.com‘ in your S3 URL with one of the following:

  • us-east-1s3-external-1.amazonaws.com

  • us-east-2s3-us-east-2.amazonaws.com

  • us-west-2s3-us-west-2.amazonaws.com

  • us-west-1s3-us-west-1.amazonaws.com

  • ca-central-1s3-ca-central-1.amazonaws.com

  • eu-west-1s3-eu-west-1.amazonaws.com

  • eu-west-2s3-eu-west-2.amazonaws.com

  • eu-west-3s3-eu-west-3.amazonaws.com

  • eu-central-1s3-eu-central-1.amazonaws.com

  • ap-southeast-1s3-ap-southeast-1.amazonaws.com

  • ap-southeast-2s3-ap-southeast-2.amazonaws.com

  • ap-northeast-1s3-ap-northeast-1.amazonaws.com

  • ap-northeast-2s3-ap-northeast-2.amazonaws.com

  • ap-south-1s3-ap-south-1.amazonaws.com

  • sa-east-1s3-sa-east-1.amazonaws.com

  • Do not forget to URL encode your AWS_SECRET per above.

  • See percent-encoding for more details on URLencoding.

👍

For Aspera URL

To use private key authentication for Aspera you can include the SetHostKey parameter in your API request

🚧

For Microsoft Azure Blob

The access_key needs to be be url encoded, per the instructions in S3 above.

🚧

For Assume Role

You can use ExternalID when accessing your S3 using AssumeRole.
To do that, please visit your account page in the UI. In the section "AWS Assume Role External ID" either generate a new External ID or copy an existing one, and then set up your AssumeRole policy so that it requires ExternalID.