@onjmin/koe 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -1,3 +1,20 @@
+/**
+ * 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.
+ *
+ * Layout:
+ *   char[8]  "FREQ0003"
+ *   int32    hopSize
+ *   float64  averageF0   ← the recorded pitch in Hz
+ *   byte[16] (blank)
+ *   int32    length
+ *   { float64 f0, float64 amp } × length
+ */
+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;
+
 /**
  * One phoneme, already trimmed to its usable oto region.
  * Sample 0 corresponds to the oto `offset` (left blank); everything before it
@@ -36,6 +53,113 @@ interface NoteEvent {
     duration: number;
 }
 
+interface OtoEntry {
+    /** Source WAV filename */
+    wav: string;
+    /** Phoneme alias */
+    alias: string;
+    /** Left blank — offset from WAV start (ms) */
+    offset: number;
+    /** Consonant portion end from offset (ms) */
+    consonant: number;
+    /** Right blank — negative = from WAV end, positive = from offset (ms) */
+    cutoff: number;
+    /** Preutterance from offset (ms) */
+    pre: number;
+    /** Overlap / crossfade region (ms) */
+    overlap: number;
+}
+/**
+ * Parse oto.ini content (already decoded to UTF-8 string).
+ * Silently skips malformed lines.
+ */
+declare function parseOto(content: string): OtoEntry[];
+
+interface PackInput {
+    oto: OtoEntry;
+    /** Full normalized 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;
+}
+interface PackOutput {
+    manifest: Manifest;
+    /** Raw PCM blob — Int16 / 48kHz / mono */
+    bin: ArrayBuffer;
+}
+interface TrimmedPhoneme {
+    /** PCM trimmed to the oto region [offset, cutoff] */
+    pcm: Int16Array;
+    /** Manifest params relative to the trimmed start (sample 0 = oto offset) */
+    entry: Omit<PhonemeEntry, "offset">;
+}
+/**
+ * Cut the full WAV PCM down to its usable oto region and recompute parameters
+ * relative to the trimmed start.
+ *
+ * UTAU oto.ini values are all in ms and measured from `offset` (the left blank),
+ * except `cutoff` (right blank):
+ *   - cutoff >= 0 : measured from the END of the file
+ *   - cutoff <  0 : region length from offset = |cutoff|
+ *
+ * After trimming, sample 0 == oto offset, so pre/overlap/consonant carry over
+ * unchanged (just converted to samples), and the slice length is the region end.
+ */
+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.
+ * Duplicate aliases are silently overwritten by the later entry.
+ */
+declare function pack(inputs: PackInput[], referencePitch?: number): PackOutput;
+
+/** Parse a note name like "E4", "G#4", "Db5" → frequency in Hz (null if invalid). */
+declare function noteNameToHz(name: string): number | null;
+/** Recorded pitch encoded in a multi-pitch alias suffix: "a い_E4" → 329.63 Hz. */
+declare function pitchFromAliasSuffix(alias: string): number | null;
+/**
+ * Estimate the fundamental frequency (Hz) of a voiced region by normalized
+ * autocorrelation. Returns 0 when no clear pitch is found (unvoiced consonant,
+ * silence, or a region too short to analyse).
+ *
+ * The signal is decimated to a lower analysis rate for speed; f0 below ~700 Hz
+ * is well within the resulting Nyquist limit. A parabolic interpolation around
+ * the best lag gives sub-sample (sub-semitone) accuracy.
+ */
+declare function detectF0(pcm: Int16Array, start: number, end: number): number;
+
+interface WavData {
+    sampleRate: number;
+    channels: number;
+    /** Normalized samples in [-1, 1], interleaved if multi-channel */
+    samples: Float32Array;
+}
+/** Parse a WAV file from an ArrayBuffer. Supports PCM 8/16/24-bit and IEEE float 32-bit. */
+declare function parseWav(buf: ArrayBuffer): WavData;
+/** Mix down to mono by averaging all channels. */
+declare function toMono(wav: WavData): WavData;
+/** Linear interpolation resample to targetRate. Expects mono input. */
+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. */
+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
@@ -59,6 +183,7 @@ declare class VoiceBank {
      * @param koe a Blob/File of the .koe archive, or a URL (served with Range support)
      */
     static load(koe: Blob | string): Promise<VoiceBank>;
+    private static fromBlob;
     /** True if the bank contains a phoneme under this alias. */
     has(phoneme: string): boolean;
     /**
@@ -118,6 +243,11 @@ declare class KoeEngine {
     stop(): void;
     /** Resume the AudioContext if suspended (e.g. after autoplay block). */
     resume(): Promise<void>;
+    /**
+     * Tear down the worklet node and close the AudioContext, releasing the audio
+     * hardware. The engine cannot be reused afterwards — create a new one.
+     */
+    dispose(): Promise<void>;
     /**
      * Read a phoneme's raw PCM and return it as a Float64Array normalised to
      * [-1, 1]. Convenience that forwards to the underlying {@link VoiceBank}.
@@ -168,14 +298,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}. */
@@ -184,6 +329,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;
@@ -242,115 +405,6 @@ declare class Worldline {
     renderNote(params: RenderNoteParams): Float32Array | null;
 }
 
-interface OtoEntry {
-    /** Source WAV filename */
-    wav: string;
-    /** Phoneme alias */
-    alias: string;
-    /** Left blank — offset from WAV start (ms) */
-    offset: number;
-    /** Consonant portion end from offset (ms) */
-    consonant: number;
-    /** Right blank — negative = from WAV end, positive = from offset (ms) */
-    cutoff: number;
-    /** Preutterance from offset (ms) */
-    pre: number;
-    /** Overlap / crossfade region (ms) */
-    overlap: number;
-}
-/**
- * Parse oto.ini content (already decoded to UTF-8 string).
- * Silently skips malformed lines.
- */
-declare function parseOto(content: string): OtoEntry[];
-
-interface WavData {
-    sampleRate: number;
-    channels: number;
-    /** Normalized samples in [-1, 1], interleaved if multi-channel */
-    samples: Float32Array;
-}
-/** Parse a WAV file from an ArrayBuffer. Supports PCM 8/16/24-bit and IEEE float 32-bit. */
-declare function parseWav(buf: ArrayBuffer): WavData;
-/** Mix down to mono by averaging all channels. */
-declare function toMono(wav: WavData): WavData;
-/** Linear interpolation resample to targetRate. Expects mono input. */
-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. */
-declare function normalizePcm(buf: ArrayBuffer): Int16Array;
-
-interface PackInput {
-    oto: OtoEntry;
-    /** Full normalized 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;
-}
-interface PackOutput {
-    manifest: Manifest;
-    /** Raw PCM blob — Int16 / 48kHz / mono */
-    bin: ArrayBuffer;
-}
-interface TrimmedPhoneme {
-    /** PCM trimmed to the oto region [offset, cutoff] */
-    pcm: Int16Array;
-    /** Manifest params relative to the trimmed start (sample 0 = oto offset) */
-    entry: Omit<PhonemeEntry, "offset">;
-}
-/**
- * Cut the full WAV PCM down to its usable oto region and recompute parameters
- * relative to the trimmed start.
- *
- * UTAU oto.ini values are all in ms and measured from `offset` (the left blank),
- * except `cutoff` (right blank):
- *   - cutoff >= 0 : measured from the END of the file
- *   - cutoff <  0 : region length from offset = |cutoff|
- *
- * After trimming, sample 0 == oto offset, so pre/overlap/consonant carry over
- * unchanged (just converted to samples), and the slice length is the region end.
- */
-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.
- * Duplicate aliases are silently overwritten by the later entry.
- */
-declare function pack(inputs: PackInput[], referencePitch?: number): PackOutput;
-
-/** Parse a note name like "E4", "G#4", "Db5" → frequency in Hz (null if invalid). */
-declare function noteNameToHz(name: string): number | null;
-/** Recorded pitch encoded in a multi-pitch alias suffix: "a い_E4" → 329.63 Hz. */
-declare function pitchFromAliasSuffix(alias: string): number | null;
-/**
- * Estimate the fundamental frequency (Hz) of a voiced region by normalized
- * autocorrelation. Returns 0 when no clear pitch is found (unvoiced consonant,
- * silence, or a region too short to analyse).
- *
- * The signal is decimated to a lower analysis rate for speed; f0 below ~700 Hz
- * is well within the resulting Nyquist limit. A parabolic interpolation around
- * the best lag gives sub-sample (sub-semitone) accuracy.
- */
-declare function detectF0(pcm: Int16Array, start: number, end: number): number;
-
-/**
- * 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.
- *
- * Layout:
- *   char[8]  "FREQ0003"
- *   int32    hopSize
- *   float64  averageF0   ← the recorded pitch in Hz
- *   byte[16] (blank)
- *   int32    length
- *   { float64 f0, float64 amp } × length
- */
-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;
-
 /**
  * Koe Archive Format (.koe)
  *   [4B] magic 'KOE\0' (big-endian)
@@ -366,4 +420,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 { 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, type ZipFile, detectF0, frqFileName, leadInFromEntry, normalizePcm, noteNameToHz, pack, packKoe, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pcmBase, pitchFromAliasSuffix, resample, samplesToMs, toInt16, toMono, trimToOto, unzipToFileMap };