@onjmin/koe 1.0.5 → 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,7 +180,27 @@ 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. */
@@ -203,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.
  *
@@ -237,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). */
@@ -420,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, type ZipFile, detectF0, frqFileName, leadInFromEntry, normalizePcm, noteNameToHz, pack, packKoe, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pcmBase, pitchFromAliasSuffix, resample, samplesToMs, toInt16, toMono, trimToOto, unzipToFileMap };
+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 };

package/dist/index.js

@@ -1,12 +1,50 @@
 // src/converter/frq.ts
-function parseFrqAverageF0(buffer) {
-  if (buffer.byteLength < 20) return null;
+var HEADER_SIZE = 40;
+function parseFrq(buffer) {
+  if (buffer.byteLength < HEADER_SIZE) return null;
   const view = new DataView(buffer);
   let header = "";
   for (let i = 0; i < 8; i++) header += String.fromCharCode(view.getUint8(i));
   if (header !== "FREQ0003") return null;
-  const avg = view.getFloat64(12, true);
-  return Number.isFinite(avg) && avg > 0 ? avg : null;
+  const hopSize = view.getInt32(8, true);
+  const averageF0 = view.getFloat64(12, true);
+  const declared = view.getInt32(36, true);
+  const available = Math.floor((buffer.byteLength - HEADER_SIZE) / 16);
+  const length = Math.max(0, Math.min(declared, available));
+  const f0 = new Float64Array(length);
+  const amp = new Float64Array(length);
+  for (let i = 0; i < length; i++) {
+    const p = HEADER_SIZE + i * 16;
+    f0[i] = view.getFloat64(p, true);
+    amp[i] = view.getFloat64(p + 8, true);
+  }
+  return {
+    hopSize: hopSize > 0 ? hopSize : 256,
+    averageF0: Number.isFinite(averageF0) && averageF0 > 0 ? averageF0 : 0,
+    f0,
+    amp
+  };
+}
+function frqAverageF0InRange(frq, startMs, endMs, sourceRate) {
+  if (!(sourceRate > 0) || frq.f0.length === 0) return 0;
+  const perFrameMs = frq.hopSize / sourceRate * 1e3;
+  if (!(perFrameMs > 0)) return 0;
+  const first = Math.max(0, Math.floor(startMs / perFrameMs));
+  const last = Math.min(frq.f0.length - 1, Math.ceil(endMs / perFrameMs));
+  let num = 0;
+  let den = 0;
+  for (let i = first; i <= last; i++) {
+    const hz = frq.f0[i];
+    if (!(hz > 0)) continue;
+    const w = frq.amp[i] > 0 ? frq.amp[i] : 1;
+    num += hz * w;
+    den += w;
+  }
+  return den > 0 ? num / den : 0;
+}
+function parseFrqAverageF0(buffer) {
+  const frq = parseFrq(buffer);
+  return frq && frq.averageF0 > 0 ? frq.averageF0 : null;
 }
 function frqFileName(wavName) {
   const dot = wavName.lastIndexOf(".");
@@ -94,11 +132,25 @@ function msToSamples(ms) {
   return Math.round(ms / 1e3 * TARGET_RATE);
 }
 var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+function otoRegion(pcmLength, oto) {
+  const start = clamp(msToSamples(oto.offset), 0, pcmLength);
+  const end = oto.cutoff < 0 ? clamp(start + msToSamples(-oto.cutoff), start, pcmLength) : clamp(pcmLength - msToSamples(oto.cutoff), start, pcmLength);
+  return { start, end };
+}
+function centerSlice(slice) {
+  const out = new Int16Array(slice.length);
+  if (slice.length === 0) return out;
+  let sum = 0;
+  for (let i = 0; i < slice.length; i++) sum += slice[i];
+  const dc = Math.round(sum / slice.length);
+  for (let i = 0; i < slice.length; i++) {
+    out[i] = clamp(slice[i] - dc, -32768, 32767);
+  }
+  return out;
+}
 function trimToOto(pcm, oto, recordedPitch = 0) {
-  const full = pcm.length;
-  const start = clamp(msToSamples(oto.offset), 0, full);
-  const end = oto.cutoff < 0 ? clamp(start + msToSamples(-oto.cutoff), start, full) : clamp(full - msToSamples(oto.cutoff), start, full);
-  const slice = pcm.subarray(start, end);
+  const { start, end } = otoRegion(pcm.length, oto);
+  const slice = centerSlice(pcm.subarray(start, end));
   const length = slice.length;
   const pre = clamp(msToSamples(oto.pre), 0, length);
   const overlap = clamp(msToSamples(oto.overlap), 0, length);
@@ -262,11 +314,14 @@ function toInt16(samples) {
   }
   return out;
 }
-function normalizePcm(buf) {
+function readWavPcm48k(buf) {
   const wav = parseWav(buf);
   const mono = toMono(wav);
   const resampled = resample(mono, 48e3);
-  return toInt16(resampled.samples);
+  return { pcm: toInt16(resampled.samples), sourceRate: wav.sampleRate };
+}
+function normalizePcm(buf) {
+  return readWavPcm48k(buf).pcm;
 }
 function readFourCC(view, pos) {
   return String.fromCharCode(
@@ -1045,13 +1100,34 @@ var KoeEngine = class {
     this.pending.set(name, load);
     return load;
   }
-  /** Stop current playback, preload the phonemes for `notes`, then queue them. */
-  async play(notes) {
+  /**
+   * 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}.
+   */
+  async play(notes, options = {}) {
     if (!this.node) throw new Error("KoeEngine: call load() before play()");
     this.node.port.postMessage({ type: "stop" });
     const names = [...new Set(notes.map((n) => n.phoneme))].filter(Boolean);
     await Promise.all(names.map((n) => this.ensurePhoneme(n)));
-    this.node.port.postMessage({ type: "play", notes });
+    const leadIn = options.leadIn === true;
+    this.node.port.postMessage({ type: "play", notes, leadIn });
+    return leadIn ? this.leadInSamples(notes) : 0;
+  }
+  /**
+   * Output samples the first note's lead-in occupies ahead of its beat —
+   * mirrors what the worklet does with `leadIn`, so callers can compensate.
+   */
+  leadInSamples(notes) {
+    const first = notes[0];
+    const m = this.bank?.manifest;
+    if (!first || !m || first.phoneme === "") return 0;
+    const entry = Object.hasOwn(m.phonemes, first.phoneme) ? m.phonemes[first.phoneme] : void 0;
+    if (!entry || entry.length <= 0) return 0;
+    const recorded = entry.pitch || m.referencePitch || first.pitch || 1;
+    const stepRate = first.pitch / recorded;
+    return stepRate > 0 ? entry.pre / stepRate : 0;
   }
   /** Stop playback and clear the queue. */
   stop() {
@@ -1304,18 +1380,22 @@ export {
   WORLDLINE_SAMPLE_RATE,
   Worldline,
   detectF0,
+  frqAverageF0InRange,
   frqFileName,
   leadInFromEntry,
   normalizePcm,
   noteNameToHz,
+  otoRegion,
   pack,
   packKoe,
+  parseFrq,
   parseFrqAverageF0,
   parseKoeHeader,
   parseOto,
   parseWav,
   pcmBase,
   pitchFromAliasSuffix,
+  readWavPcm48k,
   resample,
   samplesToMs,
   toInt16,