fractal-midi 0.1.0-alpha.0

package/dist/am4/index.d.ts

@@ -0,0 +1,28 @@
+export { KNOWN_PARAMS, PARAM_ALIASES, SCENE_MIDI_TYPE_ENUM, encode, decode, formatDisplay, formatUnitSuffix, resolveEnumValue, findEnumCandidates, } from './params.js';
+export type { Param, ParamKey, Unit } from './params.js';
+export { PARAM_NAMES, } from './paramNames.js';
+export type { ParamNameEntry } from './paramNames.js';
+export { GENERATED_PARAM_NAMES, GENERATED_PARAM_NAMES_FIRMWARE, } from './paramNamesGenerated.js';
+export { BLOCK_TYPE_VALUES, BLOCK_NAMES_BY_VALUE, resolveBlockType, } from './blockTypes.js';
+export type { BlockTypeName } from './blockTypes.js';
+export { parseLocationCode, formatLocationCode, formatLocationDisplay, TOTAL_LOCATIONS, } from './locations.js';
+export { AM4_MODEL_ID, buildSetFloatParam, buildSetParam, buildSetBlockType, buildSetBlockBypass, buildSetPresetName, buildSetSceneName, buildSwitchScene, buildSwitchPreset, buildSaveToLocation, buildGetPresetName, buildReadParam, buildRequestActiveBufferDump, isCommandAck, isWriteEcho, isReadResponse, isReadResponseLong, parseReadResponse, parseLongReadBypassFlag, parseGetPresetNameResponse, BLOCK_SLOT_PID_LOW, BLOCK_SLOT_PID_HIGH_BASE, READ_TYPE_LONG, LONG_READ_BYPASS_FLAG_BYTE, READ_VALUE_DENOMINATOR, PRESET_NAME_EMPTY_SENTINEL, } from './setParam.js';
+export type { ParamId, ReadResponse, GetPresetNameResponse } from './setParam.js';
+export { CACHE_PARAMS } from './cacheParams.js';
+export type { CacheParamKey } from './cacheParams.js';
+export { AMP_TYPES, DRIVE_TYPES, REVERB_TYPES, DELAY_TYPES, CHORUS_TYPES, FLANGER_TYPES, PHASER_TYPES, WAH_TYPES, COMPRESSOR_TYPES, GEQ_TYPES, FILTER_TYPES, TREMOLO_TYPES, ENHANCER_TYPES, GATE_TYPES, VOLPAN_MODES, TEMPO_DIVISIONS, LFO_WAVEFORMS, AMP_TYPES_VALUES, DRIVE_TYPES_VALUES, REVERB_TYPES_VALUES, DELAY_TYPES_VALUES, CHORUS_TYPES_VALUES, FLANGER_TYPES_VALUES, PHASER_TYPES_VALUES, WAH_TYPES_VALUES, COMPRESSOR_TYPES_VALUES, GEQ_TYPES_VALUES, FILTER_TYPES_VALUES, TREMOLO_TYPES_VALUES, ENHANCER_TYPES_VALUES, GATE_TYPES_VALUES, VOLPAN_MODES_VALUES, TEMPO_DIVISIONS_VALUES, LFO_WAVEFORMS_VALUES, } from './cacheEnums.js';
+export { TYPE_APPLICABILITY, TYPE_APPLICABILITY_FIRMWARE, } from './typeApplicability.js';
+export type { Applicability, ApplicabilityGate } from './typeApplicability.js';
+export { getApplicability, describeApplicability, checkApplicability, findCompatibleTypes, } from './applicability.js';
+export type { ActiveTypeContext, ApplicabilityCheck } from './applicability.js';
+export { EDITOR_CONTROLS, EDITOR_CONTROL_FIRMWARE, EDITOR_CONTROL_PARAMETER_NAMES, resolveEditorControlLabel, } from './editorControlLabels.js';
+export type { EditorControlContext, EditorControlEntry, } from './editorControlLabels.js';
+export { SYMBOLIC_IDS_BY_BLOCK } from './symbolicIds.js';
+export { PARAMETER_BRIDGE, PARAMETER_BRIDGE_FIRMWARE, resolveBridge, preferredDisplayLabel, } from './parameterBridge.js';
+export type { ParameterBridgeEntry } from './parameterBridge.js';
+export { VARIANT_RESOLVER_FIRMWARE, VARIANT_RESOLVER_BY_EFFECT_TYPE, VARIANT_RESOLVER_FALLBACK, PARAMETER_NAME_TO_CACHE_ID, UNIVERSAL_BLOCK_PARAMETERS, resolveCacheId, resolveAllCacheIds, } from './variantResolverTables.js';
+export type { ResolverEntry } from './variantResolverTables.js';
+export { transpile } from './ir/transpile.js';
+export type { WorkingBufferIR } from './ir/preset.js';
+export { DEFAULT_SCRATCH_LOCATION, EnumAmbiguityError, suggestParamName, paramKey, resolveValue, } from './shared/paramHelpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/am4/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/am4/index.ts"],"names":[],"mappings":"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"}

package/dist/am4/index.js

@@ -0,0 +1,31 @@
+// Barrel for fractal-midi/am4.
+//
+// Public surface for AM4 data and codec. Sibling subpaths (`./shared`,
+// future `./axe-fx-ii`, `./axe-fx-iii`) follow the same shape: param
+// dictionary + block-type table + wire builders + parsers.
+//
+// Pure code — no MIDI transport dependency. Bring your own.
+// Data — parameter dictionary, block-type table, location parsing.
+export { KNOWN_PARAMS, PARAM_ALIASES, SCENE_MIDI_TYPE_ENUM, encode, decode, formatDisplay, formatUnitSuffix, resolveEnumValue, findEnumCandidates, } from './params.js';
+export { PARAM_NAMES, } from './paramNames.js';
+export { GENERATED_PARAM_NAMES, GENERATED_PARAM_NAMES_FIRMWARE, } from './paramNamesGenerated.js';
+export { BLOCK_TYPE_VALUES, BLOCK_NAMES_BY_VALUE, resolveBlockType, } from './blockTypes.js';
+export { parseLocationCode, formatLocationCode, formatLocationDisplay, TOTAL_LOCATIONS, } from './locations.js';
+// Codec — wire-byte builders + parsers.
+export { AM4_MODEL_ID, buildSetFloatParam, buildSetParam, buildSetBlockType, buildSetBlockBypass, buildSetPresetName, buildSetSceneName, buildSwitchScene, buildSwitchPreset, buildSaveToLocation, buildGetPresetName, buildReadParam, buildRequestActiveBufferDump, isCommandAck, isWriteEcho, isReadResponse, isReadResponseLong, parseReadResponse, parseLongReadBypassFlag, parseGetPresetNameResponse, BLOCK_SLOT_PID_LOW, BLOCK_SLOT_PID_HIGH_BASE, READ_TYPE_LONG, LONG_READ_BYPASS_FLAG_BYTE, READ_VALUE_DENOMINATOR, PRESET_NAME_EMPTY_SENTINEL, } from './setParam.js';
+// Data tables — cache + type-applicability + enums.
+export { CACHE_PARAMS } from './cacheParams.js';
+export { AMP_TYPES, DRIVE_TYPES, REVERB_TYPES, DELAY_TYPES, CHORUS_TYPES, FLANGER_TYPES, PHASER_TYPES, WAH_TYPES, COMPRESSOR_TYPES, GEQ_TYPES, FILTER_TYPES, TREMOLO_TYPES, ENHANCER_TYPES, GATE_TYPES, VOLPAN_MODES, TEMPO_DIVISIONS, LFO_WAVEFORMS, AMP_TYPES_VALUES, DRIVE_TYPES_VALUES, REVERB_TYPES_VALUES, DELAY_TYPES_VALUES, CHORUS_TYPES_VALUES, FLANGER_TYPES_VALUES, PHASER_TYPES_VALUES, WAH_TYPES_VALUES, COMPRESSOR_TYPES_VALUES, GEQ_TYPES_VALUES, FILTER_TYPES_VALUES, TREMOLO_TYPES_VALUES, ENHANCER_TYPES_VALUES, GATE_TYPES_VALUES, VOLPAN_MODES_VALUES, TEMPO_DIVISIONS_VALUES, LFO_WAVEFORMS_VALUES, } from './cacheEnums.js';
+export { TYPE_APPLICABILITY, TYPE_APPLICABILITY_FIRMWARE, } from './typeApplicability.js';
+export { getApplicability, describeApplicability, checkApplicability, findCompatibleTypes, } from './applicability.js';
+// Editor / bridge labels (RE'd from AM4-Edit binary).
+export { EDITOR_CONTROLS, EDITOR_CONTROL_FIRMWARE, EDITOR_CONTROL_PARAMETER_NAMES, resolveEditorControlLabel, } from './editorControlLabels.js';
+export { SYMBOLIC_IDS_BY_BLOCK } from './symbolicIds.js';
+export { PARAMETER_BRIDGE, PARAMETER_BRIDGE_FIRMWARE, resolveBridge, preferredDisplayLabel, } from './parameterBridge.js';
+// Variant resolver — block.parameterName → cache-id mappings.
+export { VARIANT_RESOLVER_FIRMWARE, VARIANT_RESOLVER_BY_EFFECT_TYPE, VARIANT_RESOLVER_FALLBACK, PARAMETER_NAME_TO_CACHE_ID, UNIVERSAL_BLOCK_PARAMETERS, resolveCacheId, resolveAllCacheIds, } from './variantResolverTables.js';
+// Intermediate representation — preset model + transpiler.
+export { transpile } from './ir/transpile.js';
+// Shared helpers (paramHelpers — the channel-aware resolver lives in
+// the consumer because it needs a MIDI connection).
+export { DEFAULT_SCRATCH_LOCATION, EnumAmbiguityError, suggestParamName, paramKey, resolveValue, } from './shared/paramHelpers.js';

package/dist/am4/ir/preset.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Preset Intermediate Representation.
+ *
+ * Scope: **working buffer only** — a flat parameter map. The full preset
+ * IR (block placement, scenes, per-block channels) is deferred until the
+ * relevant protocol pieces are reverse-engineered.
+ *
+ * A `WorkingBufferIR` describes the parameter values to apply to the
+ * AM4's *currently loaded* preset. The transpiler in `./transpile.ts`
+ * turns it into an ordered SET_PARAM command sequence.
+ */
+import type { ParamKey } from '../params.js';
+/**
+ * Display values keyed by registry param key (e.g. `'amp.gain'`). Values
+ * are in human/UI units (the registry handles the scale conversion).
+ *
+ * Iteration order is preserved by the transpiler, so callers can express
+ * apply-order dependencies (e.g. set block type before block params)
+ * by ordering insertion.
+ */
+export interface WorkingBufferIR {
+    params: Partial<Record<ParamKey, number>>;
+}
+//# sourceMappingURL=preset.d.ts.map

package/dist/am4/ir/preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../../src/am4/ir/preset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3C"}

package/dist/am4/ir/preset.js

@@ -0,0 +1,12 @@
+/**
+ * Preset Intermediate Representation.
+ *
+ * Scope: **working buffer only** — a flat parameter map. The full preset
+ * IR (block placement, scenes, per-block channels) is deferred until the
+ * relevant protocol pieces are reverse-engineered.
+ *
+ * A `WorkingBufferIR` describes the parameter values to apply to the
+ * AM4's *currently loaded* preset. The transpiler in `./transpile.ts`
+ * turns it into an ordered SET_PARAM command sequence.
+ */
+export {};

package/dist/am4/ir/transpile.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Working-buffer IR → wire command sequence.
+ *
+ * Emits one SET_PARAM message per entry in `ir.params`, in insertion
+ * order. Use `sendMessages(...)` from the MIDI layer to dispatch them.
+ */
+import type { WorkingBufferIR } from './preset.js';
+export declare function transpile(ir: WorkingBufferIR): number[][];
+//# sourceMappingURL=transpile.d.ts.map

package/dist/am4/ir/transpile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transpile.d.ts","sourceRoot":"","sources":["../../../src/am4/ir/transpile.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,wBAAgB,SAAS,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,EAAE,EAAE,CAUzD"}

package/dist/am4/ir/transpile.js

@@ -0,0 +1,19 @@
+/**
+ * Working-buffer IR → wire command sequence.
+ *
+ * Emits one SET_PARAM message per entry in `ir.params`, in insertion
+ * order. Use `sendMessages(...)` from the MIDI layer to dispatch them.
+ */
+import { buildSetParam } from '../setParam.js';
+export function transpile(ir) {
+    const messages = [];
+    for (const [key, value] of Object.entries(ir.params)) {
+        if (value === undefined)
+            continue;
+        if (!Number.isFinite(value)) {
+            throw new Error(`Param "${key}" has non-finite value: ${value}`);
+        }
+        messages.push(buildSetParam(key, value));
+    }
+    return messages;
+}

package/dist/am4/locations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AM4 preset-location addressing.
+ *
+ * The AM4 stores 104 presets across 26 banks (A..Z), 4 presets per bank.
+ * Per the AM4 owner's manual, Fractal calls a stored preset's address its
+ * "location" (e.g. "Use SELECT and ABCD to choose a location to save to").
+ * On the wire, locations are a 0-based index 0..103:
+ *   A01 = 0, A02 = 1, ..., A04 = 3, B01 = 4, ..., Z04 = 103.
+ *
+ * Accepts both "A1" and zero-padded "A01" on input; emits the 3-char form
+ * on output. Users and the MCP surface always speak the letter form; the
+ * wire only sees the index.
+ *
+ * Reserved terminology: the word "slot" is reserved for block (effect)
+ * positions within a preset's signal chain — see buildSetBlockType. Do
+ * NOT use "slot" for preset locations in new code or user-facing strings.
+ */
+export declare const TOTAL_LOCATIONS: number;
+/** Parse "A01".."Z04" (or "A1".."Z4") → 0..103 wire index. Throws on bad input. */
+export declare function parseLocationCode(code: string): number;
+/** Inverse: 0..103 → "A01".."Z04" (3-char canonical form for keys + safety comparisons). */
+export declare function formatLocationCode(locationIndex: number): string;
+/**
+ * 0..103 → "A1".."Z4" — the unpadded form Fractal uses on the AM4 hardware
+ * display and throughout the AM4 Owner's Manual ("preset A1", "C3", "W4",
+ * etc.). Use this in user-facing tool output where the founder/user expects
+ * to see what the device shows. `formatLocationCode` (zero-padded) stays as
+ * the internal canonical form for safety comparisons (SCRATCH_LOCATION) and
+ * fingerprint-table keys.
+ */
+export declare function formatLocationDisplay(locationIndex: number): string;
+//# sourceMappingURL=locations.d.ts.map

package/dist/am4/locations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locations.d.ts","sourceRoot":"","sources":["../../src/am4/locations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,eAAO,MAAM,eAAe,QAA2C,CAAC;AAExE,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOnE"}

package/dist/am4/locations.js

@@ -0,0 +1,58 @@
+/**
+ * AM4 preset-location addressing.
+ *
+ * The AM4 stores 104 presets across 26 banks (A..Z), 4 presets per bank.
+ * Per the AM4 owner's manual, Fractal calls a stored preset's address its
+ * "location" (e.g. "Use SELECT and ABCD to choose a location to save to").
+ * On the wire, locations are a 0-based index 0..103:
+ *   A01 = 0, A02 = 1, ..., A04 = 3, B01 = 4, ..., Z04 = 103.
+ *
+ * Accepts both "A1" and zero-padded "A01" on input; emits the 3-char form
+ * on output. Users and the MCP surface always speak the letter form; the
+ * wire only sees the index.
+ *
+ * Reserved terminology: the word "slot" is reserved for block (effect)
+ * positions within a preset's signal chain — see buildSetBlockType. Do
+ * NOT use "slot" for preset locations in new code or user-facing strings.
+ */
+const BANK_LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const LOCATIONS_PER_BANK = 4;
+export const TOTAL_LOCATIONS = BANK_LETTERS.length * LOCATIONS_PER_BANK;
+/** Parse "A01".."Z04" (or "A1".."Z4") → 0..103 wire index. Throws on bad input. */
+export function parseLocationCode(code) {
+    const m = /^([A-Za-z])0?(\d)$/.exec(code.trim());
+    if (!m) {
+        throw new Error(`Preset location must look like "A01".."Z04" (bank A..Z + sub-index 01..04), got "${code}".`);
+    }
+    const bank = m[1].toUpperCase().charCodeAt(0) - 'A'.charCodeAt(0);
+    const sub = parseInt(m[2], 10);
+    if (sub < 1 || sub > LOCATIONS_PER_BANK) {
+        throw new Error(`Preset sub-index must be 1..${LOCATIONS_PER_BANK}, got ${sub} in "${code}".`);
+    }
+    return bank * LOCATIONS_PER_BANK + (sub - 1);
+}
+/** Inverse: 0..103 → "A01".."Z04" (3-char canonical form for keys + safety comparisons). */
+export function formatLocationCode(locationIndex) {
+    if (!Number.isInteger(locationIndex) || locationIndex < 0 || locationIndex >= TOTAL_LOCATIONS) {
+        throw new Error(`Preset location index must be integer 0..${TOTAL_LOCATIONS - 1}, got ${locationIndex}.`);
+    }
+    const bank = Math.floor(locationIndex / LOCATIONS_PER_BANK);
+    const sub = (locationIndex % LOCATIONS_PER_BANK) + 1;
+    return `${BANK_LETTERS[bank]}${sub.toString().padStart(2, '0')}`;
+}
+/**
+ * 0..103 → "A1".."Z4" — the unpadded form Fractal uses on the AM4 hardware
+ * display and throughout the AM4 Owner's Manual ("preset A1", "C3", "W4",
+ * etc.). Use this in user-facing tool output where the founder/user expects
+ * to see what the device shows. `formatLocationCode` (zero-padded) stays as
+ * the internal canonical form for safety comparisons (SCRATCH_LOCATION) and
+ * fingerprint-table keys.
+ */
+export function formatLocationDisplay(locationIndex) {
+    if (!Number.isInteger(locationIndex) || locationIndex < 0 || locationIndex >= TOTAL_LOCATIONS) {
+        throw new Error(`Preset location index must be integer 0..${TOTAL_LOCATIONS - 1}, got ${locationIndex}.`);
+    }
+    const bank = Math.floor(locationIndex / LOCATIONS_PER_BANK);
+    const sub = (locationIndex % LOCATIONS_PER_BANK) + 1;
+    return `${BANK_LETTERS[bank]}${sub}`;
+}

package/dist/am4/paramNames.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hand-maintained name table for cache-derived parameters.
+ *
+ * Pipeline (P1-010): `scripts/gen-params-from-cache.ts` walks every
+ * CONFIRMED cache block, looks up each record's `id` in this table,
+ * and emits a `KNOWN_PARAMS`-shape entry if a name is present.
+ * Records without a name here are NOT emitted — they stay dormant
+ * until a human assigns them a UI label (Session B of P1-010).
+ *
+ * Why a manual table instead of just emitting `param_{id}` placeholders:
+ * MCP tool callers (Claude) need real human names to reason about
+ * parameters. `amp.gain=6` is useful; `amp.param_11=6` is not. The
+ * cache only stores ids + ranges, not labels.
+ *
+ * Sources for labels (in priority order):
+ *   1. Wire captures that pin a name to a `(pidLow, pidHigh)` pair
+ *      (highest confidence — see SYSEX-MAP §6a for the decode rule).
+ *   2. `docs/manuals/Fractal-Audio-Blocks-Guide.txt` param descriptions.
+ *   3. AM4-Edit UI labels observed via AM4-Edit screenshots.
+ *
+ * Entry shape (two forms):
+ *   `'name'` — plain string. Generator infers unit from cache `c`
+ *     (display-scale) via the default mapping (c=10 → knob_0_10,
+ *     c=100 → percent, c=1000 → ms, c=1 → db, enum → enum).
+ *   `{ name: 'label', unit: 'hz' }` — object form with an explicit
+ *     unit override. Required when cache signature is ambiguous
+ *     (e.g. c=1 could be dB / Hz / seconds / raw-count — the cache
+ *     doesn't distinguish). Optional `displayMin` / `displayMax`
+ *     overrides round the cache's internal min/max to a cleaner UI
+ *     range where needed (e.g. reverb.predelay cache max=0.25s →
+ *     displayMax=250 ms instead of the floating-point 250.0000…).
+ *
+ * Seed (2026-04-19, Session 25): every name already registered in
+ * `KNOWN_PARAMS`. Session 26 (2026-04-20) added tone-stack + Mix
+ * Page + Drive tone/level/mix + reverb predelay + LFO rates +
+ * reverb time via the object-form overrides.
+ *
+ * OUT-OF-BAND PARAMS (not in the cache; hand-registered in
+ * `KNOWN_PARAMS` directly, not through this pipeline):
+ *   - `amp.level` / other-block `level` — pidHigh=0x0000, no cache
+ *     record at id=0.
+ *   - `{amp,drive,reverb,delay}.channel` — pidHigh=0x07D2, no cache
+ *     record (Session 08 decoded this directly from wire captures).
+ *
+ * These remain in `params.ts` regardless of what this file says.
+ */
+import type { Unit } from './params.js';
+export type ParamNameEntry = string | {
+    readonly name: string;
+    readonly unit?: Unit;
+    readonly displayMin?: number;
+    readonly displayMax?: number;
+};
+export declare const PARAM_NAMES: Readonly<Record<string, Readonly<Record<number, ParamNameEntry>>>>;
+//# sourceMappingURL=paramNames.d.ts.map

package/dist/am4/paramNames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramNames.d.ts","sourceRoot":"","sources":["../../src/am4/paramNames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAgBhH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAi1BjF,CAAC"}