p5.record.js 0.1.0

package/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2025, Kenneth Lim
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of
+   its contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,51 @@
+# p5.record.js
+
+Record your p5.js sketch and export it as a video.
+
+This p5.js addon library provides a simple interface to record your p5.js sketch into a video by using the [`captureStream()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream) API of `HTMLCanvasElement`. No external dependencies is included with this library.
+
+p5.record.js starts with a set of default configuration that covers the simplest and likely most common use, while also providing additional customization options to achieve additional functionalities:
+
+* Recording at specific defined frame rate, and in supported browsers, full control over [when individual frame capture should happen](https://developer.mozilla.org/en-US/docs/Web/API/CanvasCaptureMediaStreamTrack/requestFrame).
+* Record canvas backed objects, such as `p5.Graphics`, and HTML canvas directly.
+* Create multiple recordings at the same time.
+
+## Usage
+For different use cases, please check out the `examples/` folder. The available p5.js addon functions are as follow:
+
+* `setRecording(options)` - Set a configuration for recording, accepts an options object as argument. All options are optional. The default configuration (already set without needing to call `setRecording`) is as follow:
+  ```js
+  options = {
+  	frameRate: getTargetFrameRate(),
+  	source: canvas.elt,
+  	mimeType: "video/webm;codecs=vp8"
+  }
+  ```
+  * `frameRate` - (`Number|"manual"`) If `options.frameRate` is set to a string with value `"manual"`, sketch recording will automatically be tied to each call of `draw()`. This is useful when you have set the sketch to `noLoop()` and is manually calling `redraw()`, only available in supported browsers.
+  * `source` - An object containing a property of `canvas` of type `HTMLCanvasElement` (eg. `p5.Graphics` instance) or an `HTMLCanvasElement`.
+  * `mimeType` - The container and codec to be used for recording. Currently only a very small set of containers and codecs are supported natively, it is recommended to leave the default and reencode the video after downloading the result.
+* `startRecording()` - Start recording at specified frame rate.
+* `stopRecording()` - Stop recording and download the recording file.
+* `pauseRecording()` - Pause recording to be resumed later.
+* `resumeRecording()` - Resume previously paused recording.
+* `createRecording(options)` - Create an independent recorder instance. See the `Recorder` class below for usage of its return value. Accepts the same `options` object as `setRecording(options)` as argument but `frameRate` and `source` are required.
+
+The library also provides a `p5.Recorder` class for multiple simultaneous recording usage. In p5.js sketches, it is recommended to use `createRecording(options)` factory function to create instance of this class.
+
+### `Recorder` class
+* Constructor - `new Recorder(options)` accepts the same options object as `createRecording(options)`, ie. `frameRate` and `source` are required.
+* `state` - Recorder state, can be one of `"inactive"`, `"recording"`, or `"paused"`.
+* `start()` - Start the recording.
+* `stop()` - Stop the recording.
+* `pause()` - Pause the recording.
+* `resume()` - Resume the recording.
+* `frame()` - Record a single frame, to be used in conjunction with `options.frameRate = "manual"`
+
+## Limitations
+This library is only designed for canvas backed sketches and objects, recording of other inputs (eg. SVG) is not supported.
+
+Currently the recording output format is limited to VP8 encoded WebM video file, depending on use case you may need to reencode the video to a different format.
+
+## Future features
+* Custom output video formats
+* Record as gif and image sequence

package/examples/basic-sketch-recording/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<title>p5.record.js Basic Sketch Recording</title>
+
+	<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.min.js"></script>
+	<script src="../../dist/p5.record.min.js"></script>
+
+	<style>
+		html, body {
+			margin: 0;
+		}
+	</style>
+</head>
+<body>
+	<section style="margin: 10px;">
+		<button id="start-recording">Start Recording</button>
+		<button id="stop-recording">Stop Recording</button>
+		<button id="pause-recording">Pause Recording</button>
+		<button id="resume-recording">Resume Recording</button>
+	</section>
+	<script src="./src/sketch.js"></script>
+</body>
+</html>

package/examples/basic-sketch-recording/src/sketch.js

@@ -0,0 +1,32 @@
+let startBtn, stopBtn, pauseBtn, resumeBtn;
+
+function setup() {
+  createCanvas(400, 400);
+  background(200);
+
+  startBtn = select("#start-recording");
+  stopBtn = select("#stop-recording");
+  pauseBtn = select("#pause-recording");
+  resumeBtn = select("#resume-recording");
+
+  startBtn.mouseClicked(startRecording);
+  stopBtn.mouseClicked(stopRecording);
+  pauseBtn.mouseClicked(pauseRecording);
+  resumeBtn.mouseClicked(resumeRecording);
+}
+
+function draw() {
+  line(mouseX, mouseY, pmouseX, pmouseY);
+}
+
+function keyTyped() {
+  if(key === "a"){
+    startRecording();
+  }else if(key === "s"){
+    stopRecording();
+  }else if(key === "d"){
+    pauseRecording();
+  }else if(key === "f"){
+    resumeRecording();
+  }
+}

package/examples/frame-by-frame-recording/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<title>p5.record.js Frame By Frame Recording</title>
+
+	<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.min.js"></script>
+	<script src="../../dist/p5.record.min.js"></script>
+
+	<style>
+		html, body {
+			margin: 0;
+		}
+	</style>
+</head>
+<body>
+	<section style="margin: 10px;">
+		<button id="start-recording">Start Recording</button>
+		<button id="stop-recording">Stop Recording</button>
+		<button id="pause-recording">Pause Recording</button>
+		<button id="resume-recording">Resume Recording</button>
+	</section>
+	<script src="./src/sketch.js"></script>
+</body>
+</html>

package/examples/frame-by-frame-recording/src/sketch.js

@@ -0,0 +1,37 @@
+let data;
+let startBtn, stopBtn, pauseBtn, resumeBtn;
+
+function setup() {
+  createCanvas(400, 400);
+  background(200);
+
+  startBtn = select("#start-recording");
+  stopBtn = select("#stop-recording");
+  pauseBtn = select("#pause-recording");
+  resumeBtn = select("#resume-recording");
+
+  startBtn.mouseClicked(startRecording);
+  stopBtn.mouseClicked(stopRecording);
+  pauseBtn.mouseClicked(pauseRecording);
+  resumeBtn.mouseClicked(resumeRecording);
+
+  setRecording({
+    frameRate: "manual"
+  });
+}
+
+function draw() {
+  line(mouseX, mouseY, pmouseX, pmouseY);
+}
+
+function keyTyped() {
+  if(key === "a"){
+    startRecording();
+  }else if(key === "s"){
+    stopRecording();
+  }else if(key === "d"){
+    pauseRecording();
+  }else if(key === "f"){
+    resumeRecording();
+  }
+}

package/examples/graphics-recording/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<title>p5.record.js Basic Sketch Recording</title>
+
+	<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.min.js"></script>
+	<script src="../../dist/p5.record.min.js"></script>
+
+	<style>
+		html, body {
+			margin: 0;
+		}
+	</style>
+</head>
+<body>
+	<section style="margin: 10px;">
+		<button id="start-recording">Start Recording</button>
+		<button id="stop-recording">Stop Recording</button>
+		<button id="pause-recording">Pause Recording</button>
+		<button id="resume-recording">Resume Recording</button>
+	</section>
+	<script src="./src/sketch.js"></script>
+</body>
+</html>

package/examples/graphics-recording/src/sketch.js

@@ -0,0 +1,47 @@
+let graphic;
+let startBtn, stopBtn, pauseBtn, resumeBtn;
+
+function setup() {
+  createCanvas(400, 400);
+  background(200);
+
+  startBtn = select("#start-recording");
+  stopBtn = select("#stop-recording");
+  pauseBtn = select("#pause-recording");
+  resumeBtn = select("#resume-recording");
+
+  startBtn.mouseClicked(startRecording);
+  stopBtn.mouseClicked(stopRecording);
+  pauseBtn.mouseClicked(pauseRecording);
+  resumeBtn.mouseClicked(resumeRecording);
+
+  graphic = createGraphics(400, 400);
+
+  setRecording({
+    source: graphic
+  });
+}
+
+function draw() {
+  line(mouseX, mouseY, pmouseX, pmouseY);
+  graphic.background(255);
+  graphic.fill(255, 0, 0);
+  graphic.push();
+  graphic.translate(200, 200);
+  graphic.rotate(frameCount/10);
+  graphic.rect(-100, -100, 200, 200);
+  graphic.pop();
+  image(graphic, 100, 100, 200, 200);
+}
+
+function keyTyped() {
+  if(key === "a"){
+    startRecording();
+  }else if(key === "s"){
+    stopRecording();
+  }else if(key === "d"){
+    pauseRecording();
+  }else if(key === "f"){
+    resumeRecording();
+  }
+}

package/examples/multiple-parallel-recording/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<title>p5.record.js Basic Sketch Recording</title>
+
+	<script src="https://cdn.jsdelivr.net/npm/p5@2/lib/p5.min.js"></script>
+	<script src="../../dist/p5.record.min.js"></script>
+
+	<style>
+		html, body {
+			margin: 0;
+		}
+	</style>
+</head>
+<body>
+	<section style="margin: 10px;">
+		<button id="start-recording">Start Recording</button>
+		<button id="stop-recording">Stop Recording</button>
+		<button id="pause-recording">Pause Recording</button>
+		<button id="resume-recording">Resume Recording</button>
+	</section>
+	<script src="./src/sketch.js"></script>
+</body>
+</html>

package/examples/multiple-parallel-recording/src/sketch.js

@@ -0,0 +1,84 @@
+let graphics = [];
+let colors = [];
+let recorders = [];
+let startBtn, stopBtn, pauseBtn, resumeBtn;
+
+function setup() {
+  createCanvas(400, 400);
+  background(200);
+
+  for(let i=0; i<4; i++){
+    graphics.push(createGraphics(400, 400));
+    colors.push(color(random(255), random(255), random(255)));
+
+    const options = {
+      source: graphics[i]
+    }
+    recorders.push(createRecording(options));
+  }
+
+  startBtn = select("#start-recording");
+  stopBtn = select("#stop-recording");
+  pauseBtn = select("#pause-recording");
+  resumeBtn = select("#resume-recording");
+
+  startBtn.mouseClicked(() => {
+    recorders.forEach((recorder) => {
+      recorder.start();
+    });
+  });
+  stopBtn.mouseClicked(() => {
+    recorders.forEach((recorder) => {
+      recorder.stop();
+    });
+  });
+  pauseBtn.mouseClicked(() => {
+    recorders.forEach((recorder) => {
+      recorder.pause();
+    });
+  });
+  resumeBtn.mouseClicked(() => {
+    recorders.forEach((recorder) => {
+      recorder.resume();
+    });
+  });
+}
+
+function draw() {
+  line(mouseX, mouseY, pmouseX, pmouseY);
+
+  for(let j=0; j<2; j++){
+    for(let i=0; i<2; i++){
+      const graphic = graphics[j*2+i];
+      graphic.background(0);
+      graphic.fill(colors[j*2+i]);
+      graphic.push();
+      graphic.translate(200, 200);
+      graphic.rotate(frameCount/10);
+      graphic.rect(-100, -100, 200, 200);
+      graphic.pop();
+
+      image(graphic, i * 200, j * 200, 200, 200);
+    }
+  }
+}
+
+function keyTyped() {
+  if(key === "a"){
+    recorders.forEach((recorder) => {
+      recorder.start();
+    });
+  }else if(key === "s"){
+    recorders.forEach((recorder) => {
+      recorder.stop();
+    });
+  }else if(key === "d"){
+    recorders.forEach((recorder) => {
+      recorder.pause();
+    });
+  }else if(key === "f"){
+    recorders.forEach((recorder) => {
+      recorder.resume();
+    });
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "p5.record.js",
+  "version": "0.1.0",
+  "description": "p5.js addon providing functions to record HTML canvas based sketches",
+  "homepage": "https://github.com/limzykenneth/p5.record.js",
+  "bugs": "https://github.com/limzykenneth/p5.record.js/issues",
+  "repository": "github:limzykenneth/p5.record.js",
+  "author": "Kenneth Lim <hello@limzykenneth.com> (https://limzykenneth.com)",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "record",
+    "recorder",
+    "capture",
+    "canvas",
+    "p5",
+    "p5.js",
+    "captureStream"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/p5.record.esm.js"
+  },
+  "scripts": {
+    "build": "rollup -c rollup.config.js",
+    "dev": "rollup -c rollup.config.js --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "rollup": "^4.41.1"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,21 @@
+import terser from "@rollup/plugin-terser";
+
+export default [
+  {
+    input: "src/main.js",
+    output: {
+      file: "dist/p5.record.min.js",
+      format: "iife",
+      plugins: [
+        process.env.ROLLUP_WATCH ? null :  terser()
+      ]
+    }
+  },
+  {
+    input: "src/main.js",
+    output: {
+      file: "dist/p5.record.esm.js",
+      format: "esm"
+    }
+  }
+];

package/src/Recorder.js

@@ -0,0 +1,76 @@
+export class Recorder {
+  #stream;
+  #recorder;
+
+  constructor(options) {
+    const frameRate = options.frameRate === "manual" ? 0 : options.frameRate;
+    const chunks = [];
+    const stream = (
+      options.source instanceof HTMLCanvasElement ?
+        options.source :
+        options.source.canvas
+      ).captureStream(frameRate);
+    const recorder = new MediaRecorder(stream, {
+      mimeType: options.mimeType ?? "video/webm;codecs=vp8"
+    });
+
+    recorder.addEventListener("start", (e) => {
+      console.log("recording started");
+    });
+
+    recorder.addEventListener("stop", (e) => {
+      const blob = new Blob(chunks);
+
+      const executeDefault = typeof options?.stopCallback === "function" ?
+        options?.stopCallback(blob) :
+        true;
+
+      if(executeDefault){
+        const blobUrl = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.href = blobUrl;
+        link.download = "recording.webm";
+        link.click();
+      }
+    });
+
+    recorder.addEventListener("dataavailable", (e) => {
+      chunks.push(e.data);
+    });
+
+    recorder.addEventListener("pause", (e) => {
+      console.log("recording paused");
+    });
+
+    recorder.addEventListener("resume", (e) => {
+      console.log("recording resumed");
+    });
+
+    this.#recorder = recorder;
+    this.#stream = stream;
+  }
+
+  get state() {
+    return this.#recorder.state;
+  }
+
+  start() {
+    this.#recorder.start();
+  }
+
+  stop() {
+    this.#recorder.stop();
+  }
+
+  pause() {
+    this.#recorder.pause();
+  }
+
+  resume() {
+    this.#recorder.resume();
+  }
+
+  frame() {
+    this.#stream.getVideoTracks()[0].requestFrame();
+  }
+}

package/src/main.js

@@ -0,0 +1,63 @@
+import { Recorder } from "./Recorder.js";
+
+export function p5Record(p5, fn, lifecycles){
+  let recorder, options;
+
+  const p5VersionSemver = p5.VERSION.split(".")
+    .map((n) => parseInt(n));
+  if(!(
+    p5VersionSemver[0] > 2 ||
+    (p5VersionSemver[0] > 2 && p5VersionSemver[1] > 0) ||
+    (p5VersionSemver[0] === 2 && p5VersionSemver[1] === 0 && p5VersionSemver[2] >= 3)
+  )){
+    console.error(`p5.record.js requires p5.js >= 2.0.3`);
+    return;
+  }
+
+  p5.Recorder = Recorder;
+
+  lifecycles.postdraw = function() {
+    if(recorder && recorder.state === "recording" && options?.frameRate === "manual"){
+      recorder.frame();
+    }
+  };
+
+  fn.setRecording = function(opt) {
+    if(opt.frameRate === "manual" && !("CanvasCaptureMediaStreamTrack" in window)){
+      console.error("Your browser does not support directly specifying frame capture timing with { frameRate: 'manual' }.");
+      return;
+    }
+    options = opt;
+  };
+
+  fn.startRecording = function() {
+    options = Object.assign({
+      source: this.canvas,
+      frameRate: this.getTargetFrameRate()
+    }, options);
+    recorder = new Recorder(options);
+    recorder.start();
+  };
+
+  fn.stopRecording = function() {
+    recorder.stop();
+  };
+
+  fn.pauseRecording = function() {
+    recorder.pause();
+  };
+
+  fn.resumeRecording = function() {
+    recorder.resume();
+  };
+
+  fn.createRecording = function(options) {
+    return new Recorder(options);
+  };
+};
+
+if(typeof p5 !== "undefined"){
+  p5.registerAddon(p5Record);
+}
+
+export { Recorder };