Device profiles

Device profiles can be defined in two ways:

By providing a profiles.json configuration file (which you should package in the application's res/raw folder) that contains the profiles.
Programmatically using the following API:
CODE
```
DeviceCalibration.setConfiguration(String jsonData); 
```
setConfiguration overwrites the profiles supplied in profiles.json.

Device profiles allow you to:

Enable or disable hardware decoding where the device supports it. (By default, the player uses hardware decoding on Android 5.0 and above.)
Set a maximum bitrate to account for device hardware limitations.
Enable additional codecs on devices running Android 5.0 and above. Currently only HEVC is supported.

You can set these for:

All devices that match a performance profile by defining a generic profile.
Specific devices by defining a specific profile.

A generic profile is matched against the device using the following properties:

CpuCores – number of CPU cores
CpuFreq – CPU frequency
Neon – whether the device supports NEON (boolean)

A specific profile is matched using the following properties (as reported by the OS):

Manufacturer
Model
Product
Device
Board
Hardware
Decoder
MaxBitRate

Default settings

If no profiles.json is present or device calibration is not configured then the following default settings are used:

Bitrate capping will not be applied.
The AVC/AAC decoders used are:
- Android version 5.0 devices onward - Hardware decoders by default; software decoders can be used if required.
- Pre-Android 5.0 - Software decoders only.
No additional codecs such as HEVC will be available.

How the profile settings are applied

When the player is initialised, it obtains the device information via the Android DeviceInformation API. If calibration is enabled, it will then attempt to find a match for the device in profiles.json (or the JSON profile data if you specified it programmatically):

If a match is found in the Specific array it will use the matching configuration.
If no match is found, the player uses the defaults as specified in the Default settings section, above.

On Android versions below 5.0 if no match is found in the Specific array but a match is found in the Generic array it will use the following settings:

Software AVC/AAC decoding
The maximum bitrate specified in the profile
Additional codecs will be disabled.

Profile matching rules

The player matches the defined profiles against the device information and capabilities to select the profile to use as follows:

A single mismatch is enough to disqualify a profile, no matter how many fields do match.
A field with an empty string is ignored.
If the device matches one of the specific profiles, it will be used.
If the device does not match any specific profiles, the best-matching generic profile is used (on Android versions below 5.0).
If the device matches multiple specific profiles, the one with the highest number of matching values is used.
If the device matches multiple specific profiles and the number of matches is the same, the one that appears first in the file/JSON data is used.
If a specific profile has empty string values for all device details (except for MaxBitrate), it will not match any devices.

For generic profile matching (Android version below 5.0 only):

The value for NEON must match
The device values for CpuCores and CpuFreq must be greater than or equal to the values in a profile for it to match
If there are multiple matching profiles, the one with the highest CpuCores value is used
If there are multiple matching profiles with the same value for CpuCores, the one with the highest value for CpuFreq is used
If there are no matching profiles, a value of zero is used for MaxBitrate (i.e., unlimited).

Example code

Consider this set of device profiles:

JAVA

{
"DeviceProfiles" : {
   "Specific" : [
   {
      "Manfacturer" : "Sony",
      "Model" :       "",
      "Product" :     "",
      "Device" :      "",
      "Board" :       "",
      "Hardware" :    "",
      "Decoder" :     "Hardware",
      "MaxBitrate":   "9000000"
   },
   {
      "Manfacturer" : "Sony",
      "Model" :       "E6853",
      "Product" :     "",
      "Device" :      "",
      "Board" :       "",
      "Hardware" :    "",
      "Decoder" :     "Hardware",
      "MaxBitrate":   "6000000"
   },
   {
      "Manfacturer" : "Sony",
      "Model" :       "E5563",
      "Product" :     "",
      "Device" :      "",
      "Board" :       "",
      "Hardware" :    "",
      "Decoder" :     "Hardware",
      "MaxBitrate":   "5000000"},
   {
      "Manfacturer" : "Sony",
      "Model" :       "",
      "Product" :     "",
      "Device" :      "",
      "Board" :       "",
      "Hardware" :    "qcom",
      "Decoder" :     "Software",
      "MaxBitrate":   "3000000"
   },
   ],
   "Generic" : [
   {
      "CpuCores" :    "2",
      "CpuFreq" :     "1200000",
      "Neon" :        "1",
      "MaxBitRate" :  "500000"
   },
   {
      "CpuCores" :    "4",
      "CpuFreq" :     "1500000",
      "Neon" :        "1",
      "MaxBitRate" :  "850000"
   },
   {
      "CpuCores" :    "2",
      "CpuFreq" :     "1000000",
      "Neon" :        "0",
      "MaxBitRate" :  "300000"
   }
   ]
}
}

A Sony E6853 will match the second specific profile.
A Sony E5563 will match the third specific profile.
A Sony device that is neither an E6853 nor a E5563, but that has a value of qcom for Hardware will match the fourth specific profile (unless the player reports that it supports hardware decoding, in which case it matched the first specific profile).
Any other Sony device that supports hardware decoding will match the first specific profile.
Any other Sony device that does not support hardware decoding will not match any of the specific profiles – so the best-matching generic profile will be used.
Any device that is not a Sony will try to match one of the generic profiles. For example:
- A device with four cores, a CPU frequency of 1200000, and NEON support will match the first generic profile. This is because it does not match the second profile – the number of cores matches, but its CPU frequency is too low.
- A device without NEON support matches the third generic profile (unless it only has a single CPU core or its CPU frequency is less than 1000000, in which case it does not match any of the generic profiles).

Typically, you would provide a number of generic and specific profiles to ensure that the player can fully utilise the device capabilities for as many devices as possible. The device profile syntax is as follows:

JAVA

{
"DeviceProfiles" : {
   "Specific" : [
   {
      "Manfacturer" : "<manufacturer>"|"",
      "Model" :       "<model>"|"",
      "Product" :     "<product>"|"",
      "Device" :      "<device>"|"",
      "Board" :       "<board>"|"",
      "Hardware" :    "<hardware>"|"",
     ["Decoder" :     "Hardware"|"Software",]
      "MaxBitrate":   "<bitrate>"|"0"
   }
   [,...]
   ],
   "Generic" : [
   {
      "CpuCores" :    "<cpu_cores>",
      "CpuFreq" :     "<cpu_frequency>",
      "Neon" :        "0"|"1",
      "MaxBitRate" :  "<bitrate>"|"0"
   }
   [,...]
   ]
}
}

All key/value pairs are mandatory, except for Decoder (which is only relevant for specific profiles).
Each device detail (Manufacturer, Model, etc.) can have a value or an empty string, though at least one must have a value.
Decoder enables or disables hardware decoding (when the player determines that the device supports hardware decoding). It takes a value of "Hardware" or "Software". It is optional and has a default value of "Hardware". (Hardware decoding can only be used in specific profiles, not generic ones.)
MaxBitRate takes a value in bits/second. A value of "0" means unlimited.
You can add as many profile blocks as you like within the "Specific" and "Generic" blocks.
CpuFreq takes a value in KHz. (For example, 1200000 means 1200 MHz or 1.2 GHz.)