Release v0.3.1: Enhanced configuration validation and error handling

- Add comprehensive config parser validation with detailed error messages
- Improve encoder factory with better browser compatibility checks
- Enhance worker communication with structured message handling
- Add frame drop detection and recovery in encoder worker
- Improve stream encoding with robust error handling
- Add config-parser test suite for validation coverage
- Update dependencies and improve type definitions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: romot-co

CHANGELOG.md

@@ -5,6 +5,27 @@ 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.1] - 2025-09-22
+
+### 🎧 Added
+- Expanded audio codec coverage to include FLAC, MP3, Vorbis, linear PCM, and μ-law/A-law, with capability probing via `AudioEncoder.isConfigSupported()` and worker fallbacks when a codec is unavailable.
+
+### 🛠️ Improved
+- The configuration parser now infers codec-specific defaults (bitrate, sample rate, channels) without forcing inappropriate values onto PCM or telephony codecs.
+- `canEncode` and the MP4/WebM muxers share stricter compatibility checks so unsupported codec/container combinations are rejected before encoding begins.
+- VideoFile sources read metadata up front, align the encoder resolution, and scale frames when necessary to avoid width/height mismatches.
+- Worker creation prefers external worker scripts; the inline mock worker is now opt-in for development and tests only.
+
+### 🐛 Fixed
+- Preserved `video: false` and `audio: false` flags when merging options, restoring audio-only workflows.
+- Delayed muxer construction until after codec fallbacks complete, ensuring muxers match the actual encoder configuration.
+- MediaStream tracks are no longer stopped automatically during cleanup, leaving ownership with the caller.
+
+### 🧪 Tests
+- Extended coverage across async iterable safety, audio codec probing, worker initialization paths, and configuration merging edge cases.
+
+---
+
 ## [0.3.0] - 2025-08-07
 
 ### 💥 BREAKING CHANGES
@@ -141,4 +162,4 @@ Key areas improved:
 - Support for AAC, Opus audio codecs  
 - MP4 and WebM container formats
 - WebCodecs API integration
-- TypeScript support
+- TypeScript support

README.md

@@ -5,7 +5,7 @@ Function-First API to encode video and audio using WebCodecs API.
 [![CI](https://github.com/romot-co/webcodecs-encoder/actions/workflows/ci.yml/badge.svg)](https://github.com/romot-co/webcodecs-encoder/actions/workflows/ci.yml)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/webcodecs-encoder)](https://bundlephobia.com/result?p=webcodecs-encoder)
 
-A TypeScript library 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 a simple.
+A TypeScript library to encode video (H.264/AVC, HEVC, VP9, VP8, AV1) and audio (AAC, MP3, Opus, Vorbis, FLAC) using the WebCodecs API and mux them into MP4 or WebM containers with a simple, function-first API.
 
 ## Features
 
@@ -17,7 +17,7 @@ A TypeScript library to encode video (H.264/AVC, VP9, VP8) and audio (AAC, Opus)
 - **🎨 Progressive Enhancement**: Start simple, add complexity as needed
 - **📦 Optimized Bundle Size**: Tree-shakable with ES Modules and `sideEffects: false` for efficient bundling.
 - **🛡️ Type Safety**: Full TypeScript support with comprehensive types
-- **🎵 Audio Support**: AAC and Opus encoding with automatic configuration
+- **🎵 Audio Support**: Automatic AAC↔MP3 fallback for MP4 and Opus/Vorbis/FLAC support for WebM
 - **🎤 Audio-Only Encoding**: Support for `video: false` option (v0.2.2)
 - **📹 VideoFile Audio**: Extract and encode audio from video files (v0.2.2)
 - **⚡ Performance Optimized**: Transferable objects for faster data transfer (v0.2.2)
@@ -32,15 +32,59 @@ yarn add webcodecs-encoder
 
 ### Worker Setup
 
-A dedicated Web Worker (**webcodecs-worker.js**) must be reachable at the site root (default: `/webcodecs-worker.js`). The library falls back to an inline worker only in test environments; in production, the external file **is mandatory for security reasons**.
+The encoder runs inside a dedicated Web Worker (`/webcodecs-worker.js`). Ship that file with your app and ensure it is publicly reachable at the site root.
 
-You need to copy the worker file from `node_modules` to your public directory.
+By default the library:
+
+- **Prefers the external worker** in browsers and production builds.
+- **Falls back to an inline mock** only when running under known test runners (Vitest, Jest, `NODE_ENV=test`) or when you explicitly opt in.
+- **Never uses the inline mock in production** unless you override the safety check.
+
+Inline worker controls:
+
+| Flag | Effect |
+| --- | --- |
+| `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). |
+
+> ⚠️ 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.
+
+Copy the worker file from `node_modules` into your public assets directory during build/deploy:
 
 ```bash
 # Example for a Next.js/Vite project with a 'public' directory
 cp node_modules/webcodecs-encoder/dist/webcodecs-worker.js public/
 ```
 
+#### Example: Vite + TypeScript
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import copy from 'rollup-plugin-copy';
+
+export default defineConfig({
+  plugins: [
+    copy({
+      targets: [
+        {
+          src: 'node_modules/webcodecs-encoder/dist/webcodecs-worker.js',
+          dest: 'public'
+        }
+      ]
+    })
+  ]
+});
+```
+
+```ts
+// main.ts (development helper)
+if (import.meta.env.DEV) {
+  window.__WEBCODECS_USE_INLINE_WORKER__ = true;
+}
+```
+
 ## Quick Start
 
 ### Basic Encoding
@@ -176,7 +220,7 @@ interface EncodeOptions {
 
   /** Set to `false` to disable audio. */
   audio?: {
-    codec?: 'aac' | 'opus';
+    codec?: 'aac' | 'mp3' | 'opus' | 'vorbis' | 'flac';
     bitrate?: number;
     sampleRate?: number;
     channels?: number;
@@ -225,17 +269,25 @@ interface EncodeOptions {
 interface ProgressInfo {
   /** Percentage of completion (0-100) */
   percent: number;
+  /** Total number of frames processed */
+  processedFrames: number;
+  /** Total number of frames to encode (if known) */
+  totalFrames?: number;
   /** Current encoding speed in frames per second */
   fps: number;
-  /** Total number of frames processed */
-  frameCount: number;
-  /** Total number of frames to encode */
-  totalFrameCount: number;
+  /** Current stage label ("streaming", "finalizing", etc.) */
+  stage: string;
   /** Estimated remaining time in milliseconds */
   estimatedRemainingMs?: number;
 }
 ```
 
+> **Audio codec compatibility**
+>
+> - `container: 'mp4'` supports `aac` (default) and automatically falls back to `mp3` if AAC isn’t available.
+> - `container: 'webm'` supports `opus` (default) with `vorbis` and `flac` as fallbacks.
+> - Other codec hints are treated as best-effort; if they can’t be muxed into the requested container the encoder switches to the first compatible alternative.
+
 ### Real-time MediaStream Recording
 
 Use `encodeStream()` for real-time recording from camera, microphone, or screen sharing. This provides progressive encoding with streaming output:
@@ -546,7 +598,6 @@ for (const chunk of chunks) {
 - **Better tree-shaking**: Smaller bundle sizes with function imports
 - **Streaming support**: Real-time chunk processing
 - **Memory efficiency**: Progressive encoding without buffering entire video
-- **Cancellation**: Built-in AbortController support
 - **Error handling**: Standard async/await error handling
 
 #### Common Migration Patterns
@@ -572,12 +623,16 @@ encodeStream(stream, { onProgress })
 **Cancellation**:
 ```typescript
 // Before: recorder.cancel()
-// After: AbortController
-const controller = new AbortController();
-encodeStream(stream, { signal: controller.signal });
-controller.abort(); // Cancel encoding
+// After: Stop MediaStream tracks or break out of the loop
+const stopRecording = () => {
+  stream.getTracks().forEach(track => track.stop());
+};
+
+setTimeout(stopRecording, 5000);
 ```
 
+> The current implementation does not accept an `AbortSignal`. To cancel `encode` / `encodeStream`, stop the MediaStream tracks or end the async generator manually.
+
 See [`examples/realtime-mediastream.ts`](examples/realtime-mediastream.ts) for complete examples.
 
 ## Changelog

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "webcodecs-encoder",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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": {