@siteed/expo-audio-stream 1.0.1 → 1.0.3

package/src/useAudioRecorder.tsx

@@ -0,0 +1,415 @@
+// src/useAudioRecorder.ts
+import { Platform, Subscription } from "expo-modules-core";
+import { useCallback, useEffect, useReducer, useRef } from "react";
+
+import {
+  AudioAnalysisData,
+  AudioAnalysisEventPayload,
+  AudioFeaturesOptions,
+} from "./AudioAnalysis/AudioAnalysis.types";
+import {
+  AudioDataEvent,
+  AudioEventPayload,
+  AudioRecordingResult,
+  AudioStreamStatus,
+  RecordingConfig,
+  StartRecordingResult,
+} from "./ExpoAudioStream.types";
+import ExpoAudioStreamModule from "./ExpoAudioStreamModule";
+import { addAudioAnalysisListener, addAudioEventListener } from "./events";
+import { disableAllLoggers, enableAllLoggers, getLogger } from "./logger";
+import { WavFileInfo } from "./utils/getWavFileInfo";
+
+const TAG = "useAudioRecorder";
+const logger = getLogger(TAG);
+
+export interface ExtractMetadataProps {
+  fileUri?: string; // should provide either fileUri or arrayBuffer
+  wavMetadata?: WavFileInfo;
+  arrayBuffer?: ArrayBuffer;
+  bitDepth?: number;
+  skipWavHeader?: boolean;
+  durationMs?: number;
+  sampleRate?: number;
+  numberOfChannels?: number;
+  algorithm?: "peak" | "rms";
+  position?: number; // Optional number of bytes to skip. Default is 0
+  length?: number; // Optional number of bytes to read.
+  pointsPerSecond?: number; // Optional number of points per second. Use to reduce the number of points and compute the number of datapoints to return.
+  features?: AudioFeaturesOptions;
+  featuresExtratorUrl?: string;
+}
+
+export interface UseAudioRecorderProps {
+  debug?: boolean;
+  audioWorkletUrl?: string;
+  featuresExtratorUrl?: string;
+}
+
+export interface UseAudioRecorderState {
+  startRecording: (_: RecordingConfig) => Promise<StartRecordingResult>;
+  stopRecording: () => Promise<AudioRecordingResult | null>;
+  pauseRecording: () => void;
+  resumeRecording: () => void;
+  isRecording: boolean;
+  isPaused: boolean;
+  durationMs: number; // Duration of the recording
+  size: number; // Size in bytes of the recorded audio
+  analysisData?: AudioAnalysisData;
+}
+
+interface RecorderReducerState {
+  isRecording: boolean;
+  isPaused: boolean;
+  durationMs: number;
+  size: number;
+  analysisData?: AudioAnalysisData;
+}
+
+type RecorderAction =
+  | { type: "START" | "STOP" | "PAUSE" | "RESUME" }
+  | { type: "UPDATE_STATUS"; payload: { durationMs: number; size: number } }
+  | { type: "UPDATE_ANALYSIS"; payload: AudioAnalysisData };
+
+const defaultAnalysis: AudioAnalysisData = {
+  pointsPerSecond: 10,
+  bitDepth: 32,
+  numberOfChannels: 1,
+  durationMs: 0,
+  sampleRate: 44100,
+  samples: 0,
+  dataPoints: [],
+  amplitudeRange: {
+    min: Number.POSITIVE_INFINITY,
+    max: Number.NEGATIVE_INFINITY,
+  },
+};
+
+function audioRecorderReducer(
+  state: RecorderReducerState,
+  action: RecorderAction,
+): RecorderReducerState {
+  switch (action.type) {
+    case "START":
+      return {
+        ...state,
+        isRecording: true,
+        isPaused: false,
+        durationMs: 0,
+        size: 0,
+        analysisData: defaultAnalysis, // Reset analysis data
+      };
+    case "STOP":
+      return { ...state, isRecording: false, isPaused: false };
+    case "PAUSE":
+      return { ...state, isPaused: true, isRecording: false };
+    case "RESUME":
+      return { ...state, isPaused: false, isRecording: true };
+    case "UPDATE_STATUS":
+      return {
+        ...state,
+        durationMs: action.payload.durationMs,
+        size: action.payload.size,
+      };
+    case "UPDATE_ANALYSIS":
+      return {
+        ...state,
+        analysisData: action.payload,
+      };
+    default:
+      return state;
+  }
+}
+
+export function useAudioRecorder({
+  debug = false,
+  audioWorkletUrl,
+  featuresExtratorUrl,
+}: UseAudioRecorderProps = {}): UseAudioRecorderState {
+  const [state, dispatch] = useReducer(audioRecorderReducer, {
+    isRecording: false,
+    isPaused: false,
+    durationMs: 0,
+    size: 0,
+    analysisData: undefined,
+  });
+
+  const analysisListenerRef = useRef<Subscription | null>(null);
+  const analysisRef = useRef<AudioAnalysisData>({ ...defaultAnalysis });
+
+  // Instantiate the module for web with URLs
+  const ExpoAudioStream =
+    Platform.OS === "web"
+      ? ExpoAudioStreamModule({ audioWorkletUrl, featuresExtratorUrl })
+      : ExpoAudioStreamModule;
+
+  const onAudioStreamRef = useRef<
+    ((_: AudioDataEvent) => Promise<void>) | null
+  >(null);
+
+  const handleAudioAnalysis = useCallback(
+    async ({ analysis, visualizationDuration }: AudioAnalysisEventPayload) => {
+      const savedAnalysisData = analysisRef.current || { ...defaultAnalysis };
+
+      const maxDuration = visualizationDuration;
+
+      logger.debug(
+        `[handleAudioAnalysis] Received audio analysis: maxDuration=${maxDuration} analysis.dataPoints=${analysis.dataPoints.length} analysisData.dataPoints=${savedAnalysisData.dataPoints.length}`,
+        analysis,
+      );
+
+      // Combine data points
+      const combinedDataPoints = [
+        ...savedAnalysisData.dataPoints,
+        ...analysis.dataPoints,
+      ];
+
+      // Calculate the new duration
+      const pointsPerSecond =
+        analysis.pointsPerSecond || savedAnalysisData.pointsPerSecond;
+      const maxDataPoints = (pointsPerSecond * visualizationDuration) / 1000;
+
+      logger.debug(
+        `[handleAudioAnalysis] Combined data points before trimming: pointsPerSecond=${pointsPerSecond} visualizationDuration=${visualizationDuration} combinedDataPointsLength=${combinedDataPoints.length} vs maxDataPoints=${maxDataPoints}`,
+      );
+
+      // Trim data points to keep within the maximum number of data points
+      if (combinedDataPoints.length > maxDataPoints) {
+        combinedDataPoints.splice(0, combinedDataPoints.length - maxDataPoints);
+      }
+
+      savedAnalysisData.dataPoints = combinedDataPoints;
+      savedAnalysisData.bitDepth =
+        analysis.bitDepth || savedAnalysisData.bitDepth;
+      savedAnalysisData.durationMs =
+        combinedDataPoints.length * (1000 / pointsPerSecond);
+
+      // Update amplitude range
+      const newMin = Math.min(
+        savedAnalysisData.amplitudeRange.min,
+        analysis.amplitudeRange.min,
+      );
+      const newMax = Math.max(
+        savedAnalysisData.amplitudeRange.max,
+        analysis.amplitudeRange.max,
+      );
+
+      savedAnalysisData.amplitudeRange = {
+        min: newMin,
+        max: newMax,
+      };
+
+      logger.debug(
+        `[handleAudioAnalysis] Updated analysis data: durationMs=${savedAnalysisData.durationMs}`,
+        savedAnalysisData,
+      );
+
+      // Update the ref
+      analysisRef.current = savedAnalysisData;
+
+      // Dispatch the updated analysis data to state to trigger re-render
+      // need to use spread operator otherwise it doesnt trigger update.
+      dispatch({ type: "UPDATE_ANALYSIS", payload: { ...savedAnalysisData } });
+    },
+    [dispatch],
+  );
+
+  const handleAudioEvent = useCallback(async (eventData: AudioEventPayload) => {
+    const {
+      fileUri,
+      deltaSize,
+      totalSize,
+      lastEmittedSize,
+      position,
+      streamUuid,
+      encoded,
+      mimeType,
+      buffer,
+    } = eventData;
+    logger.debug(`[handleAudioEvent] Received audio event:`, {
+      fileUri,
+      deltaSize,
+      totalSize,
+      position,
+      mimeType,
+      lastEmittedSize,
+      streamUuid,
+      encodedLength: encoded?.length,
+    });
+    if (deltaSize === 0) {
+      // Ignore packet with no data
+      return;
+    }
+    try {
+      // Coming from native ( ios / android ) otherwise buffer is set
+      if (Platform.OS !== "web") {
+        // Read the audio file as a base64 string for comparison
+        if (!encoded) {
+          console.error(`${TAG} Encoded audio data is missing`);
+          throw new Error("Encoded audio data is missing");
+        }
+        onAudioStreamRef.current?.({
+          data: encoded,
+          position,
+          fileUri,
+          eventDataSize: deltaSize,
+          totalSize,
+        });
+      } else if (buffer) {
+        // Coming from web
+        const webEvent: AudioDataEvent = {
+          data: buffer,
+          position,
+          fileUri,
+          eventDataSize: deltaSize,
+          totalSize,
+        };
+        onAudioStreamRef.current?.(webEvent);
+        logger.debug(
+          `[handleAudioEvent] Audio data sent to onAudioStream`,
+          webEvent,
+        );
+      }
+    } catch (error) {
+      console.error(`${TAG} Error processing audio event:`, error);
+    }
+  }, []);
+
+  const checkStatus = useCallback(async () => {
+    try {
+      if (!state.isRecording) {
+        logger.debug(`Not recording, exiting status check.`);
+        return;
+      }
+
+      const status: AudioStreamStatus = ExpoAudioStream.status();
+      if (debug) {
+        logger.debug(`Status:`, status);
+      }
+
+      dispatch({
+        type: "UPDATE_STATUS",
+        payload: { durationMs: status.durationMs, size: status.size },
+      });
+    } catch (error) {
+      console.error(`${TAG} Error getting status:`, error);
+    }
+  }, [state.isRecording]);
+
+  const startRecording = useCallback(
+    async (recordingOptions: RecordingConfig) => {
+      logger.debug(`start recoding`, recordingOptions);
+
+      analysisRef.current = { ...defaultAnalysis }; // Reset analysis data
+
+      const { onAudioStream, ...options } = recordingOptions;
+      const { enableProcessing } = options;
+
+      const maxRecentDataDuration = 10000; // TODO compute maxRecentDataDuration based on screen dimensions
+      if (typeof onAudioStream === "function") {
+        onAudioStreamRef.current = onAudioStream;
+      } else {
+        console.warn(`${TAG} onAudioStream is not a function`, onAudioStream);
+        onAudioStreamRef.current = null;
+      }
+      const startResult: StartRecordingResult =
+        await ExpoAudioStream.startRecording(options);
+      dispatch({ type: "START" });
+
+      if (enableProcessing) {
+        logger.debug(`Enabling audio analysis listener`);
+        const listener = addAudioAnalysisListener(async (analysisData) => {
+          try {
+            await handleAudioAnalysis({
+              analysis: analysisData,
+              visualizationDuration: maxRecentDataDuration,
+            });
+          } catch (error) {
+            console.warn(`${TAG} Error processing audio analysis:`, error);
+          }
+        });
+
+        analysisListenerRef.current = listener;
+      }
+
+      return startResult;
+    },
+    [handleAudioAnalysis, dispatch],
+  );
+
+  const stopRecording = useCallback(async () => {
+    logger.debug(`stoping recording`);
+
+    if (analysisListenerRef.current) {
+      analysisListenerRef.current.remove();
+      analysisListenerRef.current = null;
+    }
+
+    const stopResult: AudioRecordingResult =
+      await ExpoAudioStream.stopRecording();
+    onAudioStreamRef.current = null;
+    logger.debug(`recording stopped`, stopResult);
+    dispatch({ type: "STOP" });
+    return stopResult;
+  }, [dispatch]);
+
+  const pauseRecording = useCallback(async () => {
+    logger.debug(`pause recording`);
+    const pauseResult = await ExpoAudioStream.pauseRecording();
+    dispatch({ type: "PAUSE" });
+    return pauseResult;
+  }, [dispatch]);
+
+  const resumeRecording = useCallback(async () => {
+    logger.debug(`resume recording`);
+    const resumeResult = await ExpoAudioStream.resumeRecording();
+    dispatch({ type: "RESUME" });
+    return resumeResult;
+  }, [dispatch]);
+
+  useEffect(() => {
+    let interval: ReturnType<typeof setTimeout>;
+    if (state.isRecording) {
+      interval = setInterval(checkStatus, 1000);
+    }
+    return () => {
+      if (interval) {
+        clearInterval(interval);
+      }
+    };
+  }, [checkStatus, state.isRecording]);
+
+  useEffect(() => {
+    logger.debug(`Registering audio event listener`);
+    const subscribeAudio = addAudioEventListener(handleAudioEvent);
+
+    logger.debug(`Subscribed to audio event listener and analysis listener`, {
+      subscribeAudio,
+    });
+
+    return () => {
+      logger.debug(`Removing audio event listener`);
+      subscribeAudio.remove();
+    };
+  }, [handleAudioEvent, handleAudioAnalysis]);
+
+  useEffect(() => {
+    if (debug) {
+      enableAllLoggers();
+    } else {
+      disableAllLoggers();
+    }
+  }, [debug]);
+
+  return {
+    startRecording,
+    stopRecording,
+    pauseRecording,
+    resumeRecording,
+    isPaused: state.isPaused,
+    isRecording: state.isRecording,
+    durationMs: state.durationMs,
+    size: state.size,
+    analysisData: state.analysisData,
+  };
+}

package/src/utils/convertPCMToFloat32.ts

@@ -0,0 +1,48 @@
+export const WAV_HEADER_SIZE = 44;
+export const convertPCMToFloat32 = ({
+  bitDepth,
+  buffer,
+  skipWavHeader = false,
+}: {
+  buffer: ArrayBuffer;
+  bitDepth: number;
+  skipWavHeader?: boolean;
+}): { pcmValues: Float32Array; min: number; max: number } => {
+  const dataView = new DataView(buffer);
+  const headerOffset = skipWavHeader ? WAV_HEADER_SIZE : 0;
+  const dataLength = buffer.byteLength - headerOffset;
+  const sampleLength = dataLength / (bitDepth / 8);
+  const float32Array = new Float32Array(sampleLength);
+  let min = Infinity;
+  let max = -Infinity;
+
+  for (let i = 0; i < sampleLength; i++) {
+    let value = 0;
+    const offset = headerOffset + i * (bitDepth / 8);
+    switch (bitDepth) {
+      case 8:
+        value = dataView.getUint8(offset) / 128;
+        break;
+      case 16:
+        value = dataView.getInt16(offset, true) / 32768;
+        break;
+      case 24:
+        value =
+          (dataView.getUint8(offset) +
+            (dataView.getUint8(offset + 1) << 8) +
+            (dataView.getUint8(offset + 2) << 16)) /
+          8388608;
+        break;
+      case 32:
+        value = dataView.getFloat32(offset, true);
+        break;
+      default:
+        throw new Error(`Unsupported bit depth: ${bitDepth}`);
+    }
+    if (value < min) min = value;
+    if (value > max) max = value;
+    float32Array[i] = value;
+  }
+
+  return { pcmValues: float32Array, min, max };
+};

package/src/utils/encodingToBitDepth.ts

@@ -0,0 +1,18 @@
+import { BitDepth, EncodingType } from "../ExpoAudioStream.types";
+
+export const encodingToBitDepth = ({
+  encoding,
+}: {
+  encoding: EncodingType;
+}): BitDepth => {
+  switch (encoding) {
+    case "pcm_32bit":
+      return 32;
+    case "pcm_16bit":
+      return 16;
+    case "pcm_8bit":
+      return 8;
+    default:
+      throw new Error(`Unsupported encoding type: ${encoding}`);
+  }
+};

package/src/utils/getWavFileInfo.ts

@@ -0,0 +1,125 @@
+// packages/expo-audio-stream/src/utils/getWavFileInfo.ts
+
+import { BitDepth, SampleRate } from "../ExpoAudioStream.types";
+import {
+  DATA_CHUNK_ID,
+  DEFAULT_BIT_DEPTH,
+  DEFAULT_SAMPLE_RATE,
+  FMT_CHUNK_ID,
+  INFO_CHUNK_ID,
+  RIFF_HEADER,
+  WAVE_HEADER,
+} from "../constants";
+
+// Audio format descriptions
+const AUDIO_FORMATS: { [key: number]: string } = {
+  1: "PCM",
+  3: "IEEE float",
+  6: "8-bit ITU-T G.711 A-law",
+  7: "8-bit ITU-T G.711 µ-law",
+  65534: "WAVE_FORMAT_EXTENSIBLE",
+};
+
+/**
+ * Interface representing the metadata of a WAV file.
+ */
+export interface WavFileInfo {
+  sampleRate: SampleRate;
+  numChannels: number;
+  bitDepth: BitDepth;
+  size: number; // in bytes
+  durationMs: number; // in ms
+  audioFormatDescription: string; // Description of the audio format
+  byteRate: number; // Average bytes per second
+  blockAlign: number; // Number of bytes for one sample including all channels
+  creationDateTime?: string; // Optional creation date and time
+  comments?: string; // Optional comments or tags
+  compressionType?: string; // Optional compression type
+}
+
+/**
+ * Extracts metadata from a WAV file.
+ *
+ * @param arrayBuffer - The array buffer containing the WAV file data.
+ * @returns A promise that resolves to the extracted metadata.
+ */
+export const getWavFileInfo = async (
+  arrayBuffer: ArrayBuffer,
+): Promise<WavFileInfo> => {
+  const view = new DataView(arrayBuffer);
+
+  // Check if the file is a valid RIFF/WAVE file
+  const riffHeader = view.getUint32(0, false);
+  const waveHeader = view.getUint32(8, false);
+  if (riffHeader !== RIFF_HEADER || waveHeader !== WAVE_HEADER) {
+    throw new Error("Invalid WAV file");
+  }
+
+  // Initialize variables for the metadata
+  let fmtChunkOffset = 12;
+  let sampleRate: SampleRate = DEFAULT_SAMPLE_RATE;
+  let numChannels = 0;
+  let bitDepth: BitDepth = DEFAULT_BIT_DEPTH;
+  let dataChunkSize = 0;
+  let audioFormat = 0;
+  let byteRate = 0;
+  let blockAlign = 0;
+  let creationDateTime = "";
+  let comments = "";
+
+  // Parse chunks to find the "fmt " and "data" chunks
+  while (fmtChunkOffset < view.byteLength) {
+    const chunkId = view.getUint32(fmtChunkOffset, false);
+    const chunkSize = view.getUint32(fmtChunkOffset + 4, true);
+    if (chunkId === FMT_CHUNK_ID) {
+      // "fmt "
+      audioFormat = view.getUint16(fmtChunkOffset + 8, true);
+      if (!AUDIO_FORMATS[audioFormat]) {
+        throw new Error("Unsupported WAV file format");
+      }
+      numChannels = view.getUint16(fmtChunkOffset + 10, true);
+      sampleRate = view.getUint32(fmtChunkOffset + 12, true) as SampleRate;
+      byteRate = view.getUint32(fmtChunkOffset + 16, true);
+      blockAlign = view.getUint16(fmtChunkOffset + 20, true);
+      bitDepth = view.getUint16(fmtChunkOffset + 22, true) as BitDepth;
+    } else if (chunkId === DATA_CHUNK_ID) {
+      // "data"
+      dataChunkSize = chunkSize;
+      break;
+    } else if (chunkId === INFO_CHUNK_ID) {
+      // "INFO"
+      // Read INFO chunk (assuming it contains a text-based creation date/time and comments)
+      const infoStart = fmtChunkOffset + 8;
+      const infoText = new TextDecoder().decode(
+        new Uint8Array(arrayBuffer.slice(infoStart, infoStart + chunkSize)),
+      );
+      const infoParts = infoText.split("\0");
+      creationDateTime = infoParts[0];
+      comments = infoParts[1];
+    }
+    fmtChunkOffset += 8 + chunkSize;
+  }
+
+  if (!sampleRate || !numChannels || !bitDepth || !dataChunkSize) {
+    throw new Error("Incomplete WAV file information");
+  }
+
+  // Calculate duration
+  const bytesPerSample = bitDepth / 8;
+  const numSamples = dataChunkSize / (numChannels * bytesPerSample);
+  const durationMs = (numSamples / sampleRate) * 1000;
+
+  return {
+    sampleRate,
+    numChannels,
+    bitDepth,
+    size: arrayBuffer.byteLength,
+    durationMs,
+    audioFormatDescription: AUDIO_FORMATS[audioFormat],
+    byteRate,
+    blockAlign,
+    creationDateTime: creationDateTime || undefined,
+    comments: comments || undefined,
+    compressionType: audioFormat === 1 ? "None" : AUDIO_FORMATS[audioFormat],
+  };
+};

package/src/utils/writeWavHeader.ts

@@ -0,0 +1,56 @@
+// packages/expo-audio-stream/src/utils/writeWavHeader.ts
+interface WavHeaderOptions {
+  buffer: ArrayBuffer;
+  sampleRate: number;
+  numChannels: number;
+  bitDepth: number;
+}
+
+export const writeWavHeader = ({
+  buffer,
+  sampleRate,
+  numChannels,
+  bitDepth,
+}: WavHeaderOptions): ArrayBuffer => {
+  const bytesPerSample = bitDepth / 8;
+  const numSamples = buffer.byteLength / (numChannels * bytesPerSample);
+  const view = new DataView(buffer);
+  const blockAlign = numChannels * bytesPerSample;
+  const byteRate = sampleRate * blockAlign;
+
+  // Function to write a string to the DataView
+  const writeString = (view: DataView, offset: number, string: string) => {
+    for (let i = 0; i < string.length; i++) {
+      view.setUint8(offset + i, string.charCodeAt(i));
+    }
+  };
+
+  // Check if the buffer already has a WAV header by looking for "RIFF" at the start
+  const existingHeader = view.getUint32(0, false) === 0x52494646; // "RIFF" in ASCII
+
+  if (!existingHeader) {
+    // Write the WAV header
+    writeString(view, 0, "RIFF"); // ChunkID
+    view.setUint32(4, 36 + numSamples * blockAlign, true); // ChunkSize
+    writeString(view, 8, "WAVE"); // Format
+    writeString(view, 12, "fmt "); // Subchunk1ID
+    view.setUint32(16, 16, true); // Subchunk1Size (16 for PCM)
+    view.setUint16(20, bitDepth === 32 ? 3 : 1, true); // AudioFormat (3 for float, 1 for PCM)
+    view.setUint16(22, numChannels, true); // NumChannels
+    view.setUint32(24, sampleRate, true); // SampleRate
+    view.setUint32(28, byteRate, true); // ByteRate
+    view.setUint16(32, blockAlign, true); // BlockAlign
+    view.setUint16(34, bitDepth, true); // BitsPerSample
+    writeString(view, 36, "data"); // Subchunk2ID
+    view.setUint32(40, numSamples * blockAlign, true); // Subchunk2Size
+  } else {
+    // Update the existing WAV header if necessary
+    view.setUint32(4, 36 + numSamples * blockAlign, true); // Update ChunkSize
+    view.setUint32(24, sampleRate, true); // Update SampleRate
+    view.setUint32(28, byteRate, true); // Update ByteRate
+    view.setUint16(32, blockAlign, true); // Update BlockAlign
+    view.setUint32(40, numSamples * blockAlign, true); // Update Subchunk2Size
+  }
+
+  return buffer;
+};