Layer report

analyze writes layers.json, the report that an agent reads before it writes an edit list. This page lists the fields of version layers/1. The committed JSON Schema, schemas/layers.schema.json, holds the same contract, and the test suite validates every generated report against it.

Top level

The top level takes no other field. notes is no layer group. Each layer adds one group with values, confidence, flags, needs_render, suggested_edits and unrepresentable, and extends the schema in the same change. A group with too little evidence writes values: null and says why in its confidence. values holds plain numbers with the unit in the field name.

suggested_edits is a list of records in the edit-list format, each a param or a route with unit strings, so a route keeps its source, amount and polarity. Each record’s reason is the group’s name. The mapper of the report’s synth fills the list; see Suggested edits.

unrepresentable lists the values of the group that the synth cannot reach:

A synth whose mapper writes no edit for a group leaves both lists empty. Vital writes none for the pitch, voices and envelope groups yet.

The pitch group breaks reports of layers/1 from releases up to 0.23: suggested_edits changed from an object of numbers to a list of records, pitch is a new required top-level key, and conventions requires the keys pitch, glides, drops, sub_band_line and vibrato. A reader of older reports keeps their schema.

The envelope group breaks reports of layers/1 from releases up to 0.25: envelope is a new required top-level key, and conventions requires the keys envelope, note_off, level_spread_db and pump.

The tail breaks reports of layers/1 from releases up to 0.27: values of envelope requires release_s, tail_rt60_s, tail_weight, release_confidence, tail_votes, tail_vote_count and tail_is_reverb, and conventions requires the key tail.

The voices group breaks reports of layers/1 from releases up to 0.26: voices is a new required top-level key, and conventions requires the keys voices and joins.

The mapping lists break reports of layers/1 from releases up to 0.28.x: every group requires unrepresentable, and a suggested_edits record must be a param or a route with a reason.

The notes group breaks reports of layers/1 from releases up to 0.30: notes is a new required top-level key, and conventions requires the key notes.

The checksum breaks reports of layers/1 from releases up to 0.31: source_sha256 is a new required top-level key.

The transcription group

The group records what produced the notes, so a note that flips between two machines can be traced to its settings.

The notes group

The notes that analyze writes to notes.mid: the cleaned note list rewritten with the pitch, voices and envelope groups. The analyze guide explains the rules.

A note record:

Naming

• Field names are snake_case ASCII.
• A field with a unit carries it as a suffix: _hz, _s, _ms, _db, _dbfs, _deg, _st (semitones) or _ct (cents). A field without a suffix is a count, a ratio, a share from 0 to 1, a power, a flag or a tempo in BPM.
• Integers are written as integers; every other number is a float.

Value objects

A single estimate is {"value": ..., "confidence": ...}. A statistic over active frames is {"median": ..., "iqr": ..., "confidence": ...}, the median and the interquartile range. The value, or the median and the IQR, is null exactly when the confidence states no estimate.

The confidence object follows the units page:

{"level": "high", "reasons": [{"code": "active_frames", "value": 412}], "spread": 310.0, "estimate": true}

• level is low, medium or high.
• reasons holds at least one {code, value} pair. The value is a count, a number or a flag.
• spread is optional, in the unit of the value: the IQR of a statistic, one bin width for the band edge.
• "estimate": false means no value. Such an object has reasons and neither a level nor a spread.
• An unknown field is an error.

The stem group

Every statistic over frames, band_share and band_edge_hz need at least 16 active frames; with fewer they give no estimate with the reason too_few_frames. The ranges are those of the unit types and the schema. Each convention is the text that conventions holds under the same key; the pipeline page explains the rules behind them.

stereo holds full, sub (below 120 Hz), low_mid (120 Hz to 1 kHz) and high (above 1 kHz), each {rho, sm_db, ipd_deg}, and one confidence for the screen:

A stereo value is null when it does not exist: a one-channel file, a silent channel, or a zero mid or side.

The pitch group

The pitch layer of a monophonic line; the pitch layer page explains each method. Every record carries its own confidence, always an estimate. The group’s own confidence is medium, or low when fewer than half of the track frames inside the notes are voiced within 100 cents of a sounding note, as under noise or DC. Its reasons are voiced_frames, the voiced frames of the f0 track, and note_frames, that share.

values is null when the line plays chords (reason polyphonic_line) or the stem has no notes (reason no_note_list). Otherwise it holds three lists, each in time order and each empty when nothing was found: glides, drops and vibrato. Every time is audio time from the start of the stem.

A glide:

Its reasons are motion_span (seconds), fit_residual (cents), pitch_jitter (cents) and curve_bound (flag). A glide whose motion_span is under 0.09 reads low.

A drop:

Its reasons are fit_residual and attack_time (seconds): the time the band envelope of the strike takes from 10 % to 90 % of its peak. A drop with an attack over 30 ms reads low, and one with tau_s under 0.01 or an attack over 12 ms at most medium.

A vibrato:

Its reasons are sine_share, cycles_in_span and contour_kurtosis. A vibrato holds 2.5 cycles or more; from 4 it reads high. A kurtosis below 1.25 reads low, since the contour jumps between two levels, as a trill does, and so does a vibrato on a pitch below 100 Hz.

flags holds four booleans: chord_skipped, glide_too_short (a motion between two notes lasted 35 to 90 ms over its fitted time, or over its detected span when the fit failed), weak_fundamental (a low note’s second harmonic exceeded its fundamental by 6 dB, so its drop was not reported) and no_notes. At a sample rate under about 4 times a note’s pitch the second harmonic cannot be measured, and that note is not tested for weak_fundamental. needs_render is false.

The voices group

The count of voices, read on any line, and the joins of a mono line; the voices layer page explains each method. values is null without notes (reason no_note_list) or when no note holds a sounding part in the stem (reason too_few_notes). The group’s confidence reads the share of the held time whose count agrees with the verdict (reason count_agreement). flags is empty and needs_render is false.

A join record:

The envelope group

The amplitude envelope over the pooled notes, each read note’s record, and the sidechain pump; the envelope layer page explains each method. values is null when no note was read: the stem has no notes (reason no_note_list) or every note was skipped (reason too_few_notes). The group’s own confidence is medium with 3 or more pooled notes, else low.

A statistic reads low over fewer than 3 notes or with an interquartile range above half its median. Its reasons are too_few_notes and relative_spread; attack_s adds upper_bound_share, the share of the pooled attacks that are upper bounds. A median of 0 under an interquartile range above 0 has no ratio, so the statistic reads low and writes zero_median, that range in the statistic’s unit, in place of relative_spread.

A note record:

flags holds three booleans: no_notes, attack_is_upper_bound (more than half the pooled attacks are upper bounds, so a preset should not take the attack) and pump_stripped (the pump locks to the beat over 8 counted beats or more, and its curve was taken out of the note tracks). needs_render is false.

Conventions