@onjmin/koe 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -1,16 +1,44 @@
 /**
  * UTAU `.frq` frequency-analysis files (FREQ0003). The same format OpenUtau
- * reads: an 8-byte header, hop size, then the average fundamental frequency of
- * the recording — exactly the reference pitch we need for correct resampling.
+ * reads: an 8-byte header, hop size, the average fundamental frequency of the
+ * whole recording, then a per-frame f0 / amplitude curve.
  *
  * Layout:
  *   char[8]  "FREQ0003"
- *   int32    hopSize
- *   float64  averageF0   ← the recorded pitch in Hz
+ *   int32    hopSize      ← in ORIGINAL WAV samples
+ *   float64  averageF0    ← whole-file average in Hz
  *   byte[16] (blank)
  *   int32    length
  *   { float64 f0, float64 amp } × length
  */
+interface FrqData {
+    /** Analysis hop in samples of the ORIGINAL wav (not the 48 kHz conversion) */
+    hopSize: number;
+    /** Whole-file average f0 in Hz, as stored in the header */
+    averageF0: number;
+    /** Per-frame f0 in Hz — 0 where the analyser found no clear pitch */
+    f0: Float64Array;
+    /** Per-frame amplitude, parallel to {@link f0} */
+    amp: Float64Array;
+}
+/** Parse a `.frq` file, including the per-frame curve. Null if not FREQ0003. */
+declare function parseFrq(buffer: ArrayBuffer): FrqData | null;
+/**
+ * Average f0 over the voiced frames covering a time span of the recording.
+ *
+ * The header's whole-file average includes leading silence and unvoiced
+ * consonants, so it can sit well away from the pitch actually sounding in the
+ * region a note is built from. Playback resamples the whole phoneme by one
+ * scalar ratio, so an inaccurate value both detunes the note and makes two
+ * crossfading notes drift apart in phase across the overlap — a 1% error at
+ * 233 Hz drifts ~25° over a 30 ms overlap and ~84° over 100 ms.
+ *
+ * @param startMs / endMs  span within the ORIGINAL recording, in milliseconds
+ * @param sourceRate       sample rate of the original WAV the frq describes
+ * @returns Hz, or 0 when the span holds no voiced frames
+ */
+declare function frqAverageF0InRange(frq: FrqData, startMs: number, endMs: number, sourceRate: number): number;
+/** Whole-file average f0 in Hz from a `.frq` file, or null. */
 declare function parseFrqAverageF0(buffer: ArrayBuffer): number | null;
 /** Map a WAV filename to its sibling frq filename: "あ.wav" → "あ_wav.frq". */
 declare function frqFileName(wavName: string): string;
@@ -77,7 +105,7 @@ declare function parseOto(content: string): OtoEntry[];
 
 interface PackInput {
     oto: OtoEntry;
-    /** Full normalized PCM of the source WAV (48kHz / 16bit / mono) */
+    /** Full PCM of the source WAV (48kHz / 16bit / mono) */
     pcm: Int16Array;
     /** Known recorded pitch in Hz (e.g. from the .frq file). 0/undefined → auto-detect. */
     recordedPitch?: number;
@@ -93,6 +121,16 @@ interface TrimmedPhoneme {
     /** Manifest params relative to the trimmed start (sample 0 = oto offset) */
     entry: Omit<PhonemeEntry, "offset">;
 }
+/**
+ * Resolve an oto entry's usable region within the full 48 kHz PCM.
+ *
+ * Shared with the converter CLI, which needs the same bounds to look up the
+ * region's local f0 in a `.frq` curve.
+ */
+declare function otoRegion(pcmLength: number, oto: OtoEntry): {
+    start: number;
+    end: number;
+};
 /**
  * Cut the full WAV PCM down to its usable oto region and recompute parameters
  * relative to the trimmed start.
@@ -107,8 +145,8 @@ interface TrimmedPhoneme {
  */
 declare function trimToOto(pcm: Int16Array, oto: OtoEntry, recordedPitch?: number): TrimmedPhoneme;
 /**
- * Pack normalized PCM phonemes into voice.bin + manifest.json.
- * Each phoneme is trimmed to its oto region first.
+ * Pack phonemes into voice.bin + manifest.json.
+ * Each phoneme is trimmed to its oto region and DC-centred first.
  * Duplicate aliases are silently overwritten by the later entry.
  */
 declare function pack(inputs: PackInput[], referencePitch?: number): PackOutput;
@@ -142,9 +180,44 @@ declare function toMono(wav: WavData): WavData;
 declare function resample(wav: WavData, targetRate: number): WavData;
 /** Convert Float32 [-1,1] samples to Int16 PCM. */
 declare function toInt16(samples: Float32Array): Int16Array;
-/** Normalize then convert a WAV to 48kHz/16bit/mono Int16 PCM. */
+/**
+ * Decode a WAV to 48kHz/16bit/mono Int16 PCM, reporting the source sample rate.
+ *
+ * The rate is needed to index a sibling `.frq` file, whose analysis hop is
+ * counted in ORIGINAL samples — see {@link frqAverageF0InRange}.
+ *
+ * Note this does not touch amplitude: peak levels are carried through
+ * unchanged, so a bank's own relative loudness between phonemes is preserved
+ * (UTAU's engine instead normalises each region to −6 dBFS, which is why its
+ * イ/エ段 and 語尾 samples come out louder than recorded).
+ */
+declare function readWavPcm48k(buf: ArrayBuffer): {
+    pcm: Int16Array;
+    sourceRate: number;
+};
+/**
+ * Convert a WAV to 48kHz/16bit/mono Int16 PCM.
+ *
+ * @deprecated Misnomer — this never normalised amplitude. Use
+ * {@link readWavPcm48k}, which also reports the source sample rate.
+ */
 declare function normalizePcm(buf: ArrayBuffer): Int16Array;
 
+/** Minimal file-like handle so zip entries can stand in for `File` objects. */
+interface ZipFile {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Extracts a zip archive into a flat path → file map, mirroring the shape of
+ * `webkitdirectory` file lists so the converter can treat both sources the same.
+ *
+ * Many UTAU voicebank zips are packed on Windows without the UTF-8 flag, so
+ * entry names are Shift_JIS bytes. fflate decodes those as latin1 (1 byte =
+ * 1 code point) rather than mangling them, so we can losslessly recover the
+ * original bytes and re-decode with the right encoding per entry.
+ */
+declare function unzipToFileMap(data: ArrayBuffer): Promise<Record<string, ZipFile>>;
+
 /**
  * Read-only access to a .koe voice bank: its manifest plus per-phoneme PCM,
  * fetched on demand (Blob slice or HTTP Range). The full bank is never held in
@@ -188,6 +261,21 @@ interface KoeEngineOptions {
     /** URL to koe-worklet.js. Defaults to './koe-worklet.js'. */
     workletUrl?: string;
 }
+interface PlayOptions {
+    /**
+     * Play the first note's lead-in (its consonant / preutterance region) instead
+     * of skipping straight to the vowel.
+     *
+     * Every note but the first gets its lead-in from the crossfade with the note
+     * before it. The first note has no predecessor, so the lead-in has to come
+     * from somewhere: with `leadIn` the phrase starts one preutterance EARLIER
+     * relative to its beats, and {@link KoeEngine.play} returns that offset in
+     * samples so a sequencer can schedule around it. Left off (the default), the
+     * first note keeps its beat exactly but opens on its vowel, dropping the
+     * consonant.
+     */
+    leadIn?: boolean;
+}
 /**
  * Main-thread API for the koe concatenative synthesis engine.
  *
@@ -222,8 +310,18 @@ declare class KoeEngine {
     load(koe: Blob | string): Promise<void>;
     /** Fetch one phoneme's PCM and deliver it to the worklet (deduped, cached). */
     private ensurePhoneme;
-    /** Stop current playback, preload the phonemes for `notes`, then queue them. */
-    play(notes: NoteEvent[]): Promise<void>;
+    /**
+     * Stop current playback, preload the phonemes for `notes`, then queue them.
+     *
+     * @returns the lead-in offset in samples — how far the first note's audio
+     *          starts ahead of its beat. 0 unless {@link PlayOptions.leadIn}.
+     */
+    play(notes: NoteEvent[], options?: PlayOptions): Promise<number>;
+    /**
+     * Output samples the first note's lead-in occupies ahead of its beat —
+     * mirrors what the worklet does with `leadIn`, so callers can compensate.
+     */
+    private leadInSamples;
     /** Stop playback and clear the queue. */
     stop(): void;
     /** Resume the AudioContext if suspended (e.g. after autoplay block). */
@@ -283,14 +381,29 @@ interface WorldlineLoadOptions {
      */
     scriptUrl: string;
 }
+/**
+ * A per-frame expression value: either a flat constant for the whole note, or
+ * a function evaluated once per 10ms WORLD frame for a custom curve (vibrato,
+ * portamento, scoop-in, humanize jitter, hand-drawn automation, …).
+ *
+ * `tMs` is elapsed time from the start of the rendered buffer (0 = includes
+ * the `preMs` lead-in), `totalMs` is the full rendered length (`preMs +
+ * durationMs`). Callers own all curve shaping — worldline itself has no
+ * opinion on what "vibrato" or "scoop" means, it just samples whatever
+ * function you give it once per frame.
+ */
+type CurveInput = number | ((tMs: number, totalMs: number) => number);
 interface RenderNoteParams {
     /**
      * Source phoneme PCM normalised to [-1, 1] (e.g. from
      * `VoiceBank.getPcm()` / `KoeEngine.getPcm()`).
      */
     pcm: Float64Array;
-    /** Target output pitch in Hz. */
-    pitch: number;
+    /**
+     * Target output pitch in Hz. Pass a function for vibrato, portamento,
+     * scoop-in, pitch-drift humanize, etc. — it is sampled once per 10ms frame.
+     */
+    pitch: CurveInput;
     /** Sustain / vowel duration in ms (the lead-in below is rendered on top). */
     durationMs: number;
     /** Preutterance / lead-in in ms — convert from {@link PhonemeEntry.pre}. */
@@ -299,6 +412,24 @@ interface RenderNoteParams {
     consonantMs: number;
     /** Reference tempo in BPM for worldline's internal timing. Default 120. */
     tempo?: number;
+    /**
+     * Formant/gender shift, 0-1. 0.5 (default) = unmodified. Below 0.5 skews
+     * toward a lower/thicker formant (older, huskier); above 0.5 toward a
+     * higher/thinner one (younger, brighter) — pitch itself is unaffected.
+     */
+    gender?: CurveInput;
+    /**
+     * Tension, 0-1. 0.5 (default) = neutral. Higher = tighter/more strained
+     * ("こぶし"-style push); lower = more relaxed/breathy-adjacent.
+     */
+    tension?: CurveInput;
+    /** Breathiness, 0-1. 0.5 (default) = neutral. Higher = airier/whispered. */
+    breathiness?: CurveInput;
+    /**
+     * Voicing ratio, 0-1. 1.0 (default) = fully voiced. Lower blends toward an
+     * unvoiced/falsetto-adjacent texture.
+     */
+    voicing?: CurveInput;
 }
 /** Convert a sample count at 48 kHz to milliseconds. */
 declare const samplesToMs: (samples: number) => number;
@@ -372,4 +503,4 @@ declare function parseKoeHeader(headerBytes: ArrayBuffer): {
 /** Byte offset where PCM data begins, given the JSON length. */
 declare const pcmBase: (jsonLength: number) => number;
 
-export { KoeEngine, type KoeEngineOptions, MIN_WORLDLINE_SAMPLES, type Manifest, type NoteEvent, type OtoEntry, type PackInput, type PackOutput, type PhonemeEntry, type RenderNoteParams, type TrimmedPhoneme, VoiceBank, WORLDLINE_SAMPLE_RATE, type WavData, Worldline, type WorldlineLoadOptions, detectF0, frqFileName, leadInFromEntry, normalizePcm, noteNameToHz, pack, packKoe, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pcmBase, pitchFromAliasSuffix, resample, samplesToMs, toInt16, toMono, trimToOto };
+export { type FrqData, KoeEngine, type KoeEngineOptions, MIN_WORLDLINE_SAMPLES, type Manifest, type NoteEvent, type OtoEntry, type PackInput, type PackOutput, type PhonemeEntry, type PlayOptions, type RenderNoteParams, type TrimmedPhoneme, VoiceBank, WORLDLINE_SAMPLE_RATE, type WavData, Worldline, type WorldlineLoadOptions, type ZipFile, detectF0, frqAverageF0InRange, frqFileName, leadInFromEntry, normalizePcm, noteNameToHz, otoRegion, pack, packKoe, parseFrq, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pcmBase, pitchFromAliasSuffix, readWavPcm48k, resample, samplesToMs, toInt16, toMono, trimToOto, unzipToFileMap };