@onjmin/koe 1.0.9 → 1.0.11

package/dist/index.d.ts

@@ -941,6 +941,12 @@ interface NjdNode {
 interface FeatureFrame {
     mora: string;
     pause: boolean;
+    /**
+     * For pause frames: the token that produced the pause (「。」「、」「？」, a
+     * space, a bracket…). Lets prosody rules pick a pause length per kind.
+     * Absent on pauses synthesised from a reading string.
+     */
+    punctuation?: string;
     accent_phrase_position?: number;
     accent_phrase_length?: number;
     accent_nucleus?: number;
@@ -952,6 +958,13 @@ interface FeatureFrame {
     pos?: string;
     pos_group1?: string;
 }
+/** Pause kinds a punctuation token maps to (see {@link pauseKind}). */
+type PauseKind = "sentence" | "clause" | "space";
+/**
+ * Classify the token that produced a pause: sentence-final punctuation, a
+ * clause comma, or whitespace / anything else (brackets, symbols).
+ */
+declare function pauseKind(punctuation: string | undefined): PauseKind;
 declare function analyze(nodes: NjdNode[]): {
     reading: string;
     features: FeatureFrame[];
@@ -997,6 +1010,14 @@ interface HtsProsody {
      * (Open JTalk's upper-case `I`/`U`, e.g. the "su" in "desu"). Pauses are false.
      */
     devoiced: boolean[];
+    /**
+     * Per feature-frame HTS consonant length in ms (onset of the mora's first
+     * phone to its vowel onset); 0 for pauses and vowel-initial morae. The
+     * planner uses it to end the previous vowel where the consonant starts.
+     */
+    consonantMs: number[];
+    /** Per feature-frame flag: the mora starts with an unvoiced consonant (k, s, t, h, p …). */
+    unvoicedOnset: boolean[];
     /**
      * Optional per feature-frame linear gain (1 = unity) applied to the units of
      * that mora on top of UtauTTS's own volume; filled by `shapeProsody`.
@@ -1018,11 +1039,29 @@ interface AlignHtsOptions {
      */
     kneeCents?: number;
     maxCents?: number;
+    /**
+     * Longest unvoiced run (ms) that is bridged by interpolating F0 from the
+     * voiced frame before it to the one after it. Unvoiced consonants (30–120
+     * ms) are bridged; a longer run is a devoiced vowel plus a pause plus the
+     * next phrase's consonant, and a ramp across it would carry the *next*
+     * phrase's onset pitch back onto the devoiced mora (「ございます」 rendered
+     * with a rising 「す」, since UTAU renders devoiced vowels voiced). Such
+     * runs hold the previous value over their first half and the following
+     * value over their second half. Default 120.
+     */
+    unvoicedBridgeMs?: number;
 }
 /**
  * Align HTS phoneme timing and F0 to the mora/pause sequence in `features`
  * (from `openjtalkAnalyze`). Returns null when the two mora sequences cannot
  * be matched, in which case the caller should fall back to the TCN contour.
+ *
+ * Mora boundaries are the HTS *vowel onsets*: a mora's duration runs from its
+ * vowel onset to the next mora's vowel onset (so the next consonant belongs to
+ * the end of this mora), which is how UtauTTS places units (note start =
+ * vowel onset, consonant pre-uttered). Cutting at consonant onsets instead
+ * would delay the F0 contour by one consonant (40–120 ms) relative to the
+ * rendered vowels and shift every accent fall onto the following mora.
  */
 declare function alignHtsProsody(frames: HtsProsodyFrames, features: FeatureFrame[], options?: AlignHtsOptions): HtsProsody | null;
 
@@ -1035,15 +1074,43 @@ declare function alignHtsProsody(frames: HtsProsodyFrames, features: FeatureFram
  *  - question rise: a sentence ending in 「？」 gets at least a minimum rise
  *    on its last mora; Open JTalk's interrogative label flag already makes
  *    tohoku-f01 rise, so this only tops up voices/sentences that do not
- *  - energy envelope: loudness follows pitch (accented morae louder, phrase
- *    ends softer), which a plain unit concatenation renders flat
+ *  - energy envelope (off by default, see `energyDbPerSemitone`): loudness
+ *    follows pitch per mora; the renderer now does this smoothly per frame
  *  - devoiced vowels: morae HTS predicted as devoiced (「です」「ます」…) are
  *    attenuated so the voiced sample does not shout a vowel the speaker
  *    would whisper
+ *  - pause length by punctuation: the HTS voice was trained on single
+ *    sentences, so it gives 「。」 and 「、」 the same ~300 ms; a reading voice
+ *    pauses roughly twice as long at a sentence end
+ *  - duration contrast: HTS durations are variance-shrunk (over-smoothed);
+ *    stretching them around the utterance mean restores some of the
+ *    short-particle / long-final-mora rhythm of natural speech
  *
  * Zero assets, negligible compute; everything is mora-level arithmetic.
  */
 interface ShapeProsodyOptions {
+    /**
+     * Minimum pause length in ms per pause kind (see `pauseKind`); the HTS
+     * pause is kept when it is already longer. The utterance-final pause is
+     * left alone. `null` disables the rule. Defaults: sentence 650, clause 380,
+     * space 500.
+     */
+    pauseMs?: Partial<Record<PauseKind, number>> | null;
+    /**
+     * Expansion of spoken-mora durations around the utterance mean:
+     * `mean + (d − mean) × contrast`. 1 keeps HTS as-is. Default 1.3.
+     */
+    durationContrast?: number;
+    /** Floor for a spoken mora after contrast expansion, in ms. Default 60. */
+    minMoraMs?: number;
+    /**
+     * A mora is never shortened below this fraction of its HTS duration by the
+     * contrast expansion (short morae such as devoiced 「く」 are already at
+     * their minimum). Default 0.85.
+     */
+    minShrink?: number;
+    /** Baseline pitch shift added to the whole curve, in cents. Default 0. */
+    pitchShiftCents?: number;
     /** Treat the utterance as a question (see {@link isQuestion}). Default false. */
     question?: boolean;
     /**
@@ -1055,11 +1122,19 @@ interface ShapeProsodyOptions {
      */
     questionRiseCents?: number;
     /**
-     * Loudness coupling: dB per 100 cents of pitch relative to the speaker
-     * median. 0 disables the energy envelope. Default 0.5 (≈ +2 dB at +400 cent).
+     * Per-mora loudness coupling: dB per 100 cents of pitch relative to the
+     * speaker median, applied as a step per mora through `moraGains`. Default
+     * 0: `UtauTTSAdapter.renderChunks` applies the same coupling as a smooth
+     * per-frame curve (`energyDbPerSemitone` there), which avoids level steps
+     * at the mora joins. Set this when rendering through something else.
      */
     energyDbPerSemitone?: number;
-    /** Linear gain for morae with a devoiced nucleus. Default 0.5 (−6 dB). */
+    /**
+     * Linear gain for morae with a devoiced nucleus, applied to the whole unit
+     * through `moraGains`. Default 1: `UtauTTSAdapter.renderChunks` attenuates
+     * only the vowel part of a devoiced mora (`devoicedDb`), keeping the
+     * consonant burst audible; set this when rendering through something else.
+     */
     devoicedGain?: number;
     /** Clamp for the per-mora gain. Defaults 0.35 … 1.8. */
     minGain?: number;
@@ -1067,6 +1142,17 @@ interface ShapeProsodyOptions {
 }
 /** True when the text ends with a question mark (「？」 or "?"), ignoring closing quotes. */
 declare function isQuestion(text: string): boolean;
+/**
+ * New per-frame durations: pauses lengthened by kind, spoken morae expanded
+ * around the mean. Pure; returns `durations` itself when nothing changes.
+ */
+declare function shapeDurations(durations: number[], features: FeatureFrame[], options?: Pick<ShapeProsodyOptions, "pauseMs" | "durationContrast" | "minMoraMs" | "minShrink">): number[];
+/**
+ * Re-time a cents curve from the `from` durations to the `to` durations with
+ * a piecewise-linear warp (each frame keeps its own contour, stretched or
+ * squeezed to its new length). Frame period unchanged.
+ */
+declare function warpPitchCurve(cents: number[], frameMs: number, from: number[], to: number[]): number[];
 /**
  * Apply the residual rules to an aligned HTS prosody. Returns a new object;
  * `prosody` is not modified. Pass the result to `plan({ prosody })`: the pitch
@@ -1125,6 +1211,8 @@ interface UtauTTSTimelineUnit {
         x_ms: number;
         y: number;
     }[];
+    /** Set by `UtauTTSAdapter.plan` from `HtsProsody.devoiced`: the nucleus is a devoiced vowel. */
+    devoiced?: boolean;
 }
 /** Whole-phrase placement + F0 curve (`render.WorldlineTimeline`). */
 interface UtauTTSTimeline {
@@ -1215,6 +1303,54 @@ interface UtauTTSRenderOptions {
     chunkUnits?: number;
     /** Crossfade length at a mid-phrase seam in ms. Default 20. */
     seamCrossfadeMs?: number;
+    /**
+     * Even out the loudness of the rendered units. worldline normalises every
+     * unit's level internally (the sample's own level does not reach the
+     * output), but the vowel RMS that comes out still differs by several dB
+     * from unit to unit, which a listener hears as an uneven, choppy line.
+     * Each unit's vowel RMS (middle 35–90 % of its mora) is measured on the
+     * rendered audio and pulled towards `unitLoudnessDb` by a gain curve
+     * interpolated between mora centres, so there is no step at the joins. The
+     * prosodic volume of the unit (accent loudness, devoicing) is kept.
+     * Default true.
+     */
+    normalizeUnitLoudness?: boolean;
+    /**
+     * Reference vowel RMS in dBFS. Because worldline normalises every unit,
+     * the rendered vowel level is bank-independent (≈ −15 dBFS median for a
+     * 単独音 bank at volume 100), so an absolute reference works and keeps the
+     * chunks of a streamed utterance consistent. Default −16.
+     */
+    unitLoudnessDb?: number;
+    /** Largest correction applied to a unit, in dB. Default 6. */
+    unitLoudnessMaxDb?: number;
+    /**
+     * Energy contour: loudness follows the F0 curve, in dB per semitone from
+     * the utterance's median F0, applied as a smooth per-frame gain on the
+     * rendered audio (the accent peak is louder, the phrase end softer, as in
+     * natural speech, where a read sentence loses 10–15 dB over the phrase).
+     * A plain unit concatenation renders every mora at the same level, which
+     * is heard as a bumpy, mechanical line. 0 disables. Default 0.8.
+     */
+    energyDbPerSemitone?: number;
+    /** Clamp for the energy contour, in dB. Default 6. */
+    energyMaxDb?: number;
+    /**
+     * Attenuation of the vowel part of a devoiced mora (Open JTalk's 「です」
+     * 「ます」 「あくた」…), in dB, applied from the vowel onset to the next
+     * unit's consonant so the consonant burst of the devoiced mora itself stays
+     * at full level (attenuating the whole unit made 「あくた」 sound like
+     * 「あた」). 0 disables. Default −9.
+     */
+    devoicedDb?: number;
+    /**
+     * Soft limiter on the rendered audio: samples above this linear level are
+     * compressed smoothly towards full scale (tanh knee). worldline's output
+     * already peaks close to 0 dBFS with a plain plan, and the prosodic gains
+     * push single vowels over; this keeps them from hard-clipping in the
+     * AudioContext. 0 disables. Default 0.8.
+     */
+    outputLimit?: number;
     signal?: AbortSignal;
     gender?: number;
     tension?: number;
@@ -1289,4 +1425,51 @@ declare class UtauTTSAdapter {
     synthesizeText(bank: VoiceBank, text: string, features: FeatureFrame[], options?: UtauTTSOptions & UtauTTSRenderOptions): Promise<Float32Array | null>;
 }
 
-export { type AlignHtsOptions, type AssetFetchOptions, type AssetProgress, type ConsonantClass, type FeatureFrame, type FileResult, type Frames, type FrqData, type GenerateOptions, type GenerateResult, type Grid, type HtsPhoneme, type HtsProsody, type HtsProsodyFrames, type JpreprocessModule, KoeEngine, type KoeEngineOptions, MIN_WORLDLINE_SAMPLES, type Manifest, type MoraPosition, NAIST_JDIC_FILES, type NaistJdicData, type NjdNode, type NoteEvent, type OtoEntry, type PackInput, type PackOutput, type PhonemeEntry, type PlayOptions, type RenderNoteParams, type ShapeProsodyOptions, type SkippedFile, type Syllable, type TrimmedPhoneme, UtauTTSAdapter, type UtauTTSChunk, type UtauTTSOptions, type UtauTTSPlan, type UtauTTSRenderOptions, type UtauTTSTimeline, type UtauTTSTimelineUnit, type UtauTTSUnit, VoiceBank, WORLDLINE_SAMPLE_RATE, type WavData, type WavInput, Worldline, type WorldlineLoadOptions, type ZipFile, alignHtsProsody, analyze$1 as analyze, analyzeWav, detectF0, detectGrid, encodeOto, encodeShiftJis, estimateSequence, estimateSolo, estimateVowelJoin, fetchAsset, fetchAssetBytes, fetchAssetText, formatOto, frqAverageF0InRange, frqFileName, generateOto, generateOtoForFile, initJpreprocessDictionary, isQuestion, leadInFromEntry, loadNaistJdic, locateMora, normalizePcm, noteNameToHz, analyze as openjtalkAnalyze, otoRegion, pack, packKoe, parseFrq, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pcmBase, pitchFromAliasSuffix, readWavPcm48k, readingFromFeatures, resample, samplesToMs, shapeProsody, sparse_features, splitKana, suffixFromFolderName, summarise, toHiragana, toInt16, toMono, transcribe, trimToOto, unzipToFileMap, zipFiles };
+/**
+ * Speaking style: the handful of global knobs the pipeline already has,
+ * bundled so an application can offer "calm / neutral / lively" (or map an
+ * emotion label onto them) without knowing which stage each knob lives in.
+ *
+ * Nothing here needs assets or compute: `speed` goes to
+ * `analyze_prosody(text, speed)`, `intonation` to `alignHtsProsody`,
+ * `pauseScale` / `durationContrast` / `pitchShiftCents` to `shapeProsody`,
+ * `energyDbPerSemitone` to `renderChunks`. A different HTS voice (tohoku-f01
+ * ships happy / sad / angry variants next to neutral) changes the phoneme
+ * durations and F0 themselves and composes with these knobs.
+ */
+interface SpeakingStyle {
+    /** HTS speaking rate; 1 = the voice model's own rate (~7 morae/s for tohoku-f01). */
+    speed: number;
+    /** F0 excursion scale (`AlignHtsOptions.intonationStrength`). */
+    intonation: number;
+    /** Baseline pitch shift in cents, added to the whole F0 curve. */
+    pitchShiftCents: number;
+    /** Multiplier on the punctuation pause minimums (「。」650 / 「、」380 / space 500 ms at 1). */
+    pauseScale: number;
+    /** Mora-duration contrast expansion around the mean (`ShapeProsodyOptions.durationContrast`). */
+    durationContrast: number;
+    /** Loudness contour strength in dB per semitone (`UtauTTSRenderOptions.energyDbPerSemitone`). */
+    energyDbPerSemitone: number;
+}
+type SpeakingStyleName = "neutral" | "calm" | "lively";
+/**
+ * Presets. `neutral` is the pipeline's defaults; `calm` is a reading /
+ * narration pace (slower, longer sentence pauses, gentler dynamics, slightly
+ * lower baseline); `lively` is the opposite. Values are starting points meant
+ * to be tuned by ear.
+ */
+declare const SPEAKING_STYLES: Record<SpeakingStyleName, SpeakingStyle>;
+/** A preset name, or a preset name plus overrides, or a full/partial style over `neutral`. */
+type SpeakingStyleInput = SpeakingStyleName | (Partial<SpeakingStyle> & {
+    preset?: SpeakingStyleName;
+});
+/** Resolve a style input to a complete {@link SpeakingStyle}. */
+declare function resolveSpeakingStyle(input?: SpeakingStyleInput): SpeakingStyle;
+/** Options for `alignHtsProsody` that follow the style. */
+declare function styleAlignOptions(style: SpeakingStyle): AlignHtsOptions;
+/** Options for `shapeProsody` that follow the style (merge your own, e.g. `question`, on top). */
+declare function styleShapeOptions(style: SpeakingStyle): ShapeProsodyOptions;
+/** Options for `renderChunks` / `synthesizeText` that follow the style. */
+declare function styleRenderOptions(style: SpeakingStyle): UtauTTSRenderOptions;
+
+export { type AlignHtsOptions, type AssetFetchOptions, type AssetProgress, type ConsonantClass, type FeatureFrame, type FileResult, type Frames, type FrqData, type GenerateOptions, type GenerateResult, type Grid, type HtsPhoneme, type HtsProsody, type HtsProsodyFrames, type JpreprocessModule, KoeEngine, type KoeEngineOptions, MIN_WORLDLINE_SAMPLES, type Manifest, type MoraPosition, NAIST_JDIC_FILES, type NaistJdicData, type NjdNode, type NoteEvent, type OtoEntry, type PackInput, type PackOutput, type PauseKind, type PhonemeEntry, type PlayOptions, type RenderNoteParams, SPEAKING_STYLES, type ShapeProsodyOptions, type SkippedFile, type SpeakingStyle, type SpeakingStyleInput, type SpeakingStyleName, type Syllable, type TrimmedPhoneme, UtauTTSAdapter, type UtauTTSChunk, type UtauTTSOptions, type UtauTTSPlan, type UtauTTSRenderOptions, type UtauTTSTimeline, type UtauTTSTimelineUnit, type UtauTTSUnit, VoiceBank, WORLDLINE_SAMPLE_RATE, type WavData, type WavInput, Worldline, type WorldlineLoadOptions, type ZipFile, alignHtsProsody, analyze$1 as analyze, analyzeWav, detectF0, detectGrid, encodeOto, encodeShiftJis, estimateSequence, estimateSolo, estimateVowelJoin, fetchAsset, fetchAssetBytes, fetchAssetText, formatOto, frqAverageF0InRange, frqFileName, generateOto, generateOtoForFile, initJpreprocessDictionary, isQuestion, leadInFromEntry, loadNaistJdic, locateMora, normalizePcm, noteNameToHz, analyze as openjtalkAnalyze, otoRegion, pack, packKoe, parseFrq, parseFrqAverageF0, parseKoeHeader, parseOto, parseWav, pauseKind, pcmBase, pitchFromAliasSuffix, readWavPcm48k, readingFromFeatures, resample, resolveSpeakingStyle, samplesToMs, shapeDurations, shapeProsody, sparse_features, splitKana, styleAlignOptions, styleRenderOptions, styleShapeOptions, suffixFromFolderName, summarise, toHiragana, toInt16, toMono, transcribe, trimToOto, unzipToFileMap, warpPitchCurve, zipFiles };