Manifest Personalization for HLS & AMD

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.

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.

  1. 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:

DeviceIdentifying DeviceHLS Master Manifest ModificationsCorresponding Query Parameter
iOS cellular
  • UA match on *iPhone*OS* or *iPad*OS*, and
  • match:client.edgescape2 field="NETWORK_TYPE" value="mobile" check-ips="connecting"

A preferred bit rate of 730 kbps is applied. The "b" is prefaced and followed by two, simultaneous underscore characters.

__b__=730

iOS wifi
  • UA match on *iPhone*OS* *iPad*OS*,

A preferred bit rate of 2000 kbps is applied. The "b" is prefaced and followed by two, simultaneous underscore characters.

__b__=2000

tvOS (Apple TV)
  • UA match on *AppleCoreMedia*Apple\ TV*
  • A preferred bit rate of 2000 kbps is applied. The "b" is prefaced and followed by two, simultaneous underscore characters.
  • Bit rates close to 145 kbps should not be present. We exclude bit rates lower than 200 kbps, because known Apple guidance states that you shouldn't include the 145 kbps bit rate.
  • __b__=2000
  • b-in-range=200

📘

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 firstin 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:

Settings appliedExampleResult
  • Preferred Bitrate (kbps) : 1000
1000 kbps or the bit rate closest to it, within a tolerance of ±100 kbps is set as the first bit rate in the master manifest file.
  • Preferred Bitrate (kbps) : 1500
  • Bitrates to Keep (Filter IN) : 1500 and 2000
  1. The bit rate closest to 1500 kbps (within a ± 100 kbps tolerance) is included.
  2. The bit rate closest to 2000 kbps (within a ± 100 kbps tolerance) is included.
  3. A preferred bit rate is selected, using the filtered result of 1. and 2., with the value closest to 1000 used (within a ± 100 kbps tolerance).
  • Preferred Bitrate (kbps) : 1500
  • Bitrates to Keep (Filter IN) : 1500 and 2000
  • Bitrates within Ranges to Kep (Filter IN) : 2500-3000 and 3500 and up
  1. The bit rate closest to 1500 kbps (within a ± 100 kbps tolerance) is included.
  2. The bit rate closest to 2000 kbps (within a ± 100 kbps tolerance) is included.
  3. All bit rates within the range 2500 to 3000 kbps (exclusive of boundaries), along with those greater than 3500 kbps are included.
  4. A preferred bit rate is selected, using the filtered result of 1., 2. and 3., with the value closest to 1500 kbps used.

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 firstin 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 simultaneousunderscore 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 (IMAGE_STUBIMAGE_STUB) 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.

HeaderDescription
Akamai-Manifest-Personalization-Config-Source This header indicates the source of the applied manifest personalization operations.
  • UI-. Only settings defined for the Manifest Personalization rule in the AMD configuration (UI) were used.
  • QUERY. Only query string parameter values were used.
  • UI-QUERY. A combination of configuration values was used from the Manifest Personalization rule (UI) and query string parameters were used.
Akamai-Manifest-Personalization This header reveals all manifest personalization operations, filtering and preferred bit rate, that were applied to your request. For example, Akamai-Manifest-Personalization: b-in=300,400&b-in-range=500-&__b__=600

📘

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


Did this page help you?