browsertime 22.1.0 → 22.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## 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).
+* New command: `commands.wait.byIdAndVisible(id, maxTime)` - wait for an element with id to become visible [#2137](https://github.com/sitespeedio/browsertime/pull/2137).
+
+### Fixed
+* Make sure errors are correctly logged if you cannot add text to element [#2136](https://github.com/sitespeedio/browsertime/pull/2136).
+
 ## 22.1.0 - 2024-05-20
 ### Added
 * Updated to Edge and Edgedriver 125 [#2132](https://github.com/sitespeedio/browsertime/pull/2132).

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/command/addText.js

@@ -33,7 +33,12 @@ export class AddText {
       await element.clear();
       return element.sendKeys(text);
     } catch (error) {
-      log.error('Could not add text %s to id %s', text, id);
+      log.error(
+        'Could not add text %s to id %s error:%s',
+        text,
+        id,
+        error.message
+      );
       log.verbose(error);
       throw new Error(`Could not add text ${text} to id ${id}`);
     }
@@ -57,7 +62,12 @@ export class AddText {
       await element.clear();
       return element.sendKeys(text);
     } catch (error) {
-      log.error('Could not add text %s to xpath %s', text, xpath);
+      log.error(
+        'Could not add text %s to xpath %s error: %s',
+        text,
+        xpath,
+        error.message
+      );
       log.verbose(error);
       throw new Error(`Could not add text ${text} to xpath ${xpath}`);
     }
@@ -81,7 +91,12 @@ export class AddText {
       await element.clear();
       return element.sendKeys(text);
     } catch (error) {
-      log.error('Could not add text %s to selector %s', text, selector);
+      log.error(
+        'Could not add text %s to selector %s error: %s',
+        text,
+        selector,
+        error.message
+      );
       log.verbose(error);
       throw new Error(`Could not add text ${text} to selector ${selector}`);
     }
@@ -105,7 +120,12 @@ export class AddText {
       await element.clear();
       return element.sendKeys(text);
     } catch (error) {
-      log.error('Could not add text %s to class name %s', text, className);
+      log.error(
+        'Could not add text %s to class name %s error: %s',
+        text,
+        className,
+        error.message
+      );
       log.verbose(error);
       throw new Error(`Could not add text ${text} to class name ${className}`);
     }
@@ -129,7 +149,12 @@ export class AddText {
       await element.clear();
       return element.sendKeys(text);
     } catch (error) {
-      log.error('Could not add text %s to name attribute  %s', text, name);
+      log.error(
+        'Could not add text %s to name attribute %s error: %s',
+        text,
+        name,
+        error.message
+      );
       log.verbose(error);
       throw new Error(`Could not add text ${text} to name attribute ${name}`);
     }

package/lib/core/engine/command/mouse/singleClick.js

@@ -230,7 +230,7 @@ export class SingleClick {
 
   /**
    * Clicks on a link whose visible text contains the given substring and waits on the
-   * page complete checl.
+   * page complete check.
    *
    * @async
    * @param {string} text - The substring of the visible text of the link to click.
@@ -247,4 +247,43 @@ export class SingleClick {
       throw new Error('Could not find link by partial text ' + text);
     }
   }
+
+  /**
+   * Clicks on a element with a specific id.
+   *
+   * @async
+   * @param {string} id - The id of the link to click.
+   * @returns {Promise<void>} A promise that resolves when the click action is performed.
+   * @throws {Error} Throws an error if the id is not found.
+   */
+  async byId(id) {
+    try {
+      const element = await this.browser.getDriver().findElement(By.id(id));
+      return this.actions.click(element).perform();
+    } catch (error) {
+      log.error('Could not find the element with id %s', id);
+      log.verbose(error);
+      throw new Error('Could not the element with id ' + id);
+    }
+  }
+
+  /**
+   * Clicks on a element with a specific id and wait on the page complete check
+   *
+   * @async
+   * @param {string} id - The id of the link to click.
+   * @returns {Promise<void>} A promise that resolves when the page has completed.
+   * @throws {Error} Throws an error if the id is not found.
+   */
+  async byIdAndWait(id) {
+    try {
+      const element = await this.browser.getDriver().findElement(By.id(id));
+      await this.actions.click(element).perform();
+      return this.browser.extraWait(this.pageCompleteCheck);
+    } catch (error) {
+      log.error('Could not find the element with id %s', id);
+      log.verbose(error);
+      throw new Error('Could not the element with id ' + id);
+    }
+  }
 }

package/lib/core/engine/command/wait.js

@@ -22,7 +22,7 @@ export class Wait {
   }
 
   /**
-   * Waits for an element with a specific ID to appear within a maximum time.
+   * Waits for an element with a specific ID to be located within a maximum time.
    *
    * @async
    * @param {string} id - The ID of the element to wait for.
@@ -46,6 +46,30 @@ export class Wait {
     }
   }
 
+  /**
+   * Waits for an element with a specific ID to be located and visible within a maximum time.
+   *
+   * @async
+   * @param {string} id - The ID of the element to wait for.
+   * @param {number} maxTime - Maximum time to wait in milliseconds.
+   * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
+   * @throws {Error} Throws an error if the element is not found within the specified time.
+   */
+  async byIdAndVisible(id, maxTime) {
+    const driver = this.browser.getDriver();
+    await this.byId(id, maxTime);
+    try {
+      await driver.wait(
+        webdriver.until.elementIsVisible(webdriver.By.id(id)),
+        maxTime
+      );
+    } catch (error) {
+      log.error('Element by id %s was not visible in %s ms', id, maxTime);
+      log.verbose(error);
+      throw new Error(`Element by id ${id} was not located in ${maxTime} ms`);
+    }
+  }
+
   /**
    * Waits for an element located by XPath to appear within a maximum time.
    *

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:
@@ -709,6 +723,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.1.0",
+  "version": "22.3.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/core/engine/command/addText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addText.d.ts","sourceRoot":"","sources":["../../../../lib/core/engine/command/addText.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACE,0BAKC;IAJC;;OAEG;IACH,gBAAsB;IAGxB;;;;;;;;;OASG;IACH,WALW,MAAM,MACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;;OASG;IACH,cALW,MAAM,SACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;;OASG;IACH,iBALW,MAAM,YACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;;OASG;IACH,kBALW,MAAM,aACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;;OASG;IACH,aALW,MAAM,QACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;CACF"}
+{"version":3,"file":"addText.d.ts","sourceRoot":"","sources":["../../../../lib/core/engine/command/addText.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACE,0BAKC;IAJC;;OAEG;IACH,gBAAsB;IAGxB;;;;;;;;;OASG;IACH,WALW,MAAM,MACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;;;OASG;IACH,cALW,MAAM,SACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;;;OASG;IACH,iBALW,MAAM,YACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;;;OASG;IACH,kBALW,MAAM,aACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;;;OASG;IACH,aALW,MAAM,QACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAoBzB;CACF"}

package/types/core/engine/command/mouse/singleClick.d.ts

@@ -103,7 +103,7 @@ export class SingleClick {
     byPartialLinkText(text: string): Promise<void>;
     /**
      * Clicks on a link whose visible text contains the given substring and waits on the
-     * page complete checl.
+     * page complete check.
      *
      * @async
      * @param {string} text - The substring of the visible text of the link to click.
@@ -111,5 +111,23 @@ export class SingleClick {
      * @throws {Error} Throws an error if the link is not found.
      */
     byPartialLinkTextAndWait(text: string): Promise<void>;
+    /**
+     * Clicks on a element with a specific id.
+     *
+     * @async
+     * @param {string} id - The id of the link to click.
+     * @returns {Promise<void>} A promise that resolves when the click action is performed.
+     * @throws {Error} Throws an error if the id is not found.
+     */
+    byId(id: string): Promise<void>;
+    /**
+     * Clicks on a element with a specific id and wait on the page complete check
+     *
+     * @async
+     * @param {string} id - The id of the link to click.
+     * @returns {Promise<void>} A promise that resolves when the page has completed.
+     * @throws {Error} Throws an error if the id is not found.
+     */
+    byIdAndWait(id: string): Promise<void>;
 }
 //# sourceMappingURL=singleClick.d.ts.map

package/types/core/engine/command/mouse/singleClick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"singleClick.d.ts","sourceRoot":"","sources":["../../../../../lib/core/engine/command/mouse/singleClick.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACE,kDAaC;IAZC;;OAEG;IACH,gBAAsB;IACtB;;OAEG;IACH,gBAAgE;IAChE;;OAEG;IACH,0BAA0C;IAG5C;;;;;;;;OAQG;IACH,eALW,MAAM,kBAEJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;OAOG;IACH,sBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,kBAEJ,QAAQ,IAAI,CAAC,CAsBzB;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;OAOG;IACH,yBAHa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;OAOG;IACH,mBAHa,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,iBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,wBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,wBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;;OAQG;IACH,+BAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;CACF"}
+{"version":3,"file":"singleClick.d.ts","sourceRoot":"","sources":["../../../../../lib/core/engine/command/mouse/singleClick.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACE,kDAaC;IAZC;;OAEG;IACH,gBAAsB;IACtB;;OAEG;IACH,gBAAgE;IAChE;;OAEG;IACH,0BAA0C;IAG5C;;;;;;;;OAQG;IACH,eALW,MAAM,kBAEJ,QAAQ,IAAI,CAAC,CAoBzB;IAED;;;;;;;OAOG;IACH,sBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAezB;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,kBAEJ,QAAQ,IAAI,CAAC,CAsBzB;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;OAOG;IACH,yBAHa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;OAOG;IACH,mBAHa,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,iBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,wBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,wBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;;OAQG;IACH,+BAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,SAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAYzB;IAED;;;;;;;OAOG;IACH,gBAJW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAazB;CACF"}

package/types/core/engine/command/wait.d.ts

@@ -15,7 +15,7 @@ export class Wait {
      */
     private pageCompleteCheck;
     /**
-     * Waits for an element with a specific ID to appear within a maximum time.
+     * Waits for an element with a specific ID to be located within a maximum time.
      *
      * @async
      * @param {string} id - The ID of the element to wait for.
@@ -24,6 +24,16 @@ export class Wait {
      * @throws {Error} Throws an error if the element is not found within the specified time.
      */
     byId(id: string, maxTime: number): Promise<void>;
+    /**
+     * Waits for an element with a specific ID to be located and visible within a maximum time.
+     *
+     * @async
+     * @param {string} id - The ID of the element to wait for.
+     * @param {number} maxTime - Maximum time to wait in milliseconds.
+     * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
+     * @throws {Error} Throws an error if the element is not found within the specified time.
+     */
+    byIdAndVisible(id: string, maxTime: number): Promise<void>;
     /**
      * Waits for an element located by XPath to appear within a maximum time.
      *

package/types/core/engine/command/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../../lib/core/engine/command/wait.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACE,kDASC;IARC;;OAEG;IACH,gBAAsB;IACtB;;OAEG;IACH,0BAA0C;IAG5C;;;;;;;;OAQG;IACH,SALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;;OAQG;IACH,eALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAmBzB;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAuBzB;IAED;;;;;;;OAOG;IACH,WAHW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAIzB;IAED;;;;;OAKG;IACH,oBAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;CACF"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../../lib/core/engine/command/wait.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACE,kDASC;IARC;;OAEG;IACH,gBAAsB;IACtB;;OAEG;IACH,0BAA0C;IAG5C;;;;;;;;OAQG;IACH,SALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;;;;;OAQG;IACH,mBALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAgBzB;IAED;;;;;;;;OAQG;IACH,eALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAmBzB;IAED;;;;;;;;OAQG;IACH,qBALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAuBzB;IAED;;;;;;;OAOG;IACH,WAHW,MAAM,GACJ,QAAQ,IAAI,CAAC,CAIzB;IAED;;;;;OAKG;IACH,oBAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;;;;;;OAQG;IACH,0BALW,MAAM,WACN,MAAM,GACJ,QAAQ,IAAI,CAAC,CAiBzB;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: