API docs by Redocly

m2a-connect-capture-api (1)

Download OpenAPI specification:Download

The M2A Connect Capture service allows you to provision resources to capture an MPEG Transport Stream input provided via AWS MediaConnect, and to later request exports of sections of the previously recorded content.

States of a Capture entity

A Capture can be in one of a number of states, most of which can only be controlled by the M2A Connect schedule.

  • CREATING - The state immediately after the Capture has been created, and before underlying resources required to run the capture have been allocated. Once creation has finished, the Capture will automatically switch to the STANDBY state.
  • STANDBY - The state of a capture that is ready to work, but which is not currently doing anything. Costs are not incurred in the STANDBY state. A Capture may be automatically driven from STANDBY state towards the RUNNING state when it is scheduled by an M2A Connect event. Deletion may be requested of a Capture in STANDBY state.
  • STARTING - Intermediate state for a Capture that has been scheduled to start by M2A Connect, but which has not yet become active.
  • RUNNING - A Capture which is active and able to record media, as long as media is flowing on the associated M2A Connect Source. A Capture may be automatically driven from RUNNING state towards the STANDBY state when scheduled by an M2A Connect event.
  • STOPPING - Intermediate state for a capture that has been scheduled to stop by M2A Connect, while underlying cost-incurring resourcers are freed.
  • DELETING - Intermediate state for a capture that was previously in STANDBY state, and which has just been deleted via the API. Once all underlying resources are freed, the Capture resource will disappear.

Note that Captures in the STARTING, RUNNING and STOPPING states will incur AWS running costs; even if no media is actually flowing from the associated M2A Connect Source.

Availability

The Capture service provides for 99.95% availability of the recording facility itself. In order to achieve a higher level of availability and ensure that critical video content gets stored, two different recordings of the same content should be scheduled in different AWS regions, and the calling system should be prepared to attempt to issue export requests against the recording from the other region if the initial request fails due to a gap in the record.

Service quotas

Active resources,

  • Number of concurrent running captures: 40 captures (including STARTING and RUNNING and STOPPING recordings, but excluding STANDBY and DELETING recordings)

API calls,

  • Service-wide rate limit: 10 API calls per second, per organisation

capture

Manage capture sessions

Create a capture record

The creation of a new recording will enable M2A to capture an MPEG Transport Stream being provided via MediaConnect.

Request Body schema: application/json
organisation-id
string (Organisation identifier) ^[a-zA-Z0-9_-]{8,36}$

Unique identifier used for identification of individual organisations in M2A APIs

target-account-id
string (Target account identifier) ^[a-zA-Z0-9_-]{8,36}$

Unique identifier used for identification of individual target account in M2A APIs

connect-source-id
string (Resource identifier) ^[a-zA-Z0-9_-]{8,36}$

Unique identifier used for identification of individual connect source in M2A APIs

event-policy
string (EventPolicy)
Enum: "all" "selected"

The event policy of this entity. To indicate which events for the source should be captured

object (StandardMetadata)

Responses

Request samples

Content type
application/json
{
  • "organisation-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "target-account-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "connect-source-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "event-policy": "all",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "metadata": {
    },
  • "connect-source-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "created": "2020-06-01T17:45:00Z",
  • "updated": "2020-06-01T17:45:00Z",
  • "state": "CREATING",
  • "event-policy": "all",
  • "protocol": "srt-listener",
  • "destination": {
    }
}

Filter capture depending on given parameter

The filtering of captures for a given organisation_id or source_id will help the frontend to display the relevant list of captures to customers.

path Parameters
organisation-id
required
string <uuid>

The ID of the Organisation

connect-source-id
required
string <uuid>

The ID of the Source

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{}

Update Capture by Capture ID

Update an Capture with the matching Capture ID.

path Parameters
capture-id
required
string <uuid>

The ID of the Capture

Request Body schema: application/json
state
string (CaptureState)
Enum: "CREATING" "STANDBY" "STARTING" "RUNNING" "STOPPING" "DELETING"

The workflow-state of this entity. Note that for Recording entities, this does not reflect the state of the source (which may or may not have content flowing into the recording, even if the recording is RUNNING).

event-policy
string (EventPolicy)
Enum: "all" "selected"

The event policy of this entity. To indicate which events for the source should be captured

connect-source-id
string (Resource identifier) ^[a-zA-Z0-9_-]{8,36}$

Unique identifier used for identification of individual connect source in M2A APIs

object (StandardMetadata)

Responses

Request samples

Content type
application/json
{
  • "state": "CREATING",
  • "event-policy": "all",
  • "connect-source-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "metadata": {
    }
}

Get Capture by ID

Get Capture by its ID

path Parameters
capture-id
required
string <uuid>

The ID of the Capture

Responses

Response samples

Content type
application/json
{
  • "id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "metadata": {
    },
  • "connect-source-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "created": "2020-06-01T17:45:00Z",
  • "updated": "2020-06-01T17:45:00Z",
  • "state": "CREATING",
  • "event-policy": "all",
  • "protocol": "srt-listener",
  • "destination": {
    }
}

Delete Capture by Capture ID

Delete an Capture with the matching Capture ID.

It is only possible to request deletion of a capture that is currently in the STANDBY state. Attempting to delete a resource in any other state will result in an HTTP 405 (method not allowed) error.

Requesting that a Capture be deleted may not immediately make the resource disappear. The resource will initially move to the DELETING state, and it will still be possible to retrieve the resource in this state, i.e. GET-ing the resource will result in an HTTP 200 response. After some time has passed and deletion actions have completed, the capture recource will dissapear from this API and attempts to GET it will result in an HTTP 404 response.

path Parameters
capture-id
required
string <uuid>

The ID of the Capture

Responses

Response samples

Content type
application/json
{
  • "id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "metadata": {
    },
  • "connect-source-id": "3c8e6cb8-d0f7-452f-a6ec-b62ae6a8ab54",
  • "created": "2020-06-01T17:45:00Z",
  • "updated": "2020-06-01T17:45:00Z",
  • "state": "CREATING",
  • "event-policy": "all",
  • "protocol": "srt-listener",
  • "destination": {
    }
}

Retrieve metric data based on parameters

Get metric data from a specified organisation, target account, within a set time range. Metrics can be set as "transport_discontinuity_errors,archive_range_available"

path Parameters
start-time
required
string <date-time>

The start time used for a time range query

end-time
required
string <date-time>

The end time used for a time range query

organisation-id
required
string <uuid>

The ID of the Organisation

target-account-id
required
string <uuid>

The ID of the Target Account

metrics
required
Array of strings

Comma-separated metrics to be queried for stats

Responses

Response samples

Content type
application/json
[
  • {
    }
]