@symbiote-native/audio 0.1.0

package/src/core/index.ts

@@ -0,0 +1,62 @@
+export { AudioPlayer, createAudioPlayer } from './audio-player';
+export { AudioRecorder } from './audio-recorder';
+export { AudioPlaylist, createAudioPlaylist } from './audio-playlist';
+export { AudioStream, createAudioStream } from './audio-stream';
+export {
+  setIsAudioActiveAsync,
+  setAudioModeAsync,
+  requestRecordingPermissionsAsync,
+  requestNotificationPermissionsAsync,
+  getRecordingPermissionsAsync,
+  preload,
+  clearPreloadedSource,
+  clearAllPreloadedSources,
+  getPreloadedSources,
+} from './audio-module';
+export { resolveSource, resolveSources } from './resolve-source';
+export {
+  RecordingPresets,
+  IOSOutputFormat,
+  AudioQuality,
+} from './recording-presets';
+export {
+  PLAYBACK_STATUS_UPDATE,
+  AUDIO_SAMPLE_UPDATE,
+  RECORDING_STATUS_UPDATE,
+  PLAYLIST_STATUS_UPDATE,
+  TRACK_CHANGED,
+  AUDIO_STREAM_BUFFER,
+  AUDIO_STREAM_STATUS,
+} from './types';
+export type {
+  IAudioSource,
+  IAudioSourceInfo,
+  IAudioPlayerOptions,
+  IPreloadOptions,
+  IRecordingInput,
+  IPitchCorrectionQuality,
+  IAudioStatus,
+  IRecordingStatus,
+  IRecorderState,
+  IAndroidOutputFormat,
+  IAndroidAudioEncoder,
+  IRecordingStartOptions,
+  IRecordingDirectory,
+  IRecordingOptions,
+  IRecordingOptionsWeb,
+  IRecordingOptionsIos,
+  IRecordingOptionsAndroid,
+  IRecordingSource,
+  IAudioMode,
+  IInterruptionMode,
+  IAudioMetadata,
+  IAudioPlaylistLoopMode,
+  IAudioPlaylistOptions,
+  IAudioPlaylistStatus,
+  IAudioLockScreenOptions,
+  IAudioSample,
+  IAudioStreamEncoding,
+  IAudioStreamOptions,
+  IAudioStreamBuffer,
+  IAudioStreamStatus,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,181 @@
+import { requireNativeModule, SharedObject } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+import type {
+  IAudioMetadata,
+  IAudioMode,
+  IAudioPlaylistLoopMode,
+  IAudioSample,
+  IAudioSource,
+  IAudioStatus,
+  IAudioLockScreenOptions,
+  IAudioPlaylistStatus,
+  IPitchCorrectionQuality,
+  IRecorderState,
+  IRecordingInput,
+  IRecordingOptions,
+  IRecordingStartOptions,
+  IRecordingStatus,
+} from './types';
+
+// `declare class ... extends SharedObject<Events>` (matching upstream's own AudioModule.types.ts
+// pattern, and packages/media-library/src/next/native-module.ts's precedent for this shape), not
+// a flat object type with a self-referential `new(...): T` construct signature — the latter makes
+// TypeScript report spurious `override` errors on the JS classes that `extends` these.
+// `SharedObject` is a REAL export of expo-modules-core (its JSI-backed base class) — we never
+// reimplement it, only declare the per-class surface these native classes carry.
+
+export type NativeAudioPlayerEvents = {
+  playbackStatusUpdate(status: IAudioStatus): void;
+  audioSampleUpdate(data: IAudioSample): void;
+};
+
+export declare class NativeAudioPlayer extends SharedObject<NativeAudioPlayerEvents> {
+  constructor(
+    source: IAudioSource,
+    updateInterval: number,
+    keepAudioSessionActive: boolean,
+    preferredForwardBufferDuration: number,
+  );
+  id: string;
+  playing: boolean;
+  muted: boolean;
+  loop: boolean;
+  paused: boolean;
+  isLoaded: boolean;
+  isAudioSamplingSupported: boolean;
+  isBuffering: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  playbackRate: number;
+  shouldCorrectPitch: boolean;
+  currentStatus: IAudioStatus;
+  play(): void;
+  pause(): void;
+  replace(source: IAudioSource): void;
+  seekTo(
+    seconds: number,
+    toleranceMillisBefore?: number,
+    toleranceMillisAfter?: number,
+  ): Promise<void>;
+  setPlaybackRate(
+    rate: number,
+    pitchCorrectionQuality?: IPitchCorrectionQuality,
+  ): void;
+  setAudioSamplingEnabled(enabled: boolean): void;
+  setActiveForLockScreen(
+    active: boolean,
+    metadata?: IAudioMetadata,
+    options?: IAudioLockScreenOptions,
+  ): void;
+  updateLockScreenMetadata(metadata: IAudioMetadata): void;
+  clearLockScreenControls(): void;
+  remove(): void;
+}
+
+export type NativeAudioRecorderEvents = {
+  recordingStatusUpdate: (status: IRecordingStatus) => void;
+};
+
+export declare class NativeAudioRecorder extends SharedObject<NativeAudioRecorderEvents> {
+  constructor(options: Partial<IRecordingOptions>);
+  id: string;
+  currentTime: number;
+  isRecording: boolean;
+  uri: string | null;
+  record(options?: IRecordingStartOptions): void;
+  stop(): Promise<void>;
+  pause(): void;
+  getAvailableInputs(): IRecordingInput[];
+  getCurrentInput(): Promise<IRecordingInput>;
+  setInput(inputUid: string): void;
+  getStatus(): IRecorderState;
+  /** @deprecated Use `record({ atTime: seconds })` instead. */
+  startRecordingAtTime(seconds: number): void;
+  prepareToRecordAsync(options?: Partial<IRecordingOptions>): Promise<void>;
+  /** @deprecated Use `record({ forDuration: seconds })` instead. */
+  recordForDuration(seconds: number): void;
+}
+
+export type NativeAudioPlaylistEvents = {
+  playlistStatusUpdate(status: IAudioPlaylistStatus): void;
+  trackChanged(data: { previousIndex: number; currentIndex: number }): void;
+};
+
+export declare class NativeAudioPlaylist extends SharedObject<NativeAudioPlaylistEvents> {
+  constructor(
+    sources: IAudioSource[],
+    updateInterval: number,
+    loop: IAudioPlaylistLoopMode,
+  );
+  id: string;
+  readonly currentIndex: number;
+  readonly trackCount: number;
+  readonly sources: { uri?: string; name?: string }[];
+  playing: boolean;
+  muted: boolean;
+  isLoaded: boolean;
+  isBuffering: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  playbackRate: number;
+  loop: IAudioPlaylistLoopMode;
+  currentStatus: IAudioPlaylistStatus;
+  play(): void;
+  pause(): void;
+  next(): void;
+  previous(): void;
+  skipTo(index: number): void;
+  seekTo(seconds: number): Promise<void>;
+  add(source: IAudioSource): void;
+  insert(source: IAudioSource, index: number): void;
+  remove(index: number): void;
+  clear(): void;
+  destroy(): void;
+}
+
+export type NativeAudioStreamEvents = {
+  audioStreamBuffer(buffer: {
+    data: ArrayBuffer;
+    sampleRate: number;
+    channels: number;
+    timestamp: number;
+  }): void;
+  audioStreamStatus(status: { isStreaming: boolean }): void;
+};
+
+export declare class NativeAudioStream extends SharedObject<NativeAudioStreamEvents> {
+  constructor(options: {
+    sampleRate: number;
+    channels: number;
+    encoding: string;
+  });
+  id: string;
+  readonly sampleRate: number;
+  readonly channels: number;
+  readonly isStreaming: boolean;
+  start(): Promise<void>;
+  stop(): void;
+}
+
+export type INativeAudioModule = {
+  readonly AudioPlayer: typeof NativeAudioPlayer;
+  readonly AudioRecorder: typeof NativeAudioRecorder;
+  readonly AudioPlaylist: typeof NativeAudioPlaylist;
+  readonly AudioStream: typeof NativeAudioStream;
+  setIsAudioActiveAsync(active: boolean): Promise<void>;
+  setAudioModeAsync(mode: Partial<IAudioMode>): Promise<void>;
+  requestRecordingPermissionsAsync(): Promise<PermissionResponse>;
+  requestNotificationPermissionsAsync(): Promise<PermissionResponse>;
+  getRecordingPermissionsAsync(): Promise<PermissionResponse>;
+  preload(
+    source: IAudioSource,
+    preferredForwardBufferDuration: number,
+  ): Promise<void>;
+  clearPreloadedSource(source: IAudioSource): Promise<void>;
+  clearAllPreloadedSources(): Promise<void>;
+  getPreloadedSources(): Promise<string[]>;
+};
+
+export const expoAudio = requireNativeModule<INativeAudioModule>('ExpoAudio');

package/src/core/recording-presets.ts

@@ -0,0 +1,99 @@
+// Ported verbatim from expo-audio's RecordingConstants.ts.
+import type { IRecordingOptions } from './types';
+
+/** @platform ios */
+export enum IOSOutputFormat {
+  LINEARPCM = 'lpcm',
+  AC3 = 'ac-3',
+  '60958AC3' = 'cac3',
+  APPLEIMA4 = 'ima4',
+  MPEG4AAC = 'aac ',
+  MPEG4CELP = 'celp',
+  MPEG4HVXC = 'hvxc',
+  MPEG4TWINVQ = 'twvq',
+  MACE3 = 'MAC3',
+  MACE6 = 'MAC6',
+  ULAW = 'ulaw',
+  ALAW = 'alaw',
+  QDESIGN = 'QDMC',
+  QDESIGN2 = 'QDM2',
+  QUALCOMM = 'Qclp',
+  MPEGLAYER1 = '.mp1',
+  MPEGLAYER2 = '.mp2',
+  MPEGLAYER3 = '.mp3',
+  APPLELOSSLESS = 'alac',
+  MPEG4AAC_HE = 'aach',
+  MPEG4AAC_LD = 'aacl',
+  MPEG4AAC_ELD = 'aace',
+  MPEG4AAC_ELD_SBR = 'aacf',
+  MPEG4AAC_ELD_V2 = 'aacg',
+  MPEG4AAC_HE_V2 = 'aacp',
+  MPEG4AAC_SPATIAL = 'aacs',
+  AMR = 'samr',
+  AMR_WB = 'sawb',
+  AUDIBLE = 'AUDB',
+  ILBC = 'ilbc',
+  DVIINTELIMA = 0x6d730011,
+  MICROSOFTGSM = 0x6d730031,
+  AES3 = 'aes3',
+  ENHANCEDAC3 = 'ec-3',
+}
+
+export enum AudioQuality {
+  MIN = 0,
+  LOW = 0x20,
+  MEDIUM = 0x40,
+  HIGH = 0x60,
+  MAX = 0x7f,
+}
+
+const HIGH_QUALITY: IRecordingOptions = {
+  extension: '.m4a',
+  sampleRate: 44100,
+  numberOfChannels: 2,
+  bitRate: 128000,
+  android: {
+    outputFormat: 'mpeg4',
+    audioEncoder: 'aac',
+  },
+  ios: {
+    outputFormat: IOSOutputFormat.MPEG4AAC,
+    audioQuality: AudioQuality.MAX,
+    linearPCMBitDepth: 16,
+    linearPCMIsBigEndian: false,
+    linearPCMIsFloat: false,
+  },
+  web: {
+    mimeType: 'audio/webm',
+    bitsPerSecond: 128000,
+  },
+};
+
+const LOW_QUALITY: IRecordingOptions = {
+  extension: '.m4a',
+  sampleRate: 44100,
+  numberOfChannels: 2,
+  bitRate: 64000,
+  android: {
+    extension: '.3gp',
+    outputFormat: '3gp',
+    audioEncoder: 'amr_nb',
+  },
+  ios: {
+    audioQuality: AudioQuality.MIN,
+    outputFormat: IOSOutputFormat.MPEG4AAC,
+    linearPCMBitDepth: 16,
+    linearPCMIsBigEndian: false,
+    linearPCMIsFloat: false,
+  },
+  web: {
+    mimeType: 'audio/webm',
+    bitsPerSecond: 128000,
+  },
+};
+
+/** The two preset `IRecordingOptions` bundles expo-audio ships. */
+export const RecordingPresets = {
+  HIGH_QUALITY,
+  LOW_QUALITY,
+} as const;

package/src/core/resolve-source.ts

@@ -0,0 +1,41 @@
+import { resolveAssetSource } from '@symbiote-native/engine';
+import type { IAudioSource } from './types';
+
+type IResolvedAudioSourceObject = Exclude<IAudioSource, string | number | null>;
+
+// resolveAssetSource returns `unknown` by design (the seam serves every require()'d-asset
+// consumer, not just this package) — narrow it instead of casting.
+function isAudioSourceObject(
+  value: unknown,
+): value is IResolvedAudioSourceObject {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Normalizes a source into the shape the native player accepts. A `number` (a `require()`'d
+ * local asset) resolves via `@symbiote-native/engine`'s `resolveAssetSource` seam — RN's own
+ * generic asset-registry lookup, wired by `bootstrapHost`. An actual `expo-asset` `Asset`
+ * instance is still not ported, see `types.ts`'s header comment on `IAudioSource`. A plain
+ * string is treated as a URI, matching upstream.
+ */
+export function resolveSource(source?: IAudioSource): IAudioSource | null {
+  if (source == null) {
+    return null;
+  }
+  if (typeof source === 'number') {
+    const resolved = resolveAssetSource(source);
+    return isAudioSourceObject(resolved) ? resolved : null;
+  }
+  if (typeof source === 'string') {
+    return { uri: source };
+  }
+  return source;
+}
+
+export function resolveSources(
+  sources: IAudioSource[],
+): NonNullable<IAudioSource>[] {
+  return sources
+    .map(source => resolveSource(source))
+    .filter((source): source is NonNullable<IAudioSource> => source != null);
+}

package/src/core/types.ts

@@ -0,0 +1,282 @@
+// Ported from expo-audio's Audio.types.ts / AudioModule.types.ts / AudioConstants.ts /
+// RecordingConstants.ts / AudioStream.types.ts / AudioEventKeys.ts, renamed with this repo's
+// `I`-prefix convention for object/union-shaped exported types (enums keep their upstream name,
+// matching packages/local-auth's AuthenticationType/SecurityLevel).
+//
+// `IAudioSource`'s `number` variant (a `require()`'d local asset) IS supported: it resolves via
+// `@symbiote-native/engine`'s `resolveAssetSource` seam, which wraps RN's own generic
+// `Image.resolveAssetSource` — an ordinary Metro asset-registry lookup, nothing image-specific
+// despite the name, and `mp3` is already in Metro's default `assetExts`. Only an actual `Asset`
+// CLASS instance (as opposed to the plain numeric id `require()` returns) is deliberately NOT
+// ported, along with the `downloadFirst` player option — both need `expo-asset`'s own
+// remote-caching layer, which pulls in `expo-constants` and peers on the `expo` meta-package this
+// project never depends on (root CLAUDE.md's dependency-scope invariant, and the
+// `symbiote-expo-native-module` skill §1). See the package README.
+import type { AudioQuality, IOSOutputFormat } from './recording-presets';
+
+/** Audio source information returned from native when reading sources from a queue. */
+export type IAudioSourceInfo = {
+  uri?: string;
+  name?: string;
+};
+
+/**
+ * A URI string, an object describing a remote/local (by URI) audio source, or the numeric asset
+ * id `require('./song.mp3')` produces — resolved via `resolveSource`/`resolveSources`.
+ */
+export type IAudioSource =
+  | string
+  | number
+  | null
+  | {
+      uri?: string;
+      headers?: Record<string, string>;
+      name?: string;
+    };
+
+export type IAudioPlayerOptions = {
+  /** How often (in milliseconds) to emit playback status updates. @default 500 */
+  updateInterval?: number;
+  /** @platform web */
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  /**
+   * If `true`, the audio session is not deactivated when this player pauses or finishes.
+   * @platform ios
+   * @default false
+   */
+  keepAudioSessionActive?: boolean;
+  /**
+   * Seconds to buffer ahead of the current playback position.
+   * @platform ios
+   * @platform android
+   * @default 0
+   */
+  preferredForwardBufferDuration?: number;
+};
+
+export type IPreloadOptions = {
+  /** @default 10 */
+  preferredForwardBufferDuration?: number;
+};
+
+export type IRecordingInput = {
+  name: string;
+  type: string;
+  uid: string;
+};
+
+export type IPitchCorrectionQuality = 'low' | 'medium' | 'high';
+
+export type IAudioStatus = {
+  id: string;
+  currentTime: number;
+  playbackState: string;
+  timeControlStatus: string;
+  reasonForWaitingToPlay: string;
+  mute: boolean;
+  duration: number;
+  playing: boolean;
+  loop: boolean;
+  didJustFinish: boolean;
+  isBuffering: boolean;
+  isLoaded: boolean;
+  playbackRate: number;
+  shouldCorrectPitch: boolean;
+  /** @platform ios */
+  mediaServicesDidReset?: boolean;
+  isLive: boolean;
+  currentOffsetFromLive: number | null;
+  error: string | null;
+};
+
+export type IRecordingStatus = {
+  id: string;
+  isFinished: boolean;
+  hasError: boolean;
+  error: string | null;
+  url: string | null;
+  /** @platform ios */
+  mediaServicesDidReset?: boolean;
+};
+
+export type IRecorderState = {
+  canRecord: boolean;
+  isRecording: boolean;
+  durationMillis: number;
+  mediaServicesDidReset: boolean;
+  metering?: number;
+  url: string | null;
+};
+
+/** @platform android */
+export type IAndroidOutputFormat =
+  | 'default'
+  | '3gp'
+  | 'mpeg4'
+  | 'amrnb'
+  | 'amrwb'
+  | 'aac_adts'
+  | 'mpeg2ts'
+  | 'webm';
+
+/** @platform android */
+export type IAndroidAudioEncoder =
+  'default' | 'amr_nb' | 'amr_wb' | 'aac' | 'he_aac' | 'aac_eld';
+
+export type IRecordingStartOptions = {
+  /** @platform ios @platform android @platform web */
+  forDuration?: number;
+  /** @platform ios */
+  atTime?: number;
+};
+
+/** @platform android @platform ios */
+export type IRecordingDirectory = 'cache' | 'document';
+
+export type IRecordingOptionsWeb = {
+  mimeType?: string;
+  bitsPerSecond?: number;
+};
+
+/** @platform ios */
+export type IRecordingOptionsIos = {
+  extension?: string;
+  sampleRate?: number;
+  outputFormat?: string | IOSOutputFormat | number;
+  audioQuality: AudioQuality | number;
+  bitRateStrategy?: number;
+  bitDepthHint?: number;
+  linearPCMBitDepth?: number;
+  linearPCMIsBigEndian?: boolean;
+  linearPCMIsFloat?: boolean;
+};
+
+/** @platform android */
+export type IRecordingSource =
+  | 'camcorder'
+  | 'default'
+  | 'mic'
+  | 'remote_submix'
+  | 'unprocessed'
+  | 'voice_communication'
+  | 'voice_performance'
+  | 'voice_recognition';
+
+/** @platform android */
+export type IRecordingOptionsAndroid = {
+  extension?: string;
+  sampleRate?: number;
+  outputFormat: IAndroidOutputFormat;
+  audioEncoder: IAndroidAudioEncoder;
+  maxFileSize?: number;
+  audioSource?: IRecordingSource;
+};
+
+export type IRecordingOptions = {
+  /** @default 'cache' */
+  directory?: IRecordingDirectory;
+  isMeteringEnabled?: boolean;
+  extension: string;
+  sampleRate: number;
+  numberOfChannels: number;
+  bitRate: number;
+  android: IRecordingOptionsAndroid;
+  ios: IRecordingOptionsIos;
+  web: IRecordingOptionsWeb;
+};
+
+export type IAudioMode = {
+  /** @default true */
+  playsInSilentMode: boolean;
+  /** @default 'mixWithOthers' */
+  interruptionMode: IInterruptionMode;
+  /** @default false @platform ios */
+  allowsRecording: boolean;
+  /** @default false */
+  shouldPlayInBackground: boolean;
+  /** @default false */
+  shouldRouteThroughEarpiece: boolean;
+  /** @default false @platform ios @platform android */
+  allowsBackgroundRecording?: boolean;
+};
+
+export type IInterruptionMode = 'mixWithOthers' | 'doNotMix' | 'duckOthers';
+
+export type IAudioMetadata = {
+  title?: string;
+  artist?: string;
+  albumTitle?: string;
+  artworkUrl?: string;
+};
+
+export type IAudioPlaylistLoopMode = 'none' | 'single' | 'all';
+
+export type IAudioPlaylistOptions = {
+  /** @default [] */
+  sources?: IAudioSource[];
+  /** @default 500 */
+  updateInterval?: number;
+  /** @default 'none' */
+  loop?: IAudioPlaylistLoopMode;
+  /** @platform web */
+  crossOrigin?: 'anonymous' | 'use-credentials';
+};
+
+export type IAudioPlaylistStatus = {
+  id: string;
+  currentIndex: number;
+  trackCount: number;
+  currentTime: number;
+  duration: number;
+  playing: boolean;
+  isBuffering: boolean;
+  isLoaded: boolean;
+  playbackRate: number;
+  muted: boolean;
+  volume: number;
+  loop: IAudioPlaylistLoopMode;
+  didJustFinish: boolean;
+};
+
+/** From AudioConstants.ts — which lock-screen controls to show while a player is active. */
+export type IAudioLockScreenOptions = {
+  showSeekForward?: boolean;
+  showSeekBackward?: boolean;
+  isLiveStream?: boolean;
+};
+
+export type IAudioSample = {
+  channels: { frames: number[] }[];
+  timestamp: number;
+};
+
+export type IAudioStreamEncoding = 'float32' | 'int16';
+
+export type IAudioStreamOptions = {
+  /** @default 48000 */
+  sampleRate?: number;
+  /** @default 1 */
+  channels?: number;
+  /** @default 'float32' */
+  encoding?: IAudioStreamEncoding;
+};
+
+export type IAudioStreamBuffer = {
+  data: ArrayBuffer;
+  sampleRate: number;
+  channels: number;
+  timestamp: number;
+};
+
+export type IAudioStreamStatus = {
+  isStreaming: boolean;
+};
+
+/** From AudioEventKeys.ts — event names the `SharedObject` classes' `addListener` accepts. */
+export const PLAYBACK_STATUS_UPDATE = 'playbackStatusUpdate';
+export const AUDIO_SAMPLE_UPDATE = 'audioSampleUpdate';
+export const RECORDING_STATUS_UPDATE = 'recordingStatusUpdate';
+export const PLAYLIST_STATUS_UPDATE = 'playlistStatusUpdate';
+export const TRACK_CHANGED = 'trackChanged';
+export const AUDIO_STREAM_BUFFER = 'audioStreamBuffer';
+export const AUDIO_STREAM_STATUS = 'audioStreamStatus';