Creating an origin endpoint in AWS Elemental MediaPackage - AWS Elemental MediaPackage

Creating an origin endpoint in AWS Elemental MediaPackage

This guides shows how to create an origin endpoint (endpoint) on a channel to define how MediaPackage prepares content for delivery. Content can't be served from a channel until it has an endpoint. If you're using input redundancy, each endpoint receives content from one ingest URL at a time. If MediaPackage performs a failover on the inputs for one ingest input URL, the endpoints automatically start receiving content from the other ingest URL. For more information about input redundancy and failover, see Live input redundancy AWS Elemental MediaPackage processing flow.

You can use the MediaPackage console, MediaPackage API, or AWS CLI to create an origin endpoint. When you're creating an origin endpoint, don't put sensitive identifying information like customer account numbers into free-form fields such as the name or description field. MediaPackage doesn’t require that you supply any customer data. This includes when you work with MediaPackage using the MediaPackage console, MediaPackage API, AWS CLI, or AWS SDKs. Any data that you enter into MediaPackage might get picked up for inclusion in diagnostic logs or Amazon CloudWatch Events.

To create an endpoint
  1. Access the channel that the endpoint will be associated with, as described in Viewing channel details in AWS Elemental MediaPackage.

  2. Choose Create endpoint from the Origin endpoints list.

  3. Complete the fields as described in the following topics:

  4. Choose Create.

    When you're creating an endpoint, you will receive an error if you exceed the quotas on the account. An error similar to Too many requests, please try again. Resource limit exceeded means that either you've exceeded the API request quotas, or you've already reached the maximum number of endpoints permitted on this channel.

Endpoint settings fields

The endpoint settings fields hold general information about the endpoint.

  1. For Name, enter a name that describes the origin endpoint. This is the name that you use for API and console interactions. The name is the primary identifier for the endpoint and must be unique for your account in the AWS Region and channel. Supported characters are A-Z, a-z, 0-9, _ (underscore), and - (hyphen) with a length of 1 to 256 characters. You can't use spaces in the name, and you can't change the name after you create the endpoint.

  2. (Optional) For Description, enter any descriptive text that helps you to identify the origin endpoint.

  3. For Container type, choose the type of container to attach to this origin endpoint. The container type you choose impacts the segment settings, encryption methods, and manifests you can choose.

    The container type options are:

    • TS (available for HLS and LL-HLS manifests)

    • CMAF (available for HLS, LL-HLS, and DASH manifests)

  4. For Startover window (sec.), enter the size of the window (in seconds) to create a window of the live stream that's available for on-demand viewing. Viewers can start-over or catch-up on content that falls within the window. The maximum startover window is 1,209,600 seconds (14 days). For more information about implementing start-over and catch-up TV, see Time-shifted viewing with AWS Elemental MediaPackage.

Segment settings fields

The segment settings fields hold general information about the segment.

  1. For Segment name, enter a name that describes the segment. The name is the base name of the segment used in all content manifests inside of the endpoint. Supported characters are A-Z, a-z, 0-9, _ (underscore), and - (hyphen) with a length of 1 to 256 characters. You can't use spaces in the name.

  2. For Segment duration (sec.), enter the duration (in seconds) of each segment. Enter a value equal to, or a multiple of, the input segment duration. The maximum segment duration is 30 seconds. If the value that you enter is different from the input segment duration, MediaPackage rounds segments to the nearest multiple of the input segment duration.

  3. Select Include IFrame-only stream to include an additional I-frame only stream along with the other tracks in the manifest. MediaPackage generates an I-frame only stream from the first rendition in the manifest. The service inserts EXT-I-FRAMES-ONLY tags in the output manifest, and then generates and includes an I-frames only playlist in the stream. This playlist enables player functionality like fast forward and rewind.

  4. Select Use audio rendition group to group all audio tracks into a single rendition group. All other tracks in the stream can be used with any audio rendition from the group. For more information about rendition groups, see AWS Elemental MediaPackage rendition groups reference.

  5. Select Include DVB subtitles to pass through digital video broadcasting (DVB) subtitles into the output. By default, MediaPackage excludes all DVB subtitles from the output.

  6. Select Enable SCTE support to include SCTE configuration options. If you select this, you can further define your SCTE configuration in additional fields.

  7. For Force endpoint error configuration, choose the types of problematic situations where you want MediaPackage to return a 404 response on manifests and segments requests:

    • Stale Manifests: MediaPackage stops receiving ingest streams on its input, indicating the encoder or network path have failed. This results in output stale manifests that don’t get updated any more, which results in playback sessions stopping.

    • Incomplete Manifests: MediaPackage is receiving ingest segments, but there are gaps in the timeline. This results in manifests presenting an incomplete timeline for some renditions, potentially generating playback problems.

    • Missing DRM Keys: MediaPackage was unable to retrieve an encryption key on a key-rotation operation. This results in the old encryption key still being used after the key-rotation time. While it will not affect playback, it could be problematic from a business or content-rights-entitlement perspective.

    • Slate Input: MediaPackage detects that the ingest stream(s) are flagged as including a significant proportion of slate contents (black video frames, audio silence). While playback continues, no content will be displayed by the players, which is a valid reason to failover to a different MediaPackage origin.

    When MediaPackage is configured to react to these problems, it will return 404 responses until it can present a consistent timeline in the manifests - meaning that all problematic segments will need to be evicted from the exposed DVR window in the manifest.

    Important

    Triggering such forced 404 responses is an optional behavior that should be used only if you want to implement CDN-driven failover between multiple MediaPackage origins. For more information on this types of workflow, see Cross-region failover.

  8. For SCTE filtering, choose the SCTE-35 message types that will be ad markers in the output. If you don't make a selection here, by default, MediaPackage inserts all ad markers in the output manifest.

    • Splice insert

    • Break

    • Provider advertisement

    • Distributor advertisement

    • Provider placement opportunity

    • Distributor placement opportunity

    • Provider overlay placement opportunity

    • Distributor overlay placement opportunity

    • Program

Encryption fields

Protect your content from unauthorized use through content encryption and digital rights management (DRM). MediaPackage uses the AWS Secure Packager and Encoder Key Exchange (SPEKE) API to facilitate content encryption and decryption by a DRM provider. Using SPEKE, the DRM provider supplies encryption keys to MediaPackage through the SPEKE API. The DRM provider also supplies licenses to supported media players for decryption. For more information about how SPEKE is used with services and features running in the cloud, see AWS cloud-based architecture in the Secure Packager and Encoder Key Exchange API Specification guide.

Note

To encrypt content, you must have a DRM provider, and be set up to use encryption. For information, see Content encryption and DRM in AWS Elemental MediaPackage.

  1. Choose Encrypt content to serve content with copyright protection.

  2. For Encryption method, choose the encryption method to use. If you don't see your preferred encryption method, confirm you choose the correct container type. The encryption method you choose impacts the DRM system providers you can choose. For supported encryption methods and DRM system providers, see Container and DRM system support with SPEKE.

    • The valid encryption methods for TS container types are:

      • AES-128

      • Sample AES

    • The valid encryption methods for CMAF container types are:

      • CENC

      • CBCS

  3. For DRM systems, choose the DRM system providers you're using to protect your content during distribution. You can choose more than one. If you don't see your DRM system provider, confirm you choose the correct container type and encryption method. For supported DRM system providers, see Container and DRM system support with SPEKE.

    The valid DRM systems are:

    • Clear Key AES-128

    • FairPlay

    • PlayReady

    • Widevine

  4. For Resource ID, enter an identifier for the content. The service sends this to the key server to identify the current endpoint. How unique you make this depends on how fine-grained you want access controls to be. The service does not permit you to use the same ID for two simultaneous encryption processes. The resource ID is also known as the content ID.

    The following example shows a resource ID.

    MovieNight20171126093045
  5. For Key server URL, enter the URL of the API Gateway proxy that you set up to talk to your key server. The API Gateway proxy must reside in the same AWS Region as MediaPackage.

    The following example shows a URL.

    https://1wm2dx1f33.execute-api.us-west-2.amazonaws.com/SpekeSample/copyProtection
  6. For Role ARN, enter the Amazon Resource Name (ARN) of the IAM role that provides you access to send your requests through API Gateway. Get this from your DRM solution provider.

    The following example shows a role ARN.

    "arn:aws:iam::accountID:role/SpekeAccess
  7. (Optional) For Constant initialization vector enter a 128-bit, 16-byte hex value represented by a 32-character string, used in conjunction with the key for encrypting content. If you don't specify a value, then MediaPackage creates the constant initialization vector (IV).

  8. For Key rotation interval (sec.), enter the frequency (in seconds) of key changes for live workflows, in which content is streamed real time. The service retrieves content keys before the live content begins streaming, and then retrieves them as needed over the lifetime of the workflow. By default, key rotation is 300 seconds (5 minutes), the minimum rotation interval, which is equivalent to setting it to 300. The maximum key rotation interval is 31,536,000 seconds (1 year). If you don't enter an interval, content keys aren't rotated.

    The following example setting causes the service to rotate keys every thirty minutes.

    1800

    For information about key rotation, see AWS Elemental MediaPackage key rotation behavior.

Endpoint policy fields

You must assign a channel policy to enable content to flow into your channel from sources outside of your account.

  1. Under Endpoint policy, choose an endpoint policy to enable content to flow into your channel from sources outside of your account. For more information about policies, see Resource-based policy examples.

    • Don't attach a policy - Restrict access to only those who have access to this account's credentials.

    • Attach a custom policy - Define your own policy and restrict access to as few or as many as you want. Enter a valid JSON object with the same structure as other IAM policies. The policy should follow the standard security advice of granting least privilege, or granting only the permissions required to perform a task.

    • Attach a public policy - Accept all incoming client requests to a channel's output. Enter a valid JSON object with the same structure as other IAM policies.

Manifest fields

The manifests fields hold general information about the manifest. You must attach at least one manifest to an origin endpoint. You can attach up to twenty five manifests to a single origin endpoint, and request a quota increase if necessary.

Choose the type of manifest to use. You can choose an HLS manifest, LL-HLS manifest, or DASH manifest.

Create an HLS or LL-HLS manifest

To create an HLS or LL-HLS manifest
  1. For Manifest name enter a short string that will be appended to the endpoint URL. The manifest name creates a unique path to this endpoint. If you don't enter a value, MediaPackage uses the default manifest name, index. MediaPackage automatically inserts the format extension, such as .m3u8. Supported characters are A-Z, a-z, 0-9, and - (hyphen). You can't use underscores in the name.

  2. (Optional) For Child manifest name enter a short string that will be appended to the endpoint URL. The child manifest name creates a unique path to this endpoint. Supported characters are A-Z, a-z, 0-9, and - (hyphen). You can't use underscores in the name.

  3. For Manifest window (sec.) enter the total duration (in seconds) of the manifest's content. The maximum manifest window is 900 seconds (15 minutes).

  4. For Program date/time interval (sec.) enter the interval (in seconds) for MediaPackage to insert the EXT-X-PROGRAM-DATE-TIME tags in the manifest. Program date time (PDT) is optional when using HLS manifests, but is required when using low-latency HLS manifests.

    The maximum PDT interval is 1,209,600 seconds (14 days). If you don't enter an interval, EXT-X-PROGRAM-DATE-TIME tags aren't included in the manifest.

    The EXT-X-PROGRAM-DATE-TIME tag holds the time of the segment. When PDT information is available in the source content, MediaPackage uses this same information on the output content. Otherwise, MediaPackage uses Coordinated Universal Time (UTC) for the PDT.

    The PDT information helps downstream players to synchronize the stream to the wall clock, enabling functionality like viewer seek in the playback timeline and time display on the player.

  5. For Ad markers, choose how ad markers are included in the packaged content. If you include ad markers in the content stream in your upstream encoders, then you need to inform MediaPackage what to do with the ad markers in the output. If you don't see this field, select Enable SCTE support in the origin endpoint segment settings. Choose from the following options:

    • Daterange – Insert EXT-X-DATERANGE tags to signal ads and program transition events in TS and CMAF output manifests. If you choose daterange, you must also enter a Program date/time interval (sec.) value of 1 or greater.

  6. For Filter Configuration, optionally add Manifest filter, Start time, End time, and Time delay. These filters apply to all egress requests for your endpoint.

    To automatically fill these values from an existing query string, choose Import from query string. For example, you can import the following query string to automatically fill in Filter key video_codec, Filter value h265, Filter key audio_language, Filter value fr,en-US, Start time 2023-10-20T12:20:50Z, End time 2023-10-20T13:20:50Z, and Time delay 10 seconds: aws.manifestfilter=video_codec:h265;audio_language:fr,en-US,de&start=2023-10-20T12:20:50Z&end=2023-10-20T13:20:50Z&time_delay=10

    Manifest filter

    Optionally specify one or more manifest filters for all of your manifest egress requests.

    You enter a Filter key and Filter value pair for each manifest filter. For a list of supported keys and values, see Manifest filter query parameters in AWS Elemental MediaPackage.

    For example, to restrict all manifest egress requests to 0 to 44000 Hz audio sample rate, 0 to 2147483647 video bitrate, H265 video codec, and French and English languages, enter the following key and value pairs:

    Filter key audio_sample_rate | Filter value: 0-44100

    Filter key video_bitrate | Filter value: 0-2147483647

    Filter key video_codec | Filter value: H265

    Filter key audio_language | Filter value: fr,en-US

    Start time and End time

    Optionally specify the start or end time for all of your manifest egress requests.

    For more information about start and end times, see Time-shifted viewing with AWS Elemental MediaPackage.

    Note that if you enter a start or end time using the API, or import using Import from query string in the MediaPackage console, enter dates in an ISO-8601 format.

    Time delay

    Optionally specify the time delay (in seconds) for all of your manifest egress requests.

    For more information about using time delays, see Delay content availability from AWS Elemental MediaPackage.

Note

When you include a Manifest filter, you cannot use matching query parameters for the manifest's endpoint URL. If you do, you will receive a 404 HTTP error code instead. For example, if you include a Manifest filter with a audio_sample_rate Filter key and 44100 Filter value, and you make an HTTP request for https://<example-url>/?aws.manifestfilter=audio_sample_rate:44100, you will receive a 404 error.

Create a DASH manifest

To create a DASH manifest
  1. For Manifest name, enter a short string that will be appended to the endpoint URL. The manifest name creates a unique path to this endpoint. If you don't enter a value, MediaPackage uses the default manifest name, index. MediaPackage automatically inserts the format extension, such as .mpd. Supported characters are A-Z, a-z, 0-9, and - (hyphen). You can't use underscores in the name.

  2. For Manifest window (sec.) enter the total duration (in seconds) of the manifest's content. The maximum manifest window is 900 seconds (15 minutes). You can request a quota increase if necessary.

  3. For Min update period (sec.), enter the minimum amount of time (in seconds) that the player should wait before requesting manifest updates. A lower value means that manifests are updated more frequently, but a lower value also contributes to request and response network traffic.

  4. For Min buffer time (sec.), enter the minimum amount of time (in seconds) that a player must keep in the buffer. If network conditions interrupt playback, the player will have additional buffered content before playback fails, allowing for recovery time before the viewer's experience is affected.

  5. For Suggested presentation delay (sec.), enter the amount of time (in seconds) that the player should be from the end of the manifest. This sets the content start point back x seconds from the end of the manifest (the point where content is live). For example, with a 35-second presentation delay, requests at 5:30 receive content from 5:29:25. When used with time delay, MediaPackage adds the suggested presentation delay to the time delay duration.

  6. For Segment template format, choose how MediaPackage and playback requests refer to each segment.

    • For Number with timeline, MediaPackage uses the $Number$ variable to refer to the segment in the media attribute of the SegmentTemplate tag. The value of the variable is the sequential number of the segment. SegmentTimeline is included in each segment template.

  7. For UTC timing, select the method that the player uses to synchronize to coordinated universal time (UTC) wall clock time. This enables the player and MediaPackage to run on the same UTC wall clock time. This is a requirement, otherwise playback timing or synchronization issues can occur. Choose from the following options:

    • UTC Direct

    • HTTP Head

    • HTTP Iso

    • HTTP Xsdate

  8. For UTC timing source, specify a URI to use for UTC synchronization. This is the URI used to fetch the timing data according to the scheme defined by UTC timing. This value is only valid if UTC timing is not NONE or UTC DIRECT. This value will be set as the @value attribute for the UTCTiming element. For information about @value, see DASH, DASH UTC Timing Schemes, 5.8.5.7.

  9. For DASH period triggers, choose how MediaPackage creates media presentation description (MPD) periods in the DASH output manifest. For more information, see Multi-period DASH in AWS Elemental MediaPackage. Choose from the following options:

    • Avails – Avails that pass the ScteFilter will create new periods.

    • DRM key rotation – Encryption key rotation will create new periods.

    • Source changes – Changes in the stream set will create new periods.

    • Source disruptions – Gaps in all content streams will create new periods.

    • None – MediaPackage formats the manifest as a single period. It doesn't create additional periods, unless DRM settings change.

    Note

    New periods will always be created on DRM settings changes, independently of the DASH period triggers that you configure.

  10. For Ad markers, choose how ad markers are signaled in the output manifests. All the non-ad markers that you include in the content stream in your upstream encoders will also be present in the output manifests. Choose from the following options:

    • Binary – The SCTE-35 marker is expressed as a hex-string (Base64 string) rather than full XML.

    • XML – The SCTE marker is expressed fully in XML.

  11. For Filter Configuration, optionally add Manifest filter, Start time, End time, and Time delay. These filters apply to all egress requests for your endpoint.

    To automatically fill these values from an existing query string, choose Import from query string. For example, you can import the following query string to automatically fill in Filter key video_codec, Filter value h265, Filter key audio_language, Filter value fr,en-US, Start time 2023-10-20T12:20:50Z, End time 2023-10-20T13:20:50Z, and Time delay 10 seconds: aws.manifestfilter=video_codec:h265;audio_language:fr,en-US,de&start=2023-10-20T12:20:50Z&end=2023-10-20T13:20:50Z&time_delay=10

    Manifest filter

    Optionally specify one or more manifest filters for all of your manifest egress requests.

    You enter a Filter key and Filter value pair for each manifest filter. For a list of supported keys and values, see Manifest filter query parameters in AWS Elemental MediaPackage.

    For example, to restrict all manifest egress requests to 0 to 44000 Hz audio sample rate, 0 to 2147483647 video bitrate, H265 video codec, and French and English languages, enter the following key and value pairs:

    Filter key audio_sample_rate | Filter value: 0-44100

    Filter key video_bitrate | Filter value: 0-2147483647

    Filter key video_codec | Filter value: H265

    Filter key audio_language | Filter value: fr,en-US

    Start time and End time

    Optionally specify the start or end time for all of your manifest egress requests.

    For more information about start and end times, see Time-shifted viewing with AWS Elemental MediaPackage.

    Note that if you enter a start or end time using the API, or import using Import from query string in the MediaPackage console, enter dates in an ISO-8601 format.

    Time delay

    Optionally specify the time delay (in seconds) for all of your manifest egress requests.

    For more information about using time delays, see Delay content availability from AWS Elemental MediaPackage.

Note

When you include a Manifest filter, you cannot use matching query parameters for the manifest's endpoint URL. If you do, you will receive a 404 HTTP error code instead. For example, if you include a Manifest filter with a audio_sample_rate Filter key and 44100 Filter value, and you make an HTTP request for https://<example-url>/?aws.manifestfilter=audio_sample_rate:44100, you will receive a 404 error.