@magmamath/students-features 1.7.9 → 1.7.10-rc.1

package/src/features/voice/recording/hooks/useTranscriptPanelAnimation.ts

@@ -0,0 +1,49 @@
+import { LayoutChangeEvent } from 'react-native'
+
+import {
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated'
+
+import { VOICE_TRANSCRIPT_PANEL } from '../../constants'
+
+const TIMING = { duration: 170 } as const
+
+// Width and height are animated as explicit numbers instead of reanimated
+// layout transitions: on web those run as FLIP animations that scale the
+// subtree, visibly stretching the text while the panel resizes.
+export const useTranscriptPanelAnimation = (isExpanded: boolean) => {
+  const contentHeight = useSharedValue(0)
+
+  const onContentLayout = (event: LayoutChangeEvent) => {
+    const height = event.nativeEvent.layout.height
+    if (height <= 0) return
+    contentHeight.value =
+      contentHeight.value === 0 ? height : withTiming(height, TIMING)
+  }
+
+  const containerAnimatedStyle = useAnimatedStyle(
+    () => ({
+      width: withTiming(
+        isExpanded ? VOICE_TRANSCRIPT_PANEL.WIDTH_DONE : VOICE_TRANSCRIPT_PANEL.WIDTH,
+        TIMING,
+      ),
+    }),
+    [isExpanded],
+  )
+
+  const bodyAnimatedStyle = useAnimatedStyle(
+    () => (contentHeight.value === 0 ? {} : { height: contentHeight.value }),
+    [contentHeight],
+  )
+
+  const caretAnimatedStyle = useAnimatedStyle(
+    () => ({
+      transform: [{ rotate: withTiming(isExpanded ? '180deg' : '0deg', TIMING) }],
+    }),
+    [isExpanded],
+  )
+
+  return { onContentLayout, containerAnimatedStyle, bodyAnimatedStyle, caretAnimatedStyle }
+}

package/src/features/voice/recording/hooks/useVoiceRecorder.ts

@@ -3,11 +3,34 @@ import { VoiceRecordModel } from '../model/VoiceRecord.model'
 import { useEffect } from 'react'
 import { IS_WEB } from '@magmamath/react-native-ui'
 import { VOICE_RECORDER_MAX_DURATION_MS, VoiceRecorderState } from '../../constants'
-import { addAudioInputsListenerWeb, getAvailableInputs } from '../../helpers'
+import {
+  addAudioInputsListenerWeb,
+  createWebMeteringMonitor,
+  getAvailableInputs,
+} from '../../helpers'
+import { METERING_UPDATE_INTERVAL_MS } from '../../constants'
+
+// Metering powers the live recording waveform (recorderState.metering).
+// Only native respects it — on web the level is measured by
+// createWebMeteringMonitor instead.
+const RECORDING_OPTIONS = {
+  ...RecordingPresets.LOW_QUALITY,
+  isMeteringEnabled: true,
+}
 
 export const useVoiceRecorder = (model: VoiceRecordModel) => {
-  const recorder = useAudioRecorder(RecordingPresets.LOW_QUALITY, model.recordingStatusUpdate)
-  const recorderState = useAudioRecorderState(recorder)
+  const recorder = useAudioRecorder(RECORDING_OPTIONS, model.recordingStatusUpdate)
+  const recorderState = useAudioRecorderState(recorder, METERING_UPDATE_INTERVAL_MS)
+
+  useEffect(() => {
+    if (IS_WEB) return
+    model.recorderModel.setMetering(recorderState.metering ?? null)
+  }, [recorderState.metering, model.recorderModel])
+
+  useEffect(() => {
+    if (!IS_WEB || !recorderState.isRecording) return
+    return createWebMeteringMonitor(recorder, model.recorderModel.setMetering)
+  }, [recorderState.isRecording, recorder, model.recorderModel])
 
   useEffect(() => {
     if (

package/src/features/voice/recording/hooks/useVoiceWaveform.ts

@@ -0,0 +1,46 @@
+import { useEffect, useRef, useState } from 'react'
+
+import { VOICE_WAVEFORM } from '../../constants'
+import { normalizeMetering } from '../../helpers'
+
+type UseVoiceWaveformParams = {
+  metering: number | null
+  isActive: boolean
+}
+
+const createSilentBuffer = () =>
+  new Array<number>(VOICE_WAVEFORM.BUFFER_SIZE).fill(VOICE_WAVEFORM.MIN_LEVEL)
+
+// Keeps a rolling buffer of normalized levels that scrolls right-to-left while
+// recording. We sample on a fixed interval (rather than on every metering
+// update) so the scroll speed stays constant regardless of the recorder's
+// status cadence. The latest metering value is read from a ref to avoid
+// resubscribing the interval on each change. Levels are low-pass filtered so
+// neighboring bars flow into each other instead of jumping.
+export const useVoiceWaveform = ({ metering, isActive }: UseVoiceWaveformParams) => {
+  const meteringRef = useRef(metering)
+  meteringRef.current = metering
+
+  const smoothedLevelRef = useRef(VOICE_WAVEFORM.MIN_LEVEL)
+  const [levels, setLevels] = useState<number[]>(createSilentBuffer)
+
+  useEffect(() => {
+    if (!isActive) {
+      smoothedLevelRef.current = VOICE_WAVEFORM.MIN_LEVEL
+      setLevels(createSilentBuffer())
+      return
+    }
+
+    const intervalId = setInterval(() => {
+      const target = normalizeMetering(meteringRef.current)
+      smoothedLevelRef.current +=
+        (target - smoothedLevelRef.current) * VOICE_WAVEFORM.LEVEL_SMOOTHING
+      const level = Math.max(VOICE_WAVEFORM.MIN_LEVEL, smoothedLevelRef.current)
+      setLevels((prev) => [...prev.slice(1), level])
+    }, VOICE_WAVEFORM.SAMPLE_INTERVAL_MS)
+
+    return () => clearInterval(intervalId)
+  }, [isActive])
+
+  return levels
+}

package/src/features/voice/recording/model/Recorder.model.ts

@@ -18,6 +18,7 @@ export class RecorderModel<T = unknown> {
   public readonly setVoiceRecordState = createEvent<VoiceRecorderState>()
   public readonly setAvailableInputs = createEvent<AvailableAudioInputs>()
   public readonly setLastKnownDurationMs = createEvent<number>()
+  public readonly setMetering = createEvent<number | null>()
 
   public readonly $voiceRecordState = restore(
     this.setVoiceRecordState,
@@ -25,6 +26,8 @@ export class RecorderModel<T = unknown> {
   ).reset(this.reset)
   public readonly $availableInputs = restore(this.setAvailableInputs, [])
   public readonly $lastKnownDurationMs = restore(this.setLastKnownDurationMs, 0).reset(this.reset)
+  // Live input level in dBFS while recording (powers the waveform)
+  public readonly $metering = restore(this.setMetering, null).reset(this.reset)
 
   public readonly start = createEffect(async () => {
     try {

package/src/features/voice/recording/model/VoiceRecordWithTranscript.model.ts

@@ -0,0 +1,81 @@
+import { createEffect, Effect, sample } from 'effector'
+
+import { NO_AUDIO_BE_MESSAGE, VoiceRecorderState } from '../../constants'
+import { fetchTranscriptWithRetry, GetAudioFileTranscript } from '../../transcript.helpers'
+import { VoiceTranscriptPanelModel } from './VoiceTranscriptPanel.model'
+import type { VoiceRecordModel } from './VoiceRecord.model'
+import type { VoiceRecordCollectionItem } from '../../types'
+
+export type VoiceRecordWithTranscriptModelProps = {
+  recordModel: VoiceRecordModel
+  getTranscript: GetAudioFileTranscript
+}
+
+// Wires the existing recording flow to the transcript panel:
+// recording starts → panel opens with the waveform; the recording is confirmed
+// (upload kicks off) → panel shows the loader; the uploaded file's transcript
+// arrives → panel shows the text. Deleting/discarding the record closes the panel.
+export class VoiceRecordWithTranscriptModel {
+  public readonly record: VoiceRecordModel
+  public readonly panel = new VoiceTranscriptPanelModel()
+
+  private readonly resolveTranscriptFx: Effect<VoiceRecordCollectionItem, string>
+
+  constructor({ recordModel, getTranscript }: VoiceRecordWithTranscriptModelProps) {
+    this.record = recordModel
+    this.resolveTranscriptFx = createEffect(async (record: VoiceRecordCollectionItem) => {
+      const upload = await record.audioUploadPromise
+      if (!upload || !upload.id) throw new Error('Audio upload did not return a file id')
+
+      const { text } = await fetchTranscriptWithRetry(getTranscript, upload.id)
+      if (text === NO_AUDIO_BE_MESSAGE) throw new Error('Transcript is not available')
+      return text
+    })
+
+    this.setupPanelLifecycle()
+    this.setupTranscriptPipeline()
+  }
+
+  private setupPanelLifecycle() {
+    sample({
+      clock: this.record.recorderModel.$voiceRecordState,
+      filter: (state) => state === VoiceRecorderState.RECORDING,
+      target: this.panel.open,
+    })
+    // startAudioUpload fires exactly when a recording was confirmed (the
+    // discard path never uploads), so it doubles as the panel's confirm clock.
+    sample({ clock: this.record.startAudioUpload, target: this.panel.confirm })
+    sample({ clock: [this.record.reset, this.record.stop.done], target: this.panel.discard })
+  }
+
+  private setupTranscriptPipeline() {
+    // Identity guard: a fetch result only applies if the record it was fetched
+    // for is still the current one — late results from a discarded or
+    // re-recorded take are dropped.
+    const isFetchedRecordCurrent = (
+      currentRecord: VoiceRecordCollectionItem | null,
+      { params }: { params: VoiceRecordCollectionItem },
+    ) => currentRecord === params
+
+    sample({
+      clock: this.record.$currentRecord.updates,
+      source: this.panel.$flags,
+      filter: (flags, record) => flags.isProcessing && Boolean(record?.audioUploadPromise),
+      fn: (_, record): VoiceRecordCollectionItem => record,
+      target: this.resolveTranscriptFx,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.done,
+      source: this.record.$currentRecord,
+      filter: isFetchedRecordCurrent,
+      fn: (_, { result }) => result,
+      target: this.panel.complete,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.fail,
+      source: this.record.$currentRecord,
+      filter: isFetchedRecordCurrent,
+      target: this.panel.fail,
+    })
+  }
+}

package/src/features/voice/recording/model/VoiceTranscriptPanel.model.ts

@@ -0,0 +1,76 @@
+import { createEvent, createStore, Event, sample } from 'effector'
+
+import { VoicePanelPhase } from '../../constants'
+import { DropdownModel } from '../../playing/model/Dropdown.model'
+
+type PhaseFlags = {
+  isOpen: boolean
+  isRecording: boolean
+  isProcessing: boolean
+  isDone: boolean
+}
+
+// Phase machine for the recording-flow panel: open → RECORDING (waveform),
+// confirm → PROCESSING (loader), complete/fail → DONE (transcript text).
+// The transcript shows inside a collapsible dropdown (same UX as the playing
+// side): collapsed to a short preview by default, expandable via the caret.
+// Transcript fetching itself is wired externally
+// (see VoiceRecordWithTranscriptModel).
+export class VoiceTranscriptPanelModel {
+  public readonly reset = createEvent()
+
+  public readonly dropdown = new DropdownModel()
+
+  public readonly open = createEvent()
+  public readonly confirm = createEvent()
+  public readonly complete = createEvent<string>()
+  public readonly fail = createEvent()
+  public readonly discard = createEvent()
+
+  public readonly $phase = createStore<VoicePanelPhase | null>(null)
+  public readonly $transcript = createStore('')
+  public readonly $hasError = createStore(false)
+
+  public readonly $flags = this.$phase.map(
+    (phase): PhaseFlags => ({
+      isOpen: phase !== null,
+      isRecording: phase === VoicePanelPhase.RECORDING,
+      isProcessing: phase === VoicePanelPhase.PROCESSING,
+      isDone: phase === VoicePanelPhase.DONE,
+    }),
+  )
+
+  constructor() {
+    this.setupPhaseTransitions()
+  }
+
+  // The event passes through only while the panel is in the given phase —
+  // e.g. a transcript that arrives after a discard must not reopen the panel
+  private allowInPhase<T>(clock: Event<T>, phase: VoicePanelPhase): Event<T> {
+    return sample({
+      clock,
+      source: this.$phase,
+      filter: (currentPhase) => currentPhase === phase,
+      fn: (_, payload: T) => payload,
+    })
+  }
+
+  private setupPhaseTransitions() {
+    const confirmed = this.allowInPhase(this.confirm, VoicePanelPhase.RECORDING)
+    const completed = this.allowInPhase(this.complete, VoicePanelPhase.PROCESSING)
+    const failed = this.allowInPhase(this.fail, VoicePanelPhase.PROCESSING)
+
+    this.$phase
+      .on(this.open, () => VoicePanelPhase.RECORDING)
+      .on(confirmed, () => VoicePanelPhase.PROCESSING)
+      .on(completed, () => VoicePanelPhase.DONE)
+      .on(failed, () => VoicePanelPhase.DONE)
+      .reset(this.reset)
+
+    this.$transcript.on(completed, (_, transcript) => transcript).reset(this.reset)
+    this.$hasError.on(failed, () => true).reset(this.reset)
+
+    sample({ clock: this.discard, target: this.reset })
+    sample({ clock: this.reset, target: this.dropdown.reset })
+  }
+}

package/src/features/voice/transcript.helpers.ts

@@ -0,0 +1,37 @@
+import {
+  NO_AUDIO_BE_MESSAGE,
+  TRANSCRIPT_MAX_RETRIES,
+  TRANSCRIPT_RETRY_INTERVAL_MS,
+  TranscriptionStatus,
+} from './constants'
+import type { AudioTranscriptResponse } from './types'
+
+export type TranscriptResult = { text: string; language?: string }
+export type GetAudioFileTranscript = (audioFileId: string) => Promise<AudioTranscriptResponse>
+
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// Polls the transcript endpoint until the BE finishes processing. FAILED and
+// exhausted retries both resolve to the NO_AUDIO sentinel — same contract the
+// playing side relies on.
+export const fetchTranscriptWithRetry = async (
+  getTranscript: GetAudioFileTranscript,
+  audioFileId: string,
+): Promise<TranscriptResult> => {
+  for (let attempt = 0; attempt < TRANSCRIPT_MAX_RETRIES; attempt++) {
+    const response = await getTranscript(audioFileId)
+
+    if (response.status === TranscriptionStatus.COMPLETED) {
+      return { text: response.text, language: response.language }
+    }
+
+    if (response.status === TranscriptionStatus.FAILED) {
+      return { text: NO_AUDIO_BE_MESSAGE }
+    }
+
+    if (attempt < TRANSCRIPT_MAX_RETRIES - 1) {
+      await delay(TRANSCRIPT_RETRY_INTERVAL_MS)
+    }
+  }
+  return { text: NO_AUDIO_BE_MESSAGE }
+}

package/src/features/voice/types.ts

@@ -1,7 +1,12 @@
 import { WithAbortSignal } from 'src/types/common.types'
+import { TranscriptionStatus } from './constants'
 import { getAvailableInputs } from './helpers'
 import { VoiceRecordModel } from './recording/model/VoiceRecord.model'
 import { AxiosResponse } from 'axios'
+
+// The enum moved to constants.ts (jest-safe import chain for transcript helpers);
+// re-exported here to keep the public surface unchanged.
+export { TranscriptionStatus }
 import type {
   GoogleTranslateProps as GoogleTranslatePayload,
   GoogleTranslateResponse,
@@ -60,12 +65,6 @@ export type VoiceRecorderApi = {
   deleteAudioFile: (audioFileId: string) => Promise<void>
 }
 
-export enum TranscriptionStatus {
-  PENDING = 'pending',
-  COMPLETED = 'completed',
-  FAILED = 'failed',
-}
-
 export type AudioTranscriptResponse = {
   text: string
   language: string

package/src/i18n/.generated/schema.json

@@ -73,9 +73,9 @@
       "errorTitle": "Something went wrong",
       "fast": "Fast!",
       "incorrect": "INCORRECT — ANSWER: {{answer}}",
-      "masteryGrowing": "Growing",
-      "masteryLearning": "Learning",
-      "masteryMastered": "Mastered",
+      "masteryGrowing": "Familiar",
+      "masteryLearning": "New",
+      "masteryMastered": "Automatic",
       "masteryStrong": "Strong",
       "multiplication": "Multiplication",
       "notStarted": "New",
@@ -98,7 +98,7 @@
   "teacher": {
     "fluency": {
       "allPupils": "All students",
-      "average": "Average",
+      "average": "Progress",
       "avgTimeTitle": "Avg Time / Student",
       "factFluency": "Fact Fluency",
       "factsGridLabel": "{{cols}}×{{rows}} facts",
@@ -108,7 +108,7 @@
       "noFactsPracticed": "No facts practiced yet",
       "noStudents": "This class has no students",
       "noStudentsFound": "No students match your search",
-      "overallMastery": "Overall mastery",
+      "overallMastery": "Automaticity progress",
       "progressDeveloping": "Developing",
       "progressFluent": "Fluent",
       "progressLearning": "Learning",
@@ -140,6 +140,7 @@
     "noMicrophoneAccess": "No microphone access.",
     "noMicrophoneAccessBySystem": "Microphone access denied by system settings.",
     "noMicrophoneFound": "No microphone found.",
+    "preparingTranscript": "Preparing transcript",
     "recordingDeleted": "Recording successfully deleted.",
     "redo": "Redo",
     "redoRecording": "Redo recording?",