@onjmin/koe 1.0.2 → 1.0.4

package/README.md

@@ -5,7 +5,7 @@
 UTAU の oto.ini で定義された音源を `.koe` アーカイブに変換し、WebAssembly + AudioWorklet でリアルタイム再生・高品質再合成を行う。
 
 - [DEMO](https://onjmin.github.io/koe/demo) koeフォーマット作成もこちらで
-- [npm](https://www.npmjs.com/package/@onjmin/dtm)
+- [npm](https://www.npmjs.com/package/@onjmin/koe)
 
 ---
 
@@ -94,11 +94,13 @@ await fs.writeFile("voice.koe", buf);
 
 AudioWorklet を使った連接合成エンジン。`koe-worklet.js` を同じオリジンから配信する必要がある。
 
+GitHub Pages にホストされているファイルをそのまま使える:
+
 ```ts
 import { KoeEngine } from "@onjmin/koe";
 
 const engine = new KoeEngine({
-  workletUrl: "/koe-worklet.js", // dist/koe-worklet.js を配信する
+  workletUrl: "https://onjmin.github.io/koe/demo/koe-worklet.js",
 });
 
 // .koe ファイルをロード (Blob でも URL でも可)
@@ -163,11 +165,15 @@ bank.has("a"); // boolean
 
 OpenUtau の worldline WASM で F0 分析・再合成を行う。`worldline.js` と `worldline.wasm` を配信する必要がある。
 
+GitHub Pages にホストされているファイルをそのまま使える:
+
 ```ts
 import { VoiceBank, Worldline, leadInFromEntry } from "@onjmin/koe";
 
 const bank = await VoiceBank.load("/voice.koe");
-const wl   = await Worldline.load({ scriptUrl: "/world/worldline.js" });
+const wl   = await Worldline.load({
+  scriptUrl: "https://onjmin.github.io/koe/demo/world/worldline.js",
+});
 
 const alias = "a";
 const entry = bank.manifest.phonemes[alias];

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,98 @@ 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;
+
 /**
  * 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 +168,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 +228,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}.
@@ -155,6 +270,7 @@ type WorldlineFactory = (opts?: {
 }) => Promise<WorldlineWasm>;
 declare global {
     var WorldlineModule: WorldlineFactory | undefined;
+    var importScripts: ((...urls: string[]) => void) | undefined;
 }
 interface WorldlineLoadOptions {
     /**
@@ -217,7 +333,13 @@ declare class Worldline {
     private wasm;
     readonly sampleRate = 48000;
     private constructor();
-    /** Load + instantiate the worldline WASM module (deduped per scriptUrl). */
+    /**
+     * Load + instantiate the worldline WASM module (deduped per scriptUrl).
+     *
+     * Works on the main thread (loads via `<script>`) and inside a classic Web
+     * Worker (loads via `importScripts`), so the heavy synthesis can run
+     * off-thread. The matching `worldline.wasm` is fetched next to scriptUrl.
+     */
     static load(options: WorldlineLoadOptions): Promise<Worldline>;
     /**
      * Render one note to Float32 PCM at 48 kHz.
@@ -235,115 +357,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)