webcodecs-encoder
Version:
A TypeScript library for browser environments to encode video (H.264/AVC, VP9, VP8) and audio (AAC, Opus) using the WebCodecs API and mux them into MP4 or WebM containers with real-time streaming support. New function-first API design.
108 lines (104 loc) • 3.7 kB
TypeScript
type QualityPreset = 'low' | 'medium' | 'high' | 'lossless';
type AvcBitstreamFormatOption = "annexb" | "avc";
type HevcBitstreamFormatOption = "annexb" | "hevc";
type AacBitstreamFormatOption = "aac" | "adts";
interface VideoConfig {
codec?: 'avc' | 'hevc' | 'vp9' | 'vp8' | 'av1';
/** Override codec string passed to VideoEncoder (e.g. "avc1.640028"). */
codecString?: string;
bitrate?: number;
/**
* Optional quantizer hint. Browser support varies by codec/platform.
* When set, it is forwarded to VideoEncoderConfig.
*/
quantizer?: number;
/** AVC-specific options. */
avc?: {
format?: AvcBitstreamFormatOption;
};
/** HEVC-specific options. */
hevc?: {
format?: HevcBitstreamFormatOption;
};
hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
latencyMode?: 'quality' | 'realtime';
keyFrameInterval?: number;
}
type AudioCodec = 'aac' | 'opus' | 'flac' | 'mp3' | 'vorbis' | 'pcm' | 'ulaw' | 'alaw';
interface AudioConfig {
codec?: AudioCodec;
/** Override codec string passed to AudioEncoder (e.g. "mp4a.40.2"). */
codecString?: string;
bitrate?: number;
sampleRate?: number;
channels?: number;
bitrateMode?: 'constant' | 'variable';
/** AAC-specific options. */
aac?: {
format?: AacBitstreamFormatOption;
};
}
interface ProgressInfo {
percent: number;
processedFrames: number;
totalFrames?: number;
fps: number;
stage: string;
estimatedRemainingMs?: number;
}
interface EncodeOptions {
width?: number;
height?: number;
frameRate?: number;
quality?: QualityPreset;
video?: VideoConfig | false;
audio?: AudioConfig | false;
container?: 'mp4' | 'webm';
firstTimestampBehavior?: "offset" | "strict";
latencyMode?: "quality" | "realtime";
maxVideoQueueSize?: number;
maxAudioQueueSize?: number;
backpressureStrategy?: "drop" | "wait";
onProgress?: (progress: ProgressInfo) => void;
onError?: (error: EncodeError) => void;
}
type EncodeErrorType = 'not-supported' | 'initialization-failed' | 'configuration-error' | 'invalid-input' | 'encoding-failed' | 'video-encoding-error' | 'audio-encoding-error' | 'muxing-failed' | 'cancelled' | 'timeout' | 'worker-error' | 'filesystem-error' | 'unknown';
declare class EncodeError extends Error {
type: EncodeErrorType;
cause?: unknown;
constructor(type: EncodeErrorType, message: string, cause?: unknown);
}
/**
* Encode capability verification
*/
/**
* Verify encode capability
*
* @param options Encode options
* @returns Whether encoding is possible
*/
declare function canEncode(options?: EncodeOptions): Promise<boolean>;
/**
* Dynamically generate AVC (H.264) codec string
* Uses same logic as encoder-worker.ts
*/
declare function generateAvcCodecString(width: number, height: number, frameRate: number, profile?: "high" | "main" | "baseline"): string;
/**
* Try multiple AVC profiles and return the first supported one
*/
declare function generateSupportedAvcCodecString(width: number, height: number, frameRate: number, bitrate: number, preferredProfile?: "high" | "main" | "baseline"): Promise<string | null>;
/**
* Check support for specific codec and profile (for advanced users)
*/
declare function canEncodeWithProfile(videoCodec: string, audioCodec?: string, profile?: {
width: number;
height: number;
framerate: number;
videoBitrate: number;
audioBitrate?: number;
}): Promise<{
video: boolean;
audio: boolean;
overall: boolean;
}>;
export { canEncode, canEncodeWithProfile, generateAvcCodecString, generateSupportedAvcCodecString };