@pipedog/core 0.0.0 → 0.1.0

package/dist/audio/utils.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Audio utility functions for Pipecat.
+ *
+ * Provides common audio processing utilities including mixing, format
+ * conversion, volume calculation, and codec transformations for various audio
+ * formats used in Pipecat pipelines.
+ *
+ * Porting notes: numpy is replaced by typed arrays; Python's `audioop`
+ * (G.711 μ-law/A-law), `wave` and the `loudness` package (ITU-R BS.1770
+ * integrated loudness) are reimplemented here in plain TypeScript.
+ */
+import type { BaseAudioResampler } from "./resamplers/base_audio_resampler.ts";
+import { type SOXRAudioResamplerOptions } from "./resamplers/soxr_resampler.ts";
+import { type SOXRStreamAudioResamplerOptions } from "./resamplers/soxr_stream_resampler.ts";
+export declare const SPEAKING_THRESHOLD = 20;
+/**
+ * Create an audio resampler instance for batch processing of complete audio
+ * files.
+ *
+ * @param options Options passed to the resampler constructor.
+ * @returns A configured SOXRAudioResampler instance.
+ */
+export declare function createFileResampler(options?: SOXRAudioResamplerOptions): BaseAudioResampler;
+/**
+ * Create a stream audio resampler instance.
+ *
+ * @param options Options passed to the resampler constructor.
+ * @returns A configured SOXRStreamAudioResampler instance.
+ */
+export declare function createStreamResampler(options?: SOXRStreamAudioResamplerOptions): BaseAudioResampler;
+/**
+ * Mix two audio streams together by adding their samples.
+ *
+ * Both audio streams are assumed to be 16-bit signed integer PCM data. If the
+ * streams have different lengths, the shorter one is zero-padded to match the
+ * longer stream.
+ *
+ * @param audio1 First audio stream as raw bytes (16-bit signed integers).
+ * @param audio2 Second audio stream as raw bytes (16-bit signed integers).
+ * @returns Mixed audio data as raw bytes with samples clipped to 16-bit range.
+ */
+export declare function mixAudio(audio1: Uint8Array, audio2: Uint8Array): Uint8Array;
+/**
+ * Scale the volume of an audio stream by multiplying its samples.
+ *
+ * The audio is assumed to be 16-bit signed integer PCM data.
+ *
+ * @param audio Audio as raw bytes (16-bit signed integers).
+ * @param factor The multiplier for every sample: 1.0 leaves the audio
+ *   unchanged, 0.5 halves it.
+ * @returns Scaled audio data as raw bytes with samples clipped to 16-bit range.
+ */
+export declare function scaleAudio(audio: Uint8Array, factor: number): Uint8Array;
+/**
+ * Interleave left and right mono audio channels into stereo audio.
+ *
+ * Takes two mono audio streams and combines them into a single stereo stream
+ * by interleaving the samples (L, R, L, R, ...). If the channels have
+ * different lengths, both are truncated to the shorter length.
+ *
+ * @param leftAudio Left channel audio as raw bytes (16-bit signed integers).
+ * @param rightAudio Right channel audio as raw bytes (16-bit signed integers).
+ * @returns Interleaved stereo audio data as raw bytes.
+ */
+export declare function interleaveStereoAudio(leftAudio: Uint8Array, rightAudio: Uint8Array): Uint8Array;
+/**
+ * Wrap raw PCM audio in a WAV container.
+ *
+ * The PCM data is expected to be signed 16-bit little-endian samples, which
+ * is what Pipecat pipelines carry (e.g. what `AudioBufferProcessor` emits
+ * from its audio event handlers).
+ *
+ * Trailing bytes that don't complete a frame are dropped. Without this the
+ * WAV header would report a frame count that excludes them while the data
+ * chunk still carries them, so readers would disagree about the length and a
+ * stereo stream truncated mid-frame would swap channels.
+ *
+ * @param pcm Raw PCM audio data (16-bit signed integers). Any typed view
+ *   (e.g. an `Int16Array`) is read as its underlying bytes.
+ * @param sampleRate Sample rate of the audio in Hz.
+ * @param numChannels Number of interleaved channels in the PCM data.
+ * @returns A complete in-memory WAV file.
+ */
+export declare function pcmToWav(input: Uint8Array | ArrayBufferView, sampleRate: number, numChannels?: number): Uint8Array;
+/** Audio read from a WAV container by `readWav()`. @internal */
+export interface WavData {
+    audio: Uint8Array;
+    sampleRate: number;
+    numChannels: number;
+    sampleWidth: number;
+}
+/**
+ * Read the PCM frames out of a WAV file (Python's `wave.open(...).readframes()`).
+ *
+ * @internal
+ */
+export declare function readWav(data: Uint8Array): WavData;
+/**
+ * Normalize a value to the range [0, 1] and clamp it to bounds.
+ *
+ * @param value The value to normalize.
+ * @param minValue The minimum value of the input range.
+ * @param maxValue The maximum value of the input range.
+ * @returns Normalized value clamped to the range [0, 1].
+ */
+export declare function normalizeValue(value: number, minValue: number, maxValue: number): number;
+/**
+ * Calculate the loudness level of audio data using ITU-R BS.1770.
+ *
+ * @param audio Audio data as raw bytes (16-bit signed integers). Must hold at
+ *   least 400ms of audio, the length of a BS.1770 gating block.
+ * @param sampleRate Sample rate of the audio in Hz.
+ * @returns Normalized loudness value between 0 (quiet) and 1 (loud).
+ * @throws Error if the audio is shorter than a gating block.
+ */
+export declare function calculateAudioVolume(audio: Uint8Array, sampleRate: number): number;
+/**
+ * Apply exponential smoothing to a value.
+ *
+ * Exponential smoothing is used to reduce noise in time-series data by giving
+ * more weight to recent values while still considering historical data.
+ *
+ * @param value The new value to incorporate.
+ * @param prevValue The previous smoothed value.
+ * @param factor Smoothing factor between 0 and 1. Higher values give more
+ *   weight to the new value.
+ * @returns The exponentially smoothed value.
+ */
+export declare function expSmoothing(value: number, prevValue: number, factor: number): number;
+/**
+ * Convert μ-law encoded audio to PCM and optionally resample.
+ *
+ * @param ulawBytes μ-law encoded audio data as raw bytes.
+ * @param inRate Original sample rate of the μ-law audio in Hz.
+ * @param outRate Desired output sample rate in Hz.
+ * @param resampler Audio resampler instance for rate conversion.
+ * @returns PCM audio data as raw bytes at the specified output rate.
+ */
+export declare function ulawToPcm(ulawBytes: Uint8Array, inRate: number, outRate: number, resampler: BaseAudioResampler): Promise<Uint8Array>;
+/**
+ * Convert PCM audio to μ-law encoding and optionally resample.
+ *
+ * @param pcmBytes PCM audio data as raw bytes (16-bit signed integers).
+ * @param inRate Original sample rate of the PCM audio in Hz.
+ * @param outRate Desired output sample rate in Hz.
+ * @param resampler Audio resampler instance for rate conversion.
+ * @returns μ-law encoded audio data as raw bytes at the specified output rate.
+ */
+export declare function pcmToUlaw(pcmBytes: Uint8Array, inRate: number, outRate: number, resampler: BaseAudioResampler): Promise<Uint8Array>;
+/**
+ * Convert A-law encoded audio to PCM and optionally resample.
+ *
+ * @param alawBytes A-law encoded audio data as raw bytes.
+ * @param inRate Original sample rate of the A-law audio in Hz.
+ * @param outRate Desired output sample rate in Hz.
+ * @param resampler Audio resampler instance for rate conversion.
+ * @returns PCM audio data as raw bytes at the specified output rate.
+ */
+export declare function alawToPcm(alawBytes: Uint8Array, inRate: number, outRate: number, resampler: BaseAudioResampler): Promise<Uint8Array>;
+/**
+ * Convert PCM audio to A-law encoding and optionally resample.
+ *
+ * @param pcmBytes PCM audio data as raw bytes (16-bit signed integers).
+ * @param inRate Original sample rate of the PCM audio in Hz.
+ * @param outRate Desired output sample rate in Hz.
+ * @param resampler Audio resampler instance for rate conversion.
+ * @returns A-law encoded audio data as raw bytes at the specified output rate.
+ */
+export declare function pcmToAlaw(pcmBytes: Uint8Array, inRate: number, outRate: number, resampler: BaseAudioResampler): Promise<Uint8Array>;
+/**
+ * Determine if an audio sample contains silence by checking amplitude levels.
+ *
+ * Analyzes raw PCM audio data to detect silence by comparing the maximum
+ * absolute amplitude against a predefined threshold. The audio is expected to
+ * be clean speech or complete silence without background noise.
+ *
+ * Normal speech typically produces amplitude values between ±500 to ±5000,
+ * depending on factors like loudness and microphone gain. The threshold
+ * (SPEAKING_THRESHOLD) is set well below typical speech levels to reliably
+ * detect silence vs. speech.
+ *
+ * @param pcmBytes Raw PCM audio data as bytes (16-bit signed integers).
+ * @returns True if the audio sample is considered silence (below threshold),
+ *   false otherwise.
+ */
+export declare function isSilence(pcmBytes: Uint8Array): boolean;
+export interface DetectSpeechOnsetOptions {
+    /** Analysis window length in milliseconds. */
+    frameMs?: number;
+    /** Step between windows in milliseconds (the onset resolution). */
+    hopMs?: number;
+    /**
+     * Energy gate in dBFS; windows quieter than this are silence. Sits above
+     * typical TTS noise-floor padding and below voiced onset.
+     */
+    thresholdDb?: number;
+    /** Minimum duration the energy must stay above the gate for an onset to count. */
+    minVoicedMs?: number;
+}
+/**
+ * Detect the first sample of sustained audible speech in PCM audio.
+ *
+ * Measures short-time RMS energy: the signal is downmixed to mono, scanned
+ * with a `frameMs` window hopping every `hopMs`, and each window's RMS is
+ * computed with its mean removed (a DC offset carries no energy). Onset is the
+ * start of the first run of windows whose RMS stays above `thresholdDb` for at
+ * least `minVoicedMs`.
+ *
+ * Working on energy rather than per-sample amplitude rejects noise-floor blips
+ * (a lone loud sample averages out over the window), and the minimum-duration
+ * requirement rejects brief transients. `hopMs` sets the onset resolution.
+ *
+ * Operates on a growing buffer as audio streams in: returns null until enough
+ * audio has arrived to confirm an onset, at which point the caller stops
+ * feeding it.
+ *
+ * @param pcmBytes Raw PCM audio data (16-bit signed integers).
+ * @param sampleRate Sample rate of the audio in Hz.
+ * @param numChannels Number of interleaved audio channels (downmixed to mono).
+ * @returns The per-channel sample index of speech onset, or null if no
+ *   sustained onset is present yet.
+ */
+export declare function detectSpeechOnset(pcmBytes: Uint8Array, sampleRate: number, numChannels?: number, options?: DetectSpeechOnsetOptions): number | null;
+//# sourceMappingURL=utils.d.ts.map