Media Files

Overview

While the MediaCore API facilitates file I/O, it does not directly accept file uploads nor serve file downloads. Instead, this responsibility is offloaded onto services that are dedicated to reliable storage and performant delivery.

Storage

File storage is not tied to any specific location or service. When requesting to upload a file, the client may be directed to upload it to Amazon S3 or an intermediate service that is responsible for processing the file in some way. Therefore the client can make no assumptions about the destination of the upload.

Content Delivery

Media files will be served via a CDN to minimize latency to world-wide audiences. Temporary signed URLs are used to ensure that only authorized access is permitted, so file URLs cannot be cached and should not be shared between users. The best practice is to direct your users to GET /api2/media/(media_id)/files/(file_id)/content so that they can be redirected to a new signed CDN URL that has been generated on the fly.

Embeddable Third-party Content

In addition to uploading and storing files with MediaCore, it is also possible to create files that reference third-party services like YouTube or Vimeo.

Definitions

File Types

The type of a Media File dictates what processing should occur, as well as how the file should be played and/or displayed within MediaCore.

When creating a file via POST /api2/media/(media_id)/files you can specify the type yourself, or we can try to guess the best type based on the extension of the file.

The following types are supported:

video
A file that should be played with a video player.
audio
A file that should be played with an audio player.
doc
A PDF document that should be shown in a document viewer.
image
A primary image to display in the browser.
blob
A file that should not be played or processed at all, it can only be downloaded.
captions

A file containing closed captions for a video. This can be a SRT, WebVTT, or DFXP (XML) file.

Note

When uploading with type captions you must specify the encoded_from_id as the id of the video file that the captions belong to.

Statuses

The status of a Media File indicates its processing state:

uploading
The file has been created, but the complete file has not yet been received.
processing
The file has been uploaded successfully and is requires some processing before it is ready for use.
complete
The file is ready to use.
error
The file failed to upload or process and cannot be used.
aborted
The user abandoned their upload without finishing it.

Lifecycle of an upload

  1. The client creates a MediaFile via POST /api2/media/(media_id)/files. The status of this file will be set to uploading.

  2. If, during the uploading phase, the client abandons their upload for more than 30 minutes, the file will transition to aborted.

  3. If the client completes the upload, the file will transition to the processing status.

    During the processing phase, we may:

    • Validate the contents of the MediaFile, unless the file type is blob.
    • Create one or more encodings of the MediaFile, if applicable.
    • Generate thumbnails for the Media item from the MediaFile, depending on the type of the file.
    • Convert SRT captions to the VTT format.
  1. The processing phase is over when all of the work started therein has been completed (transcript is converted, or new MediaFiles have finished encoding, etc).

    If all of the work was completed successfully, the MediaFile’s status is set to complete.

    If any of the work failed, the MediaFile’s status is set to error.

    At this time, MediaCore will send a webhook notification to your “Encoding completed” URL, if one has been configured in your site’s Notification Settings.

Listing Media Files

GET /api2/media/(media_id)/files

List files associated with a given media item.

Query Parameters:
 
  • type (optional) – One of video, audio, doc, image, or blob. By default, all types of files are returned.
  • status (optional) – Filter for media files with the given status. See Statuses for allowed values. By default, all status are returned.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "items": [
{
  "id": "2153125632",
  "source": "upload",
  "type": "video",
  "container": "mp4",
  "status": "complete",
  "encoding_profile": null,
  "display_name": "The Flipped Classroom Animated Video.mp4",
  "created_on": "2012-12-07T15:35:05Z",
  "modified_on": "2012-12-07T15:40:25Z",
  "height": 720,
  "width": 1280,
  "max_bitrate": 1009,
  "size": 13739844,
  "duration": 285,
  "duration_hms": "00:04:45",
  "encodings": [
    {
      "id": "2153125633",
      "source": "encoding",
      "type": "video"
      "container": "mp4",
      "encoding_profile": "h264.480p",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.480p)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 852,
      "height": 480,
      "max_bitrate": 374,
      "size": 5161943,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125633",
        "content": "/api2/media/123/files/2153125633/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    },
    {
      "id": "2153125634",
      "source": "encoding",
      "type": "video"
      "container": "mp4",
      "encoding_profile": "h264.720p",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.720p)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 1280,
      "height": 720,
      "max_bitrate": 649,
      "size": 8881179,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125634",
        "content": "/api2/media/123/files/2153125634/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    },
    {
      "id": "2153125635",
      "source": "encoding",
      "type": "video",
      "container": "mp4",
      "encoding_profile": "h264.baseline",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.baseline)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 400,
      "height": 224,
      "max_bitrate": 506,
      "size": 6934709,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125635",
        "content": "/api2/media/123/files/2153125635/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    }
  ],
  "links": {
    "self": "/api2/media/123/files/2153125632",
    "content": "/api2/media/123/files/2153125632/cdn",
    "parent": null,
    "media": "/api2/media/123"
  }
}
  ],
  "links": {
    "self": "/api2/media/123/files",
    "prev": null,
    "next": "/api2/media/123/files?_p=2"
  }
}

Fetching a Media File

GET /api2/media/(media_id)/files/(file_id)

Fetch an individual media file.

This will include any encodings that this file may have.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "2153125632",
  "source": "upload",
  "type": "video",
  "container": "mp4",
  "status": "complete",
  "encoding_profile": null,
  "display_name": "The Flipped Classroom Animated Video.mp4",
  "created_on": "2012-12-07T15:35:05Z",
  "modified_on": "2012-12-07T15:40:25Z",
  "height": 720,
  "width": 1280,
  "max_bitrate": 1009,
  "size": 13739844,
  "duration": 285,
  "duration_hms": "00:04:45",
  "encodings": [
    {
      "id": "2153125633",
      "source": "encoding",
      "type": "video"
      "container": "mp4",
      "encoding_profile": "h264.480p",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.480p)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 852,
      "height": 480,
      "max_bitrate": 374,
      "size": 5161943,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125633",
        "content": "/api2/media/123/files/2153125633/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    },
    {
      "id": "2153125634",
      "source": "encoding",
      "type": "video"
      "container": "mp4",
      "encoding_profile": "h264.720p",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.720p)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 1280,
      "height": 720,
      "max_bitrate": 649,
      "size": 8881179,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125634",
        "content": "/api2/media/123/files/2153125634/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    },
    {
      "id": "2153125635",
      "source": "encoding",
      "type": "video",
      "container": "mp4",
      "encoding_profile": "h264.baseline",
      "status": "complete",
      "display_name": "The Flipped Classroom Animated Video.mp4 (h264.baseline)",
      "created_on": "2012-11-16T19:05:30Z",
      "modified_on": "2012-11-16T19:05:40Z",
      "width": 400,
      "height": 224,
      "max_bitrate": 506,
      "size": 6934709,
      "duration": 285,
      "duration_hms": "00:04:45",
      "encodings": null,
      "links": {
        "self": "/api2/media/123/files/2153125635",
        "content": "/api2/media/123/files/2153125635/cdn",
        "parent": "/api2/media/123/files/2153125632",
        "media": "/api2/media/123"
      }
    }
  ],
  "links": {
    "self": "/api2/media/123/files/2153125632",
    "content": "/api2/media/123/files/2153125632/cdn",
    "parent": null,
    "media": "/api2/media/123"
  }
}

Retrieving a Media File Content URL

GET /api2/media/(media_id)/files/(file_id)/content

Retrieve the playback/download URL for the given media file.

Query Parameters:
 
  • ttl (optional) – The number of seconds that the URL should be valid for. After this timeout is reached, a new URL will have to be requested. The maximum allowed value is 3600 seconds (1 hour).
  • json (optional) – If this is defined, return a 200 OK with the CDN URL in JSON instead of responding with a 302 Found redirect to the CDN.

Redirecting to the CDN

Example Response without the json query parameter set:

HTTP/1.1 302 Found
Location: http://files.mediacore.tv/sites/1115/media/471600/h264.720p-0a89265a6bf1dfe237b44c3610696f5e.mp4?__gda__=0123456etc

Retrieving the CDN URL as JSON

Example Response with the json query parameter set:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "location": "http://files.mediacore.tv/sites/1115/media/471600/h264.720p-0a89265a6bf1dfe237b44c3610696f5e.mp4?__gda__=0123456etc"
}

Creating and Uploading Media Files

POST /api2/media/(media_id)/files

Create a Media File.

You have the option to:

  1. Upload a file to our servers.
  2. Reference third-party content on YouTube or Vimeo.
Json Parameters:
 
  • upload_type (optional) – The desired type of this file. See File Types. If this is undefined, the type will be guessed.
  • upload_name (required) – The name of the file you would like to upload. This will be used to set the display_name of the file.
  • upload_size (required) – The size of the file you would like to upload, in bytes.
  • embed_url (optional) – The URL for embeddable third-party party content, if you need to embed a video instead of upload.
  • encoded_from_id (optional) –

    The id of the Media File to associate as the original source for the file being uploaded.

    Note

    This field should only be provided for captions or winnov_asset file types.

Upload Example:

In order to upload a file, you must first request an upload URL:

POST /api2/media/123/files HTTP/1.1
Content-Type: application/json

{
   "upload_type": "video",
   "upload_name": "my-video.mp4",
   "upload_size": 13739844
}

If the file upload is approved, the response will include all the metadata on the newly created Media File, as well as an upload dict that describes how the file should be uploaded:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api2/media/123/files/2153125632

{
  "id": "2153125632",
  "source": "upload",
  "type": "video",
  "container": "mp4",
  "status": "uploading",
  "encoding_profile": null,
  "display_name": "my-video.mp4",
  "created_on": "2012-12-07T15:35:05Z",
  "modified_on": "2012-12-07T15:40:25Z",
  "height": null,
  "width": null,
  "max_bitrate": null,
  "size": 13739844,
  "duration": null
  "duration_hms": null,
  "encodings": null,
  "links": {
    "self": "/api2/media/123/files/2153125632",
    "content": "/api2/media/123/files/2153125632/content",
    "parent": null,
    "media": "/api2/media/123"
  },
  "upload": {
    "protocols": {
      "form_data": {
        "upload_url": "http://api.pandastream.com/upload",
        "upload_file_param": "file",
        "upload_post_params": {},
        "postprocess_url": "https://pacificu.mediacore.tv/api2/media/123/files/2153125632/postprocess-upload"
      }
    }
  }
}

This has created a placeholder for the upload and provided you with the details for sending the file to the upload server. See Upload Protocols for detailed instructions on how to proceed with the upload.

Deleting a Media File

DELETE /api2/media/(media_id)/files/(file_id)

Delete an individual media file and any encodings of it.

This endpoint is idempotent; attempting to delete a media item that does not exist will return a successful response.

Note

This requires the media-delete permission. In addition, users with the media-create permission can delete their own media files for up to 3 hours or until the media item has been published.

Example Response:

HTTP/1.1 204 No Content