# Time-shifted viewing with AWS Elemental MediaPackage Time-shifted viewing`time_delay` query parameters added to time-shifted viewing reference Added information on using `time_delay` query parameters. Time-shifted viewing is available with live workflows in AWS Elemental MediaPackage. *Time-shifted viewing* means that viewers can start watching a live stream at a time earlier than "now," permitting them to join from the beginning a show that's already in progress or to watch a show that's already completed. Time-shifted viewing effectively makes live events available for viewing on demand. MediaPackage supports time-shifted viewing for content that's up to 336 hours (14 days) old. You can enable time-shifted viewing for some or all of this content by defining the **startover window** on the endpoint. Manifests from within the startover window can be time shifted. The following steps describe time-shift options and how to set them up. In these steps, "now" is determined either by the program date time (PDT) present in the source content from the encoder or, if this PDT information is not included, by the MediaPackage ingest time of the most recent segment. **Important** When using time-shifted viewing, we recommend using consistent playback windows across player sessions, rather than generating a unique start or end time for each viewer. This yields better caching at the CDN, and will avoid running into potential throttling related to those requests, on the MediaPackage level. ## Step 1: Set the startover window To create time-shifted manifests, you must define the live content that will be made available to view on demand. In MediaPackage, this eligible content is identified in your startover window. The startover window can be up to 24 hours long. You can set the window on the endpoint object, either through the MediaPackage console or MediaPackage API. You might notice that the manifest lags behind real time when you initially create a startover window on an endpoint. This is because MediaPackage starts filling the manifest from the start of the window, and works up to "now." So, if you have a 24-hour startover window, MediaPackage fills the manifest starting 24 hours ago and working up to "now." ## Step 2: Choose time-shifted options You can apply time-shifted options to all manifests that originate from a MediaPackage endpoint by configuring the option on the endpoint. Alternatively, you can apply these options dynamically at the time of the content playback request by including query parameters. You can choose from the following time-shifted options: + Delay content availability: Set a delay for availability of live content. + Define a manifest start and end: Set the time blocks of content are available from within the startover window. These blocks are defined by times provided in the start and end parameters. + Limit a manifest duration : blocks of content with the specified duration are available within the startover window. The blocks are defined by the duration (in seconds) of the content and can come from different places in the startover window. To use time shifting on all manifests that originate from an endpoint, set the filter configuration in the manifest settings of the endpoint. For more information, see [Manifest fields](endpoints-create.md#endpoints-manifest). To use time shifting dynamically across requests, append query parameters to playback requests. For more information, see [Time-shifted query parameters](msettings-params.md). Learn more about these options in the following topics. **Topics** + [ ## Step 1: Set the startover window ](#enable-startover) + [ ## Step 2: Choose time-shifted options ](#use-params) + [Time-shifted query parameters](msettings-params.md) + [Time delay](time-delay.md) + [Start and end parameters](start-and-end-parameters-rules.md) + [Window duration](window-seconds.md) + [Time-shifted viewing examples](time-shift-examples.md) # Time-shifted query parameters in AWS Elemental MediaPackage Time-shifted query parameters To use time-shifted viewing query parameters, append `aws.manifestsettings` to your playback request to MediaPackage. MediaPackage evaluates the query, and serves a client manifest based on those query parameters. The following sections describe how to configure time-shift viewing query parameters. ## Query parameter formatting Use the following guidelines when constructing query parameters: + Queries are not case sensitive. + Queries can be up to 1,024 characters. + Reserved characters in the queries must be URL encoded as indicated in the [URI: General Syntax](https://datatracker.ietf.org/doc/html/rfc3986) standard. **Important** At a minimum, if your query includes multiple parameters, the following characters in the query must be URL encoded. If they're not, MediaPackage processes just the first query parameter in the string. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) If the query is malformed, MediaPackage returns an incomplete or empty manifest. For query syntax, see the following section. ## Query syntax The base query parameter for time-shifted viewing is `aws.manifestsettings`, which is followed by optional parameter name and value pairs. To construct the query, append `?aws.manifestsettings=` to the end of the MediaPackage endpoint URL, followed by parameter names and values. For a list of all of the available parameters, see [Query parameters](#msettings-parameters). An Apple HLS filter query might look like this: `https://example-mediapackage-endpoint.mediapackage.us-west-2.amazonaws.com/out/v1/examplemediapackage/index.m3u8?aws.manifestsettings=` The query syntax is listed in the following table. **Note** If you use Amazon CloudFront as your CDN, you might need to set additional configurations. For more information, see [Configure cache behavior for all endpoints](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/live-streaming.html#live-streaming-with-mediapackage-create-cache-behavior). | Query string component | Description | | --- | --- | | ? | A restricted character that marks the beginning of a query. | | aws.manifestsettings= | The base query, which is followed by parameters constructed of name and value pairs. For a list of all of the available parameters, see [Query parameters](#msettings-parameters). | | : | Used to associate the parameter name with a value. For example, parameter\$1name:value. | | ; | Separates parameters in a query that contains multiple parameters. For example, parameter1\$1name:value;parameter2\$1name:minValue-maxValue. When used in a list of parameters for the same query, implies an AND operation. | **Date and time format requirements** In all cases, the date and time must be notated in one of the following formats: + ISO 8601 dates, such as 2017-08-18T21:18:54%2B08:00, where **%2B08:00** is the timezone UTC\$108:00. The plus (\$1) must be URL-encoded. + POSIX (or Epoch) time, such as 1503091134 **DASH parameter rules** Start and end parameters in the URL request for DASH content can use standard parameter notation, or can be included as path elements in the URL. + Query parameter notation – start and end parameters are included at the end of the request URL **Example** ``` https://cf98fa7b2ee4450e.mediapackagev2.us-east-1.amazonaws.com/out/v1/997cbb27697d4863bb65488133bff26f/sports.mpd?start=1513717228&end=1513720828 ``` + Path elements – start and end parameters are included in the path of the request URL **Example** ``` https://cf98fa7b2ee4450e.mediapackagev2.us-east-1.amazonaws.com/out/v1/997cbb27697d4863bb65488133bff26f/start/2017-12-19T13:00:28-08:00/end/2017-12-19T14:00:28-08:00/sports.mpd ``` **TS and CMAF parameter rules** Start and end parameters in the URL request for TS content can use standard parameter notation. + Query parameter notation – start and end parameters are included at the end of the request URL **Example TS** ``` https://cf98fa7b2ee4450e.mediapackagev2.us-east-1.amazonaws.com/out/v1/064134724fd74667ba294657a674ae72/comedy.m3u8?start=2017-12-19T13:00:28-08:00&end=2017-12-19T14:00:28-08:00 ``` **Example CMAF** ``` https://cf98fa7b2ee4450e.mediapackagev2.us-east-1.amazonaws.com/out/v1/064134724fd74667ba294657a674ae72/manifest_id/news.m3u8?start=2018-04-04T01:14:00-08:00&end=2018-04-04T02:15:00-08:00 ``` ## Query parameters Playback devices can append the following time-shifted viewing query parameters to their requests to MediaPackage. Responses to requests with one or more of these parameters will include manifests that adhere to the specified time-shifted query parameters. If you want all manifests served from this origin endpoint to be time shifted, enable the settings on the endpoint, as described in [Creating an origin endpoint in AWS Elemental MediaPackage](endpoints-create.md). **Note** The `manifest_window_seconds` option is available only as a query parameter on a session initialization URL, and not as a setting on the endpoint. This is because the `manifest_window_seconds` query parameter modifies the standard length of the manifest that's configured through the **Manifest window** setting on the endpoint. For more information about manifest window relationships, see [Window duration](window-seconds.md). | Name | Description | Example | | --- | --- | --- | | clip\$1start\$1time | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) | stream.mpd?aws.manifestsettings=subtitle\$1language:en-US, hi;clip\$1start\$1time:1720246778 | | manifest\$1window\$1seconds | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) | stream.mpd?aws.manifestsettings=manifest\$1window\$1seconds:30 | | start | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) | stream.mpd?aws.manifestsettings=start:1732285823 | | end | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) | stream.mpd?aws.manifestsettings=end:1732300175 | | time\$1delay | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/msettings-params.html) | stream.mpd?aws.manifestsettings=time\$1delay:320 | ## URL encoding query parameters URL encoding query parameters Added information about how to URL encode the query parameters in manifest requests to MediaTailor.Manifest filters MediaPackage added support for manifest filters for endpoint egress requests. When you add query parameters to your HLS and LL-HLS playback requests, MediaPackage appends the parameters in alphabetical order to the child manifest URLs. For instance, the `end` parameter is listed before the `start` parameter. To [create a signed API request](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html#create-canonical-request) for AWS Signature Version 4 (SigV4) signing, your query strings must be URL encoded. By default, MediaPackage doesn't encode query parameters. To be a valid SigV4 signature, choose **URL-encode HLS child manifest query parameters** on your HLS or LL-HLS origin endpoint, as described in [Manifest fields](endpoints-create.md#endpoints-manifest). For more information about SigV4 and its requirements, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in *AWS Identity and Access Management User Guide*. **Example unencoded query strings** ``` hls_video-1080.m3u8?aws.manifestsettings=time_delay:10&end=2025-02-03T17:09:49Z&start=2025-02-03T17:08:49Z ``` **Example URL-encoded query strings** ``` hls_video-1080.m3u8?aws.manifestsettings=time_delay%3A10&end=2025-02-03T17%3A09%3A49Z&start=2025-02-03T17%3A08%3A49Z ``` # Delay content availability from AWS Elemental MediaPackage Time delay You can specify a duration (in seconds) for MediaPackage to delay when content is available to players. The minimum time is 0 seconds. The following rules determine the maximum time: + If `startoverwindow` is equal to `0`, the maximum time is 86,400 seconds (24 hours). + If `startoverwindow` is not equal to `0`, the maximum time is the value of `startoverwindow`. Use `time_delay` to redefine the live point and make content available at a time that equals "now" minus the delay specified. With a 60-second `time_delay`, content that MediaPackage receives at 12:20 isn't available until 12:21. Requests for playback at 12:20 will be served with content from 12:19. Likewise, if you're serving content across time zones, you can set a `time_delay` equal to the time zone difference to make content available at, for example, 8:00 local time. The time delay duration must be less than the startover window duration. **Tip** Use a `time_delay` to help reduce buffering during input switching when you're using input redundancy with short output segments. Note that the delay can increase latency in content playback. ## Using clip start with time delay Added clip-start time delay Added information about using clip-start query parameters with time delayed live content. When you use the time delay function in MediaPackage, content availability is delayed by the specified amount. As content progresses, the manifest grows to your specified manifest window (seconds). Until the manifest has reached that window size with new content, content from before the start time can be available. For example, one event ends at 925, and the other starts at 930. You set the time delay for the 930 event so that content is available at 932, and you defined your manifest window as 900 seconds (15 minutes). A viewer starts watching the event at 935, which is 3 minutes into the event. The manifest is 15 minutes long, so there is still another 12 minutes of content available from before the event started, so the viewer can see content from the event that ended at 925. Depending on your contractual obligations, you might not want viewers to have access to the earlier content. To mitigate these concerns, you can use the clip start functionality in MediaPackage. With clip start, you can specify the earliest available content in the manifest. In the previous example, you could set the clip start time to 930 to ensure that viewers can’t see content from before the current event. You can enable the clip start setting on this endpoint so that all manifests that originate from this endpoint will include the clipped time. For information about adding clip start to an endpoint, see [Creating an origin endpoint in AWS Elemental MediaPackage](endpoints-create.md). Alternatively, manifest requests that include the `aws.manifestsettings=clip_start_time:` query parameter will be clipped so that content from before the specified time is not available. Requests to this endpoint that don’t include the query parameter will receive a standard manifest, as defined by the endpoint’s settings. MediaPackage returns an error to the requesting device if the clip start is set on the endpoint and included in request query parameters. **A note about start parameters** Clip start can’t be used with *start *and *end *parameters. Clip start and start parameters offer similar functionality, but have different practical purposes. + Clip start is used to ensure that content before the set time is blocked. The manifest continues to grow, up to the defined window duration. + Start is used to ensure that content before the set time is blocked. If used with an *end *parameter, the returned manifest ends at the specified time. If not used with an *end *parameter, the returned manifest continues to grow up to the value of the startover window. # Define manifest start and end times from AWS Elemental MediaPackage Start and end parameters MediaPackage accepts requests for up to 24 hours of content. When requests with start and end parameters that are within the startover window are sent to this endpoint, MediaPackage generates a manifest for the requested timeframe. If the start parameter is outside of the startover window, or if the end parameter is before the startover window, the playback request fails. If no start and end parameters are used, the service generates a standard manifest. Start and end parameters denote the beginning and end of a time-shifted manifest from MediaPackage. The playback device can append parameters to the end of a manifest request. Alternatively, the start and end parameters can be specified for the manifest through Filter Configuration parameters. For more information, see step 7 in [Manifest fields](endpoints-create.md#endpoints-manifest). For packager-specific rules about how you can notate the parameters, see [Time-shifted query parameters](msettings-params.md). The start and end parameters determine the time boundaries of the manifest. These are the expected behaviors based on request start and end parameters: + If both start and end parameters are specified, the resulting manifest has a fixed start and end time that correspond to the specified start and end parameters. + If the end time is in the future, the tags in the manifest are consistent with an event manifest. The manifest will continue to grow until it reaches the end time, at which point it will become a VOD manifest. + If start or end parameters are used that are before the first segment is ingested, or after the last segment is ingested, the playback duration won't match the manifest duration as requested through the query parameters. + If the start time is specified and the value is earlier than when the first segment is ingested, MediaPackage uses the actual time that the first segment is ingested as the start of the manifest. + If the end time is specified and is later than when the last segment is ingested, MediaPackage uses the actual time that the last segment is ingested as the end of the manifest. + If a start parameter is specified without an end parameter, the resulting manifest will have a fixed start time corresponding to the specified start parameter, while the end of the manifest will grow as the live content progresses. **Note** For TS output, many playback devices start playback at the current time ("now"). To view the content from the actual start time of the playback window, viewers can seek back on the playback progress bar. + If no start time or end time parameters are specified, the service will generate a standard manifest. # Limit manifest duration from AWS Elemental MediaPackage Window durationAdded content about limiting the duration of a manifest Added information about `manifest_window_seconds` query parameters, which can be used to request shorter manifests on a session-level basis. To dynamically request shorter manifests than the manifest window that's configured on the endpoint, use the `?aws.manifestsettings=manifest_window_seconds:` query parameter. When used at session initialization, the resulting manifest will conform to the number of seconds that you specify in the parameter. With `manifest_window_seconds`, you can serve manifests that are a variety of lengths, all from the same endpoint. If `aws.manifestsettings=manifest_window_seconds:` isn't included in the request query parameters, MediaPackage serves a manifest the length of the window that's configured through **Manifest window (sec)** in the manifest settings when the endpoint was created. Query parameters in the `aws.manifestsettings` namespace provide additional session-level time manipulation options. See [Time-shifted query parameters](msettings-params.md) for an overview. To filter session-level manifests by audio, video, and subtitle formats, see [Manifest filtering](manifest-filtering.md). # Time-shifted viewing examples in AWS Elemental MediaPackage Time-shifted viewing examples These are MediaPackage time-shifted viewing examples. **Start parameters use case** I need content to start playing from where the customer left off. **Solution**: Include the `start` parameter in the playback request URL. Program your playback device to record the time that they customer stopped the stream, then use this timestamp as the value for the `start` parameter. **Example** ``` ...stream.mpd?aws.manifestsettings=start:1732285823 ``` **End parameters use case** I need to define when the live content ends. Content is available for playback after this point, but live content won't be added. **Solution**: Ensure the **startover window** on the endpoint accurately reflects how long you want the live content to be available for playback (up to 14 days). In playback requests, include the `end` parameter and use the time that live content ends as the parameter value. **Example** ``` ...stream.mpd?aws.manifestsettings=end:1732300175 ``` **Manifest window use case** I need to serve manifests of varying length from the same manifest URL because my customers use a variety of devices that have different limitations on manifest window lengths. **Solution**: Include the `manifest_window_seconds` parameter in playback request URLs. Use the length limitations from each device as the value of for the `manifest_window_seconds` parameter. **Example** ``` ...stream.mpd?aws.manifestsettings=manifest_window_seconds:30 ``` ``` ...stream.mpd?aws.manifestsettings=manifest_window_seconds:120 ```