Audio Player

module

Implements:

feature/conversation-recording

React Native audio player built on expo-av with MobX Keystone state management. Handles recording, playback, seeking, and waveform rendering for conversation sessions.

Player Store (MobX Keystone Model)

A single AudioPlayerStore model owns all playback and recording state. Views derive UI-ready values (formatted time, progress percentage, waveform slices). Actions mutate state in response to native callbacks. The store is registered as a root model so Keystone snapshots can persist playback position across app suspends.

Native Audio Bridge (Adapter)

A thin adapter wraps expo-av Audio.Sound and Audio.Recording behind a platform-agnostic interface. The bridge translates native callbacks (onPlaybackStatusUpdate, onRecordingStatusUpdate) into MobX Keystone actions on the store. No domain logic lives in the bridge — it is purely I/O.

Architecture

architecture Audio Player architecture

Gallery Source ⛶

Diagram Syntax Error

flowchart TD;
    classDef internal fill:#e1f5fe,stroke:#01579b,color:#01579b;
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#9e9e9e,stroke-dasharray: 5 5;
    classDef actionNode fill:#eff6ff,stroke:#2563eb,color:#2563eb;
    classDef eventNode fill:#f0fdf4,stroke:#16a34a,color:#16a34a;
    classDef policyTarget fill:#faf5ff,stroke:#9333ea,color:#9333ea,stroke-dasharray: 5 5;
    subgraph STORE
        audio-player-store["audio-player-store"]:::internal;
        click audio-player-store href "/blueprints/audio-player#component:audio-player-store" _self;
    end
    subgraph ADAPTER
        audio-bridge["audio-bridge"]:::internal;
        click audio-bridge href "/blueprints/audio-player#component:audio-bridge" _self;
    end
    subgraph INFRASTRUCTURE
        file-storage["file-storage"]:::internal;
        click file-storage href "/blueprints/audio-player#component:file-storage" _self;
    end
    subgraph UI
        player-ui["player-ui"]:::internal;
        click player-ui href "/blueprints/audio-player#component:player-ui" _self;
    end
    subgraph API
        action_play_audio("play-audio"):::actionNode;
        action_start_recording("start-recording"):::actionNode;
        action_pause_recording("pause-recording"):::actionNode;
        action_resume_recording("resume-recording"):::actionNode;
        action_stop_recording("stop-recording"):::actionNode;
        event_recording_started(["recording-started"]):::eventNode;
        event_recording_stopped(["recording-stopped"]):::eventNode;
    end
    audio-player-store -- "Delegates to the native bridge for all expo-av interactions." --> audio-bridge;
    audio-bridge -- "Reads and writes audio files from local storage." --> file-storage;
    player-ui -- "Reads state and dispatches actions." --> audio-player-store;
    audio-player-store -- "implements" --> action_play_audio;
    audio-player-store -- "implements" --> action_start_recording;
    audio-player-store -- "implements" --> action_pause_recording;
    audio-player-store -- "implements" --> action_resume_recording;
    audio-player-store -- "implements" --> action_stop_recording;
    audio-player-store -- "emits" --> event_recording_started;
    audio-player-store -- "emits" --> event_recording_stopped;
    event_recording_started -. "listens" .-> player-ui;
    event_recording_stopped -. "listens" .-> player-ui;

Components

store

audio-player-store

MobX Keystone

Root state model: currentRecordingId, status (idle | recording | playing | paused), positionMs, durationMs, metering levels. Exposes actions for play, pause, seek, startRecording, stopRecording. Derives formatted timestamps and progress ratio as views.

Collaborates with

• audio-bridge — Delegates to the native bridge for all expo-av interactions.

Implements

• play-audio
• start-recording
• pause-recording
• resume-recording
• stop-recording

Emits

• recording-started
• recording-stopped

adapter

audio-bridge

expo-av

Wraps Audio.Sound and Audio.Recording. Creates, loads, and releases native resources. Forwards status updates to the store via callback injection. Handles iOS audio session category configuration and Android focus management.

Collaborates with

• file-storage — Reads and writes audio files from local storage.

infrastructure

file-storage

expo-file-system

Manages the on-device audio file directory. Provides paths for new recordings and resolves paths for playback. Handles cleanup of orphaned files.

ui

player-ui

React Native

Renders playback controls (play/pause, seek bar, timestamp), recording indicator with live metering, and waveform visualization. Observes the audio-player-store via mobx-react-lite . Shows recording indicator and live duration counter. Transitions UI to playback-ready state.

Collaborates with

• audio-player-store — Reads state and dispatches actions.

Listens to

• recording-started — Shows recording indicator and live duration counter.
• recording-stopped — Transitions UI to playback-ready state.

Rules

Rule	Force	Realm	Reference	Description
no-bridge-logic	must	global	—	The audio bridge must contain zero domain logic. All state transitions happen in the store; the bridge only translates native callbacks.
release-resources	must	global	—	Audio.Sound and Audio.Recording instances must be unloaded when the player unmounts or switches recordings, to prevent memory leaks on both platforms.

Links

domainAudio domain: actions, events, and data model.