@grundyjs/canvas-take 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## 0.1.0 — unreleased
+## 0.2.0 — 2026-10-15
+
+- Optional caller-provided `audioTracks`, cloned at start to preserve caller ownership.
+- Audio-aware automatic WebM codec selection (Opus), with explicit MP4 support where available.
+- Audio validation and cleanup on termination, cancellation and partial setup failure.
+- Web Audio narration example and audio lifecycle tests.
+- Verified vertical MP4 recording with H.264/AAC; GitHub Releases publish through npm trusted publishing with provenance.
+
+## 0.1.0
 
 - Silent canvas recording with automatic WebM/MP4 format selection.
 - Promise-based start and stop, final-chunk handling and idempotent disposal.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Grundy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Grundy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # CanvasTake
 
-Independent TypeScript library for silent HTML canvas video recording. No runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
+Independent TypeScript library for HTML canvas video recording with optional audio tracks. No runtime dependencies or dependency on AlgiViz. ESM only, with TypeScript declarations. MIT licensed. The package does not start or draw your animation.
 
 ## Install
 
@@ -23,14 +23,14 @@ 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. 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 recording wall time, 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 audio, 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. 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.
 
 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.
 
 See [MediaRecorder stop](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/stop) and [format support](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/isTypeSupported_static).
-MediaRecorder WebM output may omit duration metadata: playback can work while the player reports an indefinite duration. For reliable seeking or publication, remux the output separately. CanvasTake does not rewrite container metadata.
+MediaRecorder WebM output may omit duration metadata: playback can work while the player reports an indefinite duration. For reliable seeking or publication, remux the output separately. CanvasTake does not rewrite container metadata.
 
 ## Options and result
 
@@ -39,9 +39,55 @@ MediaRecorder WebM output may omit duration metadata: playback can work while th
 | `fps` | Required positive finite capture rate target |
 | `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 |
 
 `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.
 
+## Record with narration
+
+Mix audio into one Web Audio destination track (multiple audio tracks are not supported by every encoder). Decode your narration before starting. Call this from a user gesture so the browser can resume the audio context:
+
+```js
+async function recordNarration(canvas, narrationBytes) {
+    const audio = new AudioContext();
+    let recorder;
+    let destination;
+    try {
+        await audio.resume();
+        const buffer = await audio.decodeAudioData(narrationBytes);
+        destination = audio.createMediaStreamDestination();
+        const source = audio.createBufferSource();
+        source.buffer = buffer;
+        source.connect(destination);
+        recorder = createCanvasRecorder(canvas, {
+            fps: 30,
+            mimeType: "video/mp4",
+            audioTracks: destination.stream.getAudioTracks(),
+        });
+        const finished = new Promise(resolve => {
+            source.addEventListener("ended", resolve, { once: true });
+        });
+        await recorder.start();
+        source.start();
+        // Run your canvas animation while the narration plays.
+        await finished;
+        return await recorder.stop();
+    } finally {
+        recorder?.dispose();
+        destination?.stream.getTracks().forEach(track => track.stop());
+        await audio.close();
+    }
+}
+```
+
+MP4 with audio requires browser encoder support; an explicit MP4 request never falls back to WebM. CanvasTake uses MediaRecorder directly and does not transcode. Audio playback and canvas animation remain caller-controlled and use real time.
+
+`video/mp4` selects a container, not specific codecs: a browser may produce VP9/Opus in MP4. If your destination requires H.264/AAC, request an explicit codec MIME such as `video/mp4;codecs=avc1,mp4a.40.2` and handle unsupported-format errors.
+
+For a browser smoke test, run `node examples/server.cjs` after building and open `http://127.0.0.1:3012/canvas-take/examples/audio.html`. It records a generated tone and moving 1080×1920 canvas with explicit H.264/AAC, requests stop after two seconds, previews the result and saves it to `canvastake-test.mp4` in the server's temporary directory. Verified in the local browser: H.264 Constrained Baseline, progressive 4:2:0, stereo AAC-LC at 48 kHz, 2.476 seconds and approximately 29.1 fps. No transcoding or remuxing was used. Actual duration/frame rate and codec support depend on the browser and runtime load.
+
+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.
+
 ## Browser and server use
 
 Recording requires a browser with `canvas.captureStream`, `MediaRecorder` and `MutationObserver`. Importing the module does not access these APIs; creating a recorder checks capture/encoder support. Node.js has no recording implementation. Codec support is detected at runtime, not inferred from the browser name.
@@ -50,5 +96,7 @@ The integration example was verified with an actual VP9 recording at 1920×1080.
 
 ## Release
 
-Run `npm test`, `npm pack --dry-run` and install the tarball in a separate consumer project. The archive contains dist, README, LICENSE, CHANGELOG and package metadata. Source and issues: [urffin/canvas-take](https://github.com/urffin/canvas-take). Version 0.1 is an initial API and may change in later minor releases. Publishing is a separate maintainer action.
-
+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.
+
+After CI passes on the release commit, publish a stable GitHub Release tagged `v<package version>`. The `npm-publish.yml` workflow checks version consistency, verifies the packed consumer and publishes with OIDC/provenance. Configure npm's trusted publisher for owner `urffin`, repository `canvas-take`, workflow `npm-publish.yml` before the first automated release. No npm token is used. Publishing is a separate maintainer action.
+

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export interface RecorderOptions {
     readonly fps: number;
     readonly videoBitsPerSecond?: number;
     readonly mimeType?: string;
+    /** Live caller-owned audio tracks; recorder owns and stops only clones. */
+    readonly audioTracks?: readonly MediaStreamTrack[];
 }
 export type RecorderState = "idle" | "recording" | "stopping" | "stopped" | "disposed";
 export interface CanvasRecorder {
@@ -16,5 +18,5 @@ export interface CanvasRecorder {
     stop(): Promise<RecordingResult>;
     dispose(): void;
 }
-/** One recorder instance produces one silent video; drawing is managed by the caller. */
+/** One recorder instance produces one video, optionally with supplied audio; drawing is managed by the caller. */
 export declare function createCanvasRecorder(canvas: HTMLCanvasElement, options: RecorderOptions): CanvasRecorder;

package/dist/index.js

@@ -14,7 +14,7 @@ function extension(mime) {
         return "mp4";
     throw new TypeError(`Unsupported video container: ${mime}`);
 }
-/** One recorder instance produces one silent video; drawing is managed by the caller. */
+/** One recorder instance produces one video, optionally with supplied audio; drawing is managed by the caller. */
 export function createCanvasRecorder(canvas, options) {
     if (!Number.isFinite(options.fps) || options.fps <= 0)
         throw new RangeError("fps must be positive and finite");
@@ -25,10 +25,18 @@ export function createCanvasRecorder(canvas, options) {
     if (typeof MediaRecorder === "undefined" || typeof canvas.captureStream !== "function") {
         throw new Error("Canvas video recording is not supported in this environment");
     }
+    const audioTracks = [...(options.audioTracks ?? [])];
+    for (const track of audioTracks) {
+        if (track.kind !== "audio" || track.readyState !== "live")
+            throw new TypeError("audioTracks must contain live audio tracks");
+    }
     const requested = options.mimeType;
     if (requested !== undefined)
         extension(requested);
-    const mime = requested ?? ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm", "video/mp4"]
+    const candidates = audioTracks.length
+        ? ["video/webm;codecs=vp9,opus", "video/webm;codecs=vp8,opus", "video/webm", "video/mp4"]
+        : ["video/webm;codecs=vp9", "video/webm;codecs=vp8", "video/webm", "video/mp4"];
+    const mime = requested ?? candidates
         .find(candidate => MediaRecorder.isTypeSupported(candidate));
     if (!mime || !MediaRecorder.isTypeSupported(mime))
         throw new Error(`Unsupported recording format: ${mime ?? "none"}`);
@@ -80,7 +88,7 @@ export function createCanvasRecorder(canvas, options) {
     function onError(event) {
         fail(event.error ?? new Error("Video recording failed"));
     }
-    function onEnded() { fail(new Error("Canvas capture track ended unexpectedly")); }
+    function onEnded() { fail(new Error("Recording track ended unexpectedly")); }
     function onStop() {
         if (!unchanged()) {
             fail(new Error("Canvas bitmap size changed during recording"));
@@ -140,6 +148,18 @@ export function createCanvasRecorder(canvas, options) {
                 stream = canvas.captureStream(options.fps);
                 if (!stream.getVideoTracks().length)
                     throw new Error("Canvas stream has no video track");
+                for (const track of audioTracks) {
+                    if (track.readyState !== "live")
+                        throw new Error("Audio track ended before recording");
+                    const clone = track.clone();
+                    try {
+                        stream.addTrack(clone);
+                    }
+                    catch (error) {
+                        clone.stop();
+                        throw error;
+                    }
+                }
                 recorder = new MediaRecorder(stream, { mimeType: mime, videoBitsPerSecond: options.videoBitsPerSecond });
                 recorder.addEventListener("start", onStart);
                 recorder.addEventListener("dataavailable", onData);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grundyjs/canvas-take",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Record HTML canvas to video with explicit resource lifecycle",
   "type": "module",
   "files": [
@@ -20,7 +20,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.mjs",
     "prepack": "npm run build",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "test:package": "node scripts/test-package.mjs"
   },
   "devDependencies": {
     "typescript": "6.0.3"