@alia.onl/sdk 7.0.0 → 7.2.0

package/src/hooks/useAmbientWave.ts

@@ -11,6 +11,7 @@ import {
   type SharedValue,
 } from 'react-native-reanimated';
 import { useSTTStore } from './useSpeechToText';
+import { LEVEL_ATTACK_MS, LEVEL_RELEASE_MS } from '../lib/audio-level';
 import type { AgentState } from '../types';
 
 export type AmbientWaveMode = 'voice' | 'tts' | 'stt' | 'thinking' | 'idle';
@@ -27,7 +28,7 @@ export interface UseAmbientWaveOptions {
   voice?: AmbientWaveVoice;
   /** Whether TTS ("read aloud") is currently playing. */
   isTTSPlaying: boolean;
-  /** Simulated TTS amplitude SharedValue (glides to 0 when not playing). */
+  /** Live "read aloud" playback level, 0..1 (glides to 0 when not playing). */
   ttsWaveAmplitude: SharedValue<number>;
   /** Text-chat generation in flight (thinking or streaming) — gentle wave motion. */
   isGenerating?: boolean;
@@ -78,6 +79,17 @@ export function useAmbientWave({ voice, isTTSPlaying, ttsWaveAmplitude, isGenera
   );
 
   // ── STT metering smoothing (floor 0.08, fast attack / slow decay, →0 on stop) ──
+  //
+  // The recorder publishes on a 100ms poll, so what makes this read as speech
+  // rather than as ten steps a second is `withTiming` interpolating between
+  // them. Read-aloud reaches the same place by a different mechanism — its
+  // player pushes buffers far too fast to route through React — off the same
+  // two constants, but NOT with the same curve: this is a fixed-duration ease
+  // that is at the target after `LEVEL_ATTACK_MS`, and `audio-level`'s is an
+  // exponential whose time constant that is, so 60ms puts it at 63% and full
+  // travel takes about three times as long. Tuning the constant moves both, by
+  // different amounts. They are shared because one number should tune one
+  // feel, not because the two are interchangeable.
   const sttIsRecording = useSTTStore((s) => s.isRecording);
   const sttMetering = useSTTStore((s) => s.metering);
   const stt = useSharedValue(0);
@@ -88,7 +100,7 @@ export function useAmbientWave({ voice, isTTSPlaying, ttsWaveAmplitude, isGenera
         stt.value = withTiming(0, { duration: 300 });
         return;
       }
-      const duration = target > stt.value ? 60 : 200;
+      const duration = target > stt.value ? LEVEL_ATTACK_MS : LEVEL_RELEASE_MS;
       stt.value = withTiming(target, { duration, easing: Easing.bezier(0.33, 1, 0.68, 1) });
     },
     [sttIsRecording, sttMetering],

package/src/hooks/useSpeechToText.ts

@@ -9,6 +9,7 @@ import {
 } from 'expo-audio';
 import { useOxy } from '@oxyhq/services';
 import { create } from 'zustand';
+import { levelFromDbfs } from '../lib/audio-level';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
 
@@ -67,8 +68,9 @@ export function useSpeechToText(options: UseSTTOptions = {}) {
     if (state === 'recording') {
       let target: number;
       if (recorderState.metering != null) {
-        // dBFS: -160 (silence) to 0 (max). Normalize using -60 as practical floor.
-        target = Math.min(1, Math.max(0, (recorderState.metering + 60) / 60));
+        // The same curve read-aloud playback uses, so one background answers
+        // both the same way — see `lib/audio-level.ts`.
+        target = levelFromDbfs(recorderState.metering);
       } else {
         // Metering unavailable — simulate gentle activity
         target = 0.12 + Math.random() * 0.18;

package/src/hooks/useTTS.ts

@@ -1,16 +1,10 @@
 import { useCallback, useEffect, useRef } from 'react';
-import type { AudioPlayer, AudioStatus } from 'expo-audio';
-import {
-  useSharedValue,
-  withRepeat,
-  withSequence,
-  withTiming,
-  cancelAnimation,
-  Easing,
-} from 'react-native-reanimated';
+import type { AudioPlayer, AudioSample, AudioStatus } from 'expo-audio';
+import { makeMutable, withTiming } from 'react-native-reanimated';
 import { useOxy } from '@oxyhq/services';
 import { errorMessage } from '../lib/utils';
 import { create } from 'zustand';
+import { createAudioLevelMeter } from '../lib/audio-level';
 import { PREFERRED_VOICE_MODEL_ID } from '../lib/config';
 
 const API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';
@@ -57,6 +51,39 @@ const useTTSStore = create<TTSStore>((set) => ({
   reset: () => set({ activeMessageId: null, playbackState: 'idle', error: null }),
 }));
 
+// ============== PLAYBACK LEVEL ==============
+
+/** How long the level takes to reach silence once a clip stops sounding. */
+const SILENCE_FADE_MS = 300;
+
+/**
+ * The live playback level, 0..1, shared by every consumer.
+ *
+ * At module scope rather than inside the hook because the two ends of it live
+ * in different components: the message list calls `readAloud` and therefore
+ * owns the player, while the ambient field behind the conversation is rendered
+ * somewhere else entirely. Each `useTTS()` call is its own React instance, so a
+ * per-instance `useSharedValue` leaves the field reading a value that nothing
+ * writes — which is why the animation it replaces had to be driven off the
+ * shared playback STATE instead of off the audio. One player, one store, one
+ * level.
+ */
+const ttsWaveAmplitude = makeMutable(0);
+
+/**
+ * Silence is a projection of playback state, not an animation of its own.
+ *
+ * Every platform stops delivering buffers the instant a clip pauses, ends or
+ * fails, so nothing would write the level down again and the field would freeze
+ * swollen wherever the last syllable left it. Subscribed once, beside the store
+ * that owns the transitions, so a transition added later cannot forget it.
+ */
+useTTSStore.subscribe((state, previous) => {
+  if (state.playbackState === 'playing') return;
+  if (previous.playbackState !== 'playing') return;
+  ttsWaveAmplitude.value = withTiming(0, { duration: SILENCE_FADE_MS });
+});
+
 // ============== HOOK ==============
 
 export function useTTS(options: UseTTSOptions = {}) {
@@ -79,9 +106,6 @@ export function useTTS(options: UseTTSOptions = {}) {
 
   const playerRef = useRef<AudioPlayer | null>(null);
 
-  // Simulated wave amplitude for visualization
-  const ttsWaveAmplitude = useSharedValue(0);
-
   // ============== AUTH ==============
 
   const getToken = useCallback((): string | null => {
@@ -89,24 +113,6 @@ export function useTTS(options: UseTTSOptions = {}) {
     return oxyServices.httpService.getAccessToken();
   }, [options.accessToken, oxyServices]);
 
-  // Animate wave when playing
-  useEffect(() => {
-    if (playbackState === 'playing') {
-      ttsWaveAmplitude.value = withRepeat(
-        withSequence(
-          withTiming(0.5, { duration: 800, easing: Easing.inOut(Easing.sin) }),
-          withTiming(0.2, { duration: 600, easing: Easing.inOut(Easing.sin) }),
-          withTiming(0.6, { duration: 700, easing: Easing.inOut(Easing.sin) }),
-          withTiming(0.15, { duration: 500, easing: Easing.inOut(Easing.sin) }),
-        ),
-        -1,
-      );
-    } else {
-      cancelAnimation(ttsWaveAmplitude);
-      ttsWaveAmplitude.value = withTiming(0, { duration: 300 });
-    }
-  }, [playbackState]);
-
   const getTTSVoice = useCallback(() => {
     return voicePref === 'male' ? 'echo' : 'nova';
   }, [voicePref]);
@@ -151,9 +157,47 @@ export function useTTS(options: UseTTSOptions = {}) {
     (async () => {
       try {
         const { createAudioPlayer } = await import('expo-audio');
-        const player = createAudioPlayer({ uri: audioUrl });
+        /**
+         * `crossOrigin` is web-only and ignored elsewhere, and it is what makes
+         * the waveform readable there: a browser will not let an `AnalyserNode`
+         * see a cross-origin media element loaded without CORS, so without this
+         * `setAudioSamplingEnabled` below silently declines and the field never
+         * moves. Clips are served by `GET /media` on the API host, which is a
+         * different origin from the app on every deployment.
+         *
+         * It costs the clip its CORS headers if the app's origin is not on the
+         * API's allowlist — but such an origin cannot load a conversation to
+         * read aloud in the first place, since `/media` and `/conversations`
+         * share that allowlist. Measured against production 2026-08-26:
+         * `Origin: https://alia.onl` is answered
+         * `access-control-allow-origin: https://alia.onl`, with `Vary: Origin`.
+         */
+        const player = createAudioPlayer({ uri: audioUrl }, { crossOrigin: 'anonymous' });
         playerRef.current = player;
 
+        /**
+         * The real waveform, which is what the ambient field behind the
+         * conversation moves to. Enabled BEFORE `play()`: on web this is what
+         * builds the analyser, and the sampling loop only starts if the player
+         * is already playing or starts afterwards.
+         *
+         * It can decline, and declining is not an error. Android routes
+         * playback sampling through `android.media.audiofx.Visualizer`, which
+         * needs `RECORD_AUDIO` already granted — and asking a person for the
+         * microphone so that a background can move would be a worse trade than
+         * the background not moving. Where it declines no buffer ever arrives,
+         * the level stays at zero and the field simply rests. That is the
+         * honest reading of "we cannot hear this", and it is deliberately not
+         * papered over with motion that does not come from the audio.
+         */
+        player.setAudioSamplingEnabled(true);
+        const meter = createAudioLevelMeter();
+        player.addListener('audioSampleUpdate', (sample: AudioSample) => {
+          const frames = sample.channels[0]?.frames;
+          if (frames === undefined) return;
+          ttsWaveAmplitude.value = meter.push(frames, Date.now());
+        });
+
         player.addListener('playbackStatusUpdate', (status: AudioStatus) => {
           if (status.error) {
             releasePlayer();

package/src/lib/audio-level.ts

@@ -0,0 +1,129 @@
+/**
+ * How audio becomes the ambient field's 0..1 level — one curve, one pair of
+ * time constants, for every source that drives it.
+ *
+ * Dictation got here first and is the reference: the recorder reports dBFS,
+ * `useSpeechToText` normalises it against a -60 floor, and `useAmbientWave`
+ * smooths it with a fast attack and a slow decay before it reaches
+ * `AmbientField`. That is the behaviour people like, so it is the behaviour
+ * everything else adopts rather than re-invents — including "read aloud", which
+ * until now drove the same field from a canned `withRepeat` loop that had never
+ * heard the clip.
+ *
+ * The two sources differ only in what they can measure and how fast:
+ *
+ * - A **recorder** publishes dBFS on a 100ms poll, through React state, and
+ *   `levelFromDbfs` is the whole conversion.
+ * - A **player** publishes raw PCM as fast as the platform samples, so it needs
+ *   `levelFromFrames` to reach the same dBFS first, and it cannot go through
+ *   React at all — a render per audio buffer is not affordable. That is why the
+ *   smoothing here is a time integration it can run per buffer rather than the
+ *   `withTiming` the 10Hz path uses. The constants are the same; the CURVES are
+ *   not. `withTiming` is at its target after `LEVEL_ATTACK_MS`, and this is an
+ *   exponential whose time constant that is — 63% of the way at 60ms, ~95% at
+ *   180. Sharing the number keeps one knob for one feel; it does not make the
+ *   two settle alike, and anyone tuning it should expect the two paths to move
+ *   by different amounts.
+ *
+ * This module deliberately imports nothing. It is the part of the metering that
+ * can be driven with a buffer and asserted on, and `react-native-reanimated`
+ * does not load outside a bundler — a level that could only be observed by
+ * playing a real clip could not have a positive control.
+ */
+
+/**
+ * The quietest the field can hear, in dBFS.
+ *
+ * Silence is -160 on a real meter and negative infinity on a computed one, so a
+ * practical floor is what makes the scale usable. -60 is dictation's, and the
+ * compression it produces is most of why that field reads well: it answers
+ * quiet speech nearly as much as loud, which is what a person watching a
+ * background wants, and unlike a linear reading it does not sit near zero for
+ * everything below a shout.
+ */
+export const LEVEL_FLOOR_DBFS = -60;
+
+/** Rise fast enough to catch the front of a syllable… */
+export const LEVEL_ATTACK_MS = 60;
+/** …and fall slowly enough that the field does not strobe between them. */
+export const LEVEL_RELEASE_MS = 200;
+
+/**
+ * dBFS, as a recorder reports it, to the field's 0..1.
+ *
+ * `Number.NEGATIVE_INFINITY` is a legitimate input — it is what digital silence
+ * computes to — and clamps to 0 like anything below the floor.
+ */
+export function levelFromDbfs(dbfs: number): number {
+  const level = (dbfs - LEVEL_FLOOR_DBFS) / -LEVEL_FLOOR_DBFS;
+  return Math.min(1, Math.max(0, level));
+}
+
+/**
+ * One buffer of PCM frames, as a player reports them, to the field's 0..1.
+ *
+ * The frames are -1..1 on every platform `expo-audio` supports, so their RMS is
+ * an amplitude ratio and `20·log₁₀` is the dBFS a recorder would have reported
+ * for the same sound. Both sources end up on one scale.
+ */
+export function levelFromFrames(frames: readonly number[]): number {
+  if (frames.length === 0) return 0;
+
+  let sumSquares = 0;
+  for (let index = 0; index < frames.length; index += 1) {
+    sumSquares += frames[index] * frames[index];
+  }
+  const rms = Math.sqrt(sumSquares / frames.length);
+
+  // log₁₀(0) is -Infinity, which `levelFromDbfs` clamps — but only because it
+  // is asked to. Digital silence is exactly this case, so it is the one that
+  // matters most.
+  return levelFromDbfs(20 * Math.log10(rms));
+}
+
+export interface AudioLevelMeter {
+  /**
+   * Fold one buffer into the running level and return it.
+   *
+   * @param frames PCM frames, each -1..1, from `AudioSample.channels[n].frames`.
+   * @param nowMs A wall clock in milliseconds. The buffer rate is not fixed —
+   *   web samples once per animation frame, the native taps run at the audio
+   *   hardware's rate — so the smoothing is integrated against real elapsed
+   *   time. The same sentence has to read the same at 30Hz and at 90Hz.
+   */
+  push(frames: readonly number[], nowMs: number): number;
+}
+
+/**
+ * A meter per clip: the level starts from silence and carries no history from
+ * whatever was playing before.
+ */
+export function createAudioLevelMeter(): AudioLevelMeter {
+  let level = 0;
+  let lastMs: number | null = null;
+
+  return {
+    push(frames, nowMs) {
+      // A platform that cannot sample sends nothing rather than zeroes, but an
+      // empty buffer is the same statement: no new evidence, so no new level.
+      if (frames.length === 0) return level;
+
+      const target = levelFromFrames(frames);
+
+      if (lastMs === null) {
+        // Nothing to smooth against on the first buffer of a clip. Smoothing it
+        // from an invented zero would put a fade-in at the start of every clip
+        // that the audio does not have.
+        lastMs = nowMs;
+        level = target;
+        return level;
+      }
+
+      const elapsed = Math.max(0, nowMs - lastMs);
+      lastMs = nowMs;
+      const tau = target > level ? LEVEL_ATTACK_MS : LEVEL_RELEASE_MS;
+      level += (target - level) * (1 - Math.exp(-elapsed / tau));
+      return level;
+    },
+  };
+}

package/src/lib/catalogue.ts

@@ -3,7 +3,7 @@
  * workstream 5).
  *
  * Every surface used to hardcode an `alia-*` identifier as its default —
- * `useAliaChat` sent `alia-v1`, `useTTS` and `useVoiceRoom` sent `alia-v1-voice`
+ * `useAliaChat` sent `kaana-v1`, `useTTS` and `useVoiceRoom` sent `kaana-v1-voice`
  * — which meant a retired identifier became a 400 in a consumer's app with
  * nothing the consumer could do about it, since the string was baked into the
  * package they installed. This module is how the SDK asks the server what it