# Specifying SCTE-35 markers using ESAM XML
<a name="specifying-scte-35-markers-using-esam-xml"></a>

If your input video doesn't contain SCTE-35 markers, but you need to specify ad insertion points in your outputs, you can provide Event Signaling and Management (ESAM) XML documents in your AWS Elemental MediaConvert job settings. When you do, MediaConvert conditions your outputs with IDR (Instantaneous Decoder Refresh) frames at the insertion points that you specify in the document. In outputs that are also wrapped in MPEG2-TS and HLS containers, MediaConvert inserts SCTE-35 time\$1signal messages at those points. 

For your **Apple HLS** output groups, you can also provide an HLS manifest conditioning XML document. You can then set up your job to condition the manifests for your HLS outputs accordingly.

**Note**  
To put SCTE-35 markers in your MPEG2-TS outputs, in addition to supplying the ESAM XML documents, you must also enable **ESAM SCTE-35** on each output. For more information, see the console procedure following this overview.

**About Timecodes in Your ESAM Documents**  
Specify the insertion points in your XML documents relative to the timing of the final output, after input clipping and stitching. Start your timing from 00:00:00:00, regardless of your timecode settings. Use the following 24-hour format with a frame number: HH:MM:SS:FF.

For example, a job has the following three inputs: a five-minute preroll, a one-hour film, and a five-minute postroll. You use input clipping to clip adjust the final 20 minutes of your one-hour input. So your output with preroll and postroll is 30 minutes long. If you want your first insertion point to appear three minutes into the main content, you would specify it at eight minutes—three minutes after your five-minute preroll. 

**To include ESAM XML documents in your job settings (console)**

1. Open the MediaConvert console at [https://console.aws.amazon.com/mediaconvert](https://console.aws.amazon.com/mediaconvert).

1. Choose **Create new job**.

1. Set up your input, output groups, and outputs for video and audio, as described in [Tutorial: Configuring job settings](setting-up-a-job.md) and [Creating outputs](output-settings.md).

1. In the **Job** pane on the left, in the **Job settings** section, choose **Settings**.

1. In the **Ad signaling** section, enable **Event signaling and messaging (ESAM)**.

1. For **Signal processing notification XML**, enter your ESAM signaling XML document as text. For an example, see [Example ESAM XML signal processing notification](example-esam-xml.md).
**Note**  
By default, MediaConvert adds a four-second preroll to the ESAM payload. This might result in MediaConvert placing the SCTE-35 message one segment earlier than the cue marker designates in the HLS manifest. To remove the preroll, set `responseSignalPreroll` to zero. This setting is a child of [EsamSettings](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs-id.html#jobs-id-model-esamsettings).

1. If you want to include information about your SCTE-35 markers in your HLS manifests, for **Manifest confirm condition notification XML**, enter your ESAM manifest conditional XML document as text. MediaConvert doesn't include information about your SCTE-35 markers in your DASH manifests.

   To insert SCTE-35 markers in the transport stream in addition to the manifest, set the `dataPassThrough` attribute in your MCC document to `"true"`. If you don't want markers in the transport stream, remove the `dataPassThrough` attributes.

   For an example, see [Example ESAM XML Manifest Confirm Condition Notification](example-esam-xml-manifest-conditioning.md). 

1. For each MPEG2-TS output where you want SCTE-35 markers, enable the markers:

   1. In the **Job** pane on the left, under **Output groups**, **File group**, choose the output.

   1. Confirm that it is an MPEG2-TS output. In the **Output settings** section, make sure that **Container** is set to **MPEG-2 Transport Stream**.

   1. Choose **Container settings**, and then scroll down to find the **PID controls** section.

   1. For **ESAM SCTE-35** choose **Enabled**.

   1. For **SCTE-35 source**, keep the default **None**.

1. Do this step only for any **Apple HLS** output groups in your job.

   If you want to condition your HLS manifest with your ESAM insertion points, follow the procedure in [Including SCTE-35 information in your HLS manifest](including-scte-35-information-in-your-hls-manifest.md). Otherwise, follow these steps to confirm that the following settings are still in their default state:

   1. Make sure that **Manifest confirm condition notification XML**, discussed in a previous step of this procedure, is empty.

   1. For each **Apple HLS** output group in your job, confirm that you have kept **Ad Markers** unchecked.

      1. In the **Job** pane on the left, under **Output groups**, choose **Apple HLS**.

      1. In the **Apple HLS group settings** section, choose **Advanced**.

      1. In the **Ad markers** section, clear the **Elemental** and **SCTE-35 enhanced** check boxes.

   1. For each output in your **Apple HLS** output groups, confirm that **SCTE-35 source** is set to **None**:

      1. In the **Job** pane on the left, under **Output groups**, **Apple HLS**, choose an output.

      1. In the **Output settings** section, choose **Transport stream settings**.

      1. For **SCTE-35 source**, choose **None**.

**To include ESAM XML documents in your jobs settings (API, SDK, AWS CLI)**

1. Include the [`esam` property](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-jobsettings-esam) and its children at the root of the job settings in your JSON job specification. These properties are shown in the following example.

   1.  Include your ESAM signal processing XML specification as a string in the setting `sccXml`. 

   1. Optionally, include a manifest confirm condition XML notification document as a string in the setting `mccXml`:

   ```
     "esam": {
       "responseSignalPreroll": 4000,
       "signalProcessingNotification": {
         "sccXml": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<SignalProcessingNotification ..."
       },
       "manifestConfirmConditionNotification": {
         "mccXml": "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>\n<ns2:ManifestConfirmConditionNotification ... " 
       }
   ```

1. For each M2TS (MPEG2 Transport Stream) output in your job, set your JSON job specification as shown in the following example. Include the property [https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m2tssettings-scte35esam](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m2tssettings-scte35esam). Set [https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m2tssettings-scte35source](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m2tssettings-scte35source) to `NONE`.

   ```
     "outputs": [
           {
             "extension": "m2ts",
             "containerSettings": {
               "container": "M2TS",
               "m2tsSettings": {
                 ...
   
                 "scte35Esam": {
                   "scte35EsamPid": 508
                 },
                 ...
                 "scte35Source": "NONE"
               }
   ```

1. If you want to condition your HLS manifests with SCTE-35 information, for each Apple HLS output group in your job, include the following. These settings are shown in the example at the end of this step:
   +  Set [https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m3u8settings-scte35source](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-m3u8settings-scte35source) to `PASSTHROUGH`.
   + Include [https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-hlsgroupsettings-admarkers](https://docs.aws.amazon.com/mediaconvert/latest/apireference/jobs.html#jobs-prop-hlsgroupsettings-admarkers) and list one or both of `ELEMENTAL_SCTE35` or `ELEMENTAL` in an array.

     For sample manifests created with each setting selected, see [Sample manifest: Elemental ad markers](sample-manifest-elemental-ad-markers.md) and [Sample manifest: SCTE-35 enhanced ad markers](sample-manifest-scte-35-enhanced-ad-markers.md).

   If you don't want to condition your HLS manifests with SCTE-35 information, keep the default setting `NONE` for `scte35Source` and don't include `adMarkers`:

   ```
     "outputGroups": [
       {
         "customName": "apple_hls",
         "outputGroupSettings": {
           "type": "HLS_GROUP_SETTINGS",
           "hlsGroupSettings": {
             "adMarkers": [
               "ELEMENTAL_SCTE35"
             ],
             ...
   
           }
         },
         "outputs": [
           {
             "extension": "m3u8",
             "nameModifier": "high",
             "outputSettings": {
               "hlsSettings": {
                 ...
               }
             },
             "containerSettings": {
               "container": "M3U8",
               "m3u8Settings": {
                 ...
                 "scte35Source": "PASSTHROUGH"
               }
   ```

1. Submit your job as usual. 

   For information about submitting AWS Elemental MediaConvert jobs programmatically, see [Getting started with AWS Elemental MediaConvert using the AWS SDKs or the AWS CLI](https://docs.aws.amazon.com/mediaconvert/latest/apireference/custom-endpoints.html) and [Getting started with AWS Elemental MediaConvert using the API](https://docs.aws.amazon.com/mediaconvert/latest/apireference/getting-started.html).

# Example ESAM XML signal processing notification
<a name="example-esam-xml"></a>

This ESAM XML block generates two 30-second ad breaks, one at 10 seconds in and the other at 75 seconds in.

```
<?xml version="1.0" encoding="UTF-8"?>
<SignalProcessingNotification xmlns="urn:cablelabs:iptvservices:esam:xsd:signal:1" xmlns:sig="urn:cablelabs:md:xsd:signaling:3.0" xmlns:common="urn:cablelabs:iptvservices:esam:xsd:common:1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" acquisitionPointIdentity="ExampleESAM">

    <common:BatchInfo batchId="1">
      <common:Source xsi:type="content:MovieType" />
    </common:BatchInfo>

    <ResponseSignal acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="1" signalPointID="10.00" action="create">
      <sig:NPTPoint nptPoint="10.00"/>
      <sig:SCTE35PointDescriptor spliceCommandType="06">
        <sig:SegmentationDescriptorInfo segmentEventId="1" segmentTypeId="52" upidType="9" upid="1" duration="PT30S" segmentNumber="1" segmentsExpected="1"/>
      </sig:SCTE35PointDescriptor>
    </ResponseSignal>
    <ConditioningInfo acquisitionSignalIDRef="1" startOffset="PT10S" duration="PT30S"/>

    <ResponseSignal acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="2" signalPointID="40.00" action="create">
      <sig:NPTPoint nptPoint="40.00" />
      <sig:SCTE35PointDescriptor spliceCommandType="06">
        <sig:SegmentationDescriptorInfo segmentEventId="1" segmentTypeId="53" upidType="9" upid="2"/>
      </sig:SCTE35PointDescriptor>
    </ResponseSignal>

    <ResponseSignal acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="3" signalPointID="75.00" action="create">
      <sig:NPTPoint nptPoint="75.00"/>
      <sig:SCTE35PointDescriptor spliceCommandType="06">
        <sig:SegmentationDescriptorInfo segmentEventId="2" segmentTypeId="52" upidType="9" upid="3" duration="PT30S" segmentNumber="2" segmentsExpected="1"/>
      </sig:SCTE35PointDescriptor>
    </ResponseSignal>
    <ConditioningInfo acquisitionSignalIDRef="3" startOffset="PT75S" duration="PT30S"/>
    
    <ResponseSignal acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="4" signalPointID="105.00" action="create">
      <sig:NPTPoint nptPoint="105.00" />
      <sig:SCTE35PointDescriptor spliceCommandType="06">
        <sig:SegmentationDescriptorInfo segmentEventId="2" segmentTypeId="53" upidType="9" upid="4"/>
      </sig:SCTE35PointDescriptor>
    </ResponseSignal>

</SignalProcessingNotification>
```

# Example ESAM XML Manifest Confirm Condition Notification
<a name="example-esam-xml-manifest-conditioning"></a>

This ESAM manifest confirm condition (MCC) XML document generates HLS manifest cue tags for two 30-second ad breaks. The first begins at 10 seconds in; the second begins at 75 seconds in. These cue manifest tags also contain data that can be used by a downstream client for ad replacement and insertion. Outputs generated with this MCC document contain a SCTE-35 message embedded into the transport stream file at the first ad break, but not at the second one.

Note the `dataPassThrough` attribute on the first ad break. When this attribute is present and set to `"true"`, MediaConvert inserts SCTE-35 markers in the transport stream in addition to the manifest. For any ad break that you want marked only in the manifest, keep out the `dataPassThrough` attribute.

MediaConvert supports manifest conditioning with ESAM only in HLS packages.

```
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns2:ManifestConfirmConditionNotification xmlns:ns2="http://www.cablelabs.com/namespaces/metadata/xsd/confirmation/2" xmlns="http://www.cablelabs.com/namespaces/metadata/xsd/core/2" xmlns:ns3="http://www.cablelabs.com/namespaces/metadata/xsd/signaling/2">
  <ns2:ManifestResponse acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="1" duration="PT30S" dataPassThrough="true"> 
  <ns2:SegmentModify>
      <ns2:FirstSegment>
        <ns2:Tag value="#EXT-X-CUE-OUT:4,SpliceType=VOD_DAI,Action=REPLACE, PAID=amazon.com/TEST2014020500000346,Acds=BA" />
      </ns2:FirstSegment>
      <ns2:SpanSegment>
        <ns2:Tag value="#EXT-X-CUE-OUT-CONT:${secondsFromSignal}/4, SpliceType=VOD_DAI,Action=REPLACE,PAID=amazon.com/TEST2014020500000346,Acds=BA" adapt="true" />
      </ns2:SpanSegment>
      <ns2:LastSegment>
        <ns2:Tag value="#EXT-X-CUE-IN:4,SpliceType=VOD_DAI" locality="after" adapt="true" />
      </ns2:LastSegment>
    </ns2:SegmentModify>
	</ns2:ManifestResponse>
  <ns2:ManifestResponse acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="2"></ns2:ManifestResponse>
  <ns2:ManifestResponse acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="3" duration="PT30S">  
  <ns2:SegmentModify>
      <ns2:FirstSegment>
        <ns2:Tag value="#EXT-X-OUT:4,SpliceType=VOD_DAI,Action=REPLACE, PAID=amazon.com/TEST2014020500000347,Acds=BA" />
      </ns2:FirstSegment>
      <ns2:SpanSegment>
        <ns2:Tag value="#EXT-X-OUT-CONT:${secondsFromSignal}/4, SpliceType=VOD_DAI,Action=REPLACE,PAID=amazon.com/TEST2014020500000346,Acds=BA" adapt="true" />
      </ns2:SpanSegment>
      <ns2:LastSegment>
        <ns2:Tag value="#EXT-X-CUE-IN:4,SpliceType=VOD_DAI" locality="after" adapt="true" />
      </ns2:LastSegment>
    </ns2:SegmentModify>
	</ns2:ManifestResponse>
	<ns2:ManifestResponse acquisitionPointIdentity="ExampleESAM" acquisitionSignalID="4"></ns2:ManifestResponse>
</ns2:ManifestConfirmConditionNotification>
```