Samples per cycle

Embed

The script finds its own origin, so nothing else is needed; the widget runs in a sandboxed frame and cannot touch your page. Set the controls and the two lines update; the preview beneath shows what your readers get.

It is CC-BY-4.0: keep the credit line the frame shows.

Preview

Fork

A fork is a copy whose manifest names its parent and the parent's version; lineage is kept forever, and the copy is yours to change. The library is its own repository: clone it, copy samples-per-cycle/ to a new name (one DNS label), set forkedFrom to { "name": "samples-per-cycle", "version": 1 }, change what you want, run npm run check, and open a pull request. Passing the check is the whole gate. Without a checkout, submit the same files to POST /api/widgets and it is served instantly as an unreviewed draft.

Source

The whole widget is these files; the repository has their history.

widget.json

{
  "name": "samples-per-cycle",
  "title": "Samples per cycle",
  "version": 1,
  "claim": "Each sample x[n] = x(n/fₛ) records only the wave's amplitude at one instant, and once the rate drops below two samples per cycle the dots no longer determine which wave produced them.",
  "summary": "Slide a slow sine's frequency and a sample rate and watch the lollipop samples thin out over a one-second window; the samples-per-cycle readout turns red below 2. A toggle connects the dots with straight lines for comparison with real reconstruction.",
  "topics": ["signals/sampling", "audio/digital"],
  "aliases": ["sampling", "sample rate", "discrete signal", "x[n]", "samples per second"],
  "params": {
    "freq": { "type": "integer", "default": 3, "min": 1, "max": 8, "label": "wave frequency in Hz" },
    "rate": { "type": "integer", "default": 24, "min": 2, "max": 60, "label": "samples per second" },
    "connect": { "type": "boolean", "default": false, "label": "connect the dots" }
  },
  "check": [
    {
      "q": "Each individual sample stores…",
      "options": ["the wave's amplitude at one instant", "the wave's frequency at that moment", "one full cycle of the wave", "one bit"],
      "answer": 0,
      "why": "A sample is a single amplitude reading, the position of the wave at one instant; frequency emerges only from how the readings change across many samples."
    },
    {
      "q": "One stored sample contains…",
      "options": ["the amplitude of the wave at one instant", "one full cycle of the wave", "the frequency at one instant", "a thousandth of a second of sound"],
      "answer": 0,
      "why": "A sample is one amplitude reading at one tick of the sample clock; pitch and timing only emerge from how thousands of readings change in sequence."
    },
    {
      "q": "CD audio uses how many samples per second?",
      "options": ["44,100", "4,410", "96,000", "1,411,200"],
      "answer": 0,
      "why": "44.1 kHz covers the 20 kHz range of hearing with margin for the anti-aliasing filter; 1,411,200 is CD's bitrate in bits per second, not its sample rate."
    },
    {
      "q": "The Nyquist–Shannon theorem says faithful capture requires…",
      "options": ["a sample rate more than twice the highest frequency present", "a sample rate equal to the highest frequency", "at least 16 bits per sample", "ten samples per cycle"],
      "answer": 0,
      "why": "Faithful capture needs more than two samples per cycle of the fastest component, which is where the readout turns red; bit depth is a separate parameter."
    },
    {
      "q": "Recording at 48,000 samples/s, the highest frequency you can faithfully represent is…",
      "options": ["just under 24 kHz", "just under 48 kHz", "96 kHz", "20 kHz exactly"],
      "answer": 0,
      "why": "The Nyquist limit is half the sample rate; everything above it must be filtered out before sampling."
    }
  ],
  "capabilities": [],
  "height": 495,
  "requires": ["pure-tone"],
  "forkedFrom": null,
  "authors": []
}

index.html

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Samples per cycle</title>
<style>
  :root {
    color-scheme: light dark;
    --bg: #f7f3ea;
    --bg-card: #efe9da;
    --border: #d8cfba;
    --text: #211d14;
    --text-dim: #6e6553;
    --accent: #31597f;
    --accent2: #b04e1b;
    --hot: #a82433;
    --ok: #3d6b4f;
    --ink-rgb: 33, 29, 20;
    --serif: "Iowan Old Style", "Palatino Linotype", Palatino, "Book Antiqua", Georgia, serif;
    --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
  }
  @media (prefers-color-scheme: dark) {
    :root {
      --bg: #161410;
      --bg-card: #1e1b15;
      --border: #383225;
      --text: #e9e3d3;
      --text-dim: #9c917c;
      --accent: #8fb8e0;
      --accent2: #dd9355;
      --hot: #df7a88;
      --ok: #82bd97;
      --ink-rgb: 233, 227, 211;
    }
  }

  * { box-sizing: border-box; }
  html, body { margin: 0; }
  body { background: transparent; color: var(--text); font-family: var(--serif); }

  .widget {
    background: var(--bg-card);
    border: 1px solid var(--border);
    border-radius: 4px;
    padding: 22px;
  }

  .control-row { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; margin-bottom: 14px; }
  .control-row.sym.single {
    display: grid; grid-template-columns: 88px 1fr; gap: 12px 16px;
    align-items: center; margin-bottom: 14px;
  }
  .control-row label { font-size: 14px; color: var(--text-dim); white-space: nowrap; }
  .ctl { display: flex; align-items: center; gap: 10px; min-width: 0; }
  .ctl input[type="range"] { flex: 1; min-width: 0; }
  .ctl .val { flex: none; width: 72px; text-align: right; font-size: 13px; }
  input[type="range"] { accent-color: var(--accent); }
  @media (max-width: 600px) { .control-row.sym.single { grid-template-columns: 64px 1fr; } }

  .toggle { display: inline-flex; align-items: baseline; gap: 7px; font-size: 13.5px; color: var(--text-dim); cursor: pointer; white-space: normal; }
  .toggle input { accent-color: var(--accent2); }

  .mono { font-family: var(--mono); font-variant-numeric: tabular-nums; }
  .dim { color: var(--text-dim); font-size: 12.5px; }

  .chips { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 8px; }
  .btn, .chip {
    font-family: var(--mono); font-size: 12.5px; color: var(--text);
    background: transparent; border: 1px solid var(--border); border-radius: 3px;
    padding: 6px 13px; cursor: pointer; transition: border-color 0.15s, color 0.15s;
  }
  .btn:hover, .chip:hover { border-color: var(--accent); color: var(--accent); }
  .btn.primary { border-color: var(--accent); color: var(--accent); }
  .btn.playing, .btn.playing:hover { border-color: var(--hot); color: var(--hot); }
  .btn.off { border-color: var(--hot); color: var(--hot); opacity: 0.85; }

  .plot { display: block; width: 100%; height: 220px; margin-top: 8px; }
  .plot.tall { height: 280px; }

  .readout-row { display: flex; gap: 28px; flex-wrap: wrap; margin: 14px 0 0; }
  .readout { text-align: left; }
  .readout .big {
    display: block; font-size: 28px; font-weight: 600; color: var(--accent);
    line-height: 1.1; min-width: 5ch; font-variant-numeric: tabular-nums;
  }
  .readout.accent .big { color: var(--accent2); }
  .readout .big.hot { color: var(--hot); }
  .readout small { color: var(--text-dim); font-size: 12.5px; }
  @media (max-width: 560px) {
    .widget { padding: 16px; }
    .readout-row { gap: 12px 18px; }
    .readout .big { font-size: 22px; }
    .plot { height: 180px; }
    .plot.tall { height: 220px; }
    .plot.pipe { height: 200px; }
    .narrow-hide { display: none; }
  }
</style>
</head>
<body>
  <div class="widget" id="root">
    <div class="control-row sym single">
      <label for="smp-f">wave freq</label>
      <span class="ctl wide"><input type="range" id="smp-f" min="1" max="8" value="3"><span class="mono val" id="smp-f-label">3 Hz</span></span>
    </div>
    <div class="control-row sym single">
      <label for="smp-fs">sample rate</label>
      <span class="ctl wide"><input type="range" id="smp-fs" min="2" max="60" value="24"><span class="mono val" id="smp-fs-label">24 /s</span></span>
    </div>
    <div class="control-row">
      <label class="toggle"><input type="checkbox" id="smp-connect"> connect the dots (linear interpolation)</label>
    </div>
    <canvas id="smp-canvas" class="plot tall"></canvas>
    <div class="readout-row">
      <div class="readout">
        <span class="big mono" id="smp-count">24</span>
        <small>samples in this 1-second window</small>
      </div>
      <div class="readout">
        <span class="big mono" id="smp-percycle">8.0</span>
        <small>samples per cycle</small>
      </div>
    </div>
  </div>
  <script src="/w/_sdk/host.js?v=1"></script>
  <script src="/w/_lib/audio.js?v=1"></script>
  <script src="widget.js?v=1"></script>
</body>
</html>

widget.js

/* Samples per cycle: lollipop samples over a slow sine; the readout turns hot below two samples per cycle. */
(() => {
  'use strict';
  const K = window.AudioKit;
  const $ = (id) => document.getElementById(id);
  let freq = 3, rate = 24, connect = false, host = null;

  function render() {
    $('smp-f-label').textContent = freq + ' Hz';
    $('smp-fs-label').textContent = rate + ' /s';
    $('smp-count').textContent = rate;
    const perCycle = rate / freq;
    const pc = $('smp-percycle');
    pc.textContent = perCycle.toFixed(1);
    pc.classList.toggle('hot', perCycle < 2);
    $('smp-connect').checked = connect;

    const { ctx, w, h } = K.setupCanvas($('smp-canvas'));
    const m = { l: 14, r: 14 };
    const pw = w - m.l - m.r;
    const mid = h / 2;
    const amp = h * 0.36;
    const sig = (t) => Math.sin(2 * Math.PI * freq * t);
    const X = (t) => m.l + t * pw;

    ctx.clearRect(0, 0, w, h);
    K.hline(ctx, m.l, w - m.r, mid, K.T.GRID);
    K.trace(ctx, m.l, w - m.r, (u) => mid - amp * sig(u), K.T.ACCENT, 2, 0.65);

    const pts = [];
    for (let n = 0; n < rate; n++) {
      const t = n / rate;
      pts.push([X(t), mid - amp * sig(t)]);
    }
    if (connect) {
      ctx.strokeStyle = K.T.ACCENT2;
      ctx.lineWidth = 1.8;
      ctx.beginPath();
      pts.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
      ctx.stroke();
    }
    pts.forEach(([x, y]) => K.lollipop(ctx, x, mid, y, 3.4));

    ctx.font = '11px ui-monospace, Menlo, monospace';
    ctx.fillStyle = K.T.DIM;
    ctx.textAlign = 'left';
    ctx.fillText('1 s window · x[n] = x(n/fₛ)', m.l + 2, 13);
    if (perCycle < 2) {
      ctx.fillStyle = K.T.HOT;
      ctx.textAlign = 'right';
      ctx.fillText('under 2 samples per cycle: the dots fit a slower wave too', w - m.r - 2, 13);
    }
  }

  const ping = (data) => { if (host && host.signal) host.signal('interaction', data); };
  const set = (p) => {
    if (typeof p.freq === 'number') { freq = K.clamp(Math.round(p.freq), 1, 8); $('smp-f').value = freq; }
    if (typeof p.rate === 'number') { rate = K.clamp(Math.round(p.rate), 2, 60); $('smp-fs').value = rate; }
    if (typeof p.connect === 'boolean') connect = p.connect;
    render();
  };

  $('smp-f').addEventListener('input', () => { set({ freq: +$('smp-f').value }); ping({ freq, rate }); });
  $('smp-fs').addEventListener('input', () => { set({ rate: +$('smp-fs').value }); ping({ freq, rate }); });
  $('smp-connect').addEventListener('input', () => { set({ connect: $('smp-connect').checked }); ping({ connect }); });
  K.debounceResize(render);
  render();

  LearnWidget.connect().then((h) => {
    host = h;
    K.fitFrame(h, $('root'));
    set(h.params || {});
    h.on('theme.changed', () => { K.readTheme(); render(); });
    h.on('params.changed', set);
    K.readTheme();
    render();
  });
})();