Release v0.3.2: add advanced codec options and worker reliability fixes

Author: romot-co

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-02-07
+
+### ✨ Added
+- Added advanced codec option support for WebCodecs:
+  - `video.codecString` / `audio.codecString`
+  - `video.quantizer`
+  - `video.avc.format` / `video.hevc.format`
+  - `audio.aac.format`
+- Exported codec option helper types for those advanced fields from the public API.
+
+### 🛠️ Improved
+- `canEncode()` now probes codec-specific configuration details (codec strings and codec-specific option blocks) for more accurate capability checks in Chrome/WebCodecs environments.
+- Worker initialization now applies and sanitizes codec-specific encoder overrides so only options valid for the selected codec are passed through.
+- Added configurable external worker URL support via `WEBCODECS_WORKER_URL` and `window.__WEBCODECS_WORKER_URL__`.
+
+### 🐛 Fixed
+- Fixed audio-only initialization to skip unnecessary video encoder setup and capability checks.
+- Fixed `AudioData` lifecycle handling to ensure internally created or provided audio frames are always closed after encode attempts.
+- Improved worker error forwarding so error handlers receive worker errors consistently even when handler registration is delayed.
+
+### 🧪 Tests
+- Expanded coverage for audio-only worker initialization, codec override parsing, capability probe option forwarding, and worker error propagation behavior.
+
+---
+
 ## [0.3.1] - 2025-09-22
 
 ### 🎧 Added

README.md

@@ -47,6 +47,7 @@ Inline worker controls:
 | `WEBCODECS_USE_INLINE_WORKER=true` or `window.__WEBCODECS_USE_INLINE_WORKER__ = true` | Force the inline mock (useful for Storybook, unit tests, etc.). |
 | `WEBCODECS_DISABLE_INLINE_WORKER=true` or `window.__WEBCODECS_DISABLE_INLINE_WORKER__ = true` | Always require the external worker. |
 | `WEBCODECS_ALLOW_INLINE_IN_PROD=true` or `window.__WEBCODECS_ALLOW_INLINE_IN_PROD__ = true` | Explicitly permit the inline mock on production builds (not recommended). |
+| `WEBCODECS_WORKER_URL=/assets/webcodecs-worker.js` or `window.__WEBCODECS_WORKER_URL__ = '/assets/webcodecs-worker.js'` | Override the external worker URL when your app is served from a sub-path/CDN. |
 
 > ⚠️ The inline worker is a **test stub** that returns placeholder bytes. Use it only for wiring/UI development. Real MP4/WebM output requires the external worker bundle.
 
@@ -213,18 +214,24 @@ interface EncodeOptions {
   /** Set to `false` for audio-only encoding. */
   video?: {
     codec?: 'avc' | 'hevc' | 'vp9' | 'vp8' | 'av1';
+    codecString?: string; // e.g. 'avc1.640028'
     bitrate?: number;
+    quantizer?: number;
+    avc?: { format?: 'annexb' | 'avc' };
+    hevc?: { format?: 'annexb' | 'hevc' };
     hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
     keyFrameInterval?: number;
   } | false;
 
   /** Set to `false` to disable audio. */
   audio?: {
     codec?: 'aac' | 'mp3' | 'opus' | 'vorbis' | 'flac';
+    codecString?: string; // e.g. 'mp4a.40.2'
     bitrate?: number;
     sampleRate?: number;
     channels?: number;
     bitrateMode?: 'constant' | 'variable';
+    aac?: { format?: 'aac' | 'adts' };
   } | false;
 
   container?: 'mp4' | 'webm';

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "webcodecs-encoder",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "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.",
   "homepage": "https://github.com/romot-co/webcodecs-encoder",
   "repository": {

package.json

@@ -17,6 +17,9 @@ export type {
   QualityPreset,
   VideoConfig,
   AudioConfig,
+  AvcBitstreamFormatOption,
+  HevcBitstreamFormatOption,
+  AacBitstreamFormatOption,
   ProgressInfo,
   EncodeErrorType,
   VideoFile,

src/index.ts

@@ -19,10 +19,29 @@ export type VideoSource =
 // Quality presets
 export type QualityPreset = 'low' | 'medium' | 'high' | 'lossless';
 
+export type AvcBitstreamFormatOption = "annexb" | "avc";
+export type HevcBitstreamFormatOption = "annexb" | "hevc";
+export type AacBitstreamFormatOption = "aac" | "adts";
+
 // Video configuration
 export 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;
@@ -41,10 +60,16 @@ export type AudioCodec =
 
 export 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;
+  };
 }
 
 // Progress information

src/types.ts

@@ -36,19 +36,28 @@ export async function canEncode(options?: EncodeOptions): Promise<boolean> {
       }
     }
 
-    // Check audio configuration (only if audio is explicitly specified)
+    // Check audio configuration
     const hasAudioConfig = options.audio && typeof options.audio === "object";
-    if (hasAudioConfig) {
-      const audioCodec = (options.audio as AudioConfig).codec || "aac";
-      const audioSupported = await testAudioCodecSupport(audioCodec, options);
-      if (!audioSupported) {
-        return false;
-      }
-    } else if (options.audio === undefined && !hasVideoConfig) {
-      // Only check audio for default configuration
-      const audioSupported = await testAudioCodecSupport("aac", options);
-      if (!audioSupported) {
-        return false;
+    const audioEnabled = options.audio !== false;
+    if (audioEnabled) {
+      if (hasAudioConfig) {
+        const audioCodec = (options.audio as AudioConfig).codec || "aac";
+        const audioSupported = await testAudioCodecSupport(audioCodec, options);
+        if (!audioSupported) {
+          return false;
+        }
+      } else {
+        const fallbackCodecs = getDefaultAudioProbeOrder(options.container);
+        let foundSupportedAudioCodec = false;
+        for (const codec of fallbackCodecs) {
+          if (await testAudioCodecSupport(codec, options)) {
+            foundSupportedAudioCodec = true;
+            break;
+          }
+        }
+        if (!foundSupportedAudioCodec) {
+          return false;
+        }
       }
     }
 
@@ -128,12 +137,14 @@ async function testVideoCodecSupport(
   try {
     const videoOptions =
       options?.video && typeof options.video === "object" ? options.video : {};
-    const codecString = getVideoCodecString(
-      codec,
-      options?.width || 640,
-      options?.height || 480,
-      options?.frameRate || 30,
-    );
+    const codecString =
+      videoOptions.codecString ||
+      getVideoCodecString(
+        codec,
+        options?.width || 640,
+        options?.height || 480,
+        options?.frameRate || 30,
+      );
     const config: VideoEncoderConfig = {
       codec: codecString,
       width: options?.width || 640,
@@ -151,6 +162,16 @@ async function testVideoCodecSupport(
       config.latencyMode = videoOptions.latencyMode;
     }
 
+    if (typeof videoOptions.quantizer === "number") {
+      (config as any).quantizer = videoOptions.quantizer;
+    }
+    if (codec === "avc" && videoOptions.avc?.format) {
+      (config as any).avc = { format: videoOptions.avc.format };
+    }
+    if (codec === "hevc" && videoOptions.hevc?.format) {
+      (config as any).hevc = { format: videoOptions.hevc.format };
+    }
+
     const support = await VideoEncoder.isConfigSupported(config);
     return support.supported || false;
   } catch {
@@ -166,9 +187,9 @@ async function testAudioCodecSupport(
   options?: EncodeOptions,
 ): Promise<boolean> {
   try {
-    const codecString = getAudioCodecString(codec);
     const audioOptions =
       typeof options?.audio === "object" ? options.audio : {};
+    const codecString = audioOptions.codecString || getAudioCodecString(codec);
 
     const isTelephonyCodec = codec === "ulaw" || codec === "alaw";
     const isPcmCodec = codec === "pcm";
@@ -204,6 +225,9 @@ async function testAudioCodecSupport(
     if (codec === "aac" && audioOptions.bitrateMode) {
       (config as any).bitrateMode = audioOptions.bitrateMode;
     }
+    if (codec === "aac" && audioOptions.aac?.format) {
+      (config as any).aac = { format: audioOptions.aac.format };
+    }
 
     const support = await AudioEncoder.isConfigSupported(config);
     return support.supported || false;
@@ -341,6 +365,15 @@ function getAudioCodecString(codec: string): string {
   }
 }
 
+function getDefaultAudioProbeOrder(
+  container?: EncodeOptions["container"],
+): string[] {
+  if (container === "webm") {
+    return ["opus", "vorbis", "flac"];
+  }
+  return ["aac", "mp3"];
+}
+
 /**
  * Check support for specific codec and profile (for advanced users)
  */

src/utils/can-encode.ts

@@ -214,46 +214,63 @@ function applyQualityPreset(
  * EncodeOptionsから内部のEncoderConfigに変換
  */
 function convertToEncoderConfig(options: EncodeOptions): EncoderConfig {
+  const videoOptions =
+    options.video && typeof options.video === "object" ? options.video : null;
+
   const config: EncoderConfig = {
     width: options.video === false ? 0 : options.width || 640,
     height: options.video === false ? 0 : options.height || 480,
     frameRate: options.frameRate || 30,
     videoBitrate:
-      options.video === false
-        ? 0
-        : (options.video as any)?.bitrate || 1_000_000,
+      options.video === false ? 0 : videoOptions?.bitrate || 1_000_000,
     audioBitrate: 0,
     sampleRate: 0,
     channels: 0,
     container: options.container || "mp4",
     codec: {
-      video:
-        options.video === false
-          ? undefined
-          : (options.video as any)?.codec || "avc",
+      video: options.video === false ? undefined : videoOptions?.codec || "avc",
       audio: undefined,
     },
     latencyMode:
       options.video === false
         ? "quality"
-        : options.latencyMode ||
-          (options.video as any)?.latencyMode ||
-          "quality",
+        : options.latencyMode || videoOptions?.latencyMode || "quality",
     hardwareAcceleration:
       options.video === false
         ? "no-preference"
-        : (options.video as any)?.hardwareAcceleration || "no-preference",
+        : videoOptions?.hardwareAcceleration || "no-preference",
     keyFrameInterval:
-      options.video === false
-        ? undefined
-        : (options.video as any)?.keyFrameInterval,
+      options.video === false ? undefined : videoOptions?.keyFrameInterval,
     audioBitrateMode: undefined,
     firstTimestampBehavior: options.firstTimestampBehavior || "offset",
     maxVideoQueueSize: options.maxVideoQueueSize || 30,
     maxAudioQueueSize: options.maxAudioQueueSize || 30,
     backpressureStrategy: options.backpressureStrategy || "drop",
   };
 
+  if (options.video !== false && videoOptions?.codecString) {
+    config.codecString = {
+      ...(config.codecString ?? {}),
+      video: videoOptions.codecString,
+    };
+  }
+
+  if (options.video !== false && videoOptions) {
+    const videoEncoderConfig: Partial<VideoEncoderConfig> = {};
+    if (typeof videoOptions.quantizer === "number") {
+      (videoEncoderConfig as any).quantizer = videoOptions.quantizer;
+    }
+    if (config.codec?.video === "avc" && videoOptions.avc?.format) {
+      (videoEncoderConfig as any).avc = { format: videoOptions.avc.format };
+    }
+    if (config.codec?.video === "hevc" && videoOptions.hevc?.format) {
+      (videoEncoderConfig as any).hevc = { format: videoOptions.hevc.format };
+    }
+    if (Object.keys(videoEncoderConfig).length > 0) {
+      config.videoEncoderConfig = videoEncoderConfig;
+    }
+  }
+
   if (options.audio !== false) {
     const audioOptions = (options.audio as any) || {};
     const requestedCodec = (audioOptions.codec || "aac") as any;
@@ -292,6 +309,21 @@ function convertToEncoderConfig(options: EncodeOptions): EncoderConfig {
     config.audioBitrateMode =
       audioOptions.bitrateMode ||
       (requestedCodec === "aac" ? "variable" : "constant");
+
+    if (audioOptions.codecString) {
+      config.codecString = {
+        ...(config.codecString ?? {}),
+        audio: audioOptions.codecString,
+      };
+    }
+
+    const audioEncoderConfig: Partial<AudioEncoderConfig> = {};
+    if (requestedCodec === "aac" && audioOptions.aac?.format) {
+      (audioEncoderConfig as any).aac = { format: audioOptions.aac.format };
+    }
+    if (Object.keys(audioEncoderConfig).length > 0) {
+      config.audioEncoderConfig = audioEncoderConfig;
+    }
   }
 
   if (options.audio === false) {