browsertime 22.2.0 → 22.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 22.3.0 - 2024-06-06
+### Added
+* Use `--enableVideoRun` to get one extra run with a video and visual metrics [#2139](https://github.com/sitespeedio/browsertime/pull/2139)
+
+## 22.3.0 - 2024-06-04
+### Added
+* Add the ability to gather power usage measurements on Android from USB power meters, thank you [Gregory Mierzwinski](https://github.com/gmierz) for PR [#2134](https://github.com/sitespeedio/browsertime/pull/2134).
+* Add support to visualmetrics to identify key frames matching the given colors, thank you [aosmond](https://github.com/aosmond) for PR [#2119](https://github.com/sitespeedio/browsertime/pull/2119).
+
+### Fixed
+* Removed DOMContentFlushed for Firefox thank you [florinbilt](https://github.com/florinbilt) for PR [#2138](https://github.com/sitespeedio/browsertime/pull/2138).
+
 ## 22.2.0 - 2024-05-24
 ### Added
 * New command: Mouse single click on a element with a specific id `commands.mouse.singleClick.byId(id)` and `commands.mouse.singleClick.byIdAndWait(id)` [#2135](https://github.com/sitespeedio/browsertime/pull/2135).

package/bin/browsertime.js

@@ -123,21 +123,34 @@ async function run(urls, options) {
         );
       }
 
-      if (options.enableProfileRun) {
-        log.info('Make one extra run to collect trace information');
+      if (options.enableProfileRun || options.enableVideoRun) {
+        log.info('Make one extra run to collect trace/video information');
         options.iterations = 1;
-        if (options.browser === 'firefox') {
-          options.firefox.geckoProfiler = true;
-        } else if (options.browser === 'chrome') {
-          options.chrome.timeline = true;
-          options.cpu = true;
-          options.chrome.enableTraceScreenshots = true;
-          options.chrome.traceCategory = [
-            'disabled-by-default-v8.cpu_profiler'
-          ];
+        if (options.enableProfileRun) {
+          if (options.browser === 'firefox') {
+            options.firefox.geckoProfiler = true;
+          } else if (options.browser === 'chrome') {
+            options.chrome.timeline = true;
+            options.cpu = true;
+            options.chrome.enableTraceScreenshots = true;
+            options.chrome.traceCategory = [
+              'disabled-by-default-v8.cpu_profiler'
+            ];
+          }
+        }
+        if (options.enableVideoRun) {
+          if (options.video === true) {
+            log.error(
+              'You can only configure video run if you do not collect any video'
+            );
+            // This is a hack to not get an error
+            options.video = false;
+            options.visualMetrics = false;
+          } else {
+            options.video = true;
+            options.visualMetrics = true;
+          }
         }
-        options.video = false;
-        options.visualMetrics = false;
         const traceEngine = new Engine(options);
         await traceEngine.start();
         await traceEngine.runMultiple(urls, scriptsByCategory);

package/lib/android/index.js

@@ -5,8 +5,10 @@ import { EOL as endOfLine } from 'node:os';
 import { execa } from 'execa';
 import intel from 'intel';
 import pkg from '@devicefarmer/adbkit';
+import usbPowerProfiler from 'usb-power-profiling/usb-power-profiling.js';
 const { Adb } = pkg;
 import get from 'lodash.get';
+import { pathToFolder } from '../support/pathToFolder.js';
 const log = intel.getLogger('browsertime.android');
 const mkdir = promisify(_mkdir);
 const delay = ms => new Promise(res => setTimeout(res, ms));
@@ -466,6 +468,41 @@ export class Android {
     const batterystats = await this._runCommandAndGet('dumpsys batterystats');
     return parsePowerMetrics(batterystats, packageName);
   }
+
+  async measureUsbPowerUsage(startTime, endTime) {
+    return getUsbPowerUsage(startTime, endTime);
+  }
+
+  async getUsbPowerUsageProfile(index, url, result, options, storageManager) {
+    let profileData = await usbPowerProfiler.profileFromData();
+    let destinationFilename = join(
+      await pathToFolder(url, options),
+      `powerProfile-${index}.json`
+    );
+
+    await storageManager.writeJson(destinationFilename, profileData);
+  }
+}
+
+async function getUsbPowerUsage(startTime, endTime) {
+  let baselineUsageData = await usbPowerProfiler.getPowerData(
+    startTime - 2,
+    endTime - 1
+  );
+  let baselineUsageTotal = baselineUsageData[0]['samples']['data'].reduce(
+    (currSum, currVal) => currSum + Number.parseInt(currVal[1]),
+    0
+  );
+  let baselineUsage =
+    baselineUsageTotal / baselineUsageData[0]['samples']['data'].length;
+
+  let powerUsageData = await usbPowerProfiler.getPowerData(startTime, endTime);
+  let powerUsage = powerUsageData[0]['samples']['data'].reduce(
+    (currSum, currVal) => currSum + Number.parseInt(currVal[1]),
+    0
+  );
+
+  return { powerUsage, baselineUsage };
 }
 
 async function parsePowerMetrics(batterystats, packageName) {

package/lib/chrome/webdriver/chromium.js

@@ -3,6 +3,7 @@ import { unlink as _unlink, rm as _rm } from 'node:fs';
 import { join } from 'node:path';
 import { logging } from 'selenium-webdriver';
 import intel from 'intel';
+import usbPowerProfiler from 'usb-power-profiling/usb-power-profiling.js';
 const log = intel.getLogger('browsertime.chrome');
 const { Type } = logging;
 import { longTaskMetrics } from '../longTaskMetrics.js';
@@ -36,6 +37,7 @@ export class Chromium {
     // Keep the HAR file for all runs
     this.hars = [];
     this.androidTmpDir = '/data/local/tmp/';
+    this.testStartTime = undefined;
   }
 
   /**
@@ -68,6 +70,10 @@ export class Chromium {
     // https://github.com/cyrus-and/chrome-remote-interface/issues/332
     if (isAndroidConfigured(this.options)) {
       await this.android.addDevtoolsFw();
+
+      if (this.options.androidUsbPower) {
+        usbPowerProfiler.startSampling();
+      }
     }
 
     this.cdpClient = new ChromeDevtoolsProtocol(this.options);
@@ -153,8 +159,12 @@ export class Chromium {
       log.info('Could not set cookie because the URL is unknown');
     }
 
-    if (this.android && this.options.androidPower) {
-      await this.android.resetPowerUsage();
+    if (this.android) {
+      if (this.options.androidPower) {
+        await this.android.resetPowerUsage();
+      } else if (this.options.androidUsbPower) {
+        await usbPowerProfiler.resetPowerData();
+      }
     }
 
     if (
@@ -165,6 +175,8 @@ export class Chromium {
       this.isTracing = true;
       return this.cdpClient.startTrace();
     }
+
+    this.testStartTime = Date.now();
   }
 
   /**
@@ -218,10 +230,25 @@ export class Chromium {
       'GET_LONG_TASKS'
     );
 
-    if (this.android && this.options.androidPower) {
-      result.power = await this.android.measurePowerUsage(
-        this.chrome.android.package
-      );
+    if (this.android) {
+      if (this.options.androidPower) {
+        result.power = await this.android.measurePowerUsage(
+          this.chrome.android.package
+        );
+      } else if (this.options.androidUsbPower) {
+        result.power = await this.android.measureUsbPowerUsage(
+          this.testStartTime,
+          Date.now()
+        );
+
+        await this.android.getUsbPowerUsageProfile(
+          index,
+          url,
+          result,
+          this.options,
+          this.storageManager
+        );
+      }
     }
 
     if (this.options.verbose >= 2 || this.chrome.enableChromeDriverLog) {

package/lib/chrome/webdriver/setupChromiumOptions.js

@@ -172,6 +172,10 @@ export function setupChromiumOptions(
     }
   }
 
+  if (browserOptions.enableVideoAutoplay) {
+    seleniumOptions.addArguments('--autoplay-policy=no-user-gesture-required');
+  }
+
   // It's a new splash screen introduced in Chrome 98
   // for new profiles
   // disable it with ChromeWhatsNewUI

package/lib/core/engine/iteration.js

@@ -15,7 +15,10 @@ import {
   addConnectivity,
   removeConnectivity
 } from '../../connectivity/index.js';
-import { jsonifyVisualProgress } from '../../support/util.js';
+import {
+  jsonifyVisualProgress,
+  jsonifyKeyColorFrames
+} from '../../support/util.js';
 import { flushDNS } from '../../support/dns.js';
 
 import { getNumberOfRunningProcesses } from '../../support/processes.js';
@@ -232,6 +235,12 @@ export class Iteration {
                 );
               }
             }
+            if (videoMetrics.visualMetrics['KeyColorFrames']) {
+              videoMetrics.visualMetrics['KeyColorFrames'] =
+                jsonifyKeyColorFrames(
+                  videoMetrics.visualMetrics['KeyColorFrames']
+                );
+            }
             result[index_].videoRecordingStart =
               videoMetrics.videoRecordingStart;
             result[index_].visualMetrics = videoMetrics.visualMetrics;

package/lib/firefox/settings/firefoxPreferences.js

@@ -151,7 +151,7 @@ export const defaultFirefoxPreferences = {
   // Preferences file used by the raptor harness
   'dom.performance.time_to_non_blank_paint.enabled': true,
   'dom.performance.time_to_contentful_paint.enabled': true,
-  'dom.performance.time_to_dom_content_flushed.enabled': true,
+  'dom.performance.time_to_dom_content_flushed.enabled': false,
   'dom.performance.time_to_first_interactive.enabled': true,
 
   // required for geckoview logging

package/lib/firefox/webdriver/firefox.js

@@ -3,6 +3,7 @@ import { promisify } from 'node:util';
 import { join } from 'node:path';
 import intel from 'intel';
 import get from 'lodash.get';
+import usbPowerProfiler from 'usb-power-profiling/usb-power-profiling.js';
 import { adapters } from 'ff-test-bidi-har-export';
 import { getEmptyHAR, mergeHars } from '../../support/har/index.js';
 import { pathToFolder } from '../../support/pathToFolder.js';
@@ -32,6 +33,7 @@ export class Firefox {
     this.aliasAndUrl = {};
     // This keep the HAR files for all runs
     this.hars = [];
+    this.testStartTime = undefined;
   }
 
   /**
@@ -71,6 +73,10 @@ export class Firefox {
       runner.getDriver(),
       this.options
     );
+
+    if (isAndroidConfigured(this.options) && this.options.androidUsbPower) {
+      usbPowerProfiler.startSampling();
+    }
   }
 
   /**
@@ -131,8 +137,12 @@ export class Firefox {
       await this.har.startRecording();
     }
 
-    if (isAndroidConfigured(this.options) && this.options.androidPower) {
-      await this.android.resetPowerUsage();
+    if (isAndroidConfigured(this.options)) {
+      if (this.options.androidPower) {
+        await this.android.resetPowerUsage();
+      } else if (this.options.androidUsbPower) {
+        await usbPowerProfiler.resetPowerData();
+      }
     }
 
     if (
@@ -158,6 +168,8 @@ export class Firefox {
       this.perfStats = new PerfStats(runner, this.firefoxConfig);
       return this.perfStats.start();
     }
+
+    this.testStartTime = Date.now();
   }
 
   /**
@@ -169,10 +181,25 @@ export class Firefox {
   async afterPageCompleteCheck(runner, index, url, alias) {
     const result = { url, alias };
 
-    if (isAndroidConfigured(this.options) && this.options.androidPower) {
-      result.power = await this.android.measurePowerUsage(
-        this.firefoxConfig.android.package
-      );
+    if (isAndroidConfigured(this.options)) {
+      if (this.options.androidPower) {
+        result.power = await this.android.measurePowerUsage(
+          this.firefoxConfig.android.package
+        );
+      } else if (this.options.androidUsbPower) {
+        result.power = await this.android.measureUsbPowerUsage(
+          this.testStartTime,
+          Date.now()
+        );
+
+        await this.android.getUsbPowerUsageProfile(
+          index,
+          url,
+          result,
+          this.options,
+          this.storageManager
+        );
+      }
     }
 
     if (

package/lib/support/cli.js

@@ -274,6 +274,11 @@ export function parseCommandLine() {
       type: 'boolean',
       group: 'chrome'
     })
+    .option('chrome.enableVideoAutoplay', {
+      describe: 'Allow videos to autoplay.',
+      type: 'boolean',
+      group: 'chrome'
+    })
     .option('chrome.timeline', {
       alias: 'chrome.trace',
       describe:
@@ -341,6 +346,15 @@ export function parseCommandLine() {
         '(You have to disable charging yourself for this - it depends on the phone model).',
       group: 'android'
     })
+    .option('android.usbPowerTesting', {
+      alias: 'androidUsbPower',
+      type: 'boolean',
+      describe:
+        'Enables android power testing using usb-power-profiling. Assumes that ' +
+        'a valid device is attached to the phone. See here for supported devices: ' +
+        'https://github.com/fqueze/usb-power-profiling?tab=readme-ov-file#supported-devices',
+      group: 'android'
+    })
     .option('chrome.CPUThrottlingRate', {
       type: 'number',
       describe:
@@ -600,6 +614,11 @@ export function parseCommandLine() {
       describe:
         'Make one extra run that collects the profiling trace log (no other metrics is collected). For Chrome it will collect the timeline trace, for Firefox it will get the Geckoprofiler trace. This means you do not need to get the trace for all runs and can skip the overhead it produces.'
     })
+    .option('enableVideoRun', {
+      type: 'boolean',
+      describe:
+        'Make one extra run that collects video and visual metrics. This means you can do your runs with --visualMetrics true --video false --enableVideoRun true to collect visual metrics from all runs and save a video from the profile/video run. If you run it together with --enableProfileRun it will also collect profiling trace.'
+    })
     .option('video', {
       type: 'boolean',
       describe:
@@ -709,6 +728,12 @@ export function parseCommandLine() {
       describe:
         'Use the portable visual-metrics processing script (no ImageMagick dependencies).'
     })
+    .option('visualMetricsKeyColor', {
+      type: 'array',
+      nargs: 8,
+      describe:
+        'Collect Key Color frame metrics when you run --visualMetrics. Each --visualMetricsKeyColor supplied must have 8 arguments: key name, red channel (0-255) low and high, green channel (0-255) low and high, blue channel (0-255) low and high, fraction (0.0-1.0) of pixels that must match each channel.'
+    })
     .option('scriptInput.visualElements', {
       describe:
         'Include specific elements in visual elements. Give the element a name and select it with document.body.querySelector. Use like this: --scriptInput.visualElements name:domSelector see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors. Add multiple instances to measure multiple elements. Visual Metrics will use these elements and calculate when they are visible and fully rendered.'

package/lib/support/util.js

@@ -230,6 +230,29 @@ export function jsonifyVisualProgress(visualProgress) {
   }
   return visualProgress;
 }
+export function jsonifyKeyColorFrames(keyColorFrames) {
+  // Original data looks like
+  //  "FrameName1=[0-133 255-300], FrameName2=[133-255] FrameName3=[]"
+  if (typeof keyColorFrames === 'string') {
+    const keyColorFramesObject = {};
+    for (const keyColorPair of keyColorFrames.split(', ')) {
+      const [name, values] = keyColorPair.split('=');
+      keyColorFramesObject[name] = [];
+      const rangePairs = values.replace('[', '').replace(']', '');
+      if (rangePairs) {
+        for (const rangePair of rangePairs.split(' ')) {
+          const [start, end] = rangePair.split('-');
+          keyColorFramesObject[name].push({
+            startTimestamp: Number.parseInt(start, 10),
+            endTimestamp: Number.parseInt(end, 10)
+          });
+        }
+      }
+    }
+    return keyColorFramesObject;
+  }
+  return keyColorFrames;
+}
 export function adjustVisualProgressTimestamps(
   visualProgress,
   profilerStartTime,

package/lib/video/postprocessing/visualmetrics/visualMetrics.js

@@ -84,6 +84,15 @@ export async function run(
     scriptArguments.push('--contentful');
   }
 
+  if (options.visualMetricsKeyColor) {
+    for (let i = 0; i < options.visualMetricsKeyColor.length; ++i) {
+      if (i % 8 == 0) {
+        scriptArguments.push('--keycolor');
+      }
+      scriptArguments.push(options.visualMetricsKeyColor[i]);
+    }
+  }
+
   // There seems to be a bug with --startwhite that makes VM bail out
   // 11:20:14.950 - Calculating image histograms
   // 11:20:14.951 - No video frames found in /private/var/folders/27/xpnvcsbs0nlfbb4qq397z3rh0000gn/T/vis-cn_JMf

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browsertime",
   "description": "Get performance metrics from your web page using Browsertime.",
-  "version": "22.2.0",
+  "version": "22.4.0",
   "bin": "./bin/browsertime.js",
   "type": "module",
   "types": "./types/scripting.d.ts",
@@ -31,6 +31,7 @@
     "lodash.pick": "4.4.0",
     "lodash.set": "4.3.2",
     "selenium-webdriver": "4.21.0",
+    "usb-power-profiling": "^1.2.0",
     "yargs": "17.7.2"
   },
   "optionalDependencies": {

package/types/android/index.d.ts

@@ -66,5 +66,10 @@ export class Android {
         'full-wifi': number;
         total: number;
     }>;
+    measureUsbPowerUsage(startTime: any, endTime: any): Promise<{
+        powerUsage: any;
+        baselineUsage: number;
+    }>;
+    getUsbPowerUsageProfile(index: any, url: any, result: any, options: any, storageManager: any): Promise<void>;
 }
 //# sourceMappingURL=index.d.ts.map

package/types/android/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/android/index.js"],"names":[],"mappings":"AAiiBA,2DAWC;AA/hBD;IACE,0BAwBC;IAfC,YAAgC;IAEhC,QAIC;IACD,UAAgC;IAGhC,6BAA6B;IAC7B,yBAA2B;IAC3B,eAAgC;IAKlC,uBAgBC;IALC,YAA4C;IAG1C,YAAoE;IAIxE,wCAEC;IAED,8CAIC;IAED,6CAIC;IAED,2CAUC;IAED,mEAYC;IAED,mEAcC;IAED,uCAEC;IAED,0CAGC;IAED,4CAMC;IAED,4CAMC;IAED,uBAGC;IAED,kCAOC;IAED;;;;;;;OAuBC;IAED,2CAKC;IAED,8BAKC;IAED;;;oDAuBC;IAED,2BAIC;IAED,qCAGC;IAED,iCAGC;IAED,wBASC;IAED,2CAOC;IAED,gCAEC;IAED,0BAIC;IAED,iCAGC;IAED,8CAIC;IAED,4BAEC;IAED,sCAYC;IAED,mDAsBC;IAED,gDA+CC;IAED;;;;;;;OAqDC;IAED,4DAQC;IAED,mCAcC;IAED,kCAQC;IAED,iCAIC;IAED;;;;OAGC;CACF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/android/index.js"],"names":[],"mappings":"AAskBA,2DAWC;AAlkBD;IACE,0BAwBC;IAfC,YAAgC;IAEhC,QAIC;IACD,UAAgC;IAGhC,6BAA6B;IAC7B,yBAA2B;IAC3B,eAAgC;IAKlC,uBAgBC;IALC,YAA4C;IAG1C,YAAoE;IAIxE,wCAEC;IAED,8CAIC;IAED,6CAIC;IAED,2CAUC;IAED,mEAYC;IAED,mEAcC;IAED,uCAEC;IAED,0CAGC;IAED,4CAMC;IAED,4CAMC;IAED,uBAGC;IAED,kCAOC;IAED;;;;;;;OAuBC;IAED,2CAKC;IAED,8BAKC;IAED;;;oDAuBC;IAED,2BAIC;IAED,qCAGC;IAED,iCAGC;IAED,wBASC;IAED,2CAOC;IAED,gCAEC;IAED,0BAIC;IAED,iCAGC;IAED,8CAIC;IAED,4BAEC;IAED,sCAYC;IAED,mDAsBC;IAED,gDA+CC;IAED;;;;;;;OAqDC;IAED,4DAQC;IAED,mCAcC;IAED,kCAQC;IAED,iCAIC;IAED;;;;OAGC;IAED;;;OAEC;IAED,6GAQC;CACF"}

package/types/support/util.d.ts

@@ -2,5 +2,6 @@ export function formatMetric(name: any, metric: any, multiple: any, inMs: any, e
 export function logResultLogLine(results: any): void;
 export function toArray(arrayLike: any): any[];
 export function jsonifyVisualProgress(visualProgress: any): any;
+export function jsonifyKeyColorFrames(keyColorFrames: any): any;
 export function adjustVisualProgressTimestamps(visualProgress: any, profilerStartTime: any, recordingStartTime: any): any;
 //# sourceMappingURL=util.d.ts.map

package/types/support/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../lib/support/util.js"],"names":[],"mappings":"AAIA,oGAeC;AACD,qDA0LC;AACD,+CAQC;AACD,gEAeC;AACD,0HAWC"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../lib/support/util.js"],"names":[],"mappings":"AAIA,oGAeC;AACD,qDA0LC;AACD,+CAQC;AACD,gEAeC;AACD,gEAsBC;AACD,0HAWC"}

package/types/video/postprocessing/visualmetrics/visualMetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visualMetrics.d.ts","sourceRoot":"","sources":["../../../../lib/video/postprocessing/visualmetrics/visualMetrics.js"],"names":[],"mappings":"AAsCA,mGAEC;AACD,0KAiHC"}
+{"version":3,"file":"visualMetrics.d.ts","sourceRoot":"","sources":["../../../../lib/video/postprocessing/visualmetrics/visualMetrics.js"],"names":[],"mappings":"AAsCA,mGAEC;AACD,0KA0HC"}

package/visualmetrics/visualmetrics-portable.py

@@ -1104,7 +1104,7 @@ def calculate_histograms(directory, histograms_file, force):
                     m = re.search(match, frame)
                     if m is not None:
                         frame_time = int(m.groupdict().get("ms"))
-                        histogram = calculate_image_histogram(frame)
+                        histogram, total, dropped = calculate_image_histogram(frame)
                         gc.collect()
                         if histogram is not None:
                             histograms.append(
@@ -1112,6 +1112,8 @@ def calculate_histograms(directory, histograms_file, force):
                                     "time": frame_time,
                                     "file": os.path.basename(frame),
                                     "histogram": histogram,
+                                    "total_pixels": total,
+                                    "dropped_pixels": dropped,
                                 }
                             )
                 if os.path.isfile(histograms_file):
@@ -1130,12 +1132,14 @@ def calculate_histograms(directory, histograms_file, force):
 
 def calculate_image_histogram(file):
     logging.debug("Calculating histogram for " + file)
+    dropped = 0
     try:
         from PIL import Image
 
         im = Image.open(file)
         width, height = im.size
-        colors = im.getcolors(width * height)
+        total = width * height
+        colors = im.getcolors(total)
         histogram = {
             "r": [0 for i in range(256)],
             "g": [0 for i in range(256)],
@@ -1151,13 +1155,16 @@ def calculate_image_histogram(file):
                     histogram["r"][pixel[0]] += count
                     histogram["g"][pixel[1]] += count
                     histogram["b"][pixel[2]] += count
+                else:
+                    dropped += 1
             except Exception:
                 pass
         colors = None
     except Exception:
+        total = 0
         histogram = None
         logging.exception("Error calculating histogram for " + file)
-    return histogram
+    return histogram, total, dropped
 
 
 ##########################################################################
@@ -1212,6 +1219,7 @@ def calculate_visual_metrics(
     dirs,
     progress_file,
     hero_elements_file,
+    key_colors,
 ):
     metrics = None
     histograms = load_histograms(histograms_file, start, end)
@@ -1225,6 +1233,7 @@ def calculate_visual_metrics(
                 f = open(progress_file, "w")
             json.dump(progress, f)
             f.close()
+        key_color_frames = calculate_key_color_frames(histograms, key_colors)
         if len(histograms) > 1:
             metrics = [
                 {"name": "First Visual Change", "value": histograms[1]["time"]},
@@ -1315,6 +1324,20 @@ def calculate_visual_metrics(
                 metrics.append({"name": "Perceptual Speed Index", "value": 0})
             if contentful:
                 metrics.append({"name": "Contentful Speed Index", "value": 0})
+        if key_color_frames:
+            keysum = ""
+            for key in key_color_frames:
+                if len(keysum):
+                    keysum += ", "
+                framesum = ""
+                for frame in key_color_frames[key]:
+                    if len(framesum):
+                        framesum += " "
+                    framesum += "{0:d}-{1:d}".format(
+                        frame["start_time"], frame["end_time"]
+                    )
+                keysum += "{0}=[{1}]".format(key, framesum)
+            metrics.append({"name": "Key Color Frames", "value": keysum})
         prog = ""
         for p in progress:
             if len(prog):
@@ -1346,6 +1369,79 @@ def load_histograms(histograms_file, start, end):
     return histograms
 
 
+def is_key_color_frame(histogram, key_color):
+    # The fraction is measured against the entire image, not just the sampled
+    # pixels. This helps avoid matching frames with only a few pixels that
+    # happen to be in the acceptable range.
+    total_fraction = histogram["total_pixels"] * key_color["fraction"]
+    if total_fraction < histogram["total_pixels"] - histogram["dropped_pixels"]:
+        for channel in ["r", "g", "b"]:
+            # Find the acceptable range around the target channel value
+            max_channel = len(histogram["histogram"][channel])
+            low = min(max_channel - 1, max(0, key_color[channel + "_low"]))
+            high = min(max_channel, max(1, key_color[channel + "_high"] + 1))
+            target_total = 0
+            for i in histogram["histogram"][channel][low:high]:
+                target_total += i
+            if target_total < total_fraction:
+                return False
+    return True
+
+
+def calculate_key_color_frames(histograms, key_colors):
+    if not key_colors:
+        return {}
+
+    key_color_frames = {}
+    for key in key_colors:
+        key_color_frames[key] = []
+
+    current = None
+    current_key = None
+    total = 0
+    matched = 0
+    buckets = 256
+    channels = ["r", "g", "b"]
+    histograms = histograms.copy()
+
+    while len(histograms) > 0:
+        histogram = histograms.pop(0)
+        matching_key = None
+        for key in key_colors:
+            if is_key_color_frame(histogram, key_colors[key]):
+                matching_key = key
+                break
+
+        if matching_key is None:
+            continue
+
+        last_histogram = histogram
+        frame_count = 1
+        while len(histograms) > 0:
+            last_histogram = histograms[0]
+            if is_key_color_frame(last_histogram, key_colors[matching_key]):
+                frame_count += 1
+                histograms.pop(0)
+            else:
+                break
+
+        logging.debug(
+            "{0:d}ms to {1:d}ms - Matched key color frame {2}".format(
+                histogram["time"], last_histogram["time"], matching_key
+            )
+        )
+
+        key_color_frames[matching_key].append(
+            {
+                "frame_count": frame_count,
+                "start_time": histogram["time"],
+                "end_time": last_histogram["time"],
+            }
+        )
+
+    return key_color_frames
+
+
 def calculate_visual_progress(histograms):
     progress = []
     first = histograms[0]["histogram"]
@@ -1760,6 +1856,24 @@ def main():
         default=False,
         help="Remove orange-colored frames from the beginning of the video.",
     )
+    parser.add_argument(
+        "--keycolor",
+        action="append",
+        nargs=8,
+        metavar=(
+            "key",
+            "red_low",
+            "red_high",
+            "green_low",
+            "green_high",
+            "blue_low",
+            "blue_high",
+            "fraction",
+        ),
+        help="Identify frames that match the given channel (0-255) low and "
+        "high. Fraction is the percentage of the pixels per channel that "
+        "must be in the given range (0-1).",
+    )
     parser.add_argument(
         "-p",
         "--viewport",
@@ -1916,6 +2030,19 @@ def main():
                     options.full,
                 )
 
+            key_colors = {}
+            if options.keycolor:
+                for key_params in options.keycolor:
+                    key_colors[key_params[0]] = {
+                        "r_low": int(key_params[1]),
+                        "r_high": int(key_params[2]),
+                        "g_low": int(key_params[3]),
+                        "g_high": int(key_params[4]),
+                        "b_low": int(key_params[5]),
+                        "b_high": int(key_params[6]),
+                        "fraction": float(key_params[7]),
+                    }
+
             # Calculate the histograms and visual metrics
             calculate_histograms(directory, histogram_file, options.force)
             metrics = calculate_visual_metrics(
@@ -1927,6 +2054,7 @@ def main():
                 directory,
                 options.progress,
                 options.herodata,
+                key_colors,
             )
 
             if options.screenshot is not None:

package/visualmetrics/visualmetrics.py

@@ -1339,7 +1339,7 @@ def calculate_histograms(directory, histograms_file, force):
                     m = re.search(match, frame)
                     if m is not None:
                         frame_time = int(m.groupdict().get("ms"))
-                        histogram = calculate_image_histogram(frame)
+                        histogram, total, dropped = calculate_image_histogram(frame)
                         gc.collect()
                         if histogram is not None:
                             histograms.append(
@@ -1347,6 +1347,8 @@ def calculate_histograms(directory, histograms_file, force):
                                     "time": frame_time,
                                     "file": os.path.basename(frame),
                                     "histogram": histogram,
+                                    "total_pixels": total,
+                                    "dropped_pixels": dropped,
                                 }
                             )
                 if os.path.isfile(histograms_file):
@@ -1365,12 +1367,14 @@ def calculate_histograms(directory, histograms_file, force):
 
 def calculate_image_histogram(file):
     logging.debug("Calculating histogram for " + file)
+    dropped = 0
     try:
         from PIL import Image
 
         im = Image.open(file)
         width, height = im.size
-        colors = im.getcolors(width * height)
+        total = width * height
+        colors = im.getcolors(total)
         histogram = {
             "r": [0 for i in range(256)],
             "g": [0 for i in range(256)],
@@ -1386,13 +1390,16 @@ def calculate_image_histogram(file):
                     histogram["r"][pixel[0]] += count
                     histogram["g"][pixel[1]] += count
                     histogram["b"][pixel[2]] += count
+                else:
+                    dropped += 1
             except Exception:
                 pass
         colors = None
     except Exception:
+        total = 0
         histogram = None
         logging.exception("Error calculating histogram for " + file)
-    return histogram
+    return histogram, total, dropped
 
 
 ##########################################################################
@@ -1618,6 +1625,7 @@ def calculate_visual_metrics(
     dirs,
     progress_file,
     hero_elements_file,
+    key_colors,
 ):
     metrics = None
     histograms = load_histograms(histograms_file, start, end)
@@ -1631,6 +1639,7 @@ def calculate_visual_metrics(
                 f = open(progress_file, "w")
             json.dump(progress, f)
             f.close()
+        key_color_frames = calculate_key_color_frames(histograms, key_colors)
         if len(histograms) > 1:
             metrics = [
                 {"name": "First Visual Change", "value": histograms[1]["time"]},
@@ -1720,6 +1729,20 @@ def calculate_visual_metrics(
                 metrics.append({"name": "Perceptual Speed Index", "value": 0})
             if contentful:
                 metrics.append({"name": "Contentful Speed Index", "value": 0})
+        if key_color_frames:
+            keysum = ""
+            for key in key_color_frames:
+                if len(keysum):
+                    keysum += ", "
+                framesum = ""
+                for frame in key_color_frames[key]:
+                    if len(framesum):
+                        framesum += " "
+                    framesum += "{0:d}-{1:d}".format(
+                        frame["start_time"], frame["end_time"]
+                    )
+                keysum += "{0}=[{1}]".format(key, framesum)
+            metrics.append({"name": "Key Color Frames", "value": keysum})
         prog = ""
         for p in progress:
             if len(prog):
@@ -1751,6 +1774,79 @@ def load_histograms(histograms_file, start, end):
     return histograms
 
 
+def is_key_color_frame(histogram, key_color):
+    # The fraction is measured against the entire image, not just the sampled
+    # pixels. This helps avoid matching frames with only a few pixels that
+    # happen to be in the acceptable range.
+    total_fraction = histogram["total_pixels"] * key_color["fraction"]
+    if total_fraction < histogram["total_pixels"] - histogram["dropped_pixels"]:
+        for channel in ["r", "g", "b"]:
+            # Find the acceptable range around the target channel value
+            max_channel = len(histogram["histogram"][channel])
+            low = min(max_channel - 1, max(0, key_color[channel + "_low"]))
+            high = min(max_channel, max(1, key_color[channel + "_high"] + 1))
+            target_total = 0
+            for i in histogram["histogram"][channel][low:high]:
+                target_total += i
+            if target_total < total_fraction:
+                return False
+    return True
+
+
+def calculate_key_color_frames(histograms, key_colors):
+    if not key_colors:
+        return {}
+
+    key_color_frames = {}
+    for key in key_colors:
+        key_color_frames[key] = []
+
+    current = None
+    current_key = None
+    total = 0
+    matched = 0
+    buckets = 256
+    channels = ["r", "g", "b"]
+    histograms = histograms.copy()
+
+    while len(histograms) > 0:
+        histogram = histograms.pop(0)
+        matching_key = None
+        for key in key_colors:
+            if is_key_color_frame(histogram, key_colors[key]):
+                matching_key = key
+                break
+
+        if matching_key is None:
+            continue
+
+        last_histogram = histogram
+        frame_count = 1
+        while len(histograms) > 0:
+            last_histogram = histograms[0]
+            if is_key_color_frame(last_histogram, key_colors[matching_key]):
+                frame_count += 1
+                histograms.pop(0)
+            else:
+                break
+
+        logging.debug(
+            "{0:d}ms to {1:d}ms - Matched key color frame {2}".format(
+                histogram["time"], last_histogram["time"], matching_key
+            )
+        )
+
+        key_color_frames[matching_key].append(
+            {
+                "frame_count": frame_count,
+                "start_time": histogram["time"],
+                "end_time": last_histogram["time"],
+            }
+        )
+
+    return key_color_frames
+
+
 def calculate_visual_progress(histograms):
     progress = []
     first = histograms[0]["histogram"]
@@ -2200,6 +2296,24 @@ def main():
         help="Wait for a full white frame after a non-white frame "
         "at the beginning of the video.",
     )
+    parser.add_argument(
+        "--keycolor",
+        action="append",
+        nargs=8,
+        metavar=(
+            "key",
+            "red_low",
+            "red_high",
+            "green_low",
+            "green_high",
+            "blue_low",
+            "blue_high",
+            "fraction",
+        ),
+        help="Identify frames that match the given channel (0-255) low and "
+        "high. Fraction is the percentage of the pixels per channel that "
+        "must be in the given range (0-1).",
+    )
     parser.add_argument(
         "--multiple",
         action="store_true",
@@ -2464,6 +2578,18 @@ def main():
             if not options.multiple:
                 if options.render is not None:
                     render_video(directory, options.render)
+                key_colors = {}
+                if options.keycolor:
+                    for key_params in options.keycolor:
+                        key_colors[key_params[0]] = {
+                            "r_low": int(key_params[1]),
+                            "r_high": int(key_params[2]),
+                            "g_low": int(key_params[3]),
+                            "g_high": int(key_params[4]),
+                            "b_low": int(key_params[5]),
+                            "b_high": int(key_params[6]),
+                            "fraction": float(key_params[7]),
+                        }
 
                 # Calculate the histograms and visual metrics
                 calculate_histograms(directory, histogram_file, options.force)
@@ -2476,6 +2602,7 @@ def main():
                     directory,
                     options.progress,
                     options.herodata,
+                    key_colors,
                 )
 
                 if options.screenshot is not None: