@openmixer/plugin-qualify 0.18.5 → 0.19.1

package/bin/plugin-qualify-sync.mjs

@@ -51,7 +51,7 @@ log(
     `memory ${s.memory === undefined ? "unbounded" : `${String(s.memory.bytes)} bytes`}`,
 );
 try {
-  const summary = await runSync(s, { force: parsed.args.force, wait: !parsed.args.noWait, refreshOnly: parsed.args.refreshPins, rejudge: parsed.args.rejudge, memoryOnly: parsed.args.memoryOnly, adapterOnly: parsed.args.adapterOnly, isolatedOnly: parsed.args.isolatedOnly, log });
+  const summary = await runSync(s, { force: parsed.args.force, wait: !parsed.args.noWait, refreshOnly: parsed.args.refreshPins, rejudge: parsed.args.rejudge, memoryOnly: parsed.args.memoryOnly, adapterOnly: parsed.args.adapterOnly, isolatedOnly: parsed.args.isolatedOnly, poolOnly: parsed.args.poolOnly, log });
   if (summary !== undefined) {
     process.stdout.write(`${summaryLine(summary)}\n`);
     // the records counted per plugin over its offers: a CLAP plugin has a record per offer

package/bin/plugin-qualify.mjs

@@ -8,6 +8,8 @@
  * Every named plugin, CLAP or LV2, is measured by plugin-hostd's probe runner (`plugin-hostd-probe`,
  * named by `OMX_PROBE_RUNNER` when it is not on `PATH`), which keeps the deadline and the limits, and is
  * judged from the probe output it writes: the verdict and the qualification record, per host profile.
+ * `plugin-qualify compare` runs the plugins through omx-clap-host, plugin-hostd, mod-host and jalv with the same checks
+ * (tools/compare-run.mjs).
  * `--all` finds the LV2 plugins of the bundles on the LV2 path, then the CLAP plugins on the standard CLAP search path (`CLAP_PATH`, then `~/.clap`, then
  * `/usr/lib/clap`). `plugin-qualify judge` judges probe outputs already written.
  */
@@ -62,6 +64,11 @@ function writePins(path, file) {
   process.stderr.write(`plugin-qualify: ${file.written.length} pin${file.written.length === 1 ? "" : "s"} written to ${path}\n`);
 }
 
+if (process.argv[2] === "compare") {
+  const { compareMain } = await import("../tools/compare-run.mjs");
+  process.exit(await compareMain(process.argv.slice(3)));
+}
+
 if (process.argv[2] === "judge") {
   const j = parseJudgeArgs(process.argv.slice(3));
   if (!j.ok) {

package/dist/clap-qualify.d.ts

@@ -76,7 +76,7 @@ export interface ClapQualifyLine {
     readonly cost?: ClapCostReading;
     /**
      * The pin (spec §11): the `.clap`'s digest by its name in its directory and the layout fingerprint
-     * the prober computed through plugin-hostd's `pin.h`, or the reason it took none.
+     * the prober computed through plugin-db's `pin.h`, or the reason it took none.
      */
     readonly integrity: IntegrityMeasurement;
 }

package/dist/compare.d.ts

@@ -0,0 +1,311 @@
+export declare const COMPARISON_RECORD_SCHEMA = "plugin-qualify.comparison-record/1";
+export declare const COMPARISON_SUMMARY_SCHEMA = "plugin-qualify.comparison-summary/1";
+export declare const COMPARISON_RECORD_SUFFIX = ".comparison.json";
+export declare const COMPARISON_SUMMARY_FILE = "comparison-summary.json";
+/** The hosts, in the order their rows are written. */
+export declare const COMPARE_HOSTS: readonly ["omx-clap-host", "plugin-hostd", "mod-host", "jalv"];
+export type CompareHost = (typeof COMPARE_HOSTS)[number];
+/** The references a published comparison is measured against: without both, a summary is not publishable. */
+export declare const REFERENCE_HOSTS: readonly CompareHost[];
+/** How each host is driven, and what of it can be observed. The page and the summary print these, so they are data. */
+export interface HostTraits {
+    readonly program: string;
+    /** `protocol`: the mod-host socket protocol (`add`, `remove`); `process`: one process per plugin (jalv). */
+    readonly drive: "protocol" | "process";
+    readonly formats: readonly ("lv2" | "clap")[];
+    /** Why the plugin latency it reports is or is not observable. */
+    readonly latency: {
+        readonly observable: boolean;
+        readonly how: string;
+    };
+    readonly rt: string;
+}
+export declare const HOST_TRAITS: Readonly<Record<CompareHost, HostTraits>>;
+export declare const isCompareHost: (s: string) => s is CompareHost;
+export interface CompareArgs {
+    readonly help: boolean;
+    readonly all: boolean;
+    readonly targets: readonly string[];
+    readonly hosts: readonly CompareHost[];
+    readonly rate: number;
+    readonly quantum: number;
+    readonly cycles: number;
+    readonly soakS: number;
+    readonly windowMs: number;
+    readonly timeoutMs: number;
+    readonly out: string | undefined;
+    readonly hostClass: string | undefined;
+    readonly set: string | undefined;
+    readonly publish: boolean;
+    readonly server: string | undefined;
+    readonly limit: number;
+    readonly force: boolean;
+    readonly format: "text" | "json";
+}
+export declare const COMPARE_DEFAULTS: {
+    readonly rate: 48000;
+    readonly quantum: 256;
+    readonly cycles: 5;
+    readonly soakS: 10;
+    readonly windowMs: 2000;
+    readonly timeoutMs: 10000;
+};
+export type ParseCompare = {
+    ok: true;
+    args: CompareArgs;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseCompareArgs(argv: readonly string[]): ParseCompare;
+export declare function compareHelpText(): string;
+export interface HostPresence {
+    readonly host: CompareHost;
+    readonly installed: boolean;
+    readonly version: string | null;
+    /** Why it is skipped, when it is. */
+    readonly reason?: string;
+}
+/** The reference hosts a publishable summary lacks, by name, with the reason each is missing. */
+export declare function missingReferences(present: readonly HostPresence[]): readonly {
+    host: CompareHost;
+    reason: string;
+}[];
+/** What a directory of records says of each host: it ran where a row of it ran, else the reason its rows give. */
+export declare function presenceFromRecords(records: readonly ComparisonRecord[]): HostPresence[];
+/** The arguments of `plugin-qualify compare summary <dir>`: the summary of the records already in a directory. */
+export type ParseSummary = {
+    ok: true;
+    args: {
+        dir: string;
+        hostClass?: string;
+        set?: string;
+        publish: boolean;
+        help: boolean;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseSummaryArgs(argv: readonly string[]): ParseSummary;
+export declare function summaryHelpText(): string;
+/** Two runs are the same comparison when every condition but the machine's JACK version and real-time grant agree. */
+export declare function sameConditions(a: ComparisonConditions, b: ComparisonConditions): boolean;
+export type CheckResult = "pass" | "fail" | "not-observable" | "not-run";
+export type FigureResult = "measured" | "not-observable" | "not-run";
+export interface Check {
+    readonly result: CheckResult;
+    readonly detail?: string;
+}
+export interface OutputCheck extends Check {
+    readonly peak?: number;
+    readonly stimulus?: Stimulus;
+}
+export interface CyclesCheck extends Check {
+    readonly done: number;
+    readonly of: number;
+}
+export interface SoakCheck extends Check {
+    readonly seconds: number;
+    readonly peakAtEnd?: number;
+}
+export interface RtCheck extends Check {
+    readonly allocations?: number;
+    readonly locks?: number;
+    /** Try-locks: they never wait, so they are reported and do not fail the check. */
+    readonly trylocks?: number;
+    readonly syscalls?: number;
+    readonly cycles?: number;
+    readonly kinds?: readonly string[];
+}
+export interface CpuFigure {
+    readonly result: FigureResult;
+    /** utime + stime of the host's processes over the soak, in percent of one core. */
+    readonly percent?: number;
+    readonly detail?: string;
+}
+export interface LatencyFigure {
+    readonly result: FigureResult;
+    readonly frames?: number;
+    readonly detail?: string;
+}
+export interface HostChecks {
+    readonly loads: Check;
+    readonly instantiates: Check;
+    readonly output: OutputCheck;
+    readonly cycles: CyclesCheck;
+    readonly soak: SoakCheck;
+    readonly rtSafe: RtCheck;
+    readonly cpu: CpuFigure;
+    readonly latency: LatencyFigure;
+}
+export interface HostRow {
+    readonly host: CompareHost;
+    readonly version: string | null;
+    readonly status: "ran" | "skipped" | "not-applicable";
+    readonly reason?: string;
+    readonly checks?: HostChecks;
+    /** The step the host died at and how, when it did. */
+    readonly crash?: {
+        readonly step: string;
+        readonly signal: string;
+    };
+    /** Loaded, instantiated, survived the cycles and the soak, never crashed, and its output was not found silent. */
+    readonly runsClean?: boolean;
+}
+export type Stimulus = "tone" | "notes" | "none";
+/** What tools/compare-host.mjs prints for one plugin under one host: observations, no judgment. */
+export interface HostObservation {
+    readonly installed: boolean;
+    readonly started?: boolean;
+    /** Each add or start: ok, the reply code, or how the host ended. */
+    readonly load?: {
+        readonly ok: boolean;
+        readonly resp?: number;
+        readonly died?: string;
+        readonly detail?: string;
+    };
+    /** The plugin's ports appeared on the graph. */
+    readonly ports?: {
+        readonly audioIn: number;
+        readonly audioOut: number;
+        readonly midiIn: number;
+    };
+    readonly stimulus?: Stimulus;
+    readonly peak?: number | null;
+    /** NaN and infinite samples read on the outputs, over both windows. */
+    readonly nonFinite?: number;
+    readonly peakProblem?: string;
+    readonly cycles?: {
+        readonly done: number;
+        readonly of: number;
+        readonly died?: string;
+        readonly failedAt?: string;
+    };
+    readonly soak?: {
+        readonly seconds: number;
+        readonly alive: boolean;
+        readonly died?: string;
+        readonly peakAtEnd?: number | null;
+    };
+    readonly rt?: readonly RtReport[];
+    readonly cpu?: {
+        readonly percent: number;
+    } | {
+        readonly problem: string;
+    };
+    readonly latencyFrames?: number | null;
+    readonly died?: {
+        readonly step: string;
+        readonly signal: string;
+    };
+    readonly problem?: string;
+}
+/** One process's rt_watch.so report. */
+export interface RtReport {
+    readonly pid: number;
+    readonly callbacks: number;
+    readonly cycles: number;
+    readonly armedCycles: number;
+    readonly allocations: number;
+    readonly locks: number;
+    readonly trylocks?: number;
+    readonly syscalls: number;
+    readonly kinds?: readonly string[];
+}
+/** A peak at or under this is silence (-100 dBFS). */
+export declare const SILENCE = 0.00001;
+/** The real-time verdict from the reports of the host's processes. */
+export declare function rtCheckOf(reports: readonly RtReport[] | undefined): RtCheck;
+/** One host's observation of one plugin as its row. */
+export declare function hostRowOf(host: CompareHost, version: string | null, obs: HostObservation, conditions: {
+    cycles: number;
+    soakS: number;
+}): HostRow;
+export interface ComparisonConditions {
+    readonly rate: number;
+    readonly quantum: number;
+    readonly cycles: number;
+    readonly soakS: number;
+    readonly windowMs: number;
+    readonly timeoutMs: number;
+    readonly jack: string;
+    readonly realtime: string;
+}
+export interface ComparisonRecord {
+    readonly schema: typeof COMPARISON_RECORD_SCHEMA;
+    readonly plugin: {
+        readonly format: string;
+        readonly id: string;
+        readonly binary?: string;
+    };
+    readonly stimulus: Stimulus;
+    readonly conditions: ComparisonConditions;
+    readonly measuredAt: string;
+    readonly hosts: readonly HostRow[];
+}
+/** The record's file name: the plugin's id made safe for a file, with a hash of the whole id so two ids never meet. */
+export declare function comparisonFileName(format: string, id: string): string;
+export declare function comparisonRecordOf(plugin: {
+    format: string;
+    id: string;
+    binary?: string;
+}, stimulus: Stimulus, conditions: ComparisonConditions, measuredAt: string, rows: readonly HostRow[]): ComparisonRecord;
+/** The row of a host that does not take this plugin's format. */
+export declare function notApplicableRow(host: CompareHost, version: string | null, format: string): HostRow;
+/** Problems with a record's shape, empty when it is one: the records repository's check holds the same rules. */
+export declare function comparisonRecordProblems(rec: unknown): string[];
+export interface HostTotals {
+    readonly host: CompareHost;
+    readonly version: string | null;
+    readonly status: "ran" | "skipped";
+    readonly reason?: string;
+    /** Plugins of a format the host takes. */
+    readonly plugins: number;
+    readonly loads: number;
+    readonly instantiates: number;
+    readonly output: number;
+    readonly runsClean: number;
+    readonly rtSafe: number;
+    /** Plugins whose real-time behaviour could be watched under this host. */
+    readonly rtObserved: number;
+    readonly crashes: number;
+    readonly cpuMedianPercent: number | null;
+    readonly latencyObservable: boolean;
+}
+export interface Beat {
+    readonly format: string;
+    readonly id: string;
+    /** The hosts it does better than on this plugin. */
+    readonly over: readonly CompareHost[];
+    /** runs-clean: it runs clean where they do not; rt-safe: its audio thread is clean where theirs is not. */
+    readonly on: "runs-clean" | "rt-safe";
+}
+export interface ComparisonSummary {
+    readonly schema: typeof COMPARISON_SUMMARY_SCHEMA;
+    readonly hostClass: string | null;
+    readonly set: string | null;
+    readonly measured: string | null;
+    readonly publishable: boolean;
+    readonly missing: readonly {
+        host: CompareHost;
+        reason: string;
+    }[];
+    readonly conditions: ComparisonConditions | null;
+    readonly records: number;
+    /** Plugins every host that ran takes and ran: the like-for-like set the headline counts. */
+    readonly common: number;
+    readonly hosts: readonly HostTotals[];
+    readonly beats: Readonly<Record<string, readonly Beat[]>>;
+}
+/**
+ * The summary of a set of comparison records. `present` is what the run found installed; a host absent from every
+ * record is still listed, skipped, with its reason. Beats are counted between hosts that both ran the plugin.
+ */
+export declare function summarise(records: readonly ComparisonRecord[], present: readonly HostPresence[], meta: {
+    hostClass?: string;
+    set?: string;
+    publish: boolean;
+}): ComparisonSummary;
+/** The text table of a summary, for the terminal. */
+export declare function summaryTable(s: ComparisonSummary): string;