Live Events - Create

Create Live Event
Creates a new live event.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaservices/{accountName}/liveEvents/{liveEventName}?api-version=2022-11-01
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Media/mediaservices/{accountName}/liveEvents/{liveEventName}?api-version=2022-11-01&autoStart={autoStart}

URI Parameters

Name In Required Type Description
accountName
path True

string

The Media Services account name.

liveEventName
path True

string

The name of the live event, maximum length is 32.

Regex pattern: ^[a-zA-Z0-9]+(-*[a-zA-Z0-9])*$

resourceGroupName
path True

string

The name of the resource group within the Azure subscription.

subscriptionId
path True

string

The unique identifier for a Microsoft Azure subscription.

api-version
query True

string

The version of the API to be used with the client request.

autoStart
query

boolean

The flag indicates if the resource should be automatically started on creation.

Request Body

Name Required Type Description
location True

string

The geo-location where the resource lives

properties.input True

LiveEventInput

Live event input settings. It defines how the live event receives input from a contribution encoder.

properties.crossSiteAccessPolicies

CrossSiteAccessPolicies

Live event cross site access policies.

properties.description

string

A description for the live event.

properties.encoding

LiveEventEncoding

Encoding settings for the live event. It configures whether a live encoder is used for the live event and settings for the live encoder if it is used.

properties.hostnamePrefix

string

When useStaticHostname is set to true, the hostnamePrefix specifies the first part of the hostname assigned to the live event preview and ingest endpoints. The final hostname would be a combination of this prefix, the media service account name and a short code for the Azure Media Services data center.

properties.preview

LiveEventPreview

Live event preview settings. Preview allows live event producers to preview the live streaming content without creating any live output.

properties.streamOptions

StreamOptionsFlag[]

The options to use for the LiveEvent. This value is specified at creation time and cannot be updated. The valid values for the array entry values are 'Default' and 'LowLatency'.

properties.transcriptions

LiveEventTranscription[]

Live transcription settings for the live event. See https://go.microsoft.com/fwlink/?linkid=2133742 for more information about the live transcription feature.

properties.useStaticHostname

boolean

Specifies whether a static hostname would be assigned to the live event preview and ingest endpoints. This value can only be updated if the live event is in Standby state

tags

object

Resource tags.

Responses

Name Type Description
200 OK

LiveEvent

OK. The request has succeeded.

201 Created

LiveEvent

Created. The request has been accepted for processing and the operation will complete asynchronously. See https://go.microsoft.com/fwlink/?linkid=2087017 for details on monitoring asynchronous Azure operations using the Azure-AsyncOperation response header.

Other Status Codes

ErrorResponse

The streaming error response describing why the operation failed.

Examples

Create a LiveEvent

Sample Request

PUT https://management.azure.com/subscriptions/0a6ec948-5a62-437d-b9df-934dc7c1b722/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/slitestmedia10/liveEvents/myLiveEvent1?api-version=2022-11-01

{
  "location": "West US",
  "tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "properties": {
    "description": "test event 1",
    "input": {
      "streamingProtocol": "RTMP",
      "keyFrameIntervalDuration": "PT6S",
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      }
    },
    "preview": {
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      }
    }
  }
}

Sample Response

azure-asyncoperation: https://management.azure.com/subscriptions/0a6ec948-5a62-437d-b9df-934dc7c1b722/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/slitestmedia10/liveeventoperations/62e4d893-d233-4005-988e-a428d9f77076?api-version=2022-11-01
location: https://management.azure.com/subscriptions/0a6ec948-5a62-437d-b9df-934dc7c1b722/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/slitestmedia10/liveevents/myLiveEvent1/operationlocations/62e4d893-d233-4005-988e-a428d9f77076?api-version=2022-11-01
{
  "name": "myLiveEvent1",
  "id": "/subscriptions/0a6ec948-5a62-437d-b9df-934dc7c1b722/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/slitestmedia10/liveevents/myLiveEvent1",
  "type": "Microsoft.Media/mediaservices/liveevents",
  "location": "West US",
  "tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "properties": {
    "description": "test event 1",
    "resourceState": "Creating",
    "provisioningState": "InProgress",
    "created": "2018-03-03T02:25:06.0982751Z",
    "lastModified": "2018-03-03T02:25:06.0982751Z",
    "useStaticHostname": false,
    "streamOptions": [],
    "input": {
      "keyFrameIntervalDuration": "PT6S",
      "streamingProtocol": "FragmentedMP4",
      "accessToken": "<accessToken>",
      "endpoints": [],
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      },
      "timedMetadataEndpoints": []
    },
    "preview": {
      "previewLocator": "c91726b4-880c-4090-94aa-e6ddb1384b37",
      "streamingPolicyName": null,
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      },
      "endpoints": []
    },
    "encoding": {
      "encodingType": "None",
      "presetName": null
    },
    "crossSiteAccessPolicies": {
      "clientAccessPolicy": null,
      "crossDomainPolicy": null
    }
  }
}
{
  "name": "myLiveEvent1",
  "id": "/subscriptions/0a6ec948-5a62-437d-b9df-934dc7c1b722/resourceGroups/mediaresources/providers/Microsoft.Media/mediaservices/slitestmedia10/liveevents/myLiveEvent1",
  "type": "Microsoft.Media/mediaservices/liveevents",
  "location": "West US",
  "tags": {
    "tag1": "value1",
    "tag2": "value2"
  },
  "properties": {
    "description": "test event 1",
    "resourceState": "Stopped",
    "provisioningState": "Succeeded",
    "created": "2018-03-03T02:25:06.0982751Z",
    "lastModified": "2018-03-03T02:25:06.0982751Z",
    "useStaticHostname": false,
    "streamOptions": [],
    "input": {
      "keyFrameIntervalDuration": "PT6S",
      "streamingProtocol": "FragmentedMP4",
      "accessToken": "<accessToken>",
      "endpoints": [],
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      },
      "timedMetadataEndpoints": []
    },
    "preview": {
      "previewLocator": "c91726b4-880c-4090-94aa-e6ddb1384b37",
      "streamingPolicyName": null,
      "accessControl": {
        "ip": {
          "allow": [
            {
              "name": "AllowAll",
              "address": "0.0.0.0",
              "subnetPrefixLength": 0
            }
          ]
        }
      },
      "endpoints": []
    },
    "encoding": {
      "encodingType": "None",
      "presetName": null
    },
    "crossSiteAccessPolicies": {
      "clientAccessPolicy": null,
      "crossDomainPolicy": null
    }
  }
}

Definitions

Name Description
createdByType

The type of identity that created the resource.

CrossSiteAccessPolicies

The client access policy.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

IPAccessControl

The IP access control.

IPRange

The IP address range in the CIDR scheme.

LiveEvent

The live event.

LiveEventEncoding

Specifies the live event type and optional encoding settings for encoding live events.

LiveEventEncodingType

Live event type. When encodingType is set to PassthroughBasic or PassthroughStandard, the service simply passes through the incoming video and audio layer(s) to the output. When encodingType is set to Standard or Premium1080p, a live encoder transcodes the incoming stream into multiple bitrates or layers. See https://go.microsoft.com/fwlink/?linkid=2095101 for more information. This property cannot be modified after the live event is created.

LiveEventEndpoint

The live event endpoint.

LiveEventInput

The live event input.

LiveEventInputAccessControl

The IP access control for live event input.

LiveEventInputProtocol

The input protocol for the live event. This is specified at creation time and cannot be updated.

LiveEventInputTrackSelection

A track selection condition. This property is reserved for future use, any value set on this property will be ignored.

LiveEventOutputTranscriptionTrack

Describes a transcription track in the output of a live event, generated using speech-to-text transcription. This property is reserved for future use, any value set on this property will be ignored.

LiveEventPreview

Live event preview settings.

LiveEventPreviewAccessControl

The IP access control for the live event preview endpoint.

LiveEventResourceState

The resource state of the live event. See https://go.microsoft.com/fwlink/?linkid=2139012 for more information.

LiveEventTimedMetadataEndpoint

The live event metadata insertion endpoint.

LiveEventTranscription

Describes the transcription tracks in the output of a live event, generated using speech-to-text transcription. This property is reserved for future use, any value set on this property will be ignored.

StreamOptionsFlag

The options to use for the LiveEvent. This value is specified at creation time and cannot be updated. The valid values for the array entry values are 'Default' and 'LowLatency'.

StretchMode

Specifies how the input video will be resized to fit the desired output resolution(s). Default is None

systemData

Metadata pertaining to creation and last modification of the resource.

createdByType

The type of identity that created the resource.

Name Type Description
Application

string

Key

string

ManagedIdentity

string

User

string

CrossSiteAccessPolicies

The client access policy.

Name Type Description
clientAccessPolicy

string

The content of clientaccesspolicy.xml used by Silverlight.

crossDomainPolicy

string

The content of crossdomain.xml used by Silverlight.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

IPAccessControl

The IP access control.

Name Type Description
allow

IPRange[]

The IP allow list.

IPRange

The IP address range in the CIDR scheme.

Name Type Description
address

string

The IP address.

name

string

The friendly name for the IP address range.

subnetPrefixLength

integer

The subnet mask prefix length (see CIDR notation).

LiveEvent

The live event.

Name Type Description
id

string

Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

location

string

The geo-location where the resource lives

name

string

The name of the resource

properties.created

string

The creation time for the live event

properties.crossSiteAccessPolicies

CrossSiteAccessPolicies

Live event cross site access policies.

properties.description

string

A description for the live event.

properties.encoding

LiveEventEncoding

Encoding settings for the live event. It configures whether a live encoder is used for the live event and settings for the live encoder if it is used.

properties.hostnamePrefix

string

When useStaticHostname is set to true, the hostnamePrefix specifies the first part of the hostname assigned to the live event preview and ingest endpoints. The final hostname would be a combination of this prefix, the media service account name and a short code for the Azure Media Services data center.

properties.input

LiveEventInput

Live event input settings. It defines how the live event receives input from a contribution encoder.

properties.lastModified

string

The last modified time of the live event.

properties.preview

LiveEventPreview

Live event preview settings. Preview allows live event producers to preview the live streaming content without creating any live output.

properties.provisioningState

string

The provisioning state of the live event.

properties.resourceState

LiveEventResourceState

The resource state of the live event. See https://go.microsoft.com/fwlink/?linkid=2139012 for more information.

properties.streamOptions

StreamOptionsFlag[]

The options to use for the LiveEvent. This value is specified at creation time and cannot be updated. The valid values for the array entry values are 'Default' and 'LowLatency'.

properties.transcriptions

LiveEventTranscription[]

Live transcription settings for the live event. See https://go.microsoft.com/fwlink/?linkid=2133742 for more information about the live transcription feature.

properties.useStaticHostname

boolean

Specifies whether a static hostname would be assigned to the live event preview and ingest endpoints. This value can only be updated if the live event is in Standby state

systemData

systemData

The system metadata relating to this resource.

tags

object

Resource tags.

type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

LiveEventEncoding

Specifies the live event type and optional encoding settings for encoding live events.

Name Type Description
encodingType

LiveEventEncodingType

Live event type. When encodingType is set to PassthroughBasic or PassthroughStandard, the service simply passes through the incoming video and audio layer(s) to the output. When encodingType is set to Standard or Premium1080p, a live encoder transcodes the incoming stream into multiple bitrates or layers. See https://go.microsoft.com/fwlink/?linkid=2095101 for more information. This property cannot be modified after the live event is created.

keyFrameInterval

string

Use an ISO 8601 time value between 0.5 to 20 seconds to specify the output fragment length for the video and audio tracks of an encoding live event. For example, use PT2S to indicate 2 seconds. For the video track it also defines the key frame interval, or the length of a GoP (group of pictures). If this value is not set for an encoding live event, the fragment duration defaults to 2 seconds. The value cannot be set for pass-through live events.

presetName

string

The optional encoding preset name, used when encodingType is not None. This value is specified at creation time and cannot be updated. If the encodingType is set to Standard, then the default preset name is ‘Default720p’. Else if the encodingType is set to Premium1080p, the default preset is ‘Default1080p’.

stretchMode

StretchMode

Specifies how the input video will be resized to fit the desired output resolution(s). Default is None

LiveEventEncodingType

Live event type. When encodingType is set to PassthroughBasic or PassthroughStandard, the service simply passes through the incoming video and audio layer(s) to the output. When encodingType is set to Standard or Premium1080p, a live encoder transcodes the incoming stream into multiple bitrates or layers. See https://go.microsoft.com/fwlink/?linkid=2095101 for more information. This property cannot be modified after the live event is created.

Name Type Description
None

string

This is the same as PassthroughStandard, please see description below. This enumeration value is being deprecated.

PassthroughBasic

string

The ingested stream passes through the live event from the contribution encoder without any further processing. In the PassthroughBasic mode, ingestion is limited to up to 5Mbps and only 1 concurrent live output is allowed. Live transcription is not available.

PassthroughStandard

string

The ingested stream passes through the live event from the contribution encoder without any further processing. Live transcription is available. Ingestion bitrate limits are much higher and up to 3 concurrent live outputs are allowed.

Premium1080p

string

A contribution live encoder sends a single bitrate stream to the live event and Media Services creates multiple bitrate streams. The output cannot exceed 1080p in resolution.

Standard

string

A contribution live encoder sends a single bitrate stream to the live event and Media Services creates multiple bitrate streams. The output cannot exceed 720p in resolution.

LiveEventEndpoint

The live event endpoint.

Name Type Description
protocol

string

The endpoint protocol.

url

string

The endpoint URL.

LiveEventInput

The live event input.

Name Type Description
accessControl

LiveEventInputAccessControl

Access control for live event input.

accessToken

string

A UUID in string form to uniquely identify the stream. This can be specified at creation time but cannot be updated. If omitted, the service will generate a unique value.

endpoints

LiveEventEndpoint[]

The input endpoints for the live event.

keyFrameIntervalDuration

string

ISO 8601 time duration of the key frame interval duration of the input. This value sets the EXT-X-TARGETDURATION property in the HLS output. For example, use PT2S to indicate 2 seconds. Leave the value empty for encoding live events.

streamingProtocol

LiveEventInputProtocol

The input protocol for the live event. This is specified at creation time and cannot be updated.

timedMetadataEndpoints

LiveEventTimedMetadataEndpoint[]

The metadata endpoints for the live event.

LiveEventInputAccessControl

The IP access control for live event input.

Name Type Description
ip

IPAccessControl

The IP access control properties.

LiveEventInputProtocol

The input protocol for the live event. This is specified at creation time and cannot be updated.

Name Type Description
FragmentedMP4

string

Smooth Streaming input will be sent by the contribution encoder to the live event.

RTMP

string

RTMP input will be sent by the contribution encoder to the live event.

LiveEventInputTrackSelection

A track selection condition. This property is reserved for future use, any value set on this property will be ignored.

Name Type Description
operation

string

Comparing operation. This property is reserved for future use, any value set on this property will be ignored.

property

string

Property name to select. This property is reserved for future use, any value set on this property will be ignored.

value

string

Property value to select. This property is reserved for future use, any value set on this property will be ignored.

LiveEventOutputTranscriptionTrack

Describes a transcription track in the output of a live event, generated using speech-to-text transcription. This property is reserved for future use, any value set on this property will be ignored.

Name Type Description
trackName

string

The output track name. This property is reserved for future use, any value set on this property will be ignored.

LiveEventPreview

Live event preview settings.

Name Type Description
accessControl

LiveEventPreviewAccessControl

The access control for live event preview.

alternativeMediaId

string

An alternative media identifier associated with the streaming locator created for the preview. This value is specified at creation time and cannot be updated. The identifier can be used in the CustomLicenseAcquisitionUrlTemplate or the CustomKeyAcquisitionUrlTemplate of the StreamingPolicy specified in the StreamingPolicyName field.

endpoints

LiveEventEndpoint[]

The endpoints for preview. Do not share the preview URL with the live event audience.

previewLocator

string

The identifier of the preview locator in Guid format. Specifying this at creation time allows the caller to know the preview locator url before the event is created. If omitted, the service will generate a random identifier. This value cannot be updated once the live event is created.

streamingPolicyName

string

The name of streaming policy used for the live event preview. This value is specified at creation time and cannot be updated.

LiveEventPreviewAccessControl

The IP access control for the live event preview endpoint.

Name Type Description
ip

IPAccessControl

The IP access control properties.

LiveEventResourceState

The resource state of the live event. See https://go.microsoft.com/fwlink/?linkid=2139012 for more information.

Name Type Description
Allocating

string

Allocate action was called on the live event and resources are being provisioned for this live event. Once allocation completes successfully, the live event will transition to StandBy state.

Deleting

string

The live event is being deleted. No billing occurs in this transient state. Updates or streaming are not allowed during this state.

Running

string

The live event resources have been allocated, ingest and preview URLs have been generated, and it is capable of receiving live streams. At this point, billing is active. You must explicitly call Stop on the live event resource to halt further billing.

StandBy

string

Live event resources have been provisioned and is ready to start. Billing occurs in this state. Most properties can still be updated, however ingest or streaming is not allowed during this state.

Starting

string

The live event is being started and resources are being allocated. No billing occurs in this state. Updates or streaming are not allowed during this state. If an error occurs, the live event returns to the Stopped state.

Stopped

string

This is the initial state of the live event after creation (unless autostart was set to true.) No billing occurs in this state. In this state, the live event properties can be updated but streaming is not allowed.

Stopping

string

The live event is being stopped and resources are being de-provisioned. No billing occurs in this transient state. Updates or streaming are not allowed during this state.

LiveEventTimedMetadataEndpoint

The live event metadata insertion endpoint.

Name Type Description
url

string

The metadata endpoint URL.

LiveEventTranscription

Describes the transcription tracks in the output of a live event, generated using speech-to-text transcription. This property is reserved for future use, any value set on this property will be ignored.

Name Type Description
inputTrackSelection

LiveEventInputTrackSelection[]

Provides a mechanism to select the audio track in the input live feed, to which speech-to-text transcription is applied. This property is reserved for future use, any value set on this property will be ignored.

language

string

Specifies the language (locale) to be used for speech-to-text transcription – it should match the spoken language in the audio track. The value should be in BCP-47 format (e.g: 'en-US'). See https://go.microsoft.com/fwlink/?linkid=2133742 for more information about the live transcription feature and the list of supported languages.

outputTranscriptionTrack

LiveEventOutputTranscriptionTrack

Describes a transcription track in the output of a live event, generated using speech-to-text transcription. This property is reserved for future use, any value set on this property will be ignored.

StreamOptionsFlag

The options to use for the LiveEvent. This value is specified at creation time and cannot be updated. The valid values for the array entry values are 'Default' and 'LowLatency'.

Name Type Description
Default

string

Live streaming with no special latency optimizations.

LowLatency

string

The live event provides lower end to end latency by reducing its internal buffers.

LowLatencyV2

string

The live event is optimized for end to end latency. This option is only available for encoding live events with RTMP input. The outputs can be streamed using HLS or DASH formats. The outputs' archive or DVR rewind length is limited to 6 hours. Use "LowLatency" stream option for all other scenarios.

StretchMode

Specifies how the input video will be resized to fit the desired output resolution(s). Default is None

Name Type Description
AutoFit

string

Pad the output (with either letterbox or pillar box) to honor the output resolution, while ensuring that the active video region in the output has the same aspect ratio as the input. For example, if the input is 1920x1080 and the encoding preset asks for 1280x1280, then the output will be at 1280x1280, which contains an inner rectangle of 1280x720 at aspect ratio of 16:9, and pillar box regions 280 pixels wide at the left and right.

AutoSize

string

Override the output resolution, and change it to match the display aspect ratio of the input, without padding. For example, if the input is 1920x1080 and the encoding preset asks for 1280x1280, then the value in the preset is overridden, and the output will be at 1280x720, which maintains the input aspect ratio of 16:9.

None

string

Strictly respects the output resolution specified in the encoding preset without considering the pixel aspect ratio or display aspect ratio of the input video.

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string

The timestamp of resource creation (UTC).

createdBy

string

The identity that created the resource.

createdByType

createdByType

The type of identity that created the resource.

lastModifiedAt

string

The timestamp of resource last modification (UTC)

lastModifiedBy

string

The identity that last modified the resource.

lastModifiedByType

createdByType

The type of identity that last modified the resource.