Add Manifest Personalization (MPer) to enhance the viewing experience by individualizing Apple HTTP Live Streaming (HLS) video quality to best suit your end-user's devices.

When a request is sent to a property hostname that's been set in your AMD property, and it matches the criteria set for a rule that includes MPer for HLS, a manifest is generated "on-the-fly." This manifest determines the appropriate video quality content for the requesting device. Manifest Personalization for HLS offers the following benefits:

• You can implement preferred bit rate and bit rate filtering. These allow you to maintain quality and performance to deliver the most optimal playback experience for each end user.

• You can offload the master manifest file manipulation. This lets you target unique device profiles and geographic/network characteristics.

• You can reduce the associated computation and storage overhead on your origin.

📘

Manifest and Playlist Manipulation in EdgeWorkers

Alternatively, you can use an EdgeWorkers function to dynamically create personalized Video on Demand (VOD) or live manifest and playlist files.

Supported video formats

Manifest Personalization is supported for use with both live and on-demand HLS media.

Get access to Manifest Personalization

You need to have this added to your contract to access the appropriate behavior in Property Manager. Contact your account representative to add this functionality.

Add Manifest Personalization and set the match criteria

Once it's on your contract, you can add Manifest Personalization to your AMD property. It's added as an optional rule to the property.

1. Create a new AMD property, or edit an existing one using Property Manager in ​Akamai Control Center​.

2. In the Property Configuration Settings options, click Add Rule.

3. In the Available Rules (by Category) field, type Manifest Personalization to filter and select it from the list.

4. By default, the Criteria is set to various common file names that represent HLS Master Manifest files. You can add or remove filenames as necessary.

📘

You can use wildcard characters for manifest filenames. For example, you could use "master-*.m3u8." But, make sure that your master manifest naming convention doesn't overlap with your media playlists and segments.

5. Set Enable Manifest Personalization to On.

Once enabled, you need to select the appropriate Mode to configure Manifest Personalization, and you can optionally apply other available settings.

Configure "Best Practices" Mode (recommended)

The Best Practice configuration mode automatically applies industry recommended settings to help provide a better playback experience, for multiple device formats.

The automatic settings are sourced from the best practices laid out by Apple:

📘

The Apple HLS Content Authoring Specification that specifies the best practices discussed above can be found here.

Configure "Manual" Mode

The Manual configuration Mode offers flexibility and lets you define your own settings (instead of using our predefined best practice settings).

You can use any or all of these settings to personalize your manifests:

• Preferred Bitrate (kbps). This option allows you to control which media playlist (the #EXT-X-STREAM-INFtag) is listed _first_in the manifest. Specify the desired bit rate (in kbps). The playlist that matches closest to this bit rate value—within a tolerance of ±100 kbps—is listed first. All other playlists maintain their current position in the manifest.

• Bitrates to Keep (Filter IN). Input a comma-separated list of individual bit rate values, in kbps to use in the manifest, or filter in, if you're using additional Manual Mode options. For example, 100,200, 400. Only media playlists within a tolerance of ± 100 kbps of the specified bit rates are kept in the manifest.

• Bitrates within Ranges to Keep (Filter IN). Input a comma-separated list of bit rate ranges, in kbps to use with the manifest, or filter in, if you're using additional Manual Mode options. For example, 100-400,1000-3000. Only media playlists within the specified bit rate ranges are kept in the manifest.

📘

If you're also including one or both of the "filter in" options, the Preferred Bitrate is picked from the final list of filtered bit rates after these operations are applied. Also, you can set open-ended ranges ("1000-") to set a starting bit rate range with no end.

Manual Mode examples

Here are a few use case examples of this functionality:

You can override settings on a per-request basis

You can include query string parameters in requests for the manifest, to customize its content. The settings specified in a query string take precedence over the settings you've defined in the Manifest Personalization rule.

1. Set the Enable Query Param based Personalization switch to On.

2. You need to set up request URLs for your clients to include the appropriate query string values.

3. As the request comes in from a specific client, its query string parameters override what you've set in the AMD property for Manifest Personalization.

This can be applied for both Best Practice and Manual modes.

Available query string values

With Enable Query Param based Personalization enabled, you can use the following values in a request's query string:

• __b__: Include this in the string and specify the desired bit rate (in kbps) to set a "Preferred Bitrate." This determines which media playlist (the #EXT-X-STREAM-INFtag) is listed _first_in the manifest, within a tolerance of ±100 kbps of each value. (So, the playlist that matches closest to the query string-set bit rate is listed first.) Note that the b in this value is prefaced and followed by _two simultaneous_underscore characters.

• b-in: Include this in the string and include a comma-separated list of bit rate values in kbps (100,200,400) to filter in "Bitrates to Keep." This lets you control which media playlists (the #EXT-X-STREAM-INFtag) are kept in the manifest, within a tolerance of ±100 kbps of each value.

• b-in-range: Include this in the string and include a comma-separated list of bit rate ranges in kbps (100-400,1000-4000) to filter in "Bitrates to Keep." Only media playlists (the #EXT-X-STREAM-INFtag) within the specified bit rate ranges are kept in the manifest.

📘

If you're also including one or both of the "filter in" options, the Preferred Bitrate is picked from the final list of filtered bit rates after these operations are applied. Also, you can set open ended ranges ("1000-") to set a starting bit rate range with no end.

Here's an example of query string parameter usage:

?__b__=500&b-in=100,200&b-in-range=500-2000

Optional settings

• Secret Key for Honoring Query Params (Optional): Use this to allow query string parameters only if the request is accompanied by the appropriate token. You can manually input a key, or use the cycle button () to automatically generate one for you. You then need to use this key to generate a token (with the TokenAuth 2.0 library), and append that token as a query string in requests for the manifest. (For example, ?mper=<token>).

  • TokenAuth 2.0 Token Generation SDKs: https://github.com/akamai?utf8=%E2%9C%93&q=token&type=&language= (You can obtain the SDKs here, and README files are available that offer instructions on use.)

  • Sample command to generate a token using our TokenAuth 2.0 python library: In the command below, n specifies the token name, w specifies the token validity window, k specifies the secret key, and a specifies the access list.

python cms_edgeauth.py -n mper -w 31536000 -k abc123 -a '/*'

• Transition Key (Optional): If necessary, specify a secondary key for query string parameter verification. This is also a TokenAuth 2.0 version key that is used for transition purposes, in the event that you disable or end-of-life what you have set as the Secret Key for Honoring Query Params key.

You can set Advanced options

Set the Show Advanced switch to On to reveal additional options for use.

Enable Debug Headers

Once enabled, your requests for the HLS Master Manifest also contain two additional headers, Akamai-Manifest-Personalizationand Akamai-Manifest-Personalization-Config-Source, that can be used for troubleshooting purposes.

📘

Debug headers are only added for requests with HTTP response codes 200 and 400.