/**
* The provider ladder for audio analysis. Each capability lists providers best first; a call takes the first one
* that is available within the requested quality and answers, falling through on failure. The result says which
* provider answered and why the ones above it did not.
*/
export type AudioCapability =
| "envelope"
| "onsets"
| "moments"
| "loudness"
| "silence"
| "kind"
| "beats"
| "downbeats"
| "bpm"
| "sections"
| "describe";
/** `best` may use any provider; `local` none that sends audio off the machine; `fast` only signal processing. */
export type AnalysisQuality = "best" | "local" | "fast";
/** Whether a provider can run here now, and if not, what is missing. */
export type Availability = { ok: true } | { ok: false; reason: string };
export interface AudioAnalysisProvider {
id: string;
/** Runs on this machine; a provider that is not local sends the audio to a service. */
local: boolean;
/** Pure signal processing: no model, no download. */
signal?: boolean;
capabilities: readonly AudioCapability[];
/** Whether it can run here now: a key, a platform, a model on disk. Missing means always. */
available?: () => Availability | Promise;
analyze: (
capability: AudioCapability,
input: Input,
options: Record,
) => Promise;
}
export type LadderOutcome = "answered" | "unavailable" | "excluded" | "failed";
export interface LadderStep {
provider: string;
outcome: LadderOutcome;
reason?: string;
}
export interface LadderResult {
value: Value | null;
/** The provider that answered; null when none could. */
provenance: string | null;
steps: LadderStep[];
warnings: string[];
}
export interface LadderOptions {
quality?: AnalysisQuality;
/** This capability's ladder, best first, in place of the default. */
ladder?: readonly string[];
/** Use only this provider. */
provider?: string;
options?: Record;
}
/** The default order per capability: every registered provider that offers it, in registration order. */
export function defaultLadder(
capability: AudioCapability,
providers: readonly AudioAnalysisProvider[],
): string[] {
return providers.filter((p) => p.capabilities.includes(capability)).map((p) => p.id);
}
/** Why a provider may not be used at this quality, or null when it may. */
export function exclusion(
provider: AudioAnalysisProvider,
quality: AnalysisQuality,
): string | null {
if (quality === "fast" && !provider.signal) return "quality fast allows signal processing only";
if (quality === "local" && !provider.local) return "quality local keeps audio on this machine";
return null;
}
const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
async function availabilityOf(
provider: AudioAnalysisProvider,
): Promise {
try {
return provider.available ? await provider.available() : { ok: true };
} catch (error) {
return { ok: false, reason: message(error) };
}
}
/** Why a provider cannot take this step, or null when it can. */
async function blocked(
id: string,
candidate: AudioAnalysisProvider | undefined,
capability: AudioCapability,
quality: AnalysisQuality,
): Promise {
if (!candidate?.capabilities.includes(capability))
return { provider: id, outcome: "unavailable", reason: `no provider ${id} for ${capability}` };
const excluded = exclusion(candidate, quality);
if (excluded) return { provider: id, outcome: "excluded", reason: excluded };
const availability = await availabilityOf(candidate);
if (!availability.ok)
return { provider: id, outcome: "unavailable", reason: availability.reason };
return null;
}
/** One line naming the providers above `answered` that could not answer, and why; null when none was passed over. */
function passedOver(capability: AudioCapability, steps: LadderStep[], answered: string | null) {
const skipped = steps.filter((s) => s.outcome === "unavailable" || s.outcome === "failed");
if (!skipped.length) return null;
const why = skipped
.map((s) => `${s.provider} ${s.outcome}${s.reason ? ` (${s.reason})` : ""}`)
.join("; ");
return answered ? `${capability}: used ${answered}; ${why}` : `${capability}: ${why}`;
}
export async function runLadder(
capability: AudioCapability,
input: Input,
providers: readonly AudioAnalysisProvider[],
{ quality = "best", ladder, provider, options = {} }: LadderOptions = {},
): Promise> {
const byId = new Map(providers.map((p) => [p.id, p]));
const order = provider ? [provider] : (ladder ?? defaultLadder(capability, providers));
const steps: LadderStep[] = [];
for (const id of order) {
const candidate = byId.get(id);
const skip = await blocked(id, candidate, capability, quality);
if (skip) {
steps.push(skip);
continue;
}
try {
const value = (await candidate!.analyze(capability, input, options)) as Value;
const warning = passedOver(capability, steps, id);
steps.push({ provider: id, outcome: "answered" });
return { value, provenance: id, steps, warnings: warning ? [warning] : [] };
} catch (error) {
steps.push({ provider: id, outcome: "failed", reason: message(error) });
}
}
const none = order.length ? "" : " (none offers it)";
const why = passedOver(capability, steps, null)?.slice(capability.length + 2);
return {
value: null,
provenance: null,
steps,
warnings: [`${capability}: no provider answered${none}${why ? `; ${why}` : ""}`],
};
}