kgames

audio.js (12380B)

---

 // Story Stamp — audio: recorded phonemes + words (Web Audio), speech synthesis
 // for everything else, and a few oscillator SFX.
 //
 // Recorded clips are listed in assets/manifest.js (generated by
 // tools/story-stamp-assets.py). Held sounds (/sss/, /mmm/, vowels) are long
 // recordings; a blend pass asks for a length and the clip is cut there with a
 // short fade — nothing is looped. A word with no recording is spoken by the
 // browser instead; phonemes are never synthesised (a synthetic "suh" would
 // break blending), so a phoneme with no clip is simply silent.
 (function (root) {
   'use strict';
 
   const SS = root.SS;
   const TEST = !!root.__TEST_MODE__;
   const scale = (ms) => (TEST ? ms * 0.1 : ms);   // test mode runs every wait at 10% speed
 
   class StoryStampAudio {
     constructor(assets, base) {
       this.assets  = assets || { phonemes: {}, words: {} };
       this.base    = base || 'assets/audio/';
       this.ctx     = null;
       this.ready   = false;
       this.buffers = {};        // key -> { buffer, offset } | null (failed)
       this.pending = {};        // key -> Promise
       this.log     = [];        // every clip played, for tests: { kind, id, len, t, at }
       this.voiceMuted = false;
       this.sfxMuted   = false;
       this._voice  = null;
       this._unlock = null;
       this._active = [];        // scheduled sources, so a blend can be cancelled
       this._timers = [];
     }
 
     // Create the context and preload the phoneme set. Safe to call repeatedly.
     init() {
       if (this.ctx) return;
       const AC = root.AudioContext || root.webkitAudioContext;
       if (!AC) return;
       try { this.ctx = new AC(); } catch (_) { return; }
       this.master = this.ctx.createGain();
       this.master.connect(this.ctx.destination);
       if (root.KGames && root.KGames.installAudioUnlock) {
         this._unlock = root.KGames.installAudioUnlock(() => [this.ctx], () => { this.ready = true; });
       } else {
         this.ready = true;
       }
       Object.keys(this.assets.phonemes || {}).forEach((id) => this.load('ph:' + id, this.assets.phonemes[id].file));
     }
 
     // ── loading ────────────────────────────────────────────────────────────
 
     load(key, file) {
       if (this.buffers[key] !== undefined) return Promise.resolve(this.buffers[key]);
       if (this.pending[key]) return this.pending[key];
       const url = this.base + file;
       const p = fetch(url)
         .then((r) => { if (!r.ok) throw new Error(r.status); return r.arrayBuffer(); })
         .then((ab) => new Promise((res, rej) => this.ctx.decodeAudioData(ab, res, rej)))
         .then((buffer) => {
           // Skip the encoder's leading silence so blends stay tight.
           const d = buffer.getChannelData(0);
           let i = 0;
           while (i < d.length && Math.abs(d[i]) < 0.012) i++;
           const entry = { buffer, offset: Math.max(0, i - 40) / buffer.sampleRate };
           this.buffers[key] = entry;
           return entry;
         })
         .catch(() => { this.buffers[key] = null; return null; });
       this.pending[key] = p;
       return p;
     }
 
     hasWord(w)    { return !!(this.assets.words && this.assets.words[w]); }
     hasPhoneme(p) { return !!(this.assets.phonemes && this.assets.phonemes[p]); }
 
     // Natural length of a clip in seconds (for timeline planning).
     phonemeDuration(p) {
       const e = this.buffers['ph:' + p];
       if (e) return e.buffer.duration - e.offset;
       const m = this.assets.phonemes && this.assets.phonemes[p];
       return m ? m.dur : 0.25;
     }
     phonemeDurations() {
       const out = {};
       Object.keys(SS.PHONEMES).forEach((p) => { out[p] = this.phonemeDuration(p); });
       return out;
     }
 
     preloadWord(w) {
       if (!this.ctx || !this.hasWord(w)) return Promise.resolve(null);
       return this.load('w:' + w, this.assets.words[w].file);
     }
 
     // ── playback ───────────────────────────────────────────────────────────
 
     _now() { return this.ctx ? this.ctx.currentTime : 0; }
 
     // Play one recorded phoneme. `len` (seconds) shortens a held sound; stops
     // and unstretchable sounds always play whole. Returns the seconds it takes.
     playPhoneme(id, opts) {
       opts = opts || {};
       const delay = opts.delay || 0;
       const nat = this.phonemeDuration(id);
       const len = SS.phonemeLength(id, opts.len == null ? nat : opts.len, { [id]: nat });
       // `at` is when the clip will sound (log order is schedule order, not play order)
       this.log.push({ kind: 'phoneme', id, len, t: Date.now(), at: Date.now() + scale(delay * 1000) });
       if (!this.ctx) return len;
       const entry = this.buffers['ph:' + id];
       if (!entry) return len;
       const at = this._now() + delay;
       const src = this.ctx.createBufferSource();
       src.buffer = entry.buffer;
       const g = this.ctx.createGain();
       src.connect(g); g.connect(this.master);
       const fadeOut = len < nat - 0.01 ? 0.045 : 0.02;
       g.gain.setValueAtTime(1, at);
       g.gain.setValueAtTime(1, at + Math.max(0, len - fadeOut));
       g.gain.linearRampToValueAtTime(0.0001, at + len);
       src.start(at, entry.offset);
       src.stop(at + len + 0.01);
       this._active.push(src);
       return len;
     }
 
     // Play the recorded word, or speak it. Resolves when it is (about) done.
     playWord(w, opts) {
       opts = opts || {};
       this.log.push({ kind: 'word', id: w, t: Date.now(), at: Date.now() + scale((opts.delay || 0) * 1000) });
       if (this.ctx && this.hasWord(w)) {
         return this.preloadWord(w).then((entry) => {
           if (!entry) return this.speak(w, opts.voice);
           const at = this._now() + (opts.delay || 0);
           const src = this.ctx.createBufferSource();
           src.buffer = entry.buffer;
           src.connect(this.master);
           src.start(at, entry.offset);
           this._active.push(src);
           const dur = entry.buffer.duration - entry.offset;
           return this._sleep(((opts.delay || 0) + dur) * 1000);
         });
       }
       return this.speak(w, opts.voice);
     }
 
     // All the sounds of a word with clear gaps (used to re-demonstrate).
     playSegmented(units, opts) {
       opts = opts || {};
       const gap = opts.gap == null ? 0.35 : opts.gap;
       const len = opts.len == null ? 0.45 : opts.len;
       let t = 0;
       units.forEach((unit, ui) => {
         if (opts.onUnit) this._timer(() => opts.onUnit(ui), t * 1000);
         unit.forEach((p) => { t += this.playPhoneme(p, { delay: t, len }) + 0.02; });
         if (ui < units.length - 1) t += gap;
       });
       return this._sleep(t * 1000 + 100);
     }
 
     // Sounding out: run SS.blendTimeline and fire onEvent for each event at
     // the right moment (visuals hang off these). The word itself is never
     // played — the child says it. Resolves when the last pass has faded.
     blend(units, onEvent) {
       const durations = this.phonemeDurations();
       const events = SS.blendTimeline(units, durations);
       let last = 0;
       events.forEach((ev) => {
         if (ev.kind === 'phoneme') this.playPhoneme(ev.id, { delay: ev.t, len: ev.len });
         if (onEvent) this._timer(() => onEvent(ev), ev.t * 1000);
         last = Math.max(last, ev.t);
       });
       return this._sleep(last * 1000).then(() => events);
     }
 
     // Stop every scheduled clip and pending callback (e.g. leaving a screen).
     cancel() {
       this._active.forEach((s) => { try { s.stop(); } catch (_) {} });
       this._active = [];
       this._timers.forEach(clearTimeout);
       this._timers = [];
       try { if (root.speechSynthesis) root.speechSynthesis.cancel(); } catch (_) {}
     }
 
     // ── speech synthesis ───────────────────────────────────────────────────
 
     _pickVoice() {
       if (this._voice || !root.speechSynthesis) return this._voice;
       let voices = [];
       try { voices = root.speechSynthesis.getVoices() || []; } catch (_) {}
       const en = voices.filter((v) => /^en[-_]/i.test(v.lang));
       const prefer = en.find((v) => /child|kid|samantha|karen|moira|google us english/i.test(v.name));
       this._voice = prefer || en.find((v) => /^en[-_]US/i.test(v.lang)) || en[0] || null;
       return this._voice;
     }
 
     // Speak text. Resolves when finished, or after an estimate if the browser
     // never reports the end (headless / no voices installed).
     speak(text, voice) {
       this.log.push({ kind: 'speak', id: text, t: Date.now(), at: Date.now() });
       const est = Math.min(6000, 350 + 65 * text.length);
       if (TEST) return this._sleep(0);
       if (this.voiceMuted) return this._sleep(150);          // muted: keep the flow moving
       if (!root.speechSynthesis) return this._sleep(est);    // no TTS at all: leave time to read
       return new Promise((resolve) => {
         let done = false;
         const finish = () => { if (!done) { done = true; resolve(); } };
         try {
           const u = new SpeechSynthesisUtterance(text);
           const v = this._pickVoice();
           if (v) u.voice = v;
           u.lang  = (v && v.lang) || 'en-US';
           u.pitch = voice && voice.pitch != null ? voice.pitch : 1.05;
           u.rate  = voice && voice.rate  != null ? voice.rate  : 0.95;
           u.onend = finish; u.onerror = finish;
           root.speechSynthesis.cancel();
           root.speechSynthesis.speak(u);
           setTimeout(finish, est + 2500);
         } catch (_) { finish(); }
       });
     }
 
     // ── SFX (oscillators; incidental, not the taught audio) ───────────────
 
     _tone(freq, dur, type, gain, when, slideTo) {
       if (!this.ctx || this.sfxMuted) return;
       const at = this._now() + (when || 0);
       const o = this.ctx.createOscillator();
       const g = this.ctx.createGain();
       o.type = type || 'sine';
       o.frequency.setValueAtTime(freq, at);
       if (slideTo) o.frequency.exponentialRampToValueAtTime(slideTo, at + dur);
       g.gain.setValueAtTime(0.0001, at);
       g.gain.exponentialRampToValueAtTime(gain || 0.15, at + 0.01);
       g.gain.exponentialRampToValueAtTime(0.0001, at + dur);
       o.connect(g); g.connect(this.master);
       o.start(at); o.stop(at + dur + 0.02);
     }
     _noise(dur, gain, when) {
       if (!this.ctx || this.sfxMuted) return;
       const at = this._now() + (when || 0);
       const n = Math.floor(this.ctx.sampleRate * dur);
       const buf = this.ctx.createBuffer(1, n, this.ctx.sampleRate);
       const d = buf.getChannelData(0);
       for (let i = 0; i < n; i++) d[i] = (Math.random() * 2 - 1) * (1 - i / n);
       const src = this.ctx.createBufferSource(); src.buffer = buf;
       const g = this.ctx.createGain(); g.gain.setValueAtTime(gain || 0.1, at);
       src.connect(g); g.connect(this.master); src.start(at);
     }
     stampLetter() { this._tone(180, 0.09, 'square', 0.05, 0, 90); this._noise(0.05, 0.05); }
     bigStamp()    { this._tone(90, 0.22, 'triangle', 0.25, 0, 45); this._noise(0.12, 0.12); }
     tick()        { this._tone(900, 0.05, 'square', 0.04); }
     wrong()       { this._tone(200, 0.25, 'triangle', 0.12, 0, 150); }
     ding()        { this._tone(880, 0.35, 'sine', 0.12); this._tone(1320, 0.5, 'sine', 0.08, 0.08); }
     sparkle()     { [0, 0.07, 0.14, 0.21].forEach((d, i) => this._tone(1200 + i * 300, 0.25, 'sine', 0.07, d)); }
     fanfare()     { [523, 659, 784, 1046].forEach((f, i) => this._tone(f, 0.3, 'triangle', 0.1, i * 0.11)); }
     whoosh()      { this._noise(0.25, 0.06); }
     pageFlip()    { this._noise(0.08, 0.05); this._noise(0.06, 0.04, 0.09); }
     slide()       { this._tone(300, 0.3, 'sine', 0.05, 0, 600); }
 
     // ── utils ──────────────────────────────────────────────────────────────
     _timer(fn, ms) { const id = setTimeout(fn, scale(ms)); this._timers.push(id); return id; }
     _sleep(ms)     { return new Promise((r) => this._timer(r, ms)); }
   }
 
   root.StoryStampAudio = StoryStampAudio;
 }(window));