@plotdb/lotion 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+## v0.1.0
+
+ - features:
+   - player: show a loading screen until `start()` ( `loading` option: `true` / custom html / `false` );
+     the stage is hidden, the control bar disabled, and `seek` / `play` ignored meanwhile
+   - player: `player.ready`, a promise resolved by `start()`
+   - block loader: wait for the interface's `ready` before exposing the render protocol
+ - tweaks:
+   - player: under `?render`, expose `window.seek` / `window.DURATION` at `start()` instead of construction,
+     so the cli never renders a scene still being prepared
+   - demo: simulate asynchronous preparation ( `?loading=<ms>`, default 1500 ) to show the loading screen
+   - cli: locate `audio/` both next to `cli.js` ( published by `fedep publish`, dist flattened ) and one level up
+     ( in the repo ), so audio commands work in either layout
+ - docs:
+   - document the loading behavior in README and `prompt/explainer.md`
+
+
+## v0.0.1
+
+ - init release
+   - runtime: spring, track, vis, bump, typing, color and DOM helpers
+   - runtime: player with timeline, chapters, keyboard control, fullscreen and render protocol
+   - block player: `@plotdb/block` runtime bundled with a loader, supporting registry and packed modes
+   - cli: `frames`, `sheet`, `video` ( optional motion blur ), `cues` and `bundle`
+   - audio: `bgm` ( bassline synthesizer ), `beats`, `sfx` and `mix`
+   - prompts: `ui-loop.md` and `explainer.md`
+   - demo pages in `web/`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zbryikt
+
+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

@@ -0,0 +1,190 @@
+# lotion
+
+Deterministic motion toolkit: write animations as a pure function of time, `seek(t)`, then
+play, scrub, embed, or render them frame by frame into video.
+
+ - runtime ( `dist/index.js` ): springs in closed form, keyframe tracks, fade windows, small DOM helpers,
+   and a player with scrubbing / chapters / fullscreen.
+ - block player ( `dist/block/player.js` ): package an animation as a `@plotdb/block` and embed it anywhere.
+ - cli ( `lotion` ): render any page following the render protocol into png frames, contact sheets or mp4,
+   and bundle blocks.
+ - audio tools ( `audio/` ): beat detection, ui sound effects, a simple bassline bgm synthesizer and a cue mixer.
+ - prompts ( `prompt/` ): workflow notes for producing motion designs and explainer animations with an AI agent.
+
+
+## Install
+
+    npm install --save @plotdb/lotion
+
+The cli additionally needs `playwright` ( with chromium installed, `npx playwright install chromium` ) and
+`ffmpeg` in `PATH`. Audio tools need `python3` with `numpy`.
+
+
+## Runtime
+
+include the script and css:
+
+    <link rel="stylesheet" href="index.min.css">
+    <script src="index.min.js"></script>
+
+create a player, build your scene into `player.stage`, then call `start()`:
+
+    p = new lotion.player do
+      root: '#demo'
+      duration: 10
+      chapters: [[0, 'intro'], [4, 'detail']]
+      seek: (t) -> seek t
+    x = lotion.track [[0, 100], [1, 800], [3, 100]]
+    dot = lotion.mk 'dot', '', p.stage
+    seek = (t) -> lotion.put dot, x(t), 300, 1, lotion.vis(t, 0.2)
+    p.start!
+
+player options:
+
+ - `root`: container element or selector.
+ - `width`, `height`: design size of the stage. default `1920` x `1080`. The stage scales to fit the container.
+ - `duration`: total length in seconds.
+ - `seek(t)`: render the frame at time `t`. must depend on `t` only.
+ - `chapters`: optional `[[t, name], ...]`, shown as ticks on the timeline and used by `←` / `→`.
+ - `start`: initial time. `?t=<sec>` in the url takes precedence.
+ - `autoplay`: default `false`.
+ - `cues`: optional function returning sound cues `[{t, ...}]`, exported by `lotion cues`.
+ - `loading`: what to show before `start()`. default `true` ( a spinner ); a string is used as custom html;
+   `false` shows nothing.
+
+player methods: `start()`, `seek(t)`, `play(go = true)`, `pause()`, `toggle()`, `fullscreen()`.
+`player.ready` is a promise resolved by `start()`.
+
+Until `start()` is called, the stage is hidden behind the loading screen, the control bar is disabled, and
+`seek` / `play` do nothing. Scenes often need asynchronous preparation before the first frame is right
+( web fonts, measuring the layout to place things ), and a half-built stage should not be seen or scrubbed.
+So build the scene, finish whatever it waits for, then call `start()`:
+
+    Promise.all([document.fonts.ready, prepare!]).then -> p.start!
+Keys ( when the player is focused ): `space` play / pause, `←` / `→` previous / next chapter, `f` fullscreen.
+
+helpers:
+
+ - `spring(t, w = 14, z = 0.8)`: step response of a damped spring, `0 -> 1`.
+ - `track(keys, opt = 'std')`: `keys` is `[[t, value, preset?], ...]`. returns `(t) -> value`, summing one
+   spring response per change of target. `opt` / `preset` is `{w, z}` or a name in `presets`
+   ( `fast`, `std`, `soft`, `move`, `ease` ).
+ - `vis(t, t0, t1, din, dout)`: fade window. `0 -> 1` from `t0`, back to `0` from `t1`.
+ - `bump(t, t0, d)`: a `0 -> 1 -> 0` pulse.
+ - `typing(t, t0, text, dt)`: the part of `text` typed by time `t`.
+ - `hex(str)`, `mixc(a, b, f)`, `rgb(c, alpha)`: color helpers working on `[r, g, b]`.
+ - `mk(cls, html, parent, prefix)`: create a div.
+ - `put(el, x, y, s, o, {hide, blur})`: set transform / opacity. hides the element by `visibility` when
+   transparent; pass `hide: false` for nested elements, since a visible child overrides a hidden parent.
+ - `txt(el, html)`: set innerHTML only when changed.
+ - `svg(tag, attrs, parent)`: create an svg element.
+
+
+## Render protocol
+
+With `?render` in the url, a page should cover the viewport with its stage and expose:
+
+ - `window.seek(t)`: render the frame at `t`.
+ - `window.DURATION`: total length in seconds.
+ - `window.cues()`: optional, list of sound cues.
+
+`lotion.player` does this automatically, and only when `start()` is called: the cli waits for `window.seek` to
+exist before rendering, so it never captures a scene that is still being prepared. Any other page can follow
+the protocol by itself; likewise, define `window.seek` only when the first frame can be rendered correctly.
+
+
+## Block Player
+
+An animation can be packaged as a [@plotdb/block](https://github.com/plotdb/block): HTML, scoped CSS and JS in
+one file, with libraries ( including lotion itself ) declared as dependencies and injected by `rescope` /
+`csscope`. `dist/block/player.js` bundles `@plotdb/block` with its dependencies ( semver, proxise, csscope,
+rescope ) and a loader, about 47KB minified.
+
+    <div data-block="my-animation"></div>
+    <script src="player.js" data-block-root="/block" data-lib-root="/assets/lib"></script>
+
+ - `data-block`: block name. optional `data-version`, `data-path`.
+ - `data-bundle`: optional url of a packed block ( see `lotion bundle` ). With it, nothing is fetched from
+   the registry, so `player.js` plus the bundle file can be copied to any site.
+ - script attributes: `data-block-root` ( default `/block`, blocks at `<root>/<name>/index.html` ),
+   `data-lib-root` ( default `/assets/lib`, libraries at `<root>/<name>/<version>/<path>` ), `data-manual`
+   ( don't mount automatically; use `lotionBlock.mount(el)` ).
+ - `window.lotionBlock`: `{manager, mount, ready}`.
+ - If a mounted block's interface provides `seek(t)` and `duration`, they are exposed per the render protocol
+   under `?render`. If it also provides `ready` ( a promise, e.g. `player.ready` ), they are exposed after it
+   resolves. A block using `lotion.player` should pass `ready: player.ready` in its interface.
+
+Note that csscope scopes a block's style to the *descendants* of its root, so put the element your style
+targets under the root ( or use `:scope` ). A block sample is in `web/src/pug/block/lotion-demo`.
+
+
+## CLI
+
+    lotion frames <src> <outdir> <t...>      one png per time
+    lotion sheet  <src> <out.png> <t...>     the same, tiled into one contact sheet
+    lotion video  <src> <out.mp4>            render to mp4
+    lotion cues   <src> <out.json>           dump window.cues()
+    lotion bundle <base-url> <block> <out>   pack a block and its dependencies into one file
+    lotion bgm | sfx | mix | beats ...       audio tools, see below
+
+`<src>` is an http(s) url, or a local html file / directory served by a built-in static server.
+
+options:
+
+ - `--width 1920 --height 1080`: viewport size.
+ - `--fps 60`, `--sub 1`, `--shutter 0.5`: video settings. with `--sub` greater than 1, each frame averages
+   `sub` sub-samples spread over `shutter` of the frame interval ( motion blur, via ffmpeg `tmix` ).
+ - `--from`, `--to`: render only a range, in seconds.
+ - `--crf 16`: x264 quality.
+ - `--cols 3`, `--tile 640`: contact sheet layout.
+ - `--query`: extra url parameters, such as `--query bar=1`.
+ - `--block-root /block`, `--lib-root /assets/lib`: registry paths for `bundle`, relative to `base-url`.
+
+
+## Audio
+
+Each command forwards its arguments to the python script of the same name in `audio/`; pass `-h` for all options.
+All times are aligned so that `t = 0` matches the start of the animation.
+
+ - `lotion bgm out.wav --bpm 120 --bars 16 --key A --scale minor --prog 1,6,3,7 --bass drive --drums four --pad`:
+   synthesize a track around a repeating bassline. bass presets: `pulse`, `octave`, `house`, `drive`, `walk`,
+   or 16 custom steps ( semitones from the chord root, `.` rest, `-` hold ). drum presets: `four`, `half`, `broken`,
+   `none`. `--loop` makes it loop seamlessly; `--grid grid.json` writes its beat grid.
+ - `lotion beats music.mp3 --start 64.11 --dur 30 --out grid.json`: estimate bpm and the beat grid
+   ( `{bpm, offset, beats, downbeats}` ). with an off-beat bassline and syncopated kicks the grid may be half a beat
+   off; correct it with `--shift 0.5`.
+ - `lotion sfx sfx/`: synthesize ui sound effects ( click, tick, scrub, pop, toggle, success, notify, type, whoosh )
+   and measure each transient peak into `sfx/peaks.json`.
+ - `lotion mix cues.json out.wav --dur 30 --music bgm.wav --sfx sfx/ [--loop | --fade 2]`: mix music with sound
+   effects placed at cue times ( `[{t, sfx, gain}]`, e.g. from `lotion cues` ), aligning each effect's measured
+   peak rather than its file start.
+
+A typical flow:
+
+    lotion bgm bgm.wav --bpm 120 --bars 16 --grid grid.json   # time the animation on this grid
+    lotion sfx sfx/
+    lotion cues page.html cues.json
+    lotion mix cues.json audio.wav --dur 32 --music bgm.wav --sfx sfx/ --fade 2
+    lotion video page.html silent.mp4
+    ffmpeg -i silent.mp4 -i audio.wav -c:v copy -c:a aac -shortest out.mp4
+
+
+## Prompts
+
+ - `prompt/ui-loop.md`: a phased workflow for short, looping, single-object UI motion with music.
+ - `prompt/explainer.md`: practices for longer explainer animations, embedding them into pages, and common pitfalls.
+
+
+## Development
+
+    npm start          # dev server for the demo in web/
+    ./build            # src -> dist, and copy to web/static/assets/lib/lotion/dev
+
+the packed block demo is generated from the running dev server:
+
+    node dist/cli.js bundle http://localhost:<port> lotion-demo web/static/block/lotion-demo.bundle.html
+
+
+## License
+
+MIT

package/audio/beats.py

@@ -0,0 +1,93 @@
+# 節拍分析: 估計 BPM 與第一拍位置, 輸出節拍格線 ( 整理自 0926-motion 的 bpm / grid / refine ).
+#  python audio/beats.py <music> [--start s] [--dur s] [--min 70] [--max 180] [--out grid.json]
+#  - BPM: onset 包絡的自相關, 同時考慮 1 / 2 / 4 倍拍長, 再以相位一致性細調到 0.005 BPM
+#  - 第一拍: 在一個週期內掃描起點, 取節拍位置上包絡總和最大者 ( 以低頻為主 ); 並補償分析窗的延遲
+#  - 小節起點: 比較 4 個相位上低頻 ( kick ) 的強度, 取最強者
+#  - 限制: bassline 落在反拍、kick 又是切分時, 拍點可能偏半拍; 以 --shift 0.5 ( 單位: 拍 ) 校正
+#  - 輸出: {bpm, offset, beats, downbeats}; 時間皆相對於 --start
+import numpy as np, argparse, json
+from common import load
+
+SR = 22050
+HOP = 256
+FPS = SR / HOP
+
+def frames(x, n=1024):
+  m = (len(x) - n) // HOP
+  return np.lib.stride_tricks.as_strided(x, (m, n), (x.strides[0] * HOP, x.strides[0])) * np.hanning(n)
+
+def onset_env(x):
+  S = np.log1p(100 * np.abs(np.fft.rfft(frames(x), axis=1)))
+  fl = np.maximum(0, np.diff(S, axis=0)).sum(1)
+  fl = fl - np.convolve(fl, np.ones(32) / 32, 'same')
+  return np.maximum(fl, 0)
+
+def low_env(x, cut=150):
+  S = np.abs(np.fft.rfft(frames(x), axis=1))
+  f = np.fft.rfftfreq(1024, 1 / SR)
+  return np.maximum(0, np.diff(np.log1p(100 * S[:, f < cut]).sum(1)))
+
+def coarse_tempo(env, lo, hi):
+  e = env - env.mean()
+  ac = np.correlate(e, e, 'full')[len(e) - 1:]
+  bpms = np.arange(lo, hi + 0.01, 0.1)
+  def score(b):
+    lag, s = 60 * FPS / b, 0
+    for k in (1, 2, 4):
+      L = lag * k; i = int(L); f = L - i
+      if i + 1 < len(ac): s += (ac[i] * (1 - f) + ac[i + 1] * f) / k
+    return s
+  sc = np.array([score(b) for b in bpms])
+  return bpms[sc.argmax()], sc.max() / ac[0]
+
+def fine_tempo(env, b0):
+  t = np.arange(len(env)) / FPS
+  bs = np.arange(b0 - 1, b0 + 1, 0.005)
+  sc = [abs(sum(np.sum(env * np.exp(-2j * np.pi * (b / 60) * k * t)) for k in (1, 2, 4))) for b in bs]
+  return bs[int(np.argmax(sc))]
+
+# 分析窗的延遲: diff 後第 i 個值反映的是第 i + 1 個窗, 窗的中心再晚半個窗長
+LAG = (HOP + 512) / SR
+
+def norm(v): return v / (v.max() + 1e-9)
+
+def grid(x, bpm):
+  env = onset_env(x); low = low_env(x)
+  m = min(len(env), len(low))
+  # 拍點以低頻 ( kick / bass 起音 ) 為主, 避免被反拍的 hat 或 16 分音符拉偏
+  e = norm(low[:m]) * 2 + norm(env[:m])
+  t = np.arange(m) / FPS
+  period = 60 / bpm
+  idx = np.arange(m)
+  def score(o): return np.interp(np.arange(o, t[-1] - 0.1, period) * FPS, idx, e).sum()
+  cands = np.arange(0, period, 0.001)
+  off = cands[int(np.argmax([score(o) for o in cands]))]
+  beats = np.arange(off, t[-1] - 0.1, period)
+  lb = np.interp(beats * FPS, np.arange(len(low)), low)
+  phase = int(np.argmax([lb[i::4].mean() for i in range(4)]))
+  beats = beats + LAG
+  return beats, beats[phase::4]
+
+if __name__ == '__main__':
+  ap = argparse.ArgumentParser(description='estimate bpm and beat grid of a music file')
+  ap.add_argument('music')
+  ap.add_argument('--start', type=float, default=0)
+  ap.add_argument('--dur', type=float, default=None)
+  ap.add_argument('--min', type=float, default=70)
+  ap.add_argument('--max', type=float, default=180)
+  ap.add_argument('--out', default=None, help='write grid json here')
+  ap.add_argument('--shift', type=float, default=0, help='shift the grid by this many beats')
+  a = ap.parse_args()
+  x = load(a.music, sr=SR, start=a.start, dur=a.dur)
+  b0, conf = coarse_tempo(onset_env(x), a.min, a.max)
+  bpm = fine_tempo(onset_env(x), b0)
+  beats, downbeats = grid(x, bpm)
+  if a.shift:
+    d = a.shift * 60 / bpm
+    beats, downbeats = beats + d, downbeats + d
+  print('bpm %.3f ( coarse %.1f, confidence %.2f )  first beat %.4fs  first downbeat %.4fs  beats %d'
+    % (bpm, b0, conf, beats[0], downbeats[0], len(beats)))
+  if a.out:
+    json.dump({'bpm': round(float(bpm), 3), 'offset': round(float(beats[0]), 4),
+      'beats': [round(float(v), 4) for v in beats], 'downbeats': [round(float(v), 4) for v in downbeats]},
+      open(a.out, 'w'), indent=1)

package/audio/bgm.py

@@ -0,0 +1,181 @@
+# 簡易背景音樂合成: 以重複的 bassline 為骨幹, 加上鼓組與和弦墊音. 只依賴 numpy.
+#  python audio/bgm.py <out.wav> [--bpm 120] [--bars 16] [--key A] [--scale minor] [--prog 1,6,3,7]
+#                      [--bass pulse] [--drums four] [--pad] [--intro 2] [--outro 2] [--loop] [--grid grid.json]
+#
+#  設計:
+#  - 和弦進行以音階級數表示 ( --prog 1,6,3,7 ), 每小節一個和弦, 循環使用
+#  - bassline 是一小節 16 格的樣式 ( --bass ), 每格為相對於和弦根音的半音數, '.' 為休止; 每小節重複, 隨和弦移調
+#  - 鼓組樣式 ( --drums ): kick / hat / clap 各 16 格
+#  - 編排: 前 --intro 小節只有 bass 與 hat, 最後 --outro 小節逐漸收掉; --loop 時不做 intro / outro,
+#    並把超出尾端的音尾繞回開頭, 可無縫循環
+#  - t = 0 即第一小節的第一拍, 方便與動畫時間軸對齊; --grid 會輸出節拍格線 ( 與 beats.py 格式相同 )
+import numpy as np, argparse, json
+from common import SR, write, normalize
+
+NOTE = {'C': 0, 'C#': 1, 'Db': 1, 'D': 2, 'D#': 3, 'Eb': 3, 'E': 4, 'F': 5, 'F#': 6, 'Gb': 6,
+  'G': 7, 'G#': 8, 'Ab': 8, 'A': 9, 'A#': 10, 'Bb': 10, 'B': 11}
+SCALE = {
+  'major': [0, 2, 4, 5, 7, 9, 11], 'minor': [0, 2, 3, 5, 7, 8, 10],
+  'dorian': [0, 2, 3, 5, 7, 9, 10], 'mixolydian': [0, 2, 4, 5, 7, 9, 10]
+}
+# bassline 樣式: 16 格, 數字為相對和弦根音的半音數, '.' 休止, '-' 延續前一音
+BASS = {
+  'pulse':  '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0',
+  'octave': '0 . 12 . 0 . 12 . 0 . 12 . 0 . 12 .',
+  'house':  '. . 0 . . . 0 . . . 0 . . . 0 12',
+  'drive':  '0 . 0 12 . 0 7 . 0 . 0 12 . 7 5 .',
+  'walk':   '0 - - - 7 - - - 12 - - - 7 - 5 -',
+}
+DRUMS = {
+  'four':   {'kick': 'x...x...x...x...', 'hat': '..x...x...x...x.', 'clap': '....x.......x...'},
+  'half':   {'kick': 'x.......x.......', 'hat': 'x.x.x.x.x.x.x.x.', 'clap': '........x.......'},
+  'broken': {'kick': 'x.....x...x.....', 'hat': '..x...x...x...xx', 'clap': '....x.......x..x'},
+  'none':   {'kick': '................', 'hat': '................', 'clap': '................'},
+}
+
+rng = np.random.default_rng(3)
+
+def hz(midi): return 440 * 2 ** ((midi - 69) / 12)
+
+def env(n, a, d, sustain=0.0, r=0.0):
+  """attack / 指數衰減至 sustain; 結尾 r 秒線性釋放"""
+  t = np.arange(n) / SR
+  e = (1 - np.exp(-t / max(a, 1e-4))) * (sustain + (1 - sustain) * np.exp(-t / d))
+  if r > 0:
+    k = min(n, int(r * SR)); e[n - k:] *= np.linspace(1, 0, k)
+  return e
+
+def saw(f, n, detune=0.0):
+  t = np.arange(n) / SR
+  x = 2 * ((f * t) % 1) - 1
+  if detune: x = 0.5 * x + 0.5 * (2 * ((f * (1 + detune) * t + 0.37) % 1) - 1)
+  return x
+
+def lowpass(x, cutoff, q=0.9):
+  """時變截止頻率的 state variable filter. cutoff 可為陣列 ( 每個 sample 一個值 )"""
+  cutoff = np.broadcast_to(cutoff, x.shape)
+  f = 2 * np.sin(np.pi * np.clip(cutoff, 20, SR / 6) / SR)
+  low = band = 0.0
+  y = np.empty_like(x)
+  damp = 1 / q
+  for i in range(len(x)):
+    low += f[i] * band
+    high = x[i] - low - damp * band
+    band += f[i] * high
+    y[i] = low
+  return y
+
+def bass_note(midi, dur, accent=1.0):
+  n = int(dur * SR)
+  x = saw(hz(midi), n, detune=0.004) + 0.5 * np.sin(2 * np.pi * hz(midi - 12) * np.arange(n) / SR)
+  cut = 180 + 1400 * accent * np.exp(-np.arange(n) / SR / 0.09)
+  return lowpass(x, cut, q=1.4) * env(n, 0.003, 0.25, 0.55, 0.02) * 0.5
+
+def kick():
+  n = int(0.35 * SR); t = np.arange(n) / SR
+  f = 48 + 110 * np.exp(-t / 0.035)
+  return np.sin(2 * np.pi * np.cumsum(f) / SR) * env(n, 0.001, 0.16) * 0.95
+
+def noise_hp(n, cut):
+  X = np.fft.rfft(rng.standard_normal(n)); fq = np.fft.rfftfreq(n, 1 / SR)
+  X[fq < cut] = 0
+  y = np.fft.irfft(X, n); return y / (np.abs(y).max() + 1e-9)
+
+def hat(open_=False):
+  n = int((0.18 if open_ else 0.05) * SR)
+  return noise_hp(n, 7000) * env(n, 0.0005, 0.06 if open_ else 0.012) * 0.22
+
+def clap():
+  n = int(0.22 * SR)
+  x = noise_hp(n, 1200) * env(n, 0.001, 0.06)
+  for d in (0.011, 0.022):  # 拍手的多重起音
+    k = int(d * SR); x[k:] += noise_hp(n - k, 1200) * env(n - k, 0.001, 0.012) * 0.6
+  return x * 0.28
+
+def pad_chord(midis, dur):
+  n = int(dur * SR)
+  x = sum(saw(hz(m), n, detune=0.006) for m in midis) / len(midis)
+  return lowpass(x, 900, q=0.7) * env(n, 0.35, 10, 0.9, 0.4) * 0.16
+
+def parse_steps(s):
+  tok = s.split() if ' ' in s.strip() else list(s)
+  if len(tok) != 16: raise SystemExit('pattern must have 16 steps: %r' % s)
+  return tok
+
+if __name__ == '__main__':
+  ap = argparse.ArgumentParser(description='synthesize a simple looping bassline track')
+  ap.add_argument('out')
+  ap.add_argument('--bpm', type=float, default=120)
+  ap.add_argument('--bars', type=int, default=16)
+  ap.add_argument('--key', default='A', help='tonic, e.g. A, C#, Eb')
+  ap.add_argument('--octave', type=int, default=2, help='octave of the bass tonic')
+  ap.add_argument('--scale', default='minor', choices=list(SCALE))
+  ap.add_argument('--prog', default='1,6,3,7', help='chord degrees, one per bar, cycled')
+  ap.add_argument('--bass', default='drive', help='preset (%s) or 16 custom steps' % ', '.join(BASS))
+  ap.add_argument('--drums', default='four', choices=list(DRUMS))
+  ap.add_argument('--pad', action='store_true', help='add sustained chord pad')
+  ap.add_argument('--intro', type=int, default=2, help='bars with bass and hat only')
+  ap.add_argument('--outro', type=int, default=2, help='bars fading out at the end')
+  ap.add_argument('--loop', action='store_true', help='seamless loop: no intro / outro, tails wrap around')
+  ap.add_argument('--swing', type=float, default=0, help='0 ~ 0.3, delays every second 16th')
+  ap.add_argument('--grid', default=None, help='write beat grid json here')
+  a = ap.parse_args()
+
+  scale = SCALE[a.scale]
+  tonic = 12 * (a.octave + 1) + NOTE[a.key]
+  prog = [int(v) for v in a.prog.split(',')]
+  bass = parse_steps(BASS.get(a.bass, a.bass))
+  drums = {k: parse_steps(v) for k, v in DRUMS[a.drums].items()}
+  intro, outro = (0, 0) if a.loop else (a.intro, a.outro)
+
+  step = 60 / a.bpm / 4
+  total = a.bars * 16 * step
+  n = int(round(total * SR))
+  out = np.zeros((n + int(SR * 2), 2), np.float32)  # 多留 2 秒放音尾
+
+  def place(x, t, gain=1.0, pan=0.0):
+    s = int(round(t * SR)); e = s + len(x)
+    l, r = np.cos((pan + 1) * np.pi / 4), np.sin((pan + 1) * np.pi / 4)
+    out[s:e, 0] += x * gain * l * 1.414
+    out[s:e, 1] += x * gain * r * 1.414
+
+  def degree(d, shift=0):
+    i = d - 1 + shift
+    return scale[i % 7] + 12 * (i // 7)
+
+  K, C = kick(), clap()
+  for bar in range(a.bars):
+    root = tonic + degree(prog[bar % len(prog)])
+    t0 = bar * 16 * step
+    # 編排: intro 只有 bass + hat; outro 逐小節降低音量
+    level = 1.0 if bar < a.bars - outro else (a.bars - bar) / (outro + 1)
+    full = bar >= intro
+    if a.pad and full:
+      d = prog[bar % len(prog)]
+      chord = [tonic + 12 + degree(d), tonic + 12 + degree(d, 2), tonic + 12 + degree(d, 4)]
+      place(pad_chord(chord, 16 * step), t0, level)
+    for i in range(16):
+      t = t0 + i * step + (a.swing * step if i % 2 else 0)
+      s = bass[i]
+      if s not in ('.', '-'):
+        length = 1
+        while i + length < 16 and bass[i + length] == '-': length += 1
+        place(bass_note(root + int(s), length * step * 0.92, 1.0 if i % 4 == 0 else 0.6), t, level)
+      if full and drums['kick'][i] == 'x': place(K, t, level)
+      if full and drums['clap'][i] == 'x': place(C, t, level * 0.9, 0.15)
+      if drums['hat'][i] == 'x': place(hat(), t, level * (1 if full else 0.7), -0.25)
+
+  if a.loop:
+    tail = out[n:].copy()
+    out = out[:n]
+    k = min(len(tail), n)
+    out[:k] += tail[:k]
+  else:
+    tail = int(SR * 1.5)
+    out = out[:n + tail]
+    out[n:] *= np.linspace(1, 0, tail)[:, None]
+  write(a.out, normalize(out * 0.9, 0.95))
+  beats = [round(i * 4 * step, 4) for i in range(a.bars * 4)]
+  print('%s  %.1f bpm  %d bars  %.2fs  key %s %s  prog %s' % (a.out, a.bpm, a.bars, total, a.key, a.scale, a.prog))
+  if a.grid:
+    json.dump({'bpm': a.bpm, 'offset': 0, 'beats': beats, 'downbeats': beats[::4]}, open(a.grid, 'w'), indent=1)

package/audio/common.py

@@ -0,0 +1,30 @@
+# 音訊工具共用: 讀檔 ( 經 ffmpeg ) 與寫 wav. 只依賴 numpy.
+import numpy as np, subprocess, wave
+
+SR = 48000
+
+def load(path, sr=SR, start=0, dur=None, channels=1):
+  """以 ffmpeg 解碼任意音訊檔, 回傳 float32 陣列 ( channels > 1 時為 (n, channels) )"""
+  cmd = ['ffmpeg', '-v', 'quiet', '-ss', str(start)] + (['-t', str(dur)] if dur else []) + \
+    ['-i', path, '-ac', str(channels), '-ar', str(sr), '-f', 'f32le', '-']
+  x = np.frombuffer(subprocess.run(cmd, capture_output=True, check=True).stdout, dtype=np.float32)
+  return x.reshape(-1, channels).copy() if channels > 1 else x.copy()
+
+def write(path, x, sr=SR):
+  """寫入 16-bit wav. x 為 (n,) 或 (n, channels), 數值範圍 -1 ~ 1"""
+  x = np.clip(np.asarray(x, dtype=np.float32), -1, 1)
+  ch = 1 if x.ndim == 1 else x.shape[1]
+  with wave.open(path, 'wb') as w:
+    w.setnchannels(ch); w.setsampwidth(2); w.setframerate(sr)
+    w.writeframes((x * 32767).astype('<i2').tobytes())
+
+def read_wav(path):
+  """讀取 16-bit wav, 回傳 (資料, sr). 多聲道時為 (n, channels)"""
+  with wave.open(path) as w:
+    ch, sr = w.getnchannels(), w.getframerate()
+    x = np.frombuffer(w.readframes(w.getnframes()), '<i2').astype(np.float32) / 32767
+  return (x.reshape(-1, ch) if ch > 1 else x), sr
+
+def normalize(x, peak=0.98):
+  m = np.abs(x).max()
+  return x * (peak / m) if m > peak else x

package/audio/mix.py

@@ -0,0 +1,51 @@
+# 混音: 背景音樂 + 依 cue 放置的音效 ( 整理自 0926-motion ).
+#  python audio/mix.py <cues.json> <out.wav> --dur s [--music f] [--start s] [--sfx dir] [--fade s] [--loop]
+#  - cues.json: [{t, sfx, gain?}, ...], 通常由 `lotion cues` 從頁面匯出
+#  - 音效以 sfx 目錄裡 peaks.json 量到的 transient peak 對齊 cue 時間, 而非檔案開頭 ( 見 sfx.py )
+#  - --music: 任意音訊檔 ( 例如 bgm.py 的輸出 ); --start 為音樂中對齊 t = 0 的位置
+#  - --loop: 超出尾端的音效回繞到開頭, 音訊可無縫循環; 否則尾端以 --fade 秒淡出
+import numpy as np, json, os, argparse
+from common import SR, load, read_wav, write, normalize
+
+ap = argparse.ArgumentParser(description='mix background music and cue-aligned sound effects')
+ap.add_argument('cues')
+ap.add_argument('out')
+ap.add_argument('--dur', type=float, required=True, help='length of the output in seconds')
+ap.add_argument('--music', default=None)
+ap.add_argument('--start', type=float, default=0, help='position in music aligned to t = 0')
+ap.add_argument('--sfx', default='sfx', help='directory of sfx wav files and peaks.json')
+ap.add_argument('--fade', type=float, default=0)
+ap.add_argument('--loop', action='store_true')
+ap.add_argument('--sfx-gain', type=float, default=0.55)
+ap.add_argument('--music-gain', type=float, default=0.8)
+a = ap.parse_args()
+
+n = int(SR * a.dur)
+mix = np.zeros((n, 2), np.float32)
+if a.music:
+  music = load(a.music, start=a.start, dur=a.dur, channels=2)[:n]
+  mix[:len(music)] = music * a.music_gain
+
+cues = json.load(open(a.cues))
+peaks = json.load(open(os.path.join(a.sfx, 'peaks.json'))) if cues else {}
+cache = {}
+for c in cues:
+  name = c['sfx']
+  if name not in cache:
+    x, _ = read_wav(os.path.join(a.sfx, name + '.wav'))
+    cache[name] = x if x.ndim == 1 else x.mean(1)
+  x = cache[name] * c.get('gain', 1) * a.sfx_gain
+  s = int(round((c['t'] - peaks.get(name, 0)) * SR))
+  idx = s + np.arange(len(x))
+  if a.loop: idx %= n
+  else:
+    m = (idx >= 0) & (idx < n); idx, x = idx[m], x[m]
+  np.add.at(mix[:, 0], idx, x)
+  np.add.at(mix[:, 1], idx, x)
+
+if a.fade > 0 and not a.loop:
+  f = int(SR * a.fade)
+  mix[n - f:] *= np.linspace(1, 0, f)[:, None]
+pk = float(np.abs(mix).max())
+write(a.out, normalize(mix))
+print('%s  cues %d  peak %.3f' % (a.out, len(cues), pk))