Audio types

export interface ToneOptions {
    frequency?: number;
    durationSeconds?: number;
    sampleRate?: number;
    volume?: number;
    attackSeconds?: number;
    releaseSeconds?: number;
}

export interface WavEncodingOptions {
    sampleFormat?: "pcm16" | "float32";
}

export interface CompiledAudioClip {
    trackId: string;
    clip: StudioAudioClip;
    startSample: TimeConversion;
    sampleCount: TimeConversion;
    fadeInSamples: TimeConversion;
    fadeOutSamples: TimeConversion;
}

export type AudioSampleRounding = "nearest" | "exact";

export interface AudioGainRamp {
    startSample: number;
    endSample: number;
    from: number;
    to: number;
}

export interface ConformedAudioSegment {
    ownerId: string;
    editorialClipId?: string;
    audio: CompiledAudioClip;
    outputStartSample: number;
    clipOffsetSamples: number;
    sampleCount: number;
    ramps: AudioGainRamp[];
}

export interface AudioConform {
    rounding?: AudioSampleRounding;
    trackSelection?: AudioTrackRef[];
    sampleRate: number;
    duration: TimeConversion;
    segments: ConformedAudioSegment[];
    windows: {
        clipId: string;
        sourceStart: TimeConversion;
        outputStart: TimeConversion;
        outputEnd: TimeConversion;
        /** Present when source playback begins after an initial silent picture hold. */
        playbackStart?: TimeConversion;
        sourceLimit: TimeConversion;
    }[];
    transitions: "sum" | "linear";
}

export interface AudioDecodeRequest {
    assetId: string;
    sourceSampleRate: number;
    startSample: number;
    sampleCount: number;
    outputSampleRate: number;
    outputSampleCount: number;
    signal?: AbortSignal;
}

/** Return trimmed/resampled mono or stereo PCM; the adapter must verify source rate and range. */
export type StudioAudioDecoder = (request: AudioDecodeRequest) => Promise<Float32Array[]>;

export interface AudioMixOptions {
    rounding?: AudioSampleRounding;
    range?: {
        startSample: number;
        endSample: number;
    };
    tracks?: readonly AudioTrackRef[];
    sampleRate?: number;
    maxSamples?: number;
    signal?: AbortSignal;
}

export interface AudioMixResult {
    range: {
        startSample: number;
        endSample: number;
    };
    sampleRate: number;
    channels: [
        Float32Array,
        Float32Array
    ];
    peak: number;
    clippedSamples: number;
    conform: AudioConform;
}

export interface AudioTrackRef {
    ownerId: string;
    trackId: string;
}

export interface FFmpegAudioDecoderOptions {
    ffmpegPath?: string;
    ffprobePath?: string;
    timeoutMs?: number;
    maxAssetBytes?: number;
}