diff --git a/packages/core/pianoroll.mjs b/packages/core/pianoroll.mjs
index f3d2c38a..2ea5727b 100644
--- a/packages/core/pianoroll.mjs
+++ b/packages/core/pianoroll.mjs
@@ -56,6 +56,40 @@ Pattern.prototype.pianoroll = function (options = {}) {
 
 // this function allows drawing a pianoroll without ties to Pattern.prototype
 // it will probably replace the above in the future
+
+/**
+ * Displays a midi-style piano roll
+ *
+ * @name pianoroll
+ * @param {Object} options Object containing all the optional following parameters as key value pairs:
+ * @param {integer} cycles defaults to 4 - number of cycles to be displayed at the same time
+ * @param {number} playhead 0 to 1, defaults to 0.5 - location of the active notes on the time axis
+ * @param {integer} vertical 0 (default) or 1 - displays the roll vertically
+ * @param {boolean} labels false (default) or true - displays labels on individual notes (see the label function)
+ * @param {integer} flipTime 0 (default) or 1 - reverse the direction of the roll
+ * @param {integer} flipValues 0 (default) or 1 - reverse the relative location of notes on the value axis
+ * @param {number} overscan 1 (default) - lookup X cycles outside of the cycles window to display notes in advance
+ * @param {boolean} hideNegative false (default) or true - hide notes with negative time (before starting playing the pattern)
+ * @param {integer} smear 0 (default) or 1 - notes leave a solid trace
+ * @param {integer} fold 0 (default) or 1 - notes takes the full value axis width
+ * @param {string} active hexadecimal or CSS color (defaults to #FFCA28) - color of the active notes
+ * @param {string} inactive hexadecimal or CSS color (defaults to #7491D2) - color of the inactive notes
+ * @param {string} background hexadecimal or CSS color (defaults to transparent) - color of the background
+ * @param {string} playheadColor hexadecimal or CSS color (defaults to transparent) - color of the line representing the play head
+ * @param {integer} fill 1 (default) or 0 - notes are filled with color (otherwise only the label is displayed)
+ * @param {boolean} fillActive: false (default) or true - active notes are filled with color
+ * @param {integer} stroke 0 (default) or 1 - notes are shown with colored borders
+ * @param {boolean} strokeActive: false (default) or true - active notes are shown with colored borders
+ * @param {integer} hideInactive 0 (default) or 1 - only active notes are shown
+ * @param {integer} colorizeInactive 1 (default) or 0 - use note color for inactive notes
+ * @param {string} fontFamily: defaults to 'monospace' - define the font used by notes labels
+ * @param {integer} minMidi integer, defaults to 10 - minimum note value to display on the value axis
+ * @param {integer} maxMidi integer, defaults to 90 - maximum note value to display on the value axis
+ * @param {integer} autorange 0 (default) or 1 - automatically calculate the minMidi and maxMidi parameters
+ *
+ * @example
+ * note("C2 A2 G2").euclid(5,8).s('piano').clip(1).color('salmon').pianoroll({vertical:1, labels:1})
+ */
 export function pianoroll({
   time,
   haps,
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 0963638f..5d485210 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -3297,6 +3297,39 @@ exports[`runs examples > example "perlin" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "pianoroll" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | note:C2 s:piano clip:1 ]",
+  "[ (1/4 → 1/3) ⇝ 3/8 | note:C2 s:piano clip:1 ]",
+  "[ 1/4 ⇜ (1/3 → 3/8) | note:A2 s:piano clip:1 ]",
+  "[ 3/8 → 1/2 | note:A2 s:piano clip:1 ]",
+  "[ (5/8 → 2/3) ⇝ 3/4 | note:A2 s:piano clip:1 ]",
+  "[ 5/8 ⇜ (2/3 → 3/4) | note:G2 s:piano clip:1 ]",
+  "[ 3/4 → 7/8 | note:G2 s:piano clip:1 ]",
+  "[ 1/1 → 9/8 | note:C2 s:piano clip:1 ]",
+  "[ (5/4 → 4/3) ⇝ 11/8 | note:C2 s:piano clip:1 ]",
+  "[ 5/4 ⇜ (4/3 → 11/8) | note:A2 s:piano clip:1 ]",
+  "[ 11/8 → 3/2 | note:A2 s:piano clip:1 ]",
+  "[ (13/8 → 5/3) ⇝ 7/4 | note:A2 s:piano clip:1 ]",
+  "[ 13/8 ⇜ (5/3 → 7/4) | note:G2 s:piano clip:1 ]",
+  "[ 7/4 → 15/8 | note:G2 s:piano clip:1 ]",
+  "[ 2/1 → 17/8 | note:C2 s:piano clip:1 ]",
+  "[ (9/4 → 7/3) ⇝ 19/8 | note:C2 s:piano clip:1 ]",
+  "[ 9/4 ⇜ (7/3 → 19/8) | note:A2 s:piano clip:1 ]",
+  "[ 19/8 → 5/2 | note:A2 s:piano clip:1 ]",
+  "[ (21/8 → 8/3) ⇝ 11/4 | note:A2 s:piano clip:1 ]",
+  "[ 21/8 ⇜ (8/3 → 11/4) | note:G2 s:piano clip:1 ]",
+  "[ 11/4 → 23/8 | note:G2 s:piano clip:1 ]",
+  "[ 3/1 → 25/8 | note:C2 s:piano clip:1 ]",
+  "[ (13/4 → 10/3) ⇝ 27/8 | note:C2 s:piano clip:1 ]",
+  "[ 13/4 ⇜ (10/3 → 27/8) | note:A2 s:piano clip:1 ]",
+  "[ 27/8 → 7/2 | note:A2 s:piano clip:1 ]",
+  "[ (29/8 → 11/3) ⇝ 15/4 | note:A2 s:piano clip:1 ]",
+  "[ 29/8 ⇜ (11/3 → 15/4) | note:G2 s:piano clip:1 ]",
+  "[ 15/4 → 31/8 | note:G2 s:piano clip:1 ]",
+]
+`;
+
 exports[`runs examples > example "pick" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | note:g ]",