@grundyjs/canvas-take 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 — 2026-11-02
+
+- Add offline video export through `/video` with caller-selected encoder/muxer factories, explicit frame/sample timing, prepared PCM, progress, bounded queues, limits and cancellation-safe resource ownership.
+- Add separate WebCodecs H.264 Baseline, AAC-LC WASM Worker and MP4 adapters. Support 44.1/48 kHz mono/stereo audio, packet-derived priming, MP4 edit lists and final sample trimming; document decoder padding behavior, timebase precision, runtime assets and bundled licenses.
+- Add recording `pause()`/`resume()`, a pause-aware `maxDurationMs`, the `finished` promise and `stopReason`, plus an audio/video browser example.
+- Add GIF `maxFramePixels`, `maxFrames` and `maxDurationMs` limits, checked before readback, with terminal cleanup and actionable retry controls in the example.
+- Skip blending for fully opaque GIF pixels. Add reproducible sync/Worker benchmarks, opacity scenes and paired gradient-regression tools/results, including measurement-noise caveats.
+- Verify actual H.264/AAC and WebM recordings, offline MP4 sample counts and A/V markers with independent FFmpeg decoding, cancellation/retry, packed TypeScript consumers and browser CI. Add a packed-package 1080×1920 H.264/AAC release smoke test.
+
+## 0.4.1 — 2026-10-28
+
+- Correct package homepage to the CanvasTake page; refresh package description, keywords and English/Russian README navigation and test instructions.
+
+- Browser CI tests in Chromium and Firefox exercise the real GIF module Worker, cancellation and a fresh export on the same page. Downloaded GIFs are independently decoded to verify pixels, dimensions, frame timings and loop count.
+
 ## 0.4.0 — 2026-10-26
 
 - Ready-made `gif/worker` adapter with a dedicated module Worker, transferable frames, request timeouts and cleanup on completion/cancellation/errors.

package/README.md

@@ -2,7 +2,9 @@
 
 [Русский](ru/README.md)
 
-Independent TypeScript library for HTML canvas video recording with optional audio tracks and offline GIF export through a separate entry point. No external runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
+[Website](https://grundyjs.ru/en/canvas-take/) · [npm](https://www.npmjs.com/package/@grundyjs/canvas-take) · [Issues](https://github.com/urffin/canvas-take/issues)
+
+Independent TypeScript library for HTML canvas recording with audio, offline H.264/AAC MP4 and GIF export through separate entry points. ESM with TypeScript declarations, no external runtime npm dependencies or dependency on AlgiViz. CanvasTake source is MIT licensed; optional adapters include [Mediabunny MPL-2.0](docs/offline-video-adapters.md#distribution-and-sources) and [AAC WASM / FFmpeg LGPL components](docs/offline-aac.md#distribution-and-source). The package does not start or draw your animation.
 
 ## Install
 
@@ -25,9 +27,9 @@ recorder.dispose();
 
 `start` resolves after the MediaRecorder start event. `stop` waits for the final dataavailable and stop events; repeated calls return the same promise. Errors reject pending operations, stop owned tracks and release chunks. `dispose` cancels an unfinished recording; it is idempotent. Each instance records once. State stays idle while start is pending; a second start is rejected.
 
-Auto format order: WebM VP9, VP8, generic WebM, MP4. With audio, the VP9 and VP8 candidates include Opus. An explicit unsupported MIME fails without silently changing the format. The result reports the actual MIME and matching extension. FPS and bitrate are targets, not guarantees. durationMs measures recording wall time, not parsed file duration.
+Auto format order: WebM VP9, VP8, generic WebM, MP4. With audio, the VP9 and VP8 candidates include Opus. An explicit unsupported MIME fails without silently changing the format. The result reports the actual MIME and matching extension. FPS and bitrate are targets, not guarantees. `durationMs` measures active recording time, excluding pauses; it is not parsed file duration.
 
-Keep canvas bitmap dimensions fixed from start until stop. CSS scaling is allowed. Size changes fail the recording. Canvas must remain origin-clean. No screen capture, pause, frame-by-frame encoding or server upload. Chunks are retained in memory: the caller should limit duration. If background-tab throttling is unacceptable, the caller should dispose when the page becomes hidden. Codec support depends on the browser and available resources.
+Keep canvas bitmap dimensions fixed from start until stop, including while paused. CSS scaling is allowed. Size changes fail the recording. Canvas must remain origin-clean. The video recorder does not support screen capture, frame-by-frame video encoding or server upload. Chunks are retained in memory: use a duration limit or stop explicitly. If background-tab throttling is unacceptable, the caller should dispose when the page becomes hidden. Codec support depends on the browser and available resources.
 
 Development: Node.js 22+, `npm install`, `npm test`, `npm pack`. ESM and declarations are emitted to dist. `npm pack` rebuilds automatically; `npm publish` runs tests before packing. The integration example expects AlgiViz in a sibling directory and is served by the included local server.
 
@@ -42,8 +44,36 @@ MediaRecorder WebM output may omit duration metadata: playback can work while th
 | `videoBitsPerSecond` | Optional positive finite encoder bitrate target |
 | `mimeType` | Optional explicit supported `video/webm` or `video/mp4` MIME, including codecs |
 | `audioTracks` | Optional readonly list of live audio `MediaStreamTrack`s; omitted or empty records silently |
+| `maxDurationMs` | Since 0.5.0: optional positive safe integer; active-time budget in ms, excluding pauses |
+
+`stop()` returns `{ blob, mimeType, extension, durationMs, stopReason }` (`stopReason` is available since 0.5.0). Keep the recorder in a try/finally and call `dispose()` even if your animation fails. Revoke object URLs when no longer needed.
+
+### Pause, resume and active-time limit (since 0.5.0)
+
+```js
+const recorder = createCanvasRecorder(canvas, { fps: 30, maxDurationMs: 30_000 });
+try {
+    await recorder.start();
+    // In your UI handlers: await recorder.pause(); await recorder.resume();
+    const result = await recorder.finished;
+    // finished waits for automatic completion; calling stop() would stop immediately.
+    console.log(result.stopReason, result.durationMs); // 'duration-limit' or 'manual'
+} finally {
+    recorder.dispose();
+}
+```
+
+`pause()` and `resume()` resolve after their native events. State changes between `recording` and `paused` at those events; the native recorder can change state earlier. Repeated calls toward the current stable state succeed without further action; repeated calls to the same pending operation return the same promise. An opposite operation while one is pending rejects. Calls before start completes, during stopping, or after completion/disposal reject. Stopping from a pause succeeds. Stopping, disposal or failure rejects an unfinished pause/resume operation; normal stopping still produces the final video.
+
+`finished` is a stable promise available from creation. It resolves with the final result on manual or automatic completion, and rejects on failure/disposal. `stop()` remains idempotent and returns that same result. `stopReason` is `manual` or `duration-limit`, according to the first stop request. Without `maxDurationMs` there is no automatic stop. Invalid limits throw before capture; supplied limits are snapshotted at creation.
 
-`stop()` returns `{ blob, mimeType, extension, durationMs }`. Keep the recorder in a try/finally and call `dispose()` even if your animation fails. Revoke object URLs when no longer needed.
+The budget starts at the start event, stops counting at the pause event, and resumes at the resume event. The limit requests normal stopping and retains the final chunk; it does not discard the recording. Timers, event delivery and encoding can be delayed, so this is not a frame-exact file-duration cap. The active time reported in `durationMs` can exceed the requested limit under load. Pause/stop never stop caller-owned audio tracks or pause your animation/narration source; coordinate those separately if their timeline should pause too. Owned capture tracks and audio clones are stopped, and timers/listeners/chunks released, on completion, failure or disposal.
+
+Build and serve `examples/video.html` with the example server for format selection, a generated tone, pause/resume, manual stop, an active-time limit, preview and download. Browser tests record and play real WebM and supported H.264/AAC MP4, check decoded audio, pause exclusion and track ownership; unavailable codecs are explicitly skipped. Native event behavior is specified by [MediaStream Recording](https://www.w3.org/TR/mediastream-recording/#methods).
+
+The [video verification notes](docs/video-recording.md) describe six flash/beep markers across two pauses, independent FFmpeg decoding with container timestamps, and a negative control with intentionally delayed audio. FFmpeg is a development-only dependency.
+
+Initial captured video material can precede the native start event, especially while an audio engine starts. The active-time budget does not trim such startup material from the file; file duration can therefore include additional startup time as well as finalization delay.
 
 ## Record with narration
 
@@ -90,6 +120,25 @@ For a browser smoke test, run `node examples/server.cjs` after building and open
 
 The audio track list is copied at creation and validated again at start. CanvasTake clones the tracks at start and stops only its clones and canvas capture tracks on completion, disposal or failure. The caller owns the original tracks and AudioContext. Unexpected termination of a recorded clone fails recording. Calling `stop()` on an original track does not stop its clone; call `recorder.stop()` to finish the recording. Finishing an AudioBufferSource does not end the destination track either.
 
+## Offline video controller (since 0.5.0)
+
+`@grundyjs/canvas-take/video` exports `createOfflineVideoExporter` and adapter contracts for offline frame/audio timelines. Supply separate encoder and muxer factories. Optional `/video/webcodecs` (`createWebCodecsVideoEncoder`), `/video/aac` (`createAacAudioEncoder`) and `/video/mp4` (`createMp4Muxer`) entries export real **H.264 Baseline / AAC-LC MP4**, with optional prepared PCM audio. Video requires native WebCodecs support; AAC runs in a dedicated Worker using a bundled libavcodec WASM backend, including where native AAC encoding is unavailable. Independent FFmpeg decoding checks sample counts, priming, padding and A/V timing.
+
+```js
+import { createOfflineVideoExporter } from '@grundyjs/canvas-take/video';
+// options supplies video.encoder/config, optional prepared audio, and muxer.
+const exporter = await createOfflineVideoExporter(options);
+try {
+    drawFrame(0);
+    await exporter.addFrame(canvas, { timestampUs: 0, durationUs: 33_333 });
+    const result = await exporter.finish();
+} finally {
+    exporter.dispose();
+}
+```
+
+Frames form a contiguous timeline from zero in integer microseconds; durations and audio sample positions do not depend on encoding speed. The controller snapshots inputs, limits queues, serializes muxing and releases owned adapters on completion/failure/abort. Audio uses an explicit strict or trim/pad policy. See [real adapters, usage and timing precision](docs/offline-video-adapters.md), [AAC delay and sample-count verification](docs/offline-aac.md), the [runnable example](examples/offline-video.html) and [API details](docs/offline-video-api.md). Video boundaries use 57,600 Hz ticks; audio uses sample positions, a priming edit and a shortened final sample duration. MP4 presentation length excludes AAC padding; raw decoders that return full AAC frames must apply the container endpoint.
+
 ## Offline GIF export
 
 Available since version 0.3.0.
@@ -158,7 +207,33 @@ The default Worker URL is resolved relative to the adapter module. For direct br
 
 Progress works with every encoder, not just the Worker adapter. Immutable snapshots arrive after each completed frame (`encoding`), before finishing (`finalizing`), and at `finished`, `failed`, `aborted` or unfinished `disposed`. `framesEncoded` and `durationMs` include only successfully encoded frames, using rounded GIF durations. `totalFrames` is an optional positive-integer display hint, not a limit; absent hints are omitted from events. No percentage or ETA is guessed; a full frame count does not mean finalization is complete. There is no initial event. Observer exceptions are ignored; aborting or disposing from an observer is supported. Disposing after a terminal outcome emits no additional event.
 
-The offline `examples/gif.html` now demonstrates this adapter, progress and cancellation.
+The offline `examples/gif.html` demonstrates this adapter, progress and cancellation. Its limit controls (since 0.5.0) default to the example's exact 800×450, 121-frame, 8,000 ms output, including the final hold. Empty fields omit limits. A limit error explains what to increase, restores the controls for retry, and clears any previous download/preview when a new attempt starts.
+
+### GIF limits (since 0.5.0)
+
+Set optional limits on `createGifExporter`; they apply to every encoder, including the synchronous and Worker adapters:
+
+```js
+const gif = createGifExporter({
+    encoder: createGifWorkerEncoder(),
+    maxFramePixels: 1920 * 1080,
+    maxFrames: 600,
+    maxDurationMs: 30_000
+});
+try {
+    await gif.addFrame(canvas, 50);
+    const blob = await gif.finish();
+} catch (error) {
+    // A limit violation rejects addFrame with RangeError naming the limit.
+    console.error(error);
+} finally {
+    gif.dispose();
+}
+```
+
+All three values must be positive safe integers; omitting one leaves that dimension unlimited by this API (existing GIF format constraints still apply). Bounds are inclusive: `maxFramePixels` checks `width * height`, `maxFrames` counts successfully encoded frames, and `maxDurationMs` sums frame delays **after rounding each to GIF's 10 ms units**, excluding playback repetitions. For example, two 54 ms frames consume 100 ms; a 55 ms frame consumes 60 ms. `totalFrames` remains a display hint independent of `maxFrames`.
+
+Invalid limit values throw `RangeError` during creation, before allocating an encoder/Worker. Exceeding a limit rejects `addFrame` before reading pixels or submitting the rejected frame. The exporter enters terminal `failed`, emits one failed progress event with only previously completed frames/duration, detaches its abort listener and disposes its encoder (terminating the owned Worker). `finish` cannot return a partial GIF after this failure; create a fresh exporter to retry. Source canvases are retained. These limits bound input work, not exact memory usage or output byte size.
 
 ### Supplying another encoder
 
@@ -193,6 +268,16 @@ Recording requires a browser with `canvas.captureStream`, `MediaRecorder` and `M
 
 The integration example was verified with an actual VP9 recording at 1920×1080. This is not a promise that every browser can produce WebM or MP4. A canvas containing cross-origin content without CORS may not be captured.
 
+## Development checks
+
+Run `npm test` for unit and Node Worker tests, and `npm run test:package` for an isolated packed consumer. For real browser tests, first run `npx playwright install chromium firefox`, then `npm run test:browser`. These check recording, offline MP4/AAC and GIF export, cancellation/retry, resource cleanup and independently decoded timing/audio. `npm run test:next` checks the packed library with Next.js/Turbopack. See [GIF verification](docs/gif-encoder.md#verification) and [AAC/sample-count verification](docs/offline-aac.md#independent-verification).
+
+`npm run test:release-video` packs and installs the candidate, then exports a 10-second 1080×1920 H.264/AAC video from only the installed assets. It checks all 300 decoded frames, 480,000 presentation audio samples, playback, dimensions and four independent A/V markers. MP4 and metrics are saved under `test-results/release-video/`.
+
+GIF performance comparisons: run `npm run benchmark:gif` (or add `-- --quick` for a short run). See [benchmark methodology and reports](docs/gif-benchmark.md) for the resolution/duration matrix, timing boundaries and limitations.
+
+Use `npm run benchmark:gif -- --compare-opacity` to compare the pre-optimization core with the current core on opaque, mixed-alpha and translucent-gradient scenes.
+
 ## Release
 
 Run `npm test` and `npm run test:package` (packs and installs the tarball in an isolated consumer, then checks TypeScript declarations and runtime imports). The archive contains dist, README, LICENSE, CHANGELOG and package metadata. Source and issues: [urffin/canvas-take](https://github.com/urffin/canvas-take). The 0.x API may change in later minor releases.

package/dist/aac-PROVENANCE.md

@@ -0,0 +1,171 @@
+# @mediabunny/aac-encoder
+
+[![](https://img.shields.io/npm/v/@mediabunny/aac-encoder)](https://www.npmjs.com/package/@mediabunny/aac-encoder)
+[![](https://img.shields.io/bundlephobia/minzip/@mediabunny/aac-encoder)](https://bundlephobia.com/package/@mediabunny/aac-encoder)
+[![](https://img.shields.io/npm/dm/@mediabunny/aac-encoder)](https://www.npmjs.com/package/@mediabunny/aac-encoder)
+[![](https://img.shields.io/discord/1390044844285497344?logo=discord&label=Discord)](https://discord.gg/hmpkyYuS4U)
+
+<div align="center">
+    <img src="../../docs/public/mediabunny-logo.svg" width="180" height="180">
+</div>
+
+Some browsers lack support for AAC encoding in their WebCodecs implementations. This extension package provides a reliable AAC-LC encoder for use with [Mediabunny](https://github.com/Vanilagy/mediabunny). It is implemented using Mediabunny's [custom coder API](https://mediabunny.dev/guide/supported-formats-and-codecs#custom-coders) and uses a fast, size-optimized WASM build of [FFmpeg](https://ffmpeg.org/)'s AAC encoder under the hood.
+
+> This package, like the rest of Mediabunny, is enabled by its [sponsors](https://mediabunny.dev/#sponsors) and their donations. If you've derived value from this package, please consider [leaving a donation](https://github.com/sponsors/Vanilagy)! 💘
+
+## Installation
+
+This library peer-depends on Mediabunny. Install both using npm:
+```bash
+npm install mediabunny @mediabunny/aac-encoder
+```
+
+Alternatively, directly include them using a script tag:
+```html
+<script src="mediabunny.js"></script>
+<script src="mediabunny-aac-encoder.js"></script>
+```
+
+This will expose the global objects `Mediabunny` and `MediabunnyAacEncoder`. Use `mediabunny-aac-encoder.d.ts` to provide types for these globals. You can download the built distribution files from the [releases page](https://github.com/Vanilagy/mediabunny/releases).
+
+## Usage
+
+```ts
+import { registerAacEncoder } from '@mediabunny/aac-encoder';
+
+registerAacEncoder();
+```
+That's it - Mediabunny now uses the registered AAC encoder automatically.
+
+If you want to be more correct, check for native browser support first:
+```ts
+import { canEncodeAudio } from 'mediabunny';
+import { registerAacEncoder } from '@mediabunny/aac-encoder';
+
+if (!(await canEncodeAudio('aac'))) {
+    registerAacEncoder();
+}
+```
+
+## Example
+
+Here, we convert an input file to an MP4 with AAC audio:
+
+```ts
+import {
+    Input,
+    ALL_FORMATS,
+    BlobSource,
+    Output,
+    BufferTarget,
+    Mp4OutputFormat,
+    canEncodeAudio,
+    Conversion,
+} from 'mediabunny';
+import { registerAacEncoder } from '@mediabunny/aac-encoder';
+
+if (!(await canEncodeAudio('aac'))) {
+    // Only register the custom encoder if there's no native support
+    registerAacEncoder();
+}
+
+const input = new Input({
+    source: new BlobSource(file), // From a file picker, for example
+    formats: ALL_FORMATS,
+});
+const output = new Output({
+    format: new Mp4OutputFormat(),
+    target: new BufferTarget(),
+});
+
+const conversion = await Conversion.init({
+    input,
+    output,
+    audio: {
+        codec: 'aac',
+    },
+});
+await conversion.execute();
+
+output.target.buffer; // => ArrayBuffer containing the MP4 file
+```
+
+For more ways of using Mediabunny, refer to its [guide](https://mediabunny.dev/guide/introduction).
+
+## Building and development
+
+For simplicity, all built WASM artifacts are included in the repo, since these rarely change. However, here are the instructions for building them from scratch:
+
+[Install Emscripten](https://emscripten.org/docs/getting_started/downloads.html) and clone [FFmpeg](https://github.com/FFmpeg/FFmpeg). Then, from the Mediabunny root and with Emscripten sourced in:
+
+```bash
+export FFMPEG_PATH=/path/to/ffmpeg
+export MEDIABUNNY_ROOT=$PWD
+
+# Build FFmpeg
+cd $FFMPEG_PATH
+emmake make distclean
+emconfigure ./configure \
+    --target-os=none \
+    --arch=x86_32 \
+    --enable-cross-compile \
+    --disable-asm \
+    --disable-x86asm \
+    --disable-inline-asm \
+    --disable-programs \
+    --disable-doc \
+    --disable-debug \
+    --disable-all \
+    --disable-everything \
+    --disable-autodetect \
+    --disable-pthreads \
+    --disable-runtime-cpudetect \
+    --enable-avcodec \
+    --enable-encoder=aac \
+    --cc="emcc" \
+    --cxx=em++ \
+    --ar=emar \
+    --ranlib=emranlib \
+    --extra-cflags="-DNDEBUG -Oz -flto -msimd128" \
+    --extra-ldflags="-Oz -flto"
+emmake make
+
+# Compile the bridge between JavaScript and FFmpeg's API
+cd $MEDIABUNNY_ROOT/packages/aac-encoder
+emcc src/bridge.c \
+    $FFMPEG_PATH/libavcodec/libavcodec.a \
+    $FFMPEG_PATH/libavutil/libavutil.a \
+    -I$FFMPEG_PATH \
+    -s MODULARIZE=1 \
+    -s EXPORT_ES6=1 \
+    -s SINGLE_FILE=1 \
+    -s ALLOW_MEMORY_GROWTH=1 \
+    -s ENVIRONMENT=web,worker \
+    -s FILESYSTEM=0 \
+    -s MALLOC=emmalloc \
+    -s SUPPORT_LONGJMP=0 \
+    -s EXPORTED_RUNTIME_METHODS=cwrap,HEAPU8 \
+    -s EXPORTED_FUNCTIONS=_malloc,_free \
+    -msimd128 \
+    -flto \
+    -Oz \
+    -o build/aac.js
+```
+
+This generates `build/aac.js`, which contains both the JavaScript "glue code" as well as the compiled WASM inlined.
+
+### Building the package
+
+Then, the complete JavaScript package can be built alongside the rest of Mediabunny by running `npm run build` in Mediabunny's root.
+
+## Provenance
+
+The build artifacts included in this repo, which are also the ones bundled into the published package, were built with exactly the commands above, from:
+
+- FFmpeg [`60a2818f76dcd1fee3155b1791304af104a0fc1b`](https://github.com/FFmpeg/FFmpeg/commit/60a2818f76dcd1fee3155b1791304af104a0fc1b) (`n9.1-dev-2902-g60a2818f76d`), unmodified
+- Emscripten 4.0.21 (`d6f42310010ddec0753a69bab01a4b33aae255b7`)
+- `src/bridge.c` of this package
+
+SHA-256 of the WASM binary inlined in `build/aac.js`: `4123d56ed650255a14535d8438680a78df67ae9324e4874a88becfb37bf18c66`
+
+FFmpeg is licensed under the LGPL v2.1 or later; this build enables no GPL, version 3 or nonfree components. Its license files are in [`licenses/ffmpeg`](./licenses/ffmpeg). To use a modified FFmpeg, rebuild using the steps above.