create or update account filter.md
Create or Update Account Filter
Media API · Asset Filters
PUT https://app.mk.io/api/v1/projects/{project_name}/media/accountFilters/{filter_name}
Create or Update Account Filter.
RBAC Capability Required: ams.accountfilter.create or ams.accountfilter.update
Authentication
Authorizationheader — Bearer authentication of the formBearer <token>.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_name |
string | Yes | — |
filter_name |
string | Yes | — |
Request body
Content type: application/json
properties· object · Required — Properties for the account filterfirstQuality· object · Optional — This parameter defines the initial quality level when playback starts. This is the first bitrate in the ladder. If a value is set that does not match the ladder, the closest value will be used. Setting a high value may increase the time it takes to start playback, but ensures that initial video quality is high.bitrate· integer · Required — Denotes the target video bitrate to be used when starting playback of an HLS manifest. The video representation with the bitrate closest to the defined bitrate will be presented first among the available representations in the HLS manifest.
presentationTimeRange· object · Optional — This parameter is used to cut an asset into a smaller asset by specifying a start and end time.endTime· string · Optional · format: date-time — For live content only (including live events that have finished). Indicates the end of the presentation window, likeendTimestampbut as an explicit UTC time.endTimestamp· integer · Optional · >=0 — For both VOD and live content. Indicates the end of the presentation window, in units of timescale. Given a timescale of "1", a value of "N" set here will constrain the video manifest to contain exactly "N" seconds of content. This value is relative to the actual start of the content, not the startTimestamp. Examples: - timescale=1, startTimestamp=0, endTimestamp=10: The first 10 seconds of content will be included in the output. - timescale=1, startTimestamp=10, endTimestamp=70: The 60 seconds of content starting at 10 seconds will be included in the output. - timescale=10000000, startTimestamp=0, endTimestamp=100000000: The first 10 seconds of content will be included in the output. In cases where the endTimestamp does not perfectly align with a segment boundary, the endTimestamp will be rounded down to the nearest segment boundary.forceEndTimestamp· boolean · Optional — A validation parameter. When set, requires that the filter endTimestamp be set. This might be useful to limit the duration of a locator associated with a long-running live event, once the live event has ended and the video manifest is closed.liveBackoffDuration· integer · Optional — For live content only (including live events that have finished). Truncates content from the head of a live video manifest by the specified duration. In effect, setting this value creates a buffer between the client and the true live point by omitting content from the head of a manifest. This is a useful capability in cases where CDN latency and other "network realities" make it difficult to deliver a true live experience, and result in content being presented in the manifest that is not yet available in caches. For example, if you set this value to 30 seconds, the client will see a manifest that is 30 seconds behind the true live point. This means that the client will not be able to play the first 30 seconds of content, but will be able to play the content that is 30 seconds old and newer. The maximum live backoff duration is 300 seconds.presentationWindowDuration· integer · Optional — For live content only (including live events that have finished). Indicates the duration of the presentation window, in units of timescale. A presentation window is the depth of content present in the live manifest. For example, if you set this value to 300 seconds, the client will see a manifest containing 300 seconds of content, even if the underlying asset is much longer. This is useful for restricting playback to the very latest content, or for restricting seek positions in content. The minimum presentation window duration is 10 seconds.startTime· string · Optional · format: date-time — For live content only (including live events that have finished). Indicates the start of the presentation window, likestartTimestampbut as an explicit UTC time.startTimestamp· integer · Optional · >=0 — For both VOD and live content. Indicates the start of the presentation window, in units of timescale. Given a timescale of "1", a value of "N" set here will clip the first "N" seconds of content from the beginning of the video manifest. Examples: timescale=1, startTimestamp=0, endTimestamp=10: The first 10 seconds of content will be included in the output. timescale=1, startTimestamp=10, endTimestamp=70: The 60 seconds of content starting at 10 seconds will be included in the output. timescale=10000000, startTimestamp=0, endTimestamp=100000000: The first 10 seconds of content will be included in the output. In cases where the startTimestamp does not perfectly align with a segment boundary, the endTimestamp will be rounded down to the nearest segment boundary.timescale· integer · Optional · 1 to 1000000000 · Defaults to 10000000 — Defines the unit of time for all the values in this object. The value is expressed in ticks per second. The default value of 10,000,000 increments per second (or 10 MHz) is used if this parameter is not specified. IF you're a video engineer doing Serious Business, consider setting this to 48,000 or 90,000 representing 90Khz and 48Khz respectively. If you're a mere mortal, a value of 1 is sensible and would represent seconds. For example, with a timescale set to "1", the startTimestamp and endTimestamp values are expressed in seconds. So a startTimestamp of 10 and an endTimestamp of 20 would represent a 10 second window of content. Segments overlapping this window would be included in the output.
tracks· list of objects · Optional — Defines the tracks to include in the output. If multiple FilterTrackSelection objects are provided, their configurations will be OR'd together. For instance, if you want to include all audio tracks that are not English, and all video tracks that are between 3 and 5 Mbps, you would provide two FilterTrackSelection objects.- Array items (object):
trackSelections· list of objects · Required — Defines the tracks to include in the output. Multiple entries here will be AND'd together. Typically, you will want to select a matching Type, such as video, and then select additional filters. For instance, to include all audio tracks that are not English, and all video tracks that are between 3 and 5 Mbps, you would provide three FilterTrackSelection objects: ```json [ {"property": "Type", "operation": "Equal", "value": "Audio"}, {"property": "Bitrate", "operation": "Equal", "value": "3000000-5000000"}, {"property": "Language", "operation": "NotEqual", "value": "en"}]
- Array items (object):
- Array items (object):
- `operation` · enum · **Required** — Set to either 'Equal' or 'NotEqual'. Tracks matching this predicate will be included. Examples: To include all audio tracks, set operation to 'Equal', property to 'Type', and value to 'Audio'.
- Allowed values: `Equal`, `NotEqual`
- `property` · enum · **Required** — The property to match against. Supported properties include: Bitrate, FourCC, Language, Name, Type, and Unknown. - Bitrate may be provided as a single numeric value '100000' or as a range '500000-1000000'. - FourCC is the codec, and may be one of 'avc1', 'hev1', and 'hvc1' for video, or one of 'mp4a' and 'ec-3' for audio. - Language is the value of a language tag to include, as specified in RFC 5646. - Name is the name of the track as specified in the manifest. - Type is one of either 'video', 'audio', or 'text'.
- Allowed values: `Unknown`, `Type`, `Name`, `Language`, `FourCC`, `Bitrate`
- `value` · string · **Required** — The value to match against. Values are not case-sensitive.
## Example request
```bash
curl -X PUT "https://app.mk.io/api/v1/projects/{project_name}/media/accountFilters/{filter_name}" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"properties": {
"firstQuality": {
"bitrate": 0
},
"presentationTimeRange": {
"endTime": "2024-01-01T00:00:00Z",
"endTimestamp": 0,
"forceEndTimestamp": true,
"liveBackoffDuration": 0,
"presentationWindowDuration": 0,
"startTime": "2024-01-01T00:00:00Z",
"startTimestamp": 0,
"timescale": 10000000
},
"tracks": [
{
"trackSelections": [
{
"operation": "Equal",
"property": "Unknown",
"value": "string"
}
]
}
]
}
}'
Responses
200 — Account Filter was updated
id· string · Optional — Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}name· string · Optional · 1-260 characters · pattern: ^[^9<>%&:?/*+]+$ — The name of the resourceproperties· object · Required — Properties for the account filterfirstQuality· object · Optional — This parameter defines the initial quality level when playback starts. This is the first bitrate in the ladder. If a value is set that does not match the ladder, the closest value will be used. Setting a high value may increase the time it takes to start playback, but ensures that initial video quality is high.bitrate· integer · Required — Denotes the target video bitrate to be used when starting playback of an HLS manifest. The video representation with the bitrate closest to the defined bitrate will be presented first among the available representations in the HLS manifest.
presentationTimeRange· object · Optional — This parameter is used to cut an asset into a smaller asset by specifying a start and end time.endTime· string · Optional · format: date-time — For live content only (including live events that have finished). Indicates the end of the presentation window, likeendTimestampbut as an explicit UTC time.endTimestamp· integer · Optional · >=0 — For both VOD and live content. Indicates the end of the presentation window, in units of timescale. Given a timescale of "1", a value of "N" set here will constrain the video manifest to contain exactly "N" seconds of content. This value is relative to the actual start of the content, not the startTimestamp. Examples: - timescale=1, startTimestamp=0, endTimestamp=10: The first 10 seconds of content will be included in the output. - timescale=1, startTimestamp=10, endTimestamp=70: The 60 seconds of content starting at 10 seconds will be included in the output. - timescale=10000000, startTimestamp=0, endTimestamp=100000000: The first 10 seconds of content will be included in the output. In cases where the endTimestamp does not perfectly align with a segment boundary, the endTimestamp will be rounded down to the nearest segment boundary.forceEndTimestamp· boolean · Optional — A validation parameter. When set, requires that the filter endTimestamp be set. This might be useful to limit the duration of a locator associated with a long-running live event, once the live event has ended and the video manifest is closed.liveBackoffDuration· integer · Optional — For live content only (including live events that have finished). Truncates content from the head of a live video manifest by the specified duration. In effect, setting this value creates a buffer between the client and the true live point by omitting content from the head of a manifest. This is a useful capability in cases where CDN latency and other "network realities" make it difficult to deliver a true live experience, and result in content being presented in the manifest that is not yet available in caches. For example, if you set this value to 30 seconds, the client will see a manifest that is 30 seconds behind the true live point. This means that the client will not be able to play the first 30 seconds of content, but will be able to play the content that is 30 seconds old and newer. The maximum live backoff duration is 300 seconds.presentationWindowDuration· integer · Optional — For live content only (including live events that have finished). Indicates the duration of the presentation window, in units of timescale. A presentation window is the depth of content present in the live manifest. For example, if you set this value to 300 seconds, the client will see a manifest containing 300 seconds of content, even if the underlying asset is much longer. This is useful for restricting playback to the very latest content, or for restricting seek positions in content. The minimum presentation window duration is 10 seconds.startTime· string · Optional · format: date-time — For live content only (including live events that have finished). Indicates the start of the presentation window, likestartTimestampbut as an explicit UTC time.startTimestamp· integer · Optional · >=0 — For both VOD and live content. Indicates the start of the presentation window, in units of timescale. Given a timescale of "1", a value of "N" set here will clip the first "N" seconds of content from the beginning of the video manifest. Examples: timescale=1, startTimestamp=0, endTimestamp=10: The first 10 seconds of content will be included in the output. timescale=1, startTimestamp=10, endTimestamp=70: The 60 seconds of content starting at 10 seconds will be included in the output. timescale=10000000, startTimestamp=0, endTimestamp=100000000: The first 10 seconds of content will be included in the output. In cases where the startTimestamp does not perfectly align with a segment boundary, the endTimestamp will be rounded down to the nearest segment boundary.timescale· integer · Optional · 1 to 1000000000 · Defaults to 10000000 — Defines the unit of time for all the values in this object. The value is expressed in ticks per second. The default value of 10,000,000 increments per second (or 10 MHz) is used if this parameter is not specified. IF you're a video engineer doing Serious Business, consider setting this to 48,000 or 90,000 representing 90Khz and 48Khz respectively. If you're a mere mortal, a value of 1 is sensible and would represent seconds. For example, with a timescale set to "1", the startTimestamp and endTimestamp values are expressed in seconds. So a startTimestamp of 10 and an endTimestamp of 20 would represent a 10 second window of content. Segments overlapping this window would be included in the output.
tracks· list of objects · Optional — Defines the tracks to include in the output. If multiple FilterTrackSelection objects are provided, their configurations will be OR'd together. For instance, if you want to include all audio tracks that are not English, and all video tracks that are between 3 and 5 Mbps, you would provide two FilterTrackSelection objects.- Array items (object):
trackSelections· list of objects · Required — Defines the tracks to include in the output. Multiple entries here will be AND'd together. Typically, you will want to select a matching Type, such as video, and then select additional filters. For instance, to include all audio tracks that are not English, and all video tracks that are between 3 and 5 Mbps, you would provide three FilterTrackSelection objects: ```json [ {"property": "Type", "operation": "Equal", "value": "Audio"}, {"property": "Bitrate", "operation": "Equal", "value": "3000000-5000000"}, {"property": "Language", "operation": "NotEqual", "value": "en"}]
- Array items (object):
- Array items (object):
- `operation` · enum · **Required** — Set to either 'Equal' or 'NotEqual'. Tracks matching this predicate will be included. Examples: To include all audio tracks, set operation to 'Equal', property to 'Type', and value to 'Audio'.
- Allowed values: `Equal`, `NotEqual`
- `property` · enum · **Required** — The property to match against. Supported properties include: Bitrate, FourCC, Language, Name, Type, and Unknown. - Bitrate may be provided as a single numeric value '100000' or as a range '500000-1000000'. - FourCC is the codec, and may be one of 'avc1', 'hev1', and 'hvc1' for video, or one of 'mp4a' and 'ec-3' for audio. - Language is the value of a language tag to include, as specified in RFC 5646. - Name is the name of the track as specified in the manifest. - Type is one of either 'video', 'audio', or 'text'.
- Allowed values: `Unknown`, `Type`, `Name`, `Language`, `FourCC`, `Bitrate`
- `value` · string · **Required** — The value to match against. Values are not case-sensitive.
- `systemData` · object · Optional — Metadata pertaining to creation and last modification of the resource.
- `createdAt` · string · **Required** · _format: date-time_ — The timestamp of resource creation (UTC).
- `createdBy` · string · **Required** — The identity that created the resource.
- `createdByType` · enum · **Required** — The type of identity that created the resource.
- Allowed values: `User`, `Application`, `ManagedIdentity`, `Key`
- `internalId` · string · **Required** · _format: uuid_ — The internal ID of the resource.
- `lastModifiedAt` · string · **Required** · _format: date-time_ — The timestamp of resource last modification (UTC).
- `lastModifiedBy` · string · **Required** — The identity that last modified the resource.
- `lastModifiedByType` · enum · **Required** — The type of identity that last modified the resource.
- Allowed values: `User`, `Application`, `ManagedIdentity`, `Key`
- `type` · string · Optional — The type of the resource. E.g. "Microsoft.Media/mediaservices/assets"
Example:
```json
{
"id": "string",
"name": "name",
"properties": {
"firstQuality": {
"bitrate": 0
},
"presentationTimeRange": {
"endTime": "2024-01-01T00:00:00Z",
"endTimestamp": 0,
"forceEndTimestamp": true,
"liveBackoffDuration": 0,
"presentationWindowDuration": 0,
"startTime": "2024-01-01T00:00:00Z",
"startTimestamp": 0,
"timescale": 10000000
},
"tracks": [
{
"trackSelections": [
{
"operation": "Equal",
"property": "Unknown",
"value": "string"
}
]
}
]
},
"systemData": {
"createdAt": "2024-01-01T00:00:00Z",
"createdBy": "string",
"createdByType": "User",
"internalId": "00000000-0000-0000-0000-000000000000",
"lastModifiedAt": "2024-01-01T00:00:00Z",
"lastModifiedBy": "string",
"lastModifiedByType": "User"
},
"type": "string"
}
201 — Account Filter was created
Example:
400 — Bad Request
error· object · Required — Pertinent information about the errorcode· string · Required — The error code.detail· string · Required — The error message.extraDetail· map from strings to any · Optional — Extra information regarding this error.[any key]· any — map of additional properties
ref· string · Required — A reference to the request that caused the error.status· integer · Required — The HTTP status code
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
401 — Unauthorized
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
403 — Forbidden
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
404 — Not Found
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
429 — Too Many Requests
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
500 — Internal Server Error
Example:
{
"error": {
"code": "string",
"detail": "string",
"extraDetail": {
"key": null
}
},
"ref": "string",
"status": 0
}
Source spec: media-api · operationId: [put]_/api/v1/projects/{project_name}/media/accountFilters/{filter_name}