audio-inspect/dist/features/index.d.ts

Lightweight yet powerful audio analysis library

/**
 * FFTプロバイダーの種類
 */
type FFTProviderType = 'webfft' | 'native' | 'custom';
/**
 * FFT結果
 */
interface FFTResult {
    /** 複素数結果（インターリーブ形式：実部、虚部、実部、虚部...） */
    complex: Float32Array;
    /** 振幅スペクトラム */
    magnitude: Float32Array;
    /** 位相スペクトラム */
    phase: Float32Array;
    /** 周波数ビン（Hz） */
    frequencies: Float32Array;
}

/**
 * audio-inspect ライブラリの型定義
 */

/**
 * 音声データの構造
 */
interface AudioData {
    /** サンプルレート（Hz） */
    sampleRate: number;
    /** チャンネルごとのオーディオデータ */
    channelData: Float32Array[];
    /** 音声の長さ（秒） */
    duration: number;
    /** チャンネル数 */
    numberOfChannels: number;
    /** サンプル数 */
    length: number;
}
/**
 * 窓関数の種類（拡張版）
 */
type WindowFunction = 'hann' | 'hamming' | 'blackman' | 'rectangular' | 'none';
/**
 * 振幅測定のオプション
 */
interface AmplitudeOptions {
    channel?: number;
    asDB?: boolean;
    reference?: number;
    truePeak?: boolean;
    oversamplingFactor?: number;
    interpolation?: 'linear' | 'cubic' | 'sinc';
}
/**
 * プログレス通知オプション
 */
interface ProgressOptions {
    onProgress?: (percent: number, message?: string) => void;
}
/**
 * 基本的な解析結果インターフェース
 */
interface BaseAnalysisResult {
    /** メタデータ */
    sampleRate: number;
    duration: number;
    /** 処理情報 */
    processingTime?: number;
}
/**
 * 新しいWaveform解析結果（Float32Array対応）
 */
interface WaveformAnalysisResult extends BaseAnalysisResult {
    /** 振幅データ（直接使用可能） */
    amplitudes: Float32Array;
    /** タイムスタンプ（オプショナル） */
    timestamps?: Float32Array;
    /** メタデータ */
    frameCount: number;
    samplesPerFrame: number;
    framesPerSecond: number;
    /** 統計情報 */
    maxAmplitude: number;
    averageAmplitude: number;
}
/**
 * 新しいPeaks解析結果（Float32Array対応）
 */
interface PeaksAnalysisResult extends BaseAnalysisResult {
    /** サンプル位置 */
    positions: Float32Array;
    /** ピーク振幅 */
    amplitudes: Float32Array;
    /** 時間（秒） */
    times: Float32Array;
    /** 統計情報 */
    maxAmplitude: number;
    averageAmplitude: number;
    count: number;
}
/**
 * 新しいRMS解析結果（統一されたインターフェース）
 */
interface RMSAnalysisResult extends BaseAnalysisResult {
    /** RMS値 */
    value: number;
    /** デシベル値（オプショナル） */
    valueDB?: number;
    /** 処理したチャンネル */
    channel: number;
}

/**
 * ピーク検出のオプション
 */
interface PeaksOptions {
    /** 抽出するピークの数（デフォルト: 100） */
    count?: number;
    /** ピーク検出の閾値（0-1、デフォルト: 0.1） */
    threshold?: number;
    /** 解析するチャンネル（デフォルト: 0、-1で全チャンネルの平均） */
    channel?: number;
    /** 最小ピーク間距離（サンプル数、デフォルト: サンプルレート/100） */
    minDistance?: number;
}
/**
 * ピーク情報
 */
interface Peak {
    /** ピークの位置（サンプル数） */
    position: number;
    /** ピークの時間位置（秒） */
    time: number;
    /** ピークの振幅（0-1） */
    amplitude: number;
}
/**
 * ピーク検出結果
 */
interface PeaksResult {
    /** 検出されたピーク */
    peaks: Peak[];
    /** 最大振幅 */
    maxAmplitude: number;
    /** 平均振幅 */
    averageAmplitude: number;
}
/**
 * ピーク検出を行う
 */
declare function getPeaks(audio: AudioData, options?: PeaksOptions): PeaksResult;
/**
 * RMS（Root Mean Square）を計算
 */
declare function getRMS(audio: AudioData, optionsOrChannel?: AmplitudeOptions | number): number;
/**
 * ピーク振幅を計算
 */
declare function getPeakAmplitude(audio: AudioData, options?: AmplitudeOptions): number;

/**
 * ゼロクロッシング率を計算
 */
declare function getZeroCrossing(audio: AudioData, channel?: number): number;
/**
 * 波形データ取得のオプション
 */
interface WaveformOptions {
    /** 1秒あたりのサンプル数（解像度、デフォルト: 60） */
    framesPerSecond?: number;
    /** 解析するチャンネル（デフォルト: 0、-1で全チャンネルの平均） */
    channel?: number;
    /** 振幅の計算方法（デフォルト: 'rms'） */
    method?: 'rms' | 'peak' | 'average';
}
/**
 * 波形データポイント
 */
interface WaveformPoint {
    /** 時間位置（秒） */
    time: number;
    /** 振幅値（0-1） */
    amplitude: number;
}
/**
 * 波形データ取得結果
 */
interface WaveformResult {
    /** 波形データポイントの配列 */
    waveform: WaveformPoint[];
    /** 最大振幅 */
    maxAmplitude: number;
    /** 平均振幅 */
    averageAmplitude: number;
    /** フレーム数 */
    frameCount: number;
    /** フレームあたりのサンプル数 */
    samplesPerFrame: number;
}
/**
 * 時間軸に沿った波形データを取得
 */
declare function getWaveform(audio: AudioData, options?: WaveformOptions): WaveformResult;
/**
 * 新しいWaveform解析オプション（プログレス通知対応）
 */
interface WaveformAnalysisOptions extends ProgressOptions {
    /** 1秒あたりのサンプル数（解像度、デフォルト: 60） */
    framesPerSecond?: number;
    /** 解析するチャンネル（デフォルト: 0、-1で全チャンネルの平均） */
    channel?: number;
    /** 振幅の計算方法（デフォルト: 'rms'） */
    method?: 'rms' | 'peak' | 'average';
}
/**
 * 新しいPeaks解析オプション（プログレス通知対応）
 */
interface PeaksAnalysisOptions extends ProgressOptions {
    /** 抽出するピークの数（デフォルト: 100） */
    count?: number;
    /** ピーク検出の閾値（0-1、デフォルト: 0.1） */
    threshold?: number;
    /** 解析するチャンネル（デフォルト: 0、-1で全チャンネルの平均） */
    channel?: number;
    /** 最小ピーク間距離（サンプル数、デフォルト: サンプルレート/100） */
    minDistance?: number;
}
/**
 * 新しいRMS解析オプション（プログレス通知対応）
 */
interface RMSAnalysisOptions extends ProgressOptions {
    channel?: number;
    asDB?: boolean;
    reference?: number;
}
/**
 * 新しいWaveform解析（Float32Array対応）
 */
declare function getWaveformAnalysis(audio: AudioData, options?: WaveformAnalysisOptions): WaveformAnalysisResult;
/**
 * 新しいPeaks解析（Float32Array対応）
 */
declare function getPeaksAnalysis(audio: AudioData, options?: PeaksAnalysisOptions): PeaksAnalysisResult;
/**
 * 新しいRMS解析（統一されたインターフェース）
 */
declare function getRMSAnalysis(audio: AudioData, options?: RMSAnalysisOptions): RMSAnalysisResult;

/**
 * FFT分析のオプション
 */
interface FFTOptions {
    /** FFTサイズ（デフォルト: 2048、2の累乗である必要があります） */
    fftSize?: number;
    /** ウィンドウ関数（デフォルト: 'hann'） */
    windowFunction?: WindowFunction;
    /** オーバーラップ率（デフォルト: 0.5） */
    overlap?: number;
    /** 解析するチャンネル（デフォルト: 0、-1で全チャンネルの平均） */
    channel?: number;
    /** FFTプロバイダー（デフォルト: 'native'） */
    provider?: FFTProviderType;
    /** プロファイリングを有効にする（WebFFTのみ） */
    enableProfiling?: boolean;
}
/**
 * スペクトラム解析のオプション
 */
interface SpectrumOptions extends FFTOptions {
    /** 最小周波数（Hz、デフォルト: 0） */
    minFrequency?: number;
    /** 最大周波数（Hz、デフォルト: ナイキスト周波数） */
    maxFrequency?: number;
    /** dB表示かどうか（デフォルト: true） */
    decibels?: boolean;
    /** 時間フレーム数（スペクトログラム用、デフォルト: 100） */
    timeFrames?: number;
}
/**
 * スペクトログラムデータ
 */
interface SpectrogramData {
    /** 時間軸（秒） */
    times: Float32Array;
    /** 周波数軸（Hz） */
    frequencies: Float32Array;
    /** 強度データ（時間 x 周波数） */
    intensities: Float32Array[];
    /** フレーム数 */
    timeFrames: number;
    /** 周波数ビン数 */
    frequencyBins: number;
}
/**
 * FFT分析結果
 */
interface FFTAnalysisResult extends FFTResult {
    /** FFTサイズ */
    fftSize: number;
    /** 使用されたウィンドウ関数 */
    windowFunction: string;
    /** プロバイダー名 */
    providerName: string;
}
/**
 * スペクトラム解析結果
 */
interface SpectrumAnalysisResult {
    /** 周波数（Hz） */
    frequencies: Float32Array;
    /** 強度 */
    magnitudes: Float32Array;
    /** dB値（decielsオプションがtrueの場合） */
    decibels?: Float32Array;
    /** スペクトログラム（timeFrames > 1の場合） */
    spectrogram?: SpectrogramData;
}
/**
 * FFT分析を行う
 *
 * @param audio - 音声データ
 * @param options - FFTオプション
 * @returns FFT結果
 */
declare function getFFT(audio: AudioData, options?: FFTOptions): Promise<FFTAnalysisResult>;
/**
 * スペクトラム解析を行う
 *
 * @param audio - 音声データ
 * @param options - スペクトラムオプション
 * @returns スペクトラム解析結果
 */
declare function getSpectrum(audio: AudioData, options?: SpectrumOptions): Promise<SpectrumAnalysisResult>;

/**
 * スペクトル特徴量のオプション
 */
interface SpectralFeaturesOptions {
    /** FFTサイズ */
    fftSize?: number;
    /** 窓関数 */
    windowFunction?: 'hann' | 'hamming' | 'blackman' | 'none';
    /** 解析するチャンネル */
    channel?: number;
    /** 最小周波数 */
    minFrequency?: number;
    /** 最大周波数 */
    maxFrequency?: number;
    /** スペクトルロールオフの閾値（0-1） */
    rolloffThreshold?: number;
}
/**
 * スペクトル特徴量の結果
 */
interface SpectralFeaturesResult {
    /** スペクトル重心（Hz） */
    spectralCentroid: number;
    /** スペクトル帯域幅（Hz） */
    spectralBandwidth: number;
    /** スペクトルロールオフ（Hz） */
    spectralRolloff: number;
    /** スペクトルフラットネス（0-1） */
    spectralFlatness: number;
    /** スペクトルフラックス */
    spectralFlux?: number;
    /** ゼロ交差率 */
    zeroCrossingRate: number;
    /** 使用された周波数範囲 */
    frequencyRange: {
        min: number;
        max: number;
    };
}
/**
 * 時系列スペクトル特徴量のオプション
 */
interface TimeVaryingSpectralOptions extends SpectralFeaturesOptions {
    /** フレームサイズ */
    frameSize?: number;
    /** ホップサイズ */
    hopSize?: number;
    /** フレーム数（指定しない場合は全体を解析） */
    numFrames?: number;
}
/**
 * 時系列スペクトル特徴量の結果
 */
interface TimeVaryingSpectralResult {
    /** 時間軸（秒） */
    times: Float32Array;
    /** スペクトル重心の時系列 */
    spectralCentroid: Float32Array;
    /** スペクトル帯域幅の時系列 */
    spectralBandwidth: Float32Array;
    /** スペクトルロールオフの時系列 */
    spectralRolloff: Float32Array;
    /** スペクトルフラットネスの時系列 */
    spectralFlatness: Float32Array;
    /** スペクトルフラックスの時系列 */
    spectralFlux: Float32Array;
    /** ゼロ交差率の時系列 */
    zeroCrossingRate: Float32Array;
    /** フレーム情報 */
    frameInfo: {
        frameSize: number;
        hopSize: number;
        numFrames: number;
    };
}
/**
 * スペクトルエントロピーのオプション
 */
interface SpectralEntropyOptions {
    /** FFTサイズ */
    fftSize?: number;
    /** 窓関数 */
    windowFunction?: 'hann' | 'hamming' | 'blackman' | 'none';
    /** 解析するチャンネル */
    channel?: number;
    /** 最小周波数 */
    minFrequency?: number;
    /** 最大周波数 */
    maxFrequency?: number;
}
/**
 * スペクトルエントロピーの結果
 */
interface SpectralEntropyResult {
    /** スペクトルエントロピー（ビット） */
    entropy: number;
    /** 正規化されたスペクトルエントロピー（0-1） */
    entropyNorm: number;
    /** 使用された周波数範囲 */
    frequencyRange: {
        min: number;
        max: number;
    };
}
/**
 * スペクトルクレストファクターのオプション
 */
interface SpectralCrestOptions {
    /** FFTサイズ */
    fftSize?: number;
    /** 窓関数 */
    windowFunction?: 'hann' | 'hamming' | 'blackman' | 'none';
    /** 解析するチャンネル */
    channel?: number;
    /** 最小周波数 */
    minFrequency?: number;
    /** 最大周波数 */
    maxFrequency?: number;
    /** dB値で返すかどうか */
    asDB?: boolean;
}
/**
 * スペクトルクレストファクターの結果
 */
interface SpectralCrestResult {
    /** スペクトルクレストファクター（線形） */
    crest: number;
    /** スペクトルクレストファクター（dB） */
    crestDB?: number;
    /** ピーク値 */
    peak: number;
    /** 平均値 */
    average: number;
    /** 使用された周波数範囲 */
    frequencyRange: {
        min: number;
        max: number;
    };
}
/**
 * 単一フレームのスペクトル特徴量を計算
 * @param audio 音声データ
 * @param options オプション
 * @returns スペクトル特徴量
 */
declare function getSpectralFeatures(audio: AudioData, options?: SpectralFeaturesOptions): Promise<SpectralFeaturesResult>;
/**
 * 時系列スペクトル特徴量を計算
 * @param audio 音声データ
 * @param options オプション
 * @returns 時系列スペクトル特徴量
 */
declare function getTimeVaryingSpectralFeatures(audio: AudioData, options?: TimeVaryingSpectralOptions): Promise<TimeVaryingSpectralResult>;
/**
 * スペクトルエントロピーを計算
 * @param audio 音声データ
 * @param options オプション
 * @returns スペクトルエントロピー
 */
declare function getSpectralEntropy(audio: AudioData, options?: SpectralEntropyOptions): Promise<SpectralEntropyResult>;
/**
 * スペクトルクレストファクターを計算
 * @param audio 音声データ
 * @param options オプション
 * @returns スペクトルクレストファクター
 */
declare function getSpectralCrest(audio: AudioData, options?: SpectralCrestOptions): Promise<SpectralCrestResult>;
/**
 * MFCCのオプション（拡張版）
 */
interface MFCCOptions {
    /** フレームサイズ（ミリ秒、デフォルト: 25） */
    frameSizeMs?: number;
    /** ホップサイズ（ミリ秒、デフォルト: 10） */
    hopSizeMs?: number;
    /** FFTサイズ（未指定時は自動計算） */
    fftSize?: number;
    /** 窓関数（'hann', 'hamming', 'blackman', 'rectangular'） */
    windowFunction?: WindowFunction;
    /** 解析するチャンネル */
    channel?: number;
    /** Melフィルタバンクの数（デフォルト: 40） */
    numMelFilters?: number;
    /** MFCC係数の数（デフォルト: 13） */
    numMfccCoeffs?: number;
    /** 最小周波数（Hz、デフォルト: 0） */
    minFrequency?: number;
    /** 最大周波数（Hz、デフォルト: サンプルレート/2） */
    maxFrequency?: number;
    /** プリエンファシス係数（デフォルト: 0.97） */
    preEmphasis?: number;
    /** ログのリフタリング係数（デフォルト: 22） */
    lifterCoeff?: number;
}
/**
 * MFCCの結果
 */
interface MFCCResult {
    /** MFCC係数（各行が時刻、各列が係数） */
    mfcc: number[][];
    /** 時間軸（秒） */
    times: Float32Array;
    /** フレーム情報 */
    frameInfo: {
        frameSizeMs: number;
        hopSizeMs: number;
        numFrames: number;
        numCoeffs: number;
    };
    /** 使用された周波数範囲 */
    frequencyRange: {
        min: number;
        max: number;
    };
}
/**
 * MFCC（Mel-Frequency Cepstral Coefficients）を計算
 * @param audio 音声データ
 * @param options オプション
 * @returns MFCC
 */
declare function getMFCC(audio: AudioData, options?: MFCCOptions): Promise<MFCCResult>;
/**
 * MFCCデルタ係数の拡張オプション
 */
interface MFCCDeltaOptions extends MFCCOptions {
    /** デルタ係数計算の窓サイズ（デフォルト: 2） */
    deltaWindowSize?: number;
    /** デルタ係数を計算するかどうか */
    computeDelta?: boolean;
    /** デルタデルタ係数を計算するかどうか */
    computeDeltaDelta?: boolean;
}
/**
 * MFCCデルタ係数の拡張結果
 */
interface MFCCDeltaResult extends MFCCResult {
    /** デルタ係数（計算された場合） */
    delta?: number[][];
    /** デルタデルタ係数（計算された場合） */
    deltaDelta?: number[][];
}
/**
 * AudioDataからMFCCとデルタ係数を統合計算
 * @param audio 音声データ
 * @param options オプション
 * @returns MFCC、デルタ係数、デルタデルタ係数
 */
declare function getMFCCWithDelta(audio: AudioData, options?: MFCCDeltaOptions): Promise<MFCCDeltaResult>;

interface EnergyOptions {
    frameSize?: number;
    hopSize?: number;
    channel?: number;
    normalized?: boolean;
    windowFunction?: 'rectangular' | 'hann' | 'hamming';
}
interface EnergyResult {
    times: Float32Array;
    energies: Float32Array;
    totalEnergy: number;
    statistics: {
        mean: number;
        std: number;
        max: number;
        min: number;
    };
}
declare function getEnergy(audio: AudioData, options?: EnergyOptions): EnergyResult;

interface CrestFactorOptions {
    channel?: number;
    windowSize?: number;
    hopSize?: number;
    method?: 'simple' | 'weighted';
}
interface CrestFactorResult {
    crestFactor: number;
    crestFactorLinear: number;
    peak: number;
    rms: number;
    timeVarying?: {
        times: Float32Array;
        values: Float32Array;
        valuesLinear: Float32Array;
        peaks: Float32Array;
        rmsValues: Float32Array;
    } | undefined;
}
declare function getCrestFactor(audio: AudioData, options?: CrestFactorOptions): CrestFactorResult;

interface StereoAnalysisOptions {
    frameSize?: number;
    hopSize?: number;
    calculatePhase?: boolean;
    calculateITD?: boolean;
    calculateILD?: boolean;
}
interface StereoAnalysisResult {
    correlation: number;
    coherence?: Float32Array;
    width: number;
    widthFrequency?: Float32Array;
    balance: number;
    phaseDifference?: number;
    phaseCorrelation?: number;
    midSideRatio: number;
    itd?: number;
    ild?: number;
    goniometer?: {
        x: Float32Array;
        y: Float32Array;
    };
}
declare function getStereoAnalysis(audio: AudioData, options?: StereoAnalysisOptions): Promise<StereoAnalysisResult>;
declare function getTimeVaryingStereoAnalysis(_audio: AudioData, _options?: StereoAnalysisOptions & {
    windowSize?: number;
}): Promise<{
    times: Float32Array;
    correlation: Float32Array;
    width: Float32Array;
    balance: Float32Array;
}>;

interface VADOptions {
    channel?: number;
    frameSizeMs?: number;
    hopSizeMs?: number;
    method?: 'energy' | 'zcr' | 'combined' | 'adaptive';
    energyThreshold?: number;
    zcrThresholdLow?: number;
    zcrThresholdHigh?: number;
    adaptiveAlpha?: number;
    noiseFactor?: number;
    minSilenceDurationMs?: number;
    minSpeechDurationMs?: number;
    preEmphasis?: boolean;
    smoothing?: boolean;
}
interface VADSegment {
    start: number;
    end: number;
    type: 'speech' | 'silence';
    confidence?: number;
}
interface VADResult {
    segments: VADSegment[];
    speechRatio: number;
    features?: {
        energies: Float32Array;
        zcrs: Float32Array;
        decisions: Float32Array;
        times: Float32Array;
    };
}
/**
 * VAD（音声区間検出）を実行
 */
declare function getVAD(audio: AudioData, options?: VADOptions): VADResult;

interface LUFSOptions {
    channelMode?: 'mono' | 'stereo';
    gated?: boolean;
    calculateShortTerm?: boolean;
    calculateMomentary?: boolean;
    calculateLoudnessRange?: boolean;
    calculateTruePeak?: boolean;
}
interface LUFSResult {
    integrated: number;
    shortTerm?: Float32Array;
    momentary?: Float32Array;
    loudnessRange?: number;
    truePeak?: number[];
    statistics?: {
        percentile10: number;
        percentile95: number;
    };
}
declare function getLUFS(audio: AudioData, options?: LUFSOptions): LUFSResult;
declare class RealtimeLUFSProcessor {
    private sampleRate;
    private channelMode;
    private blockSize;
    private hopSize;
    private blockBuffer;
    private maxBlocks;
    private currentSamples;
    private sampleCount;
    private biquadStates;
    private totalSamplesProcessed;
    constructor(sampleRate: number, channelMode?: 'mono' | 'stereo', maxDurationMs?: number);
    /**
     * 新しいオーディオチャンクを処理
     * @param chunk - 入力オーディオチャンク（チャンネルごとのFloat32Array配列）
     * @returns 現在のLUFS値（integrated, momentary, shortTerm）
     */
    process(chunk: Float32Array[]): {
        integrated: number;
        momentary: number;
        shortTerm: number;
    };
    /**
     * 現在の統合ラウドネスを計算
     */
    private calculateCurrentLUFS;
    /**
     * 状態をリセット
     */
    reset(): void;
    /**
     * 現在のブロックバッファ数を取得
     */
    getBufferSize(): number;
}
interface RealtimeLUFSOptions {
    channelMode?: 'mono' | 'stereo';
    maxDurationMs?: number;
}
/**
 * リアルタイムLUFS処理器を取得
 * @param sampleRate サンプルレート
 * @param options 処理オプション
 * @returns リアルタイムLUFS処理器
 */
declare function getLUFSRealtime(sampleRate: number, options?: RealtimeLUFSOptions): RealtimeLUFSProcessor;

export { type CrestFactorOptions, type CrestFactorResult, type EnergyOptions, type EnergyResult, type FFTAnalysisResult, type FFTOptions, type LUFSOptions, type LUFSResult, type MFCCDeltaOptions, type MFCCDeltaResult, type MFCCOptions, type MFCCResult, type Peak, type PeaksAnalysisOptions, type PeaksOptions, type PeaksResult, type RMSAnalysisOptions, type RealtimeLUFSOptions, type SpectralCrestOptions, type SpectralCrestResult, type SpectralEntropyOptions, type SpectralEntropyResult, type SpectralFeaturesOptions, type SpectralFeaturesResult, type SpectrogramData, type SpectrumAnalysisResult, type SpectrumOptions, type StereoAnalysisOptions, type StereoAnalysisResult, type TimeVaryingSpectralOptions, type TimeVaryingSpectralResult, type VADOptions, type VADResult, type VADSegment, type WaveformAnalysisOptions, type WaveformOptions, type WaveformPoint, type WaveformResult, getCrestFactor, getEnergy, getFFT, getLUFS, getLUFSRealtime, getMFCC, getMFCCWithDelta, getPeakAmplitude as getPeak, getPeakAmplitude, getPeaks, getPeaksAnalysis, getRMS, getRMSAnalysis, getSpectralCrest, getSpectralEntropy, getSpectralFeatures, getSpectrum, getStereoAnalysis, getTimeVaryingSpectralFeatures, getTimeVaryingStereoAnalysis, getVAD, getWaveform, getWaveformAnalysis, getZeroCrossing };