Upload content v2

Choose an approach to add your content to your JW Player account.

👍

IMPORTANT

This is a beta offering. By using this documentation, you are agreeing to abide by the terms of the JW Player Beta Program Agreement.


Not all content upload use cases are the same. Sometimes you need to upload multiple, small files from a local machine. Other times, you might be creating an application that uploads videos from a browser. This article explains several approaches to add content to your account while addressing these varied needs.



General

When you upload content to your JW Player account, you must send a POST request with a JSON body to the media endpoint to create a media entity -- your content. The JSON body contains two top-level objects: upload and metadata.

Within the upload object, use method to define the upload approach. The method property must have one of the following values:

  • direct
  • multipart
  • fetch

For some upload approaches, additional information is included within the upload object.

Within the metadata object, you can define descriptive information (for example: title, description, author) about the media you are uploading.

{
    "upload": {
       "method": "direct"
    },
    "metadata:": { 
        "author":"Joe Schmoe",
        "category": "Movies",
        "custom_params":{ 
            "is_film":"true"
        },
        "tags":[ 
            "comedy"
        ],
        "title": "Joe’s adventure",
        "duration": 6000,
        "publish_start_date": "2020-02-20T08:58:26+00:00",
        "publish_end_date": "2021-02-20T08:58:26+00:00",
        "external_id": "1231",
        "description": "Joe goes on an adventure"
   }
}

Media assets must have a minimum duration of 2 seconds.



Upload Methods

JW Player provides the following methods to upload content.

ApproachFile Location & SizeAdditional Notes
Direct Single Upload via S3Location: Local machine

Best for uploading files that are 100 MB or less
Use when the media file is on the local machine

The file should be small enough that retrying the entire file upload is not an issue.
Multipart Resumable UploadLocation: Local machine

Best for uploading files that are 100MB-25GB
Use when the media file is on the local machine

The file should be large enough that retrying the entire upload is an issue. The upload needs to be paused & resumed, or upload progress needs to be reliably reported.
Fetch Upload via URLLocation: Remote

Accommodates files up to 25GB
Use when the media is hosted on another platform and your content needs to be hosted in your JW Player account

📘

File size limitations and recommendations may increase during 2021.


› Direct Single Upload via S3


The direct upload method is the simplest way to get a locally available, smaller (<100MB) file ingested into JW Player's platform. The process involves directly uploading the file to a provided link. Because of this, the direct upload method is not resumable, and network errors will require starting over.


Use the following steps to upload your media:

  1. Make a POST /v2/sites/{site_id}/media call to create a new media object. Within the JSON body, set upload.method to direct and define the metadata of the media item. Refer to the POST /v2/sites/site_id/media/ reference for more information about acceptable metadata body parameters.

    The API call returns a response with the upload_link location.

    In the following sample, only the media item's metadata.title is defined.
curl -X POST https://api.jwplayer.com/v2/sites/{site_id}/media \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json' \
 -d '{ "upload": { "method": "direct" }, "metadata": {"title": "My Uploaded Video"} }'

  1. Upload the local media file to the upload_link location.

    If you included mime_type in the create media request, you must set the Content-Type header on the upload request to the exact same value. Similarly, if you exclude mime_type in the create media request, you must omit the Content-Type header in the upload request.
curl --upload-file {path_to_file} "{upload_link}"

  1. After the uploading process has completed, make a GET /v2/sites/{site_id}/media/{media_id} call to retrieve the media transcoding status.
curl -X GET https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id} \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json'

› Multipart Resumable Upload


When you have a file that is >100 MB in size that you need to upload from your local machine, you should use this approach.

This method has several advantages:

Speed: CDN acceleration and parallelized uploading can decrease the time required to upload.
Resumability: Network failures don't require starting over. Uploading can be paused.
Measurability: Upload progress can be reliably measured.

🚧

Due to the additional requests that this approach uses, additional network overhead will be created on the network where the requests are being made.


Uploading via the multipart method requires several steps:

  1. Make a POST /v2/sites/{site_id}/media call to create a new media object. Within the JSON body, set upload.method to multipart and define the metadata of the media item. Refer to the POST /v2/sites/site_id/media/ reference for more information about acceptable metadata body parameters.

    The API call will return a response with the upload_id and upload_token. These fields will be used to interact with the Upload API.

    In the following sample, only the media item's metadata.title is defined.
curl -X POST https://api.jwplayer.com/v2/sites/{site_id}/media \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json' \
 -d '{ "upload": { "method": "multipart" }, "metadata": {"title": "My Multipart Upload Video"} }'

  1. Determine the number of parts into which the file should be split and the size of each part. For example, if a file is 500MB, you could split the file into 5 MB parts. This means that your part count will be 100 parts. You should choose your part size to optimize either for resumability (smaller part sizes) or reducing network overhead (larger part sizes).

    The minimum size for a part is 5 MB (with the exception of the last part).
    The maximum number of possible parts is 10,000.

  1. Make a GET /v2/uploads/{upload_id}/parts call to get a list of upload parts.

    You can copy the following sample. Be sure to replace the {upload_id} and {upload_token} placeholders with the upload_id and upload_token that you received from API response in step 1. Also, set page_length to the part count. In the example, 100 is used. The API call will return a response that lists 100 parts. Each part will have an upload_link location.
curl 'https://api.jwplayer.com/v2/uploads/{upload_id}/parts?page=1&page_length=100' \
 -H 'Authorization: Bearer {upload_token}' \
 -H 'Content-Type: application/json'

  1. Upload the bytes of the local media file part to the upload_link location. Be sure to replace the {path_to_your_video} with the actual path to the file. Use the following table to define the bs, count, and skip parameters within your request.
ParameterDescription
bsSize of the part in megabytes (M)
countNumber of parts

This should always be 1.
skipNumber of previous uploaded part to jump over

Below is an example of reading 5 MB parts at a time and uploading each part to its respective upload_link.

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=0 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_1}"

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=1 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_2}"

...

dd if=~/{path_to_your_video}.mp4 bs=5M count=1 skip=99 | curl \
  -XPUT -H "Content-Type:" \
  --data-binary @- \
  "{upload_link_100}"

  1. After all parts have been uploaded, make a PUT /v1/uploads/{upload_id}/complete call. This signals to JW Player that all parts have been uploaded.
curl -X PUT \
  -H "Authorization: Bearer {upload_token}" \
  -H "Content-Type: application/json" \
  "https://api.jwplayer.com/v2/uploads/{upload_id}/complete"

📘

TIP

Subsequent calls to GET /v1/uploads/{upload_id}/parts will return both completed and uncompleted parts.

Completed parts will have the etag field set to an MD5 hash of the uploaded part and upload_link field will no longer be present. Counting the number of completed parts is a way of checking the progress of an upload.


  1. Make a GET /v2/sites/{site_id}/media/{media_id} call to retrieve the media transcoding status.
curl -X GET https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id} \
 -H 'Authorization: Bearer {v2_api_secret}' \
 -H 'Content-Type: application/json'

› Fetch Upload via URL


If a media file is already remotely hosted elsewhere (for example in Dropbox, Google, or Amazon) JW Player can ingest this file directly from the source. Using the link to a remotely-hosted file, a fetch upload ingests the media file into your JW Player account.


Fetch uploads are performed with a single request:

Make a POST /v2/sites/{site_id}/media call to create a new media object. Within the upload object of the JSON body, set method to fetch and set download_url to the URL of the media. Within the metadata object of the JSON body, define the metadata of the media item. Refer to the POST /v2/sites/site_id/media/ reference for more information about acceptable metadata body parameters.

The API call will return a response with "status": "processing". This status indicates that the media object was successfully created and that media transcoding has begun.

In the following sample, only the media item's metadata.title is defined.

curl -X POST https://api.jwplayer.com/v2/sites/{site_id}/media \
  -H 'Authorization: Bearer {v2_api_secret}' \
  -H 'Content-Type: application/json' \
  -d '{ "upload": { "method": "fetch", "download_url": "http://LinkToMyVideo.com/video.mp4" }, "metadata": {"title": "My Fetch Video"} }'


Did this page help you?