Summary: Audio player spike for the 7Mind React Native app: what the Flutter player does, how pulse-app plays media, the three candidate libraries, and the recommendation expo-audio with what it implies. Sources: spike on 2026-11-16 (pulse-app branch claude/spike-audio-player-311fa6, report apps/sevenmind/docs/spikes/audio-player.md, not pushed); Flutter lib/features/player/ on origin/main of 7mind-mobile-apps-monorepo; pulse-app apps/native and packages/data; npm, package source and GitHub issues of the candidates Last updated: 2026-11-17


Recommendation

Use expo-audio ~58.0.12 in apps/sevenmind only, with one long-lived AudioPlayer at module scope behind a 7Mind player store that the player screen, a mini bar and the lock screen all read.

  • It covers what the Flutter player needs: background audio, lock screen and notification with title, speaker and artwork, configurable ±10 s buttons, interruption handling, local files, a start position and an end event. It needs no view in the tree.
  • It ships with the Expo SDK, so its version moves with expo. MIT, Expo module (New Architecture), maintained weekly.
  • No Gymondo, Buddyfit, TV or shared-package code changes and no existing version moves; the lockfile only gains expo-audio.

Fallback: react-native-video, if “same library as Gymondo” outweighs the audio fit. react-native-track-player is out: v4 has had no release since 2025-08, v5 (@rntp/player) needs a paid licence for commercial use.

What the Flutter player does

just_audio 0.10 plays, audio_service 0.18 owns the media session.

  • One recording per full-screen player route. Closing it stops playback. There is no mini player and no audio queue; on completion a card offers the next course item or the next piece of the collection, and the user taps it.
  • Sources: the remote fileUrl (Cloudinary mp3) or the downloaded file, with a resume position (course progress every 15 s, collection resume store).
  • Lock screen: title, speaker, duration, artwork. ±10 s only when the category allows it; no seeking on uncompleted prevention sessions; headset next/previous mapped to ±10 s (RTN-222).
  • Interruptions: just_audio defaults (pause on calls and focus loss, resume after transient ones, pause on unplugged headphones).
  • Tracking: listening intervals (merged under 5 s gaps, dropped under 1 s) feed analytics, local stats and Apple Health; “started” after 5 s listened; “completed” at outro minus 20 s, else “cancelled”; a snapshot every 15 s lets the next launch send “cancelled” after the app was killed.
  • Not in the Flutter player: speed, sleep timer, background sounds, casting, auto-advance, CarPlay or Android Auto.

What pulse-app does

apps/native uses react-native-video 6.19.3 with the Expo plugin options enableBackgroundAudio and enableNotificationControls. The <Video> lives in ExternalPlaybackHost, mounted once in RootNavigator behind the screens, and a Zustand store drives it, which is how playback survives navigation. resolvePlaybackPolicy sets background play and notification controls per play from the user’s background preference. Offline workouts are HLS downloads through Gymondo’s own native downloader module, tied to react-native-video; 7Mind’s single mp3 files do not need it.

Options

expo-audioreact-native-videoreact-native-track-player
Version58.0.12, pinned by the SDK6.19.3, already in pulse-appv4 4.1.2 (2025-08); v5 @rntp/player 5.13
LicenceMITMITv4 Apache-2.0; v5 commercial
Needs a mounted viewnoyesno
Lock-screen skip intervalconfigurable, default 10 sfixed 10 sconfigurable
QueueAudioPlaylistnoneyes
Known issues that matter#52192 Android crash when a playlist moves to a track added after setActiveForLockScreen; #53110 iOS play() can stall right after another player stops#5086 foreground-service crash on sticky restart; #4209 audio focus after an interruptionv4 unmaintained

Implications

  • Native config: ['expo-audio', { enableBackgroundPlayback: true, microphonePermission: false, recordAudioAndroid: false }] adds the iOS audio background mode, the Android media-playback foreground service and its permissions, and no microphone permission. At play time: setAudioModeAsync({ playsInSilentMode: true, shouldPlayInBackground: true, interruptionMode: 'doNotMix' }).
  • We build: the player store and mini bar; the tracking logic ported from the Flutter bloc (intervals, thresholds, position saving, the post-kill “cancelled” event); the completion screen with the next item; playing downloaded files; Apple Health later.
  • Gaps: no switch that hides only the lock-screen scrubber (locked prevention sessions); headset next/previous do nothing for a single player, so RTN-222 needs custom work. A mini player that keeps playing while browsing is new behaviour compared with Flutter.
  • Risks: iOS untested; use one long-lived player and replace() its source (#53110); SDK upgrades need a player regression pass, the API changed a lot across SDK 55 to 58.
  • Effort: about 3 to 3.5 weeks for one developer on both platforms, without downloads and Apple Health.

Verified on the Android emulator

A throwaway prototype (module-scope player plus a mini bar outside the navigator, playing a public 7Mind Cloudinary mp3) ran on patrol_api34 (API 34) in a Debug build.

  • Verified: build, typecheck and lint on Expo 58 / react-native-tvos 0.88; playback across navigation, in the background and with the screen off; notification with title, speaker, artwork, ±10 s and scrubber; play/pause from the notification and media keys; a phone call pauses and hang-up resumes; +10 s from the notification moved playback forward.
  • Not settled: −10 s while paused did not show in the app; after swiping the app away in recents it kept playing, but the swipe may not have closed the task.
  • Not tested: iOS, downloaded files, end of track, the app being killed, Bluetooth, other apps’ audio.