Vega Parental Controls

Vega Parental Controls provides application developers a centralized way to restrict viewing of video content based on the end-user’s content restriction settings.

For API reference, see the Vega Parental Controls API Overview.

• Content Ratings
  • Concepts
    • Rating systems
    • Content ratings
    • Content Descriptors
  • Building a content rating
  • Supported content rating systems with identifier listings
    • Rating systems
    • Ratings Systems with values and descriptions
    • Content descriptors
• Content restriction levels (CRL)
  • Querying the content restriction level programmatically
• Integrating with parental controls for content restriction management
  • Prerequisites
  • Add parental controls to Your project
    • Declare parental controls privileges
    • Code sample

The user creates a PIN when enabling parental controls the first time. Afterwards, when another user encounters a restricted video, the PIN prompt appears. That user must enter the correct PIN in order to access that content.

The content restriction level is is set by the user in Settings > Preferences > Parental Controls > Viewing Restrictions.

Content Ratings

Concepts

Rating systems

A rating system is a standard for video content, such as movies and television shows. For example, the Motion Picture Association (MPA) and TV Parental Guidelines are commonly used rating standards in the United States. Korea Media Rating Board is a standard for Korean films. Most content rating systems have a recommended minimum age for viewers.

Content ratings

A content rating is assigned to a particular video by according to one of these rating system. For example, the MPA assigns the movie Titanic a rating of PG-13.

Content Descriptors

A rating system may use content descriptors to specify content warnings about a video. For example, the TV Parental Guidelines system uses the descriptors D, L, S, and V (suggestive dialogue, coarse language, sexual content, and violence) in their TV-14 rating.

Building a content rating

A content rating is represented in code as an object that can be passed to the parental controls API functions. The @amazon-devices/kepler-media-content-metadata NPM package defines these content rating objects. Typical usage of the content rating builder looks like the following.

import { ContentMetadataComponent } from '@amazon-devices/kepler-media-content-metadata';

// Defines a content rating of PG within the MPA ratings system.
const contentRating = await ContentMetadataComponent.makeContentRatingBuilder()
  .ratingsSystem('US_TV')
  .rating('US_TV_Y7')
  // The array of content descriptors is optional. You may pass an empty array or
  // simply omit calling this setter.
  .contentDescriptors(['US_TV_FV'])
  .build();

For an application that plays content served by a video catalog, the ratingsSystem and rating values come from the catalog metadata, rather than as hard-coded strings. Vega maintains a set of standard strings to represent each ratings system and each rating, so applications must translate these strings to standard Vega strings. The following is an example.

import { ContentMetadataComponent } from '@amazon-devices/kepler-media-content-metadata';

interface VideoData {
  contentRating: string;
}

// Mock of what might be returned from the catalog server.
// In this example, buildContentRating will return undefined (unrated) for
// the ratings TV::PG and MPA::X, since our translator doesn't recognize them.
async function fetchVideoData(): Promise<VideoData[]> {
  return [
    { contentRating: 'MPA::G' },
    { contentRating: 'MPA::PG' },
    { contentRating: 'MPA::PG-13' },
    { contentRating: 'TV::PG' }, // Unrecognized rating
    { contentRating: 'MPA::R' },
    { contentRating: 'MPA::NC-17' },
    { contentRating: 'MPA::X' }, // Unrecognized rating
  ]
}

// The purpose of this function is to translate these rating strings
// coming from the catalog server into standard Vega rating strings.
// In this example, we only know how to translate MPA ratings.
async function buildContentRating(videoData: VideoData): Promise<ContentRating|undefined> {
  let ratingsSystem: string = '';
  let rating: string = '';
  const [catalogRatingSystem, catalogRating] = videoData.contentRating.split('::');
  switch (catalogRatingSystem) {
    case 'MPA':
      ratingsSystem = 'US_MV';
      switch (catalogRating) {
        case 'G':
          rating = 'US_MV_G';
          break;
          case 'PG':
            rating = 'US_MV_PG';
            break;
          case 'PG-13':
            rating = 'US_MV_PG13';
            break;
          case 'R':
            rating = 'US_MV_R';
            break;
          case 'NC-17':
            rating = 'US_MV_NC17';
            break;
      }
  }
  // On an error, we receive an undefined content rating, which represents
  // unrated content. This always triggers a PIN prompt if parental controls
  // is enabled. TV::PG and MPA::X will throw errors here, since 
  // empty strings are passed which the builder does't allow.
  let result;
  try {
    result = await ContentMetadataComponent.makeContentRatingBuilder()
      .ratingsSystem(ratingsSystem)
      .rating(rating)
      .build();
  } catch(e) {
    console.log(`Failed to build content rating: ${videoData.contentRating} -> ${ratingsSystem}::${rating}\n${e}`);
  }
  return result;
}

Supported content rating systems with identifier listings

Rating systems

Ratings Systems with values and descriptions

Ratings System: SAMR

• SAMR_ALL - Recommended for all ages.
• SAMR_7 - Recommended for ages 7 and over.
• SAMR_13 - Recommended for ages 13 and over.
• SAMR_16 - Recommended for ages 16 and over.
• SAMR_18 - Recommended for ages 18 and over.
• SAMR_NR - Not rated.

Ratings System: AR_TV

• AR_TV - Suitable for all audiences. Programs may contain mild violence, language and mature situations.
• AR_TV_SAM_13 - Suitable for ages 13 and up. Programs may contain mild to moderate language and mild violence and sexual references.
• AR_TV_SAM_16 - Suitable for ages 16 and up. Programs may contain more intensive violence and coarse language, partial nudity and moderate sexual references.
• AR_TV_SAM_18 - Suitable for mature audiences only. Programs contain strong violence, coarse language and explicit sexual references.
• AR_TV_C - Suitable for 18-year-olds and over. Restricted to specially licensed venues.

Ratings System: AU_TV

• AU_TV_P - Recommended for younger children aged between 2 and 11 years.
• AU_TV_C - Recommended for older children aged between 5 and 14 years.
• AU_TV_G - Recommended for all ages.
• AU_TV_PG - Parental guidance is recommended for young viewers under 15.
• AU_TV_M - Recommended for mature audiences aged 15 years and over.
• AU_TV_MA - Not suitable for children and teens under 15, due to sexual descriptions, coarse language, adult themes or drug use.
• AU_TV_AV - Not suitable for children and teens under 15. This category is used specifically for violent programs.
• AU_TV_R - Not for children under 18. Content may include graphic violence, sexual situations, coarse language and explicit drug use.
• AU_TV_X - Restricted to 18 years and over. This classification is a special and legally restricted category which contains only sexually explicit content.

Ratings System: BR_TV

• BR_TV_ER - Especially recommended for children.
• BR_TV_L - Content is suitable for all audiences.
• BR_TV_10 - Content suitable for viewers over the age of 10.
• BR_TV_12 - Content suitable for viewers over the age of 12.
• BR_TV_14 - Content suitable for viewers over the age of 14.
• BR_TV_16 - Content suitable for viewers over the age of 16.
• BR_TV_18 - Content suitable for viewers over the age of 18.

Ratings System: CA_TV_EN

• CA_TV_EN_EXEMPT - Exempt from ratings.
• CA_TV_EN_C - Suitable for children ages 2–7.
• CA_TV_EN_C8 - Suitable for children ages 8 and older.
• CA_TV_EN_G - Suitable for the entire family.
• CA_TV_EN_PG - May contain moderate violence, profanity, nudity, and sexual references.
• CA_TV_EN_14 - Intended for viewers ages 14 and older.
• CA_TV_EN_18 - Intended for viewers ages 18 and older.

Ratings System: CA_TV_FR

• CA_TV_FR_E - Exempt from ratings.
• CA_TV_FR_G - Appropriate for all ages.
• CA_TV_FR_8 - Appropriate for children 8.
• CA_TV_FR_13 - Suitable for children 13.
• CA_TV_FR_16 - Recommended for children over the age of 16.
• CA_TV_FR_18 - Only to be viewed by adults.

Ratings System: DTMB

• DTMB_4- Recommended for ages 4 and over.
• DTMB_5 - Recommended for ages 5 and over.
• DTMB_6 - Recommended for ages 6 and over.
• DTMB_7 - Recommended for ages 7 and over.
• DTMB_8 - Recommended for ages 8 and over.
• DTMB_9 - Recommended for ages 9 and over.
• DTMB_10 - Recommended for ages 10 and over.
• DTMB_11 - Recommended for ages 11 and over.
• DTMB_12 - Recommended for ages 12 and over.
• DTMB_13 - Recommended for ages 13 and over.
• DTMB_14 - Recommended for ages 14 and over.
• DTMB_15 - Recommended for ages 15 and over.
• DTMB_16 - Recommended for ages 16 and over.
• DTMB_17 - Recommended for ages 17 and over.
• DTMB_18 - Recommended for ages 18 and over.

Ratings System: DVB

• DVB_4- Recommended for ages 4 and over.
• DVB_5 - Recommended for ages 5 and over.
• DVB_6 - Recommended for ages 6 and over.
• DVB_7 - Recommended for ages 7 and over.
• DVB_8 - Recommended for ages 8 and over.
• DVB_9 - Recommended for ages 9 and over.
• DVB_10 - Recommended for ages 10 and over.
• DVB_11 - Recommended for ages 11 and over.
• DVB_12 - Recommended for ages 12 and over.
• DVB_13 - Recommended for ages 13 and over.
• DVB_14 - Recommended for ages 14 and over.
• DVB_15 - Recommended for ages 15 and over.
• DVB_16 - Recommended for ages 16 and over.
• DVB_17 - Recommended for ages 17 and over.
• DVB_18 - Recommended for ages 18 and over.

Ratings System: ES_DVB

• ES_DVB_ALL- Recommended for all ages.
• ES_DVB_C- Recommended for children.
• ES_DVB_X- Recommended for adults.
• ES_DVB_4- Recommended for ages 4 and over.
• ES_DVB_5 - Recommended for ages 5 and over.
• ES_DVB_6 - Recommended for ages 6 and over.
• ES_DVB_7 - Recommended for ages 7 and over.
• ES_DVB_8 - Recommended for ages 8 and over.
• ES_DVB_9 - Recommended for ages 9 and over.
• ES_DVB_10 - Recommended for ages 10 and over.
• ES_DVB_11 - Recommended for ages 11 and over.
• ES_DVB_12 - Recommended for ages 12 and over.
• ES_DVB_13 - Recommended for ages 13 and over.
• ES_DVB_14 - Recommended for ages 14 and over.
• ES_DVB_15 - Recommended for ages 15 and over.
• ES_DVB_16 - Recommended for ages 16 and over.
• ES_DVB_17 - Recommended for ages 17 and over.
• ES_DVB_18 - Recommended for ages 18 and over.

Ratings System: FR_DVB

• FR_DVB_U- Recommended for all ages.
• FR_DVB_4- Recommended for ages 4 and over.
• FR_DVB_5 - Recommended for ages 5 and over.
• FR_DVB_6 - Recommended for ages 6 and over.
• FR_DVB_7 - Recommended for ages 7 and over.
• FR_DVB_8 - Recommended for ages 8 and over.
• FR_DVB_9 - Recommended for ages 9 and over.
• FR_DVB_10 - Recommended for ages 10 and over.
• FR_DVB_11 - Recommended for ages 11 and over.
• FR_DVB_12 - Recommended for ages 12 and over.
• FR_DVB_13 - Recommended for ages 13 and over.
• FR_DVB_14 - Recommended for ages 14 and over.
• FR_DVB_15 - Recommended for ages 15 and over.
• FR_DVB_16 - Recommended for ages 16 and over.
• FR_DVB_17 - Recommended for ages 17 and over.
• FR_DVB_18 - Recommended for ages 18 and over.

Ratings System: ISDB

• ISDB_4- Recommended for ages 4 and over.
• ISDB_5 - Recommended for ages 5 and over.
• ISDB_6 - Recommended for ages 6 and over.
• ISDB_7 - Recommended for ages 7 and over.
• ISDB_8 - Recommended for ages 8 and over.
• ISDB_9 - Recommended for ages 9 and over.
• ISDB_10 - Recommended for ages 10 and over.
• ISDB_11 - Recommended for ages 11 and over.
• ISDB_12 - Recommended for ages 12 and over.
• ISDB_13 - Recommended for ages 13 and over.
• ISDB_14 - Recommended for ages 14 and over.
• ISDB_15 - Recommended for ages 15 and over.
• ISDB_16 - Recommended for ages 16 and over.
• ISDB_17 - Recommended for ages 17 and over.
• ISDB_18 - Recommended for ages 18 and over.
• ISDB_19 - Recommended for ages 19 and over.
• ISDB_20 - Recommended for ages 20 and over.

Ratings System: KR_TV

• KR_TV_ALL - Appropriate for all ages.
• KR_TV_7 - May contain material inappropriate for children younger than 7, and parental discretion should be used.
• KR_TV_12 - May deemed inappropriate for those younger than 12, and parental discretion should be used.
• KR_TV_15 - May be inappropriate for children under 15, and that parental discretion should be used.
• KR_TV_19 - For adults only.

Ratings System: IN_CBFC

• IN_CBFC_U - Unrestricted public exhibition.
• IN_CBFC_UA - Unrestricted public exhibition, but with parental guidance for children below the age of 12 years.
• IN_CBFC_A - Restricted to adults.
• IN_CBFC_S - Restricted to any special class of persons.

Ratings System: JP_EIRIN

• JP_EIRIN_G - General, suitable for all ages.
• JP_EIRIN_PG12 - Parental guidance requested for young people under 12 years.
• JP_EIRIN_R15 - No one under 15 admitted.
• JP_EIRIN_R18 - No one under 18 admitted.

Ratings System: NZ_TV

• NZ_TV_G - Programmes which exclude material likely to be unsuitable for children. Programmes may not necessarily be designed for child viewers but should not contain material likely to alarm or distress them.
• NZ_TV_PGR - Programmes containing material more suited for mature audiences but not necessarily unsuitable for child viewers when subject to the guidance of a parent or an adult.
• NZ_TV_AO - Programmes containing adult themes and directed primarily at mature audiences.

Ratings System: SG_TV

• SG_TV_G - Suitable for all ages.
• SG_TV_PG - Suitable for all but parents should guide their young.
• SG_TV_PG13 - Suitable for persons aged 13 and above but parental guidance is advised for children below 13.
• SG_TV_NC16 - Suitable for persons aged 16 and above.
• SG_TV_M18 - Suitable for persons aged 18 and above.
• SG_TV_R21 - Suitable for adults aged 21 and above.

Ratings System: TH_TV

• TH_TV_4 - Suitable for audiences 3 to 5 years of age.
• TH_TV_6 - Suitable for audiences 6 to 12 years of age.
• TH_TV_10 - Suitable for all audiences.
• TH_TV_13 - Parental guidance suggested for viewers age below 13.
• TH_TV_18 - Parental guidance suggested for viewers age below 18.
• TH_TV_19 - Not suitable for children and teenagers.

Ratings System: UK_BBFC

• UK_BBFC_U - (Universal – Suitable for all) – A U-rated film should be suitable for audiences aged four years and over.
• UK_BBFC_PG - (Parental Guidance) – General viewing, but some scenes may be unsuitable for young children. A PG-rated film should not unsettle a child aged around eight or older..
• UK_BBFC_12 - (Suitable for 12 years and over) – Films classified 12A and video works classified 12 contain material that is not generally suitable for children aged under 12. No one younger than 12 may see a 12A-rated film in a cinema unless accompanied by an adult. No one younger than 12 may rent or buy a 12 rated video work.
• UK_BBFC_12A - (Suitable for 12 years and over) – Films classified 12A and video works classified 12 contain material that is not generally suitable for children aged under 12. No one younger than 12 may see a 12A-rated film in a cinema unless accompanied by an adult. No one younger than 12 may rent or buy a 12 rated video work.
• UK_BBFC_15 - (Suitable only for 15 years and older) – No-one under 15 is allowed to see a 15-rated film at the cinema or buy/rent a 15-rated video.
• UK_BBFC_18 - (Suitable only for adults) – No-one under 18 is allowed to see an 18-rated film at the cinema or buy/rent an 18-rated video.
• UK_BBFC_R18 - (To be shown only in specially licensed cinemas, or supplied only in licensed sex shops, and to adults only) – The R18 category is a special and legally restricted classification primarily for explicit works of consenting sex or strong fetish material involving adults. Films may only be shown to adults in specially licensed cinemas, and video works may be supplied to adults only in licensed sex shops. R18-rated video works may not be supplied by mail order.

Ratings System: US_MV

• US_MV_G - General Audiences. All Ages Admitted.
• US_MV_PG - Parental Guidance Suggested. Some Material May Not Be Suitable For Children.
• US_MV_PG13 - Parents Strongly Cautioned. Some Material May Be Inappropriate For Children Under 13.
• US_MV_R - Restricted. Children Under 17 Require Accompanying Parent or Adult Guardian.
• US_MV_NC17 - No One 17 and Under Admitted.

Ratings System: US_TV

• US_TV_Y - All Children.
• US_TV_Y7 - Directed to Older Children.
• US_TV_G - General Audience.
• US_TV_PG - Parental Guidance Suggested.
• US_TV_14 - Parents Strongly Cautioned.
• US_TV_MA - Mature Audiences Only.

Ratings System: ZA_FPB

• ZA_FPB_A - Suitable for all.
• ZA_FPB_PG - Parental Guidance.
• ZA_FPB_7_9PG - Not suitable for children under the age of 7. Children aged 7–9 years old may not be admitted unless accompanied by an adult.
• ZA_FPB_10_12PG - Not suitable for children under the age of 10. Children aged 10–12 years old may not be admitted unless accompanied by an adult.
• ZA_FPB_13 - Not suitable for children under the age of 13.
• ZA_FPB_16 - Not suitable for persons under the age of 16.
• ZA_FPB_18 - Not suitable for persons under the age of 18.
• ZA_FPB_X18 - No one under 18 admitted; restricted to licensed adult premises.

Content descriptors

The following are some descriptions for TV ratings for the US and Brazil.

Ratings System: US_TV

• US_TV_FV - Fantasy Violence. Valid only for US_TV_Y7.
• US_TV_D - Suggestive Dialogue. Valid for US_TV_PG and US_TV_14.
• US_TV_L - Coarse or Crude Language. Valid for US_TV_PG, US_TV_14, and US_TV_MA.
• US_TV_S - Sexual Situations. Valid for US_TV_PG, US_TV_14, and US_TV_MA.
• US_TV_V - Violence. Valid for US_TV_PG, US_TV_14, and US_TV_MA.

Ratings System: BR_TV

• BR_TV_D - Drugs. Valid for BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18.
• BR_TV_S - Sex. Valid for BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18.
• BR_TV_V - Violence. Valid for BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18.

Content restriction levels (CRL)

A content restriction level (CRL) is an end-user configuration that defines the most mature content an app is allowed to present without a PIN challenge (given that parental controls are enabled). Each level is represented as a reverse-DNS string, and applicable restriction levels differ by region.

The following table describes the different levels and what they map to in different rating systems.

Querying the content restriction level programmatically

The content restriction level can be queried and an application can use it to affect the user experience in other ways, such as displaying a restricted badge on applicable content. This API returns the name of the content restriction level and a list of ratings that define the CRL. An application cannot set the CRL, but only query it. The CRL is set by the end user in the app settings.

import { ParentalControlsComponent } from '@amazon-devices/kepler-parental-controls';

const preferenceReader = ParentalControlsComponent.makePreferenceReader();
const crl = preferenceReader.getContentRestrictionLevel();
console.log(JSON.stringify(crl, undefined, 2));
/* Example output:
{
  "name": "com.amazon.kepler.parental_controls/content_restriction_levels/us/teen",
  "allowedContentRatings": [
    {
      "ratingLevel": {
        "ratingsSystem": "US_MV",
        "rating": "US_MV_PG13"
      },
      "contentDescriptors": []
    },
    {
      "ratingLevel": {
        "ratingsSystem": "US_TV",
        "rating": "US_TV_PG"
      },
      "contentDescriptors": []
    }
  ]
}
*/

Integrating with parental controls for content restriction management

To integrate with Vega Parental Controls, call the gateContentPlayback function with a content rating and handle its response by specifying if playback should proceed. Vega Parental Controls handle comparing the content rating with the content restriction level and present the PIN challenge if it’s required.

The gateContentPlayback function is async, since it may suspend the application while waiting for the user to enter a PIN. This function may resolve without a prompt, which occurs if parental controls are disabled or if the content isn’t restricted.

Prerequisites

• You must have access to the content ratings for your video catalog so you can pass them to Vega Parental Controls.
• You must have a React Native for Vega app.
• You must have Vega SDK version 0.12 or higher, and the corresponding device software defined in the Vega SDK Release Notes.

Add parental controls to Your project

Add a package.json dependency to @amazon-devices/kepler-media-content-metadata@^1.0.0 and @amazon-devices/kepler-parental-controls@^1.0.0.

{
  ...
  "dependencies": {
     ...
    "@amazon-devices/kepler-media-content-metadata": "^1.0.0",
    "@amazon-devices/kepler-parental-controls": "^1.0.0"
  }
}

Declare parental controls privileges

In your manifest.toml file, add a [wants.service] entry to com.amazon.kepler.pcon.service.main.

[[wants.service]]
id = "com.amazon.kepler.pcon.service.main"

Then add a [needs.privilege] entry for each of the Vega Parental Controls you need to call. Typically it’s just com.amazon.kepler.parental_controls.gates.restricted-content-playback. The privileges required for each of these are documented in @amzn_kepler-parental-controls-docs.zip.

Copy code Copied to clipboard.

[[needs.privilege]]
id = "com.amazon.kepler.parental_controls.gates.restricted-content-playback"

Code sample

A working example of Vega Parental Controls can be found in the VegaVideoApp sample app’s PlayerScreen.tsx.

import { ContentMetadataComponent } from '@amazon-devices/kepler-media-content-metadata';
import { ParentalControlsComponent } from '@amazon-devices/kepler-parental-controls';

// These rating strings represent standard Vega rating strings.
// See "Building a content rating" for discussion about translating strings from
// catalog metadata.
interface VideoData {
  ratingsSystem: string;
  rating: string;
  ...
}

async function playVideo(videoData: VideoData) {
  // Default to an undefined, "Unrated" content rating.
  let contentRating;

  try {
     contentRating = await ContentMetadataComponent.makeContentRatingBuilder()
       .ratingsSystem(videoData.ratingsSystem)
       .rating(videoData.rating)
       .build();
  } catch (e) {
    // The builder can throw an exception if the rating is
    // invalid. We'll just fallback to "Unrated" behavior (always
    // show PIN prompt if parental controls is enabled) in that case.
    console.error(`Failed to build content rating ${videoData.ratingsSystem}::${videoData.rating}: ${e}`);
  }

  // This is where the parental controls UI would take over
  // if the content is restricted.
  const response = await ParentalControlsComponent.gateContentPlayback(contentRating);

  if (response.canPlaybackProceed) {
    // Play the video if allowed...
    videoPlayer.play(videoData);
  } else {
     // ...otherwise, exit.
     navigateBack();
  }
}

Last updated: Sep 30, 2025