rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/score/dsp.ts

@@ -0,0 +1,272 @@
+// the signal blocks the score's synth is made of, each a pure function over Float32Arrays: the ADSR points, the biquad
+// (the Web Audio formulas, so an instrument sounds as it does in a browser synth), the compressor, the soft ceiling and
+// an FFT convolution for the room. Hot loops sit in top level functions over their arrays, no closure per sample
+
+/** [seconds from note start, gain] points; the last one is 0 at release end. A note released during its attack or
+ *  decay releases from the level it reached, never from the peak, so a short note never clicks */
+export function envPoints(env: { a: number; d: number; s: number; r: number }, dur: number, peak: number): [number, number][] {
+    const a = Math.max(0.001, env.a)
+    const d = Math.max(0, env.d)
+    const s = Math.max(0, Math.min(1, env.s)) * peak
+    const r = Math.max(0.005, env.r)
+    const off = Math.max(0, dur)
+    const pts: [number, number][] = [[0, 0]]
+    if (off <= a) pts.push([off, peak * (off / a)])
+    else {
+        pts.push([a, peak])
+        if (off <= a + d) pts.push([off, d === 0 ? s : peak + (s - peak) * ((off - a) / d)])
+        else {
+            pts.push([a + d, s])
+            pts.push([off, s])
+        }
+    }
+    const last = pts[pts.length - 1]
+    pts.push([(last?.[0] ?? off) + r, 0])
+    return pts.filter((p, i) => i === 0 || p[0] !== pts[i - 1]?.[0] || p[1] !== pts[i - 1]?.[1])
+}
+
+/** multiplies `buf` (its first sample at `t0` seconds after the note start) by the envelope's points */
+export function applyEnvelope(buf: Float32Array, n: number, t0: number, rate: number, pts: readonly [number, number][]): void {
+    let k = 1
+    for (let i = 0; i < n; i++) {
+        const t = t0 + i / rate
+        while (k < pts.length - 1 && t > pts[k]![0]) k++
+        const p = pts[k - 1]!
+        const q = pts[k]!
+        const g = t >= q[0] ? q[1] : q[0] === p[0] ? q[1] : p[1] + (q[1] - p[1]) * ((t - p[0]) / (q[0] - p[0]))
+        buf[i] = buf[i]! * (t < 0 ? 0 : g)
+    }
+}
+
+export type FilterType = 'lowpass' | 'highpass' | 'bandpass'
+
+/** a biquad in place, Web Audio's coefficients: lowpass and highpass read q in dB, bandpass as a plain q */
+export function biquad(buf: Float32Array, n: number, rate: number, type: FilterType, freq: number, q: number): void {
+    const f = Math.max(1, Math.min(rate / 2 - 1, freq))
+    const w0 = (2 * Math.PI * f) / rate
+    const cw = Math.cos(w0)
+    const sw = Math.sin(w0)
+    let b0: number, b1: number, b2: number
+    let alpha: number
+    if (type === 'bandpass') {
+        alpha = sw / (2 * Math.max(1e-4, q))
+        b0 = alpha
+        b1 = 0
+        b2 = -alpha
+    } else {
+        alpha = sw / (2 * 10 ** (q / 20))
+        const sign = type === 'lowpass' ? 1 : -1
+        b0 = (1 - sign * cw) / 2
+        b1 = sign * (1 - sign * cw)
+        b2 = b0
+    }
+    const a0 = 1 + alpha
+    biquadRun(buf, n, b0 / a0, b1 / a0, b2 / a0, (-2 * cw) / a0, (1 - alpha) / a0)
+}
+
+function biquadRun(buf: Float32Array, n: number, b0: number, b1: number, b2: number, a1: number, a2: number): void {
+    let z1 = 0
+    let z2 = 0
+    for (let i = 0; i < n; i++) {
+        const x = buf[i]!
+        const y = b0 * x + z1
+        z1 = b1 * x - a1 * y + z2
+        z2 = b2 * x - a2 * y
+        buf[i] = y
+    }
+}
+
+const CEILING = 0.98
+const KNEE = 0.7
+
+/** linear below the knee, tanh into the ceiling above it (slope 1 at the knee, so the join is smooth) */
+export function softClip(x: number): number {
+    const a = Math.abs(x)
+    if (a <= KNEE) return x
+    return Math.sign(x) * (KNEE + (CEILING - KNEE) * Math.tanh((a - KNEE) / (CEILING - KNEE)))
+}
+
+export interface CompressorDef {
+    /** dB */
+    threshold: number
+    /** dB */
+    knee: number
+    ratio: number
+    /** seconds */
+    attack: number
+    release: number
+}
+
+const lin = (db: number): number => 10 ** (db / 20)
+const dbOf = (x: number): number => 20 * Math.log10(Math.max(1e-12, x))
+
+/** the static curve of a browser compressor: a knee shaped by `k`, then the ratio's line; the knee's `k` is searched so
+ *  the curve meets the ratio's slope at the knee's top, and the output is lifted by its makeup gain */
+function staticCurve(c: CompressorDef): { saturate: (x: number) => number; makeup: number } {
+    const linThr = lin(c.threshold)
+    const kneeThrDb = c.threshold + c.knee
+    const kneeThr = lin(kneeThrDb)
+    const slope = 1 / c.ratio
+    const kneeCurve = (x: number, k: number): number => (x < linThr ? x : linThr + (1 - Math.exp(-k * (x - linThr))) / k)
+    const slopeAt = (x: number, k: number): number => {
+        if (x < linThr) return 1
+        const x2 = x * 1.001
+        return (dbOf(kneeCurve(x2, k)) - dbOf(kneeCurve(x, k))) / (dbOf(x2) - dbOf(x))
+    }
+    let lo = 0.1
+    let hi = 10000
+    let k = 5
+    for (let i = 0; i < 15; i++) {
+        if (slopeAt(kneeThr, k) < slope) hi = k
+        else lo = k
+        k = Math.sqrt(lo * hi)
+    }
+    const yKneeDb = dbOf(kneeCurve(kneeThr, k))
+    const saturate = (x: number): number => (x < kneeThr ? kneeCurve(x, k) : lin(yKneeDb + slope * (dbOf(x) - kneeThrDb)))
+    return { saturate, makeup: (1 / saturate(1)) ** 0.6 }
+}
+
+/** a stereo compressor in place, 6 ms of lookahead: the gain follows the louder channel, falling at `attack` and
+ *  rising at `release`, in dB */
+export function compress(l: Float32Array, r: Float32Array, rate: number, c: CompressorDef): void {
+    const { saturate, makeup } = staticCurve(c)
+    const n = l.length
+    // the curve sampled in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
+    const lo = -60
+    const step = 0.05
+    const table = new Float32Array(Math.ceil((24 - lo) / step) + 2)
+    for (let i = 0; i < table.length; i++) {
+        const x = lin(lo + i * step)
+        table[i] = dbOf(saturate(x) / x)
+    }
+    compressRun(l, r, n, Math.round(0.006 * rate), Math.exp(-1 / (Math.max(1e-4, c.attack) * rate)), Math.exp(-1 / (Math.max(1e-4, c.release) * rate)), table, lo, step, makeup)
+}
+
+function compressRun(l: Float32Array, r: Float32Array, n: number, delay: number, att: number, rel: number, table: Float32Array, lo: number, step: number, makeup: number): void {
+    const dl = new Float32Array(delay)
+    const dr = new Float32Array(delay)
+    let env = 0
+    const last = table.length - 1
+    for (let i = 0; i < n; i++) {
+        const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
+        let target = 0
+        if (x > 1e-3) {
+            const p = (20 * Math.log10(x) - lo) / step
+            const j = Math.min(last - 1, Math.max(0, p | 0))
+            const f = Math.min(1, Math.max(0, p - j))
+            target = table[j]! + (table[j + 1]! - table[j]!) * f
+        }
+        env = target < env ? target + (env - target) * att : target + (env - target) * rel
+        const g = makeup * 10 ** (env / 20)
+        const k = i % delay
+        const yl = dl[k]!
+        const yr = dr[k]!
+        dl[k] = l[i]!
+        dr[k] = r[i]!
+        l[i] = yl * g
+        r[i] = yr * g
+    }
+}
+
+/** an in place radix 2 FFT; `inverse` scales by 1/n */
+export function fft(re: Float64Array, im: Float64Array, inverse: boolean): void {
+    const n = re.length
+    for (let i = 1, j = 0; i < n; i++) {
+        let bit = n >> 1
+        for (; j & bit; bit >>= 1) j ^= bit
+        j ^= bit
+        if (i < j) {
+            const tr = re[i]!
+            re[i] = re[j]!
+            re[j] = tr
+            const ti = im[i]!
+            im[i] = im[j]!
+            im[j] = ti
+        }
+    }
+    const sign = inverse ? 1 : -1
+    for (let len = 2; len <= n; len <<= 1) {
+        const ang = (sign * 2 * Math.PI) / len
+        const wr = Math.cos(ang)
+        const wi = Math.sin(ang)
+        const half = len >> 1
+        for (let i = 0; i < n; i += len) {
+            let cr = 1
+            let ci = 0
+            for (let k = 0; k < half; k++) {
+                const a = i + k
+                const b = a + half
+                const xr = re[b]! * cr - im[b]! * ci
+                const xi = re[b]! * ci + im[b]! * cr
+                re[b] = re[a]! - xr
+                im[b] = im[a]! - xi
+                re[a] = re[a]! + xr
+                im[a] = im[a]! + xi
+                const nr = cr * wr - ci * wi
+                ci = cr * wi + ci * wr
+                cr = nr
+            }
+        }
+    }
+    if (inverse) for (let i = 0; i < n; i++) {
+        re[i] = re[i]! / n
+        im[i] = im[i]! / n
+    }
+}
+
+/** adds `gain` times (inL, inR) convolved with the stereo impulse (irL, irR) to (outL, outR): overlap add, both
+ *  channels in one complex transform a block */
+export function convolveInto(inL: Float32Array, inR: Float32Array, irL: Float32Array, irR: Float32Array, outL: Float32Array, outR: Float32Array, gain: number): void {
+    const m = irL.length
+    let size = 1
+    while (size < 4 * m) size <<= 1
+    const block = size - m + 1
+    // the two impulses' spectra from one transform of irL + i irR, split by conjugate symmetry
+    const hr = new Float64Array(size)
+    const hi = new Float64Array(size)
+    hr.set(irL)
+    hi.set(irR)
+    fft(hr, hi, false)
+    const lr = new Float64Array(size)
+    const li = new Float64Array(size)
+    const rr = new Float64Array(size)
+    const ri = new Float64Array(size)
+    for (let k = 0; k < size; k++) {
+        const j = (size - k) % size
+        lr[k] = (hr[k]! + hr[j]!) / 2
+        li[k] = (hi[k]! - hi[j]!) / 2
+        rr[k] = (hi[k]! + hi[j]!) / 2
+        ri[k] = (hr[j]! - hr[k]!) / 2
+    }
+    const xr = new Float64Array(size)
+    const xi = new Float64Array(size)
+    const yr = new Float64Array(size)
+    const yi = new Float64Array(size)
+    const n = outL.length
+    for (let at = 0; at < inL.length; at += block) {
+        const len = Math.min(block, inL.length - at)
+        xr.fill(0)
+        xi.fill(0)
+        let loud = false
+        for (let i = 0; i < len; i++) {
+            xr[i] = inL[at + i]!
+            xi[i] = inR[at + i]!
+            if (xr[i] !== 0 || xi[i] !== 0) loud = true
+        }
+        if (!loud) continue
+        fft(xr, xi, false)
+        spectrumTimes(xr, xi, lr, li, yr, yi)
+        fft(yr, yi, true)
+        for (let i = 0; i < size && at + i < n; i++) outL[at + i] = outL[at + i]! + gain * yr[i]!
+        spectrumTimes(xr, xi, rr, ri, yr, yi)
+        fft(yr, yi, true)
+        for (let i = 0; i < size && at + i < n; i++) outR[at + i] = outR[at + i]! + gain * yi[i]!
+    }
+}
+
+function spectrumTimes(ar: Float64Array, ai: Float64Array, br: Float64Array, bi: Float64Array, or: Float64Array, oi: Float64Array): void {
+    for (let k = 0; k < ar.length; k++) {
+        or[k] = ar[k]! * br[k]! - ai[k]! * bi[k]!
+        oi[k] = ar[k]! * bi[k]! + ai[k]! * br[k]!
+    }
+}

package/src/trailer/score/palette.ts

@@ -0,0 +1,188 @@
+import type { InstrumentDef } from './pattern.ts'
+
+/** one cycle of a wave from its harmonic levels (the fundamental first), for an instrument's `wave` */
+export function additive(levels: number[], samples = 64): number[] {
+    return Array.from({ length: samples }, (_, i) =>
+        levels.reduce((sum, level, k) => sum + level * Math.sin((2 * Math.PI * (k + 1) * i) / samples), 0),
+    )
+}
+
+// the default instrument palette; a score spreads one and overrides what it needs: `lead: { ...INST.lead, duty: 0.25 }`.
+// With no `export const instruments` in its code, a score plays these
+export const INST = {
+    lead: {
+        osc: 'pulse',
+        duty: 0.5,
+        vol: 0.4,
+        env: { a: 0.015, d: 0.15, s: 0.65, r: 0.1 },
+        vibrato: { delay: 0.18, depth: 0.12, rate: 5.5 },
+        reverb: 0.2,
+    },
+    lead25: {
+        osc: 'pulse',
+        duty: 0.25,
+        vol: 0.38,
+        env: { a: 0.015, d: 0.12, s: 0.6, r: 0.1 },
+        vibrato: { delay: 0.2, depth: 0.12, rate: 5.5 },
+        reverb: 0.2,
+    },
+    flute: {
+        osc: 'triangle',
+        vol: 0.55,
+        env: { a: 0.03, d: 0.2, s: 0.75, r: 0.15 },
+        vibrato: { delay: 0.25, depth: 0.15, rate: 5 },
+        reverb: 0.35,
+    },
+    ocarina: {
+        osc: 'triangle',
+        vol: 0.5,
+        env: { a: 0.045, d: 0.2, s: 0.8, r: 0.2 },
+        vibrato: { delay: 0.3, depth: 0.12, rate: 4.8 },
+        reverb: 0.35,
+    },
+    // odd harmonics, as a clarinet's
+    reed: {
+        osc: 'wave',
+        wave: additive([1, 0.05, 0.45, 0.04, 0.2, 0.02, 0.08]),
+        tone: 2600,
+        vol: 0.4,
+        env: { a: 0.03, d: 0.2, s: 0.75, r: 0.14 },
+        vibrato: { delay: 0.3, depth: 0.1, rate: 5 },
+        reverb: 0.3,
+    },
+    // a soft electric piano: a round body, a touch of the fourth harmonic for the tine
+    keys: {
+        osc: 'wave',
+        wave: additive([1, 0.4, 0.1, 0.14, 0.03]),
+        vol: 0.34,
+        env: { a: 0.004, d: 0.55, s: 0.1, r: 0.3 },
+        reverb: 0.3,
+    },
+    glock: {
+        osc: 'wave',
+        wave: additive([1, 0, 0, 0.25]),
+        vol: 0.3,
+        env: { a: 0.002, d: 0.9, s: 0, r: 0.6 },
+        reverb: 0.45,
+    },
+    cello: {
+        osc: 'saw',
+        tone: 1500,
+        vol: 0.26,
+        env: { a: 0.09, d: 0.3, s: 0.85, r: 0.3 },
+        detune: 7,
+        unison: 2,
+        vibrato: { delay: 0.35, depth: 0.1, rate: 5 },
+        reverb: 0.35,
+    },
+    bell: { osc: 'sine', vol: 0.4, env: { a: 0.002, d: 0.6, s: 0.1, r: 0.5 }, reverb: 0.4 },
+    pluck: { osc: 'pulse', duty: 0.125, vol: 0.3, env: { a: 0.002, d: 0.12, s: 0.15, r: 0.05 }, reverb: 0.2 },
+    arp: { osc: 'pulse', duty: 0.25, vol: 0.22, env: { a: 0.002, d: 0.08, s: 0.3, r: 0.03 }, pan: 0.25, reverb: 0.15 },
+    harmony: {
+        osc: 'pulse',
+        duty: 0.25,
+        vol: 0.28,
+        env: { a: 0.01, d: 0.15, s: 0.55, r: 0.1 },
+        pan: -0.3,
+        reverb: 0.25,
+    },
+    pad: {
+        osc: 'saw',
+        vol: 0.16,
+        env: { a: 0.35, d: 0.4, s: 0.7, r: 0.6 },
+        detune: 8,
+        unison: 2,
+        filter: { type: 'lowpass', freq: 1400, q: 0.7 },
+        reverb: 0.5,
+    },
+    strings: {
+        osc: 'saw',
+        vol: 0.2,
+        env: { a: 0.12, d: 0.3, s: 0.8, r: 0.3 },
+        detune: 6,
+        unison: 2,
+        filter: { type: 'lowpass', freq: 2600, q: 0.8 },
+        vibrato: { delay: 0.3, depth: 0.08, rate: 5 },
+        reverb: 0.4,
+    },
+    brass: {
+        osc: 'saw',
+        vol: 0.3,
+        env: { a: 0.03, d: 0.2, s: 0.7, r: 0.12 },
+        filter: { type: 'lowpass', freq: 2200, q: 1.2 },
+        vibrato: { delay: 0.25, depth: 0.1, rate: 5.5 },
+        reverb: 0.25,
+    },
+    bass: { osc: 'triangle', vol: 0.65, env: { a: 0.002, d: 0.06, s: 0.9, r: 0.05 } },
+    bassPulse: {
+        osc: 'pulse',
+        duty: 0.5,
+        vol: 0.3,
+        env: { a: 0.002, d: 0.1, s: 0.7, r: 0.04 },
+        filter: { type: 'lowpass', freq: 900 },
+    },
+    bassSaw: {
+        osc: 'saw',
+        vol: 0.32,
+        env: { a: 0.002, d: 0.12, s: 0.6, r: 0.05 },
+        filter: { type: 'lowpass', freq: 700, q: 2 },
+    },
+    kick: {
+        osc: 'sine',
+        vol: 0.75,
+        env: { a: 0, d: 0.16, s: 0, r: 0.03 },
+        sweep: { semis: -24, time: 0.07 },
+        pitch: 52,
+    },
+    snare: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.35,
+        env: { a: 0, d: 0.12, s: 0, r: 0.04 },
+        filter: { type: 'bandpass', freq: 1800, q: 0.8 },
+        reverb: 0.15,
+    },
+    hat: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.1,
+        env: { a: 0, d: 0.03, s: 0, r: 0.012 },
+        filter: { type: 'highpass', freq: 6500 },
+    },
+    openhat: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.09,
+        env: { a: 0, d: 0.18, s: 0, r: 0.06 },
+        filter: { type: 'highpass', freq: 5500 },
+    },
+    crash: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.18,
+        env: { a: 0, d: 0.9, s: 0, r: 0.3 },
+        filter: { type: 'highpass', freq: 4000 },
+        reverb: 0.3,
+    },
+    tom: { osc: 'sine', vol: 0.55, env: { a: 0, d: 0.18, s: 0, r: 0.05 }, sweep: { semis: -7, time: 0.15 } },
+    shaker: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.08,
+        env: { a: 0.005, d: 0.04, s: 0, r: 0.01 },
+        filter: { type: 'highpass', freq: 8000 },
+    },
+    // a pure sine under the bass register, felt more than heard; play it in octave 1 or 2
+    sub: { osc: 'sine', vol: 0.7, env: { a: 0.01, d: 0.2, s: 0.85, r: 0.12 } },
+    clap: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.3,
+        env: { a: 0.002, d: 0.14, s: 0, r: 0.06 },
+        filter: { type: 'bandpass', freq: 1200, q: 1.4 },
+        reverb: 0.3,
+    },
+} satisfies Record<string, InstrumentDef>
+
+/** the drum kit letters most songs use */
+export const KIT = { k: 'kick', s: 'snare', h: 'hat', o: 'openhat', c: 'crash', x: 'shaker' }

package/src/trailer/score/pattern.ts

@@ -0,0 +1,91 @@
+// the score's note grammar and its instruments: one token a grid row, an instrument as plain data the synth plays.
+// Pure: no audio here (synth.ts renders)
+
+/** oscillator families: chiptune roots (pulse, wave, noise) plus the smoother modern ones */
+export type Osc = 'pulse' | 'saw' | 'triangle' | 'sine' | 'wave' | 'noise'
+
+export interface InstrumentDef {
+    osc: Osc
+    /** 0..1 */
+    vol: number
+    /** ADSR in seconds, sustain as a 0..1 level */
+    env: { a: number; d: number; s: number; r: number }
+    /** pulse only: duty cycle 0.05..0.95 */
+    duty?: number
+    /** wave only: one cycle of samples in -1..1, any length */
+    wave?: number[]
+    /** pulse, saw and wave: the frequency in Hz above which the harmonics fall away, default 3000; higher is brighter */
+    tone?: number
+    /** noise only: 'white' hiss or 'metal' (short period, pitched) */
+    noise?: 'white' | 'metal'
+    /** detune in cents, and extra unison voices spread by it */
+    detune?: number
+    unison?: number
+    filter?: { type: 'lowpass' | 'highpass' | 'bandpass'; freq: number; q?: number }
+    /** depth in semitones, rate in Hz, delay in seconds from the note start */
+    vibrato?: { delay: number; depth: number; rate: number }
+    /** portamento between consecutive notes, seconds */
+    glide?: number
+    /** -1 left .. 1 right */
+    pan?: number
+    /** 0..1 send to the score's reverb */
+    reverb?: number
+    /** pitch slide from each note start: `semis` over `time` seconds (kicks, toms, zaps) */
+    sweep?: { semis: number; time: number }
+    /** the midi note a drum letter plays this instrument at, default 60 */
+    pitch?: number
+}
+
+// one token a row, whitespace separated, '|' ignored:
+//   C4 C#4 Db4    note (octave 0..8)       .    hold the previous note
+//   -             silence                  k    drum letter (from `drums`)
+// zero length modifiers glued before a row token: `@lead:C4` switches instrument, `v8:C4` sets the volume 0..15
+// (15 = the instrument's vol) from that note on
+type Row = { kind: 'note'; midi: number } | { kind: 'hold' } | { kind: 'off' } | { kind: 'drum'; letter: string }
+
+export interface RowEvent {
+    row: Row
+    instrument?: string
+    vol?: number
+}
+
+const NOTE_RE = /^([A-G])([#b]?)(\d)$/
+const SEMI: Record<string, number> = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 }
+
+export function noteToMidi(token: string): number | null {
+    const m = NOTE_RE.exec(token)
+    if (!m) return null
+    const [, letter, acc, oct] = m
+    const base = SEMI[letter ?? '']
+    if (base === undefined || oct === undefined) return null
+    return 12 * (Number(oct) + 1) + base + (acc === '#' ? 1 : acc === 'b' ? -1 : 0)
+}
+
+export function midiToHz(midi: number): number {
+    return 440 * 2 ** ((midi - 69) / 12)
+}
+
+export function parsePattern(text: string, drums: Record<string, string> = {}): RowEvent[] {
+    const out: RowEvent[] = []
+    for (const raw of text.split(/\s+/)) {
+        if (raw === '' || raw === '|') continue
+        const parts = raw.split(':')
+        const body = parts.pop() ?? ''
+        const ev: RowEvent = { row: { kind: 'off' } }
+        for (const mod of parts) {
+            if (mod.startsWith('@')) ev.instrument = mod.slice(1)
+            else if (/^v\d{1,2}$/.test(mod)) ev.vol = Number(mod.slice(1))
+            else throw new Error(`pattern token "${raw}": unknown modifier "${mod}"`)
+        }
+        if (body === '.') ev.row = { kind: 'hold' }
+        else if (body === '-') ev.row = { kind: 'off' }
+        else if (drums[body] !== undefined) ev.row = { kind: 'drum', letter: body }
+        else {
+            const midi = noteToMidi(body)
+            if (midi === null) throw new Error(`pattern token "${raw}": not a note, a drum letter, '.' or '-'`)
+            ev.row = { kind: 'note', midi }
+        }
+        out.push(ev)
+    }
+    return out
+}