@magmamath/students-features 1.8.6 → 1.8.8-rc.1

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,121 @@
+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
+}
+
+type ResultGuardSource = {
+  currentRecord: VoiceRecordCollectionItem | null
+  isDismissPending: boolean
+}
+
+// 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) => {
+      // A restored recording already carries its uploaded file id; a fresh take
+      // gets it from the in-flight upload promise.
+      const fileId = record.id ?? (await record.audioUploadPromise)?.id
+      if (!fileId) throw new Error('Audio upload did not return a file id')
+
+      const { text } = await fetchTranscriptWithRetry(getTranscript, fileId)
+      if (text === NO_AUDIO_BE_MESSAGE) throw new Error('Transcript is not available')
+      return text
+    })
+
+    this.setupPanelLifecycle()
+    this.setupTranscriptPipeline()
+    this.setupTranscriptRestore()
+  }
+
+  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 })
+    // The record resets as a side effect of a wrong answer (the attempt key
+    // rotates to a take with no recording). While the panel is handling its own
+    // dismissal — dimming a shown transcript, or waiting for one that is still
+    // loading — that incidental reset must not close it early; the panel owns
+    // the close.
+    sample({
+      clock: [this.record.reset, this.record.stop.done],
+      source: this.panel.$isHandlingDismissal,
+      filter: (isHandlingDismissal) => !isHandlingDismissal,
+      target: this.panel.discard,
+    })
+  }
+
+  private setupTranscriptPipeline() {
+    // A fetch result applies when the record it was fetched for is still the
+    // current one — late results from a discarded or re-recorded take are
+    // dropped. The exception is a pending dismissal: a wrong answer rotates
+    // $currentRecord away from the take it was fetched for, but that take's
+    // transcript is exactly the one the panel is waiting to show before it
+    // closes, so it must still apply.
+    const shouldApplyResult = (
+      { currentRecord, isDismissPending }: ResultGuardSource,
+      { params }: { params: VoiceRecordCollectionItem },
+    ) => isDismissPending || currentRecord === params
+
+    const resultGuardSource = {
+      currentRecord: this.record.$currentRecord,
+      isDismissPending: this.panel.$isDismissPending,
+    }
+
+    sample({
+      clock: this.record.$currentRecord.updates,
+      source: this.panel.$flags,
+      filter: (flags, record) =>
+        flags.isProcessing && Boolean(record?.audioUploadPromise) && !record?.id,
+      fn: (_, record): VoiceRecordCollectionItem => record,
+      target: this.resolveTranscriptFx,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.done,
+      source: resultGuardSource,
+      filter: shouldApplyResult,
+      fn: (_, { result }) => result,
+      target: this.panel.complete,
+    })
+    sample({
+      clock: this.resolveTranscriptFx.fail,
+      source: resultGuardSource,
+      filter: shouldApplyResult,
+      target: this.panel.fail,
+    })
+  }
+
+  // Reopening a problem whose recording was already uploaded: $currentRecord is
+  // restored with its file id (no live take in progress), so the live pipeline
+  // never runs. Reopen the panel into the loader and refetch — a still-pending
+  // transcript keeps polling, a completed one resolves on the first call.
+  private setupTranscriptRestore() {
+    const restored = sample({
+      clock: this.record.$currentRecord.updates,
+      filter: (record): record is VoiceRecordCollectionItem => Boolean(record?.id),
+    })
+    sample({ clock: restored, target: this.panel.restore })
+    sample({ clock: restored, target: this.resolveTranscriptFx })
+  }
+}

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

@@ -0,0 +1,137 @@
+import { combine, createEvent, createStore, Event, sample } from 'effector'
+import { delay } from 'patronum'
+
+import { VOICE_TRANSCRIPT_PANEL, 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).
+// restore → PROCESSING is the reopen path: a saved recording becomes current
+// again (no live take), so the panel jumps straight to the loader and refetches.
+// 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 restore = createEvent()
+  public readonly confirm = createEvent()
+  public readonly complete = createEvent<string>()
+  public readonly fail = createEvent()
+  public readonly discard = createEvent()
+  // Ask the panel to dismiss itself gracefully — dim the transcript, linger,
+  // then close (vs. discard, which closes immediately). Wired to a wrong answer
+  // by the consumer; the panel itself stays domain-agnostic and owns the timing.
+  public readonly requestDismiss = createEvent()
+
+  public readonly $phase = createStore<VoicePanelPhase | null>(null)
+  public readonly $transcript = createStore('')
+  public readonly $hasError = createStore(false)
+  public readonly $isDimmed = createStore(false)
+  // A dismissal asked for while the transcript is still loading: there is
+  // nothing to dim yet, so we remember it and run the dismissal once the
+  // transcript resolves into the DONE phase.
+  public readonly $isDismissPending = createStore(false)
+
+  // True while the panel owns its own dismissal — either already dimming a
+  // shown transcript, or waiting for an in-flight transcript before it can.
+  // The consumer reads this so an incidental record reset can't close the
+  // panel out from under a dismissal in progress.
+  public readonly $isHandlingDismissal = combine(
+    this.$isDimmed,
+    this.$isDismissPending,
+    (isDimmed, isDismissPending) => isDimmed || isDismissPending,
+  )
+
+  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()
+    this.setupDelayedDismissal()
+  }
+
+  // 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(this.restore, () => VoicePanelPhase.PROCESSING)
+      .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.restore])
+    this.$hasError.on(failed, () => true).reset([this.reset, this.restore])
+
+    sample({ clock: this.discard, target: this.reset })
+    sample({ clock: [this.reset, this.restore], target: this.dropdown.reset })
+  }
+
+  private setupDelayedDismissal() {
+    const beginDismissal = createEvent()
+
+    // Transcript already shown → dim and dismiss right away.
+    const dismissWhileDone = this.allowInPhase(this.requestDismiss, VoicePanelPhase.DONE)
+
+    // Transcript still loading → there is nothing to dim, so defer the request.
+    const dismissWhileProcessing = this.allowInPhase(this.requestDismiss, VoicePanelPhase.PROCESSING)
+    this.$isDismissPending
+      .on(dismissWhileProcessing, () => true)
+      .reset([this.reset, this.open, this.restore])
+
+    // A deferred request fires the moment the transcript resolves into DONE.
+    const deferredDismiss = sample({
+      clock: this.$phase.updates,
+      source: this.$isDismissPending,
+      filter: (isDismissPending, phase) => isDismissPending && phase === VoicePanelPhase.DONE,
+      fn: () => undefined,
+    })
+
+    sample({ clock: [dismissWhileDone, deferredDismiss], target: beginDismissal })
+
+    this.$isDimmed.on(beginDismissal, () => true).reset([this.reset, this.open, this.restore])
+
+    const dismissTimeout = delay({
+      source: beginDismissal,
+      timeout: VOICE_TRANSCRIPT_PANEL.WRONG_ANSWER_DISMISS_DELAY_MS,
+    })
+    // The phase guard drops the timer if the panel was already discarded or a
+    // new recording started during the linger window
+    sample({
+      clock: this.allowInPhase(dismissTimeout, VoicePanelPhase.DONE),
+      target: this.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

@@ -165,6 +165,7 @@
   "voice": {
     "attempt": "Attempt {{ number }}",
     "cancel": "Cancel",
+    "couldNotUnderstand": "We couldn't understand your voice. Please try again!",
     "delete": "Delete",
     "deleteRecording": "Delete recording?",
     "noMicrophoneAccess": "No microphone access.",