diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c436f70 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +node_modules/ +cutaway-out/ +__pycache__/ +*.pyc diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3c28d3a --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2026 Nyxera0x +Copyright (c) 2026 whaleyxbt + +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. diff --git a/README.md b/README.md index b1b6e8e..ab75050 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,76 @@ -# Cutaway +# cutaway -A cutaway is a machine drawn with its shell opened, so you see the mechanism inside. This is the method for building one as a live 3D film from a single reference image: Claude Code writes every shell, gear and part as three.js code, checks the result against the picture, and films the object taking itself apart. It works for anything with a dense core: robotic animals, engines, drones, devices. +A Claude Code skill that turns one picture into a 3D object that takes itself apart. -This repository holds the method, not the output: +Give Claude an image of a robotic animal, a machine or a device. It rebuilds it in three.js, every shell, gear and fang written as code, checks the build against the picture line by line, and films it: a cursor presses a button, that part comes apart under its own camera, then the whole object explodes and snaps back together. -- the job description Claude reads before every animal; -- the checklist format and a full example; -- every prompt, step by step; -- the corrections that made it work. +![Theraphos TH-8 robotic tarantula](docs/tarantula.gif) -There is no code here and no renders. Claude writes the code on your machine from these files. - -## What you need - -- **Claude Code** on Opus. -- **An image model** (ChatGPT works) for the reference picture. -- **Node.js 20 or newer**, **ffmpeg** and **Python 3** for the video and the sound. Claude Code installs them if you ask. - -## How it runs - -1. **Generate the reference.** One picture sets the look and nothing else. See [PROMPTS.md](PROMPTS.md), step 1. -2. **Add the job description.** Copy [JOB_DESCRIPTION.md](JOB_DESCRIPTION.md) into your project and point Claude at it before every animal. -3. **Write a checklist for this picture.** 10 to 12 numbered lines on what this one image stands on. See [CHECKLIST.md](CHECKLIST.md). -4. **Run the still loop.** Claude renders a still, stacks it next to the reference and grades every line. It stops after round 2 and waits for you. -5. **Measure.** Dark-pixel share against the reference, and the proportions in numbers. Eyeballing lets a tidy diagram through. -6. **Save every correction** into the job description. [LESSONS.md](LESSONS.md) lists ours. -7. **Film it.** Port the approved film of the animal with the closest body 1:1 and change the body only. Every beat gets its own camera. -8. **Write the short version.** A 10-second version is its own script, never a montage of the long one. -9. **Render frame by frame** and score the sound on the same script. - -## Files - -| File | What it is | +| Serrasal PX-7 robotic piranha | Vespion VX-9 robotic wasp | |---|---| -| [JOB_DESCRIPTION.md](JOB_DESCRIPTION.md) | The brief Claude reads before every animal: the look, the order of work, the camera, the film | -| [CHECKLIST.md](CHECKLIST.md) | How to write a checklist for one picture, a template and a full 12-line example | -| [PROMPTS.md](PROMPTS.md) | Every prompt, from the reference image to the sound | -| [LESSONS.md](LESSONS.md) | Each mistake, what it looked like, and the line it added to the job description | +| ![Serrasal PX-7 robotic piranha](docs/piranha.gif) | ![Vespion VX-9 robotic wasp](docs/wasp.gif) | -## What it costs +## Install -- A still runs about 400,000 tokens over 3 rounds. -- A film runs another 150,000 to 400,000. -- Run 2 animals at a time, not 4, and look at both after round 2. A note there still changes the outcome; after round 6 it only costs tokens. -- An animal whose body is unlike anything you have filmed costs about twice as much. Pick one close to an approved body, or know the price first. +``` +npx skills add Nyxera0x/cutaway -g -a claude-code +``` + +Then, once, in the installed folder: + +``` +npm install && npx playwright install chromium +``` + +You need Node.js 20 or newer. For the video you also need `ffmpeg`, and for the sound Python 3. + +## Use + +Give Claude Code a picture and ask in plain words: + +> Here is a robotic mantis. Build it as a 3D object I can take apart, and stop at the still so I can check it. + +> Turn this image of a robot crab into a 20-second film where every part comes apart. + +> I approved the still. Film it the way the piranha example is filmed. + +No picture yet? `docs/PROMPTS.md` has the prompt that generated ours. + +Or open one of the 3 examples first: + +``` +node sims/build.mjs tarantula-film # cutaway-out/dist/tarantula-film.html +node sims/build.mjs piranha-film +node sims/build.mjs wasp-film +``` + +## How it works + +1. **One reference picture** sets the look. Claude reads it and rebuilds it; it never imports it. +2. **A checklist for that picture**: 10 to 12 numbered lines Claude grades yes, partial or no every round. +3. **Measured, not eyeballed**: the share of dark mechanism and the proportions, both against the picture. +4. **A still first.** Claude stops after round 2 and waits for your yes. Nothing gets filmed before it. +5. **The film** reuses the example with the closest body 1:1 and changes the body only. Every part gets its own camera. +6. **A 10-second version** gets its own script, its own opening and its own exit. + +The whole method is in `docs/`, written so you can follow it with or without the code. + +## What is inside + +| | | +|---|---| +| `SKILL.md` | What Claude reads: the order of work, the rules that make it look right, the review loop. | +| `docs/JOB_DESCRIPTION.md` | The brief Claude reads before every object. Your corrections go into it. | +| `docs/CHECKLIST.md`, `docs/PROMPTS.md`, `docs/LESSONS.md` | The checklist format with a full example, every prompt, every mistake and the line it added. | +| `sims/tarantula-*`, `sims/piranha-*`, `sims/wasp-*` | 3 complete objects. `-shared` is the object, `-film` the full film, `-demo` the 10-second version. | +| `sims/green/` | The page around every object and the green look, plus 3 review tools: leftover-colour probe, camera track, part anchors. | +| `sims/kit/` | Runtime, stage, shader warm-up. | +| `sims/build.mjs` | Bundles an object into one HTML file, three.js and fonts inlined. | +| `sims/capture.mjs` | Renders the film frame by frame to a 60 fps mp4, or to review sheets of stills. | +| `sfx/`, `run_sfx.py` | Procedural sound on the film's timeline, mastered to −14 LUFS. | + +## Credits + +Built on [whaleyxbt/claude-motion](https://github.com/whaleyxbt/claude-motion) (MIT): the runtime, frame capture, sound engine and review rules come from there. Recorded samples are CC0 from Freesound, prepared by [Barty-Bart/motion-graphics](https://github.com/Barty-Bart/motion-graphics); sources in `sfx/samples/SOURCES.md`. + +MIT licence. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..7a7284c --- /dev/null +++ b/SKILL.md @@ -0,0 +1,172 @@ +--- +name: cutaway +description: Build a robotic cutaway of any object or creature from one reference image - a three.js scene written entirely in code that takes itself apart on camera, a page with a button for every part, and a 60 fps film with a synced procedural score. Claude matches the build to the picture, grades it line by line, measures its density and proportions, and films it only after the user approves the still. Use when someone hands over a picture of a robotic animal, machine or device and wants it built in 3D, opened up part by part, or recorded; or asks for a "cutaway", an "exploded view", a "robot animal simulator" or "make this image a 3D model that comes apart". +--- + +# Cutaway + +One picture in, one object out: built from code, opened part by part, filmed. The visitor sees the object move, a cursor presses a button, and that part comes apart under its own camera while live cards around it react. The same code records the film frame by frame, with a score built on the same timeline. + +`SKILL_DIR` below is the folder this file lives in. Builds and renders go to `./cutaway-out` of the folder you run from. + +## First run + +``` +cd "$SKILL_DIR" && npm install && npx playwright install chromium +``` + +The pages need nothing else. The video needs `ffmpeg` on PATH and the score needs Python 3 (standard library only). Set `FFMPEG`, `PYTHON` or `CHROMIUM` to point at other binaries. + +## The 3 examples + +Build one, open the HTML, watch it take itself apart. Start a new object from the example whose body is closest. + +| | The object | Its parts | Worth stealing | +|---|---|---|---| +| `tarantula-*` | A robotic tarantula on 8 bristled legs, a glass abdomen full of lit coils. | Optics, a front leg coming apart on its servos, the abdomen cage opening, the head plates lifting; two jumps. | A walking body: an alternating tetrapod gait integrated from velocity keys, a jump with a crouch and a tuck. | +| `piranha-*` | A deep-bodied robotic piranha with 2 rows of glass fangs and a glass flank over drive gears. | The eye unscrewing in macro, the tail stalk telescoping, the glass flank opening from above, the jaw dropping from below. | One camera per beat aimed at its own part; a mirrored scene; a lunge at the lens. | +| `wasp-*` | A robotic wasp with frosted wings, a telescoping abdomen and a glass stinger. | Optics, a wing pulled out of its hinge and turned over, thorax gears, the abdomen telescoping. | A slow-motion explode as a warp of film time into scene time; a dive in from above and a climb out of the frame. | + +Each comes in 3 folders: `-shared/` holds the object, `-film/` the full film (it also opens as a looping page), `-demo/` a 10-second version with its own script. + +``` +node "$SKILL_DIR/sims/build.mjs" piranha-film # → cutaway-out/dist/piranha-film.html, offline, ~900 KB +node "$SKILL_DIR/sims/build.mjs" # all of them +``` + +## The method + +The 4 files in `docs/` are the method. Read them before the first object, and keep `docs/JOB_DESCRIPTION.md` open the whole time. + +| File | What it holds | +|---|---| +| `docs/JOB_DESCRIPTION.md` | The brief: the look, the order of work, the camera, the film, the short version. Every correction the user gives goes into it, one line per mistake. | +| `docs/CHECKLIST.md` | How to write 10 to 12 numbered lines on what one picture stands on, a template and a full example. | +| `docs/PROMPTS.md` | Every prompt, from the reference image to the sound. | +| `docs/LESSONS.md` | Every mistake so far and the line it added to the brief. | + +The order, every time: + +1. **The reference.** One picture. If the user has none, generate one with the prompt in `docs/PROMPTS.md`. It sets the look and nothing else: never import it, rebuild it. +2. **Measure the picture.** Body height, head length, jaw or limb length as shares of the body length. Dark-pixel share (luma under 80) in its bounding box. +3. **Write the checklist** for this picture before the first line of code. +4. **The still loop.** Build, render a still posed like the reference, stack reference | still | an approved still, plus the stack at 900 px wide, grade every line yes / partial / no against the picture. **Stop after round 2 and show the user.** Nothing gets filmed until they say yes. +5. **The film.** Port the example with the closest body 1:1: its tour, its beat times, its moves, distances scaled. Change the body only. Give every part its own camera. +6. **The short version.** Its own script, never pieces of the long film. +7. **Render and score.** + +## How an object is built + +One folder per object, split by job. The examples follow this exactly: + +| File | Job | +|---|---| +| `spider.js` / `piranha.js` / `bee.js` | The body, built from code: shells, gears, pistons, hoses, lenses, membranes. Every part that comes apart is its own group with a named anchor; `pose(state)` sets the whole object for one moment. | +| `parts.js` | The shop: materials (gloss white shell, accent, graphite, black, steel, lens, glass) and shape helpers. `PAL` holds the colours. | +| `stage.js` | The studio: paper backdrop, lights, soft floor shadow, post. `frame(cam)` draws one frame. | +| `tour.js` / `tour_bee.js` / `tour_v2.js` | The film as functions of time: each act's clock, the flight or walk, the explode, every camera, the telemetry for the page. | +| `sim_green.js` | The wiring: state for t → pose, flight, camera, page. Applies the green look. | +| `../green/` | The page around every object (title, pill buttons the cursor presses, a section list, 4 cards, labels with leaders) and the green look (`look.js`). | +| `score.py` | The sound on the film's timeline. | + +For an object outside `SKILL_DIR`, make a folder with a `main.js` and import the kit by name: `import {runSim} from 'cutaway-kit/runtime.js'`. Build it with `node "$SKILL_DIR/sims/build.mjs" ./my-object`. + +## Rules that decide whether it works + +1. **Start from the picture, never from imagination.** Asked for a robot animal with nothing to match, the model returns a generic toy. With a picture and a checklist it rebuilds what is in front of it. +2. **Port the closest approved film.** A new body on an existing choreography works; a new body on a new choreography is twice the rounds. Flag an object with no close body before starting. +3. **Measure, don't eyeball.** Features pass the checklist while the whole reads as a tidy white diagram. Dark share must reach 0.8 of the reference's; proportions must match within a few hundredths. +4. **One main set of limbs.** Legs, or wings, or tentacles. Two systems fighting for the same half second is noise. +5. **Dense core, plates with gaps.** Break white surfaces into separate curved plates in 3 sizes with gaps over the mechanism. A long smooth shell reads as a toy however many rounds it gets. +6. **Every beat its own camera.** Aim at the part itself, from its own side and height, and push in while it hangs open. Check with `sims/green/cam_track.mjs`: if az, el and distance barely move between beats, the film looks parked. +7. **Review after round 2, 2 objects at a time.** A note after round 2 changes the outcome; after round 6 it only costs tokens. + +## The green look + +`sims/green/look.js` turns any object green without touching its code: set `PAL.orange` and the paper before the build, then call `retint(root)` after the build and after every pose. It handles material colours, emissive glows, HDR glow colours above 1, colours a pose rewrites every frame, lights and vertex colours. `SHIFT` moves the subject into the page's 3D window. Before a render, run `node sims/green/probe_warm.mjs `: it lists any warm colour left. + +## render(t) contract + +```js +import {runSim} from '../kit/runtime.js'; + +const DEFAULTS = {duration: 20, fps: 60, hud: {enabled: false}, director: {enabled: false}}; + +runSim(DEFAULTS, async ({cfg, canvas, capture}) => { + // build the scene, precompute anything stateful + return {render(t) { /* draw frame t from scratch */ return {}; }, resize() {}}; +}); +``` + +- `render(t)` is pure: no `Math.random` (use `rng(seed)` from `kit/util.js` at setup), no `Date`, no state carried between frames. Capture calls it at arbitrary times. +- Anything integrated over time (a gait, the gears' busy clock, a speed ramp) is tabulated at load; `render` only reads the tables. +- Every beat goes into `-film/timeline.json` in seconds. The score reads the same file. +- A short version may run its scene faster than the film: `{"duration": 11.3, "film": 10.0}` plays 11.3 s of scene in 10 s. +- Frame 0 is the thumbnail. It must already show the object big, front 3/4, moving. + +## Commands + +``` +node "$SKILL_DIR/sims/build.mjs" piranha-film +node "$SKILL_DIR/sims/capture.mjs" piranha-film --size 1600x900 --dpr 1.2 --stills beats --cols 4 --out cutaway-out/piranha-beats.png +node "$SKILL_DIR/sims/capture.mjs" piranha-film --size 1600x900 --dpr 1.2 --still 9.4 --out cutaway-out/piranha-9.4.png +node "$SKILL_DIR/sims/capture.mjs" piranha-film --size 1600x900 --dpr 2.4 --out cutaway-out/piranha-4k.mp4 +python "$SKILL_DIR/run_sfx.py" "$SKILL_DIR/sims/piranha-shared/score.py" +ffmpeg -y -i cutaway-out/piranha-4k.mp4 -i cutaway-out/piranha-score.wav -map 0:v -map 1:a -vf scale=1920:1080:flags=lanczos -c:v libx264 -crf 16 -pix_fmt yuv420p -c:a aac -b:a 256k -shortest -movflags +faststart cutaway-out/piranha.mp4 +``` + +For a demo whose scene runs faster than its film, score the scene and stretch the sound by the same factor: + +``` +TL="$SKILL_DIR/sims/piranha-demo/timeline.json" OUT=cutaway-out/piranha-demo-scene.wav python "$SKILL_DIR/run_sfx.py" "$SKILL_DIR/sims/piranha-shared/score.py" +ffmpeg -y -i cutaway-out/piranha-demo-scene.wav -af atempo=1.12 cutaway-out/piranha-demo-score.wav +``` + +`--size` is the CSS layout and `--dpr` multiplies it: 1600 x 900 at 1.2 gives 1920 x 1080, at 2.4 gives 4K to bring down to 1080p (thin veins stay sharp). Capture prints the GPU it got; a software renderer means the GPU flags in `paths.mjs` did not take. + +## Review loop + +You cannot watch the video; you can look at frames. Never report an object as done without reading sheets of the current render. + +1. `--stills beats`: one tile per timeline beat, 0.3 s after it, each labelled `t=`. +2. Read every tile against the checklist below. +3. Zoom in: `--stills every:0.2 --from A --to B` for a transition, `--still T` for one full frame. +4. `node sims/green/cam_track.mjs ` prints the camera every 0.5 s; `node sims/green/anchors_dump.mjs ` prints the parts' rest points to aim cameras at. +5. Fix, rebuild, go back to 1. Stop when a full pass finds nothing. +6. Final: `node "$SKILL_DIR/sheet.mjs" --video --timeline ` and read that too. + +Checklist: + +- **The object.** Every part that comes apart goes back where it was; nothing passes through anything; the cards match the motion. +- **Composition.** The opening part fills the frame; the rest may run off. Labels never cover the part they name. +- **The look.** No warm colour left (`probe_warm.mjs`). Green only as lines and glows, never dots. +- **Camera.** A new side, height or distance at every beat. No beat parked. +- **Timing.** A part opens in about 1 s, holds, closes in 0.5 s; a new beat every 2 to 3 s. + +## three.js traps the examples already hit + +- A glow colour above 1 (an HDR `MeshBasicMaterial`) breaks `getHSL`: read and write it at unit peak. +- A colour the pose rewrites every frame comes back each frame: retint whatever changed since the last write. +- Colours baked into vertex attributes ignore the material: retint the `color` attribute too. +- `smoothstep(a, b, x)` with `a > b` returns 0 on Windows (ANGLE/D3D). Write `1.0 - smoothstep(b, a, x)`. +- One NaN pixel blacks out the whole frame through bloom. Clamp every `pow()` base in a shader. + +## Sound + +`sfx/` synthesises every sound in pure Python (48 kHz, reproducible) and reads the film's timeline, so sound cannot drift out of sync. `python "$SKILL_DIR/run_sfx.py" --list` shows the generators. `sfx/score_kit.py` has the bed and accents the 3 scores use: a chord bed with soft drums, a pad, airy whooshes, clicks and ticks. + +- Every time comes from the timeline, never a typed number. +- Mastering is automatic: −14 LUFS, true peak ≤ −2 dBFS. +- Accent, never narrate: a quiet click per button, a short accent on every part that moves, continuous motion silent. + +## Taste, with numbers + +- Frame 0: the front 3/4 hero view, the object big and already moving. +- A beat every 2 to 3 s. Visible wing beats 1.5 to 2.5 Hz; faster only as a motion-blurred fan. +- Bristles and spikes 0.15 to 0.25 of the limb's thickness. +- The object fills 60-70% of the 3D window at rest; the opening part fills the frame. +- One accent colour, and it marks what is moving right now. + +## Credits + +The kit, frame capture, sfx engine and review rules come from [whaleyxbt/claude-motion](https://github.com/whaleyxbt/claude-motion) (MIT). The recorded samples are CC0 from Freesound, trimmed by [Barty-Bart/motion-graphics](https://github.com/Barty-Bart/motion-graphics) (MIT); sources in `sfx/samples/SOURCES.md`. diff --git a/CHECKLIST.md b/docs/CHECKLIST.md similarity index 100% rename from CHECKLIST.md rename to docs/CHECKLIST.md diff --git a/JOB_DESCRIPTION.md b/docs/JOB_DESCRIPTION.md similarity index 100% rename from JOB_DESCRIPTION.md rename to docs/JOB_DESCRIPTION.md diff --git a/LESSONS.md b/docs/LESSONS.md similarity index 100% rename from LESSONS.md rename to docs/LESSONS.md diff --git a/PROMPTS.md b/docs/PROMPTS.md similarity index 100% rename from PROMPTS.md rename to docs/PROMPTS.md diff --git a/docs/piranha.gif b/docs/piranha.gif new file mode 100644 index 0000000..a6e5950 Binary files /dev/null and b/docs/piranha.gif differ diff --git a/docs/tarantula.gif b/docs/tarantula.gif new file mode 100644 index 0000000..c514f7f Binary files /dev/null and b/docs/tarantula.gif differ diff --git a/docs/wasp.gif b/docs/wasp.gif new file mode 100644 index 0000000..1262fd1 Binary files /dev/null and b/docs/wasp.gif differ diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..c31b441 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,545 @@ +{ + "name": "cutaway", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "cutaway", + "version": "1.0.0", + "license": "MIT", + "dependencies": { + "@fontsource-variable/inter": "5.3.0", + "@fontsource/jetbrains-mono": "5.3.0", + "esbuild": "0.28.1", + "playwright": "1.58.2", + "three": "0.186.1" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz", + "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz", + "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz", + "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz", + "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz", + "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz", + "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz", + "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz", + "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz", + "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz", + "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz", + "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz", + "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==", + "cpu": [ + "loong64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz", + "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==", + "cpu": [ + "mips64el" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz", + "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz", + "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz", + "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==", + "cpu": [ + "s390x" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz", + "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz", + "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz", + "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz", + "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz", + "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz", + "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz", + "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz", + "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz", + "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz", + "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@fontsource-variable/inter": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/@fontsource-variable/inter/-/inter-5.3.0.tgz", + "integrity": "sha512-OupL48va4JNofb97w6NYeF9S7W/kHNKM0Er8Dem5nqi4jeOLrVJDoE8tZEpnMJmtkvNbB1EIPPwHcdkF6b1oUA==", + "license": "OFL-1.1", + "funding": { + "url": "https://github.com/sponsors/ayuhito" + } + }, + "node_modules/@fontsource/jetbrains-mono": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/@fontsource/jetbrains-mono/-/jetbrains-mono-5.3.0.tgz", + "integrity": "sha512-fqDfB5I9f1p1TV486aUgB9t8zP84P0O1FtQR5Ol9vjwPy+S+EIGlVYm1cvj2W5shcZMTg2nZFdVMoH5wFu8a1A==", + "license": "OFL-1.1", + "funding": { + "url": "https://github.com/sponsors/ayuhito" + } + }, + "node_modules/esbuild": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz", + "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==", + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.1", + "@esbuild/android-arm": "0.28.1", + "@esbuild/android-arm64": "0.28.1", + "@esbuild/android-x64": "0.28.1", + "@esbuild/darwin-arm64": "0.28.1", + "@esbuild/darwin-x64": "0.28.1", + "@esbuild/freebsd-arm64": "0.28.1", + "@esbuild/freebsd-x64": "0.28.1", + "@esbuild/linux-arm": "0.28.1", + "@esbuild/linux-arm64": "0.28.1", + "@esbuild/linux-ia32": "0.28.1", + "@esbuild/linux-loong64": "0.28.1", + "@esbuild/linux-mips64el": "0.28.1", + "@esbuild/linux-ppc64": "0.28.1", + "@esbuild/linux-riscv64": "0.28.1", + "@esbuild/linux-s390x": "0.28.1", + "@esbuild/linux-x64": "0.28.1", + "@esbuild/netbsd-arm64": "0.28.1", + "@esbuild/netbsd-x64": "0.28.1", + "@esbuild/openbsd-arm64": "0.28.1", + "@esbuild/openbsd-x64": "0.28.1", + "@esbuild/openharmony-arm64": "0.28.1", + "@esbuild/sunos-x64": "0.28.1", + "@esbuild/win32-arm64": "0.28.1", + "@esbuild/win32-ia32": "0.28.1", + "@esbuild/win32-x64": "0.28.1" + } + }, + "node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/playwright": { + "version": "1.58.2", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz", + "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==", + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.58.2" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "fsevents": "2.3.2" + } + }, + "node_modules/playwright-core": { + "version": "1.58.2", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz", + "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==", + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/three": { + "version": "0.186.1", + "resolved": "https://registry.npmjs.org/three/-/three-0.186.1.tgz", + "integrity": "sha512-blFeqb49wRCSGUGj7gtpfnSGHy2lwDk94RhUmS1c/hTby70kvChbWpkJ4Pm1390LqzzvTmzgXKHPEafJwCb8jA==", + "license": "MIT" + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..da33cd2 --- /dev/null +++ b/package.json @@ -0,0 +1,18 @@ +{ + "name": "cutaway", + "version": "1.0.0", + "private": true, + "description": "A Claude Code skill that builds a robotic cutaway of any object from one reference image: a 3D simulator that takes itself apart, recorded to 60 fps video.", + "license": "MIT", + "scripts": { + "setup": "npm install && npx playwright install chromium", + "build": "node sims/build.mjs" + }, + "dependencies": { + "@fontsource-variable/inter": "5.3.0", + "@fontsource/jetbrains-mono": "5.3.0", + "esbuild": "0.28.1", + "playwright": "1.58.2", + "three": "0.186.1" + } +} diff --git a/paths.mjs b/paths.mjs new file mode 100644 index 0000000..7946dd5 --- /dev/null +++ b/paths.mjs @@ -0,0 +1,30 @@ +// Paths and browser flags for the kit. Everything resolves from this folder, so the skill runs wherever it is installed. +// Override any of them with an environment variable. + +import {createRequire} from 'node:module'; +import path from 'node:path'; +import {fileURLToPath} from 'node:url'; + +const ROOT = path.dirname(fileURLToPath(import.meta.url)); + +export const FFMPEG = process.env.FFMPEG || 'ffmpeg'; +export const FFPROBE = process.env.FFPROBE || 'ffprobe'; +export const PYTHON = process.env.PYTHON || (process.platform === 'win32' ? 'python' : 'python3'); + +// three, esbuild, fonts and playwright: `npm install` in this folder puts them here. +export const DEPS = process.env.CUTAWAY_DEPS || path.join(ROOT, 'node_modules'); +// Unset: playwright uses the Chromium that `npx playwright install chromium` downloaded. +export const CHROMIUM = process.env.CHROMIUM || undefined; +// Real GPU WebGL instead of a software rasteriser. On Windows d3d11 plus --force_high_performance_gpu keeps ANGLE off +// an integrated GPU when a discrete one exists. capture.mjs prints the GPU it got on every run. +export const CHROMIUM_ARGS = [ + ...(process.platform === 'win32' ? ['--use-angle=d3d11'] : []), + '--force_high_performance_gpu', '--ignore-gpu-blocklist', '--enable-gpu-rasterization', '--enable-webgl', '--hide-scrollbars', +]; + +// Builds and renders land in ./cutaway-out of the folder you run from. +export const OUT = path.resolve(process.env.CUTAWAY_OUT || 'cutaway-out'); +export const DIST = path.join(OUT, 'dist'); + +export const fromDeps = (id) => createRequire(path.join(DEPS, 'x.js'))(id); +export const playwright = () => fromDeps('playwright'); diff --git a/run_sfx.py b/run_sfx.py new file mode 100644 index 0000000..ff8b146 --- /dev/null +++ b/run_sfx.py @@ -0,0 +1,10 @@ +"""Render a cue sheet to a mastered WAV from any folder: python run_sfx.py | --list""" + +import os +import sys + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) + +from sfx.__main__ import main # noqa: E402 + +main() diff --git a/sfx/__init__.py b/sfx/__init__.py new file mode 100644 index 0000000..d38f6b1 --- /dev/null +++ b/sfx/__init__.py @@ -0,0 +1,10 @@ +"""Procedural sound design for motion graphics. Pure Python stdlib, 48 kHz stereo. + + python run_sfx.py sfx/cues/effort.py render a cue sheet to WAV + python run_sfx.py --list list the sound generators +""" + +from .mix import Mix +from .synth import SR + +__all__ = ["Mix", "SR"] diff --git a/sfx/__main__.py b/sfx/__main__.py new file mode 100644 index 0000000..1714f8a --- /dev/null +++ b/sfx/__main__.py @@ -0,0 +1,64 @@ +"""CLI: render a cue sheet, or list the available generators.""" + +import argparse +import importlib.util +import inspect +import json +import os +import sys + +from . import synth +from .mix import Mix + + +def list_generators(): + for name, fn in inspect.getmembers(synth, inspect.isfunction): + if fn.__module__ != synth.__name__ or name.startswith("_"): + continue + doc = (fn.__doc__ or "").strip().splitlines()[0] if fn.__doc__ else "" + print(f"{name}{inspect.signature(fn)}\n {doc}") + + +def load_cues(path): + spec = importlib.util.spec_from_file_location("cues", path) + cues = importlib.util.module_from_spec(spec) + spec.loader.exec_module(cues) + if not hasattr(cues, "score"): + sys.exit(f"{path} needs a score(mix, tl) function") + return cues + + +def main(): + ap = argparse.ArgumentParser(prog="python run_sfx.py", description="Render a cue sheet to a mastered WAV.") + ap.add_argument("cues", nargs="?", help="cue sheet: a .py file with score(mix, tl)") + ap.add_argument("--timeline", help="timeline JSON (default: the cue sheet's TIMELINE, else timeline.json)") + ap.add_argument("--out", help="output WAV (default: the cue sheet's OUT, else cutaway-out/.wav, or $CUTAWAY_OUT)") + ap.add_argument("--list", action="store_true", help="list sound generators and exit") + args = ap.parse_args() + + if args.list: + list_generators() + return + if not args.cues: + ap.error("pass a cue sheet, or --list") + + cues = load_cues(args.cues) + # A relative TIMELINE in the cue sheet is read next to the cue sheet, so it runs from any folder. + timeline = args.timeline or os.path.join(os.path.dirname(os.path.abspath(args.cues)), getattr(cues, "TIMELINE", "timeline.json")) + stem = os.path.splitext(os.path.basename(args.cues))[0] + out = args.out or getattr(cues, "OUT", os.path.join(os.environ.get("CUTAWAY_OUT", "cutaway-out"), f"{stem}.wav")) + with open(timeline, encoding="utf8") as f: + tl = json.load(f) + + mix = Mix(tl["duration"], seed=getattr(cues, "SEED", 11)) + cues.score(mix, tl) + stats = mix.master(target_lufs=getattr(cues, "TARGET_LUFS", -14.0)) + mix.write(out) + print( + f"wrote {out}: {tl['duration']}s, {mix.count} sounds, " + f"{stats['lufs']:.1f} LUFS, true peak {stats['peak_db']:.1f} dBFS, drive {stats['drive']}" + ) + + +if __name__ == "__main__": + main() diff --git a/sfx/dsp.py b/sfx/dsp.py new file mode 100644 index 0000000..6363160 --- /dev/null +++ b/sfx/dsp.py @@ -0,0 +1,453 @@ +"""DSP building blocks (oscillators, filters, delays, reverb), pure Python stdlib at 48 kHz. + +Used by sound scripts that need more than the one-shot generators in synth.py, +e.g. sims/engine/sound.py. + +Signals are plain lists of floats. Speed comes from two tricks: + +- A Python per-sample loop costs about 0.3 µs/sample and a list comprehension + about 0.05 µs. So constant-pitch oscillators are one comprehension (the naive + ramp) plus a sparse PolyBLEP fix-up at each wrap. Feedback delays and the + reverb combs/allpasses run one block at a time, where the block is no longer + than the delay, so every block depends only on earlier blocks and is a single + comprehension. +- Filters whose state really is sequential (SVF, biquad, ladder) are tight + loops, run only on short one-shots or on the few full-length buses that need + them. +""" + +import math + +from .synth import SR + +TAU = 2.0 * math.pi +_tanh = math.tanh + + +# ---------------------------------------------------------------- buffers + + +def zeros(n): + return [0.0] * n + + +def add(dst, src, at=0, gain=1.0): + """dst[at:] += gain * src, in place, clipped to dst.""" + if at < 0: + src = src[-at:] + at = 0 + end = min(len(dst), at + len(src)) + if end <= at: + return + seg = dst[at:end] + if gain == 1.0: + dst[at:end] = [a + b for a, b in zip(seg, src)] + else: + dst[at:end] = [a + b * gain for a, b in zip(seg, src)] + + +def scaled(x, g): + return [v * g for v in x] + + +def mul(x, y): + return [a * b for a, b in zip(x, y)] + + +def summed(a, b): + return [p + q for p, q in zip(a, b)] + + +def rms(x): + return math.sqrt(sum(v * v for v in x) / len(x)) if x else 0.0 + + +def peak(x): + return max(max(x), -min(x)) if x else 0.0 + + +def pan_gains(pan): + """Equal-power pan, -1 left .. +1 right.""" + ang = (pan + 1.0) * math.pi / 4.0 + return math.cos(ang), math.sin(ang) + + +def fade(x, fin=0, fout=0): + """Linear fade in/out over fin/fout samples, in place.""" + n = len(x) + fin, fout = min(fin, n), min(fout, n) + for i in range(fin): + x[i] *= i / fin + for i in range(fout): + x[n - 1 - i] *= i / fout + return x + + +# ------------------------------------------------------------ oscillators + + +def _blep(out, phase, dt, n, h=1.0): + """Subtract the PolyBLEP residual at every wrap of the ramp phase + i*dt (downward jump 2h).""" + k = 1 + while True: + j = math.ceil((k - phase) / dt) + # float guard: make j the first sample whose wrapped phase is small + if j < n and (phase + j * dt) % 1.0 > 0.5: + j += 1 + if j >= 1 and (phase + (j - 1) * dt) % 1.0 < 0.5: + j -= 1 + if j - 1 >= n: + break + if 0 <= j < n: + u = ((phase + j * dt) % 1.0) / dt + if u < 1.0: + out[j] -= h * (u + u - u * u - 1.0) + if 1 <= j <= n: + u = (((phase + (j - 1) * dt) % 1.0) - 1.0) / dt + if u > -1.0: + out[j - 1] -= h * (u * u + u + u + 1.0) + k += 1 + + +def saw(freq, n, phase=0.0): + """Band-limited sawtooth (PolyBLEP) at constant freq, -1..1.""" + dt = freq / SR + phase %= 1.0 + out = [2.0 * ((phase + i * dt) % 1.0) - 1.0 for i in range(n)] + if 0.0 < dt < 0.5: + _blep(out, phase, dt, n) + return out + + +def pulse(freq, n, width=0.5, phase=0.0): + """Band-limited pulse as the difference of two PolyBLEP saws; zero mean.""" + a = saw(freq, n, phase) + b = saw(freq, n, phase + width) + return [p - q for p, q in zip(a, b)] + + +def sine(freq, n, phase=0.0): + w = TAU * freq / SR + ph = TAU * phase + sin = math.sin + return [sin(ph + w * i) for i in range(n)] + + +def noise(rng, n): + r = rng.random + return [2.0 * r() - 1.0 for _ in range(n)] + + +# ---------------------------------------------------------------- filters + + +def _norm(b0, b1, b2, a0, a1, a2): + return (b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0) + + +def lp(fc, q=0.7071): + w = TAU * min(fc, 0.45 * SR) / SR + c, al = math.cos(w), math.sin(w) / (2 * q) + return _norm((1 - c) / 2, 1 - c, (1 - c) / 2, 1 + al, -2 * c, 1 - al) + + +def hp(fc, q=0.7071): + w = TAU * min(fc, 0.45 * SR) / SR + c, al = math.cos(w), math.sin(w) / (2 * q) + return _norm((1 + c) / 2, -(1 + c), (1 + c) / 2, 1 + al, -2 * c, 1 - al) + + +def bp(fc, q=1.0): + w = TAU * min(fc, 0.45 * SR) / SR + c, al = math.cos(w), math.sin(w) / (2 * q) + return _norm(al, 0.0, -al, 1 + al, -2 * c, 1 - al) + + +def peaking(fc, q, db): + a = 10 ** (db / 40) + w = TAU * min(fc, 0.45 * SR) / SR + c, al = math.cos(w), math.sin(w) / (2 * q) + return _norm(1 + al * a, -2 * c, 1 - al * a, 1 + al / a, -2 * c, 1 - al / a) + + +def shelf(fc, db, high=True): + a = 10 ** (db / 40) + w = TAU * min(fc, 0.45 * SR) / SR + c, s = math.cos(w), math.sin(w) + al = s / 2 * math.sqrt(2) + sa = 2 * math.sqrt(a) * al + if high: + return _norm( + a * ((a + 1) + (a - 1) * c + sa), -2 * a * ((a - 1) + (a + 1) * c), a * ((a + 1) + (a - 1) * c - sa), + (a + 1) - (a - 1) * c + sa, 2 * ((a - 1) - (a + 1) * c), (a + 1) - (a - 1) * c - sa, + ) + return _norm( + a * ((a + 1) - (a - 1) * c + sa), 2 * a * ((a - 1) - (a + 1) * c), a * ((a + 1) - (a - 1) * c - sa), + (a + 1) + (a - 1) * c + sa, -2 * ((a - 1) + (a + 1) * c), (a + 1) + (a - 1) * c - sa, + ) + + +def biquad(x, c): + """Static biquad (transposed direct form II); c from lp/hp/bp/peaking/shelf.""" + b0, b1, b2, a1, a2 = c + z1 = z2 = 0.0 + out = [0.0] * len(x) + i = 0 + for v in x: + y = b0 * v + z1 + z1 = b1 * v - a1 * y + z2 + z2 = b2 * v - a2 * y + out[i] = y + i += 1 + return out + + +def svf(x, fc, q=0.7071, mode="lp", ctrl=32): + """Zero-delay-feedback state-variable filter (Cytomic/Simper), stable under fast modulation. + + fc: Hz, or a function of the sample index evaluated every `ctrl` samples. + mode: 'lp', 'bp' or 'hp'. + """ + n = len(x) + out = [0.0] * n + k = 1.0 / q + ic1 = ic2 = 0.0 + const = not callable(fc) + if const: + ctrl = max(n, 1) + tan = math.tan + pis = math.pi / SR + for s in range(0, n, ctrl): + f = fc if const else fc(s) + f = 10.0 if f < 10.0 else 20000.0 if f > 20000.0 else f + g = tan(pis * f) + a1 = 1.0 / (1.0 + g * (g + k)) + a2 = g * a1 + a3 = g * a2 + e = s + ctrl if s + ctrl < n else n + if mode == "lp": + for i in range(s, e): + v3 = x[i] - ic2 + v1 = a1 * ic1 + a2 * v3 + v2 = ic2 + a2 * ic1 + a3 * v3 + ic1 = v1 + v1 - ic1 + ic2 = v2 + v2 - ic2 + out[i] = v2 + elif mode == "bp": + for i in range(s, e): + v3 = x[i] - ic2 + v1 = a1 * ic1 + a2 * v3 + v2 = ic2 + a2 * ic1 + a3 * v3 + ic1 = v1 + v1 - ic1 + ic2 = v2 + v2 - ic2 + out[i] = v1 + else: + for i in range(s, e): + xi = x[i] + v3 = xi - ic2 + v1 = a1 * ic1 + a2 * v3 + v2 = ic2 + a2 * ic1 + a3 * v3 + ic1 = v1 + v1 - ic1 + ic2 = v2 + v2 - ic2 + out[i] = xi - k * v1 - v2 + return out + + +def onepole_hp(x, fc): + """Gentle 6 dB/oct high-pass; used as a DC blocker.""" + a = math.exp(-TAU * fc / SR) + out = [0.0] * len(x) + px = py = 0.0 + i = 0 + for v in x: + py = a * (py + v - px) + px = v + out[i] = py + i += 1 + return out + + +def sweep(x, start, end, f0, f1, mode="lp", q=0.9, wet_in=0.0, wet_out=0.0): + """Filter x[start:end] in place, cutoff gliding exponentially f0 -> f1. + + wet_in / wet_out (fractions of the region) crossfade from / back to the + dry signal, so the region's edges are seamless. + """ + start, end = max(0, start), min(len(x), end) + n = end - start + if n <= 0: + return + seg = x[start:end] + r = f1 / f0 + y = svf(seg, lambda i: f0 * r ** (i / n), q, mode, 32) + a = max(1, int(wet_in * n)) + b = max(1, int(wet_out * n)) + out = [] + for i in range(n): + w = 1.0 + if wet_in and i < a: + w = i / a + if wet_out and i > n - b: + w = min(w, (n - i) / b) + out.append(seg[i] + (y[i] - seg[i]) * w) + x[start:end] = out + + +# ------------------------------------------------------- delay and reverb + +_COMBS = (1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617) +_ALLPASSES = (556, 441, 341, 225) + + +def _comb(x, m, fb, damp): + """Freeverb comb, block-vectorized; the in-loop damping is a 2-tap low-pass.""" + n = len(x) + a = fb * (1.0 - damp) + b = fb * damp + w = [0.0] * (n + m + 1) # w[i + m + 1] = W(i) + for s in range(0, n, m): + e = min(s + m, n) + w[s + m + 1:e + m + 1] = [xi + a * p + b * q for xi, p, q in zip(x[s:e], w[s + 1:e + 1], w[s:e])] + return w[1:n + 1] + + +def _allpass(x, m, g=0.5): + n = len(x) + v = [0.0] * (n + m) # v[i + m] = V(i) + for s in range(0, n, m): + e = min(s + m, n) + v[s + m:e + m] = [xi + g * p for xi, p in zip(x[s:e], v[s:e])] + return [p - xi for xi, p in zip(x, v)] + + +def reverb(x, size=0.7, damp=0.45, scale=1.0, spread=23): + """Freeverb (8 combs + 4 allpasses per side): mono in, (left, right) wet out. + + size 0..1 maps to comb feedback 0.7..0.98; scale stretches every delay + (0.3 = small room, 1.5 = hall). Output is roughly level-matched to input. + """ + fb = 0.7 + 0.28 * size + r = SR / 44100 * scale + outs = [] + for off in (0, spread): + acc = None + for m in _COMBS: + c = _comb(x, max(8, int((m + off) * r)), fb, damp) + acc = c if acc is None else [p + q for p, q in zip(acc, c)] + for m in _ALLPASSES: + acc = _allpass(acc, max(8, int((m + off) * r))) + outs.append(acc) + g = math.sqrt((1 - fb * fb) / 8.0) * 1.4 + return [v * g for v in outs[0]], [v * g for v in outs[1]] + + +def pingpong(x, d, fb=0.5, damp=0.35): + """Ping-pong delay, mono in -> (left, right) wet; first echo left at d samples, then alternating.""" + n = len(x) + xp = [0.0] * d + x + a = [0.0] * (n + d + 1) # a[i + d + 1] = A(i) + b = [0.0] * (n + d + 1) + c0 = fb * (1.0 - damp) + c1 = fb * damp + for s in range(0, n, d): + e = min(s + d, n) + av = [xi + c0 * p + c1 * q for xi, p, q in zip(xp[s:e], b[s + 1:e + 1], b[s:e])] + bv = [c0 * p + c1 * q for p, q in zip(a[s + 1:e + 1], a[s:e])] + a[s + d + 1:e + d + 1] = av + b[s + d + 1:e + d + 1] = bv + return a[d + 1:], b[d + 1:] + + +# --------------------------------------------------------------- dynamics + + +def softclip(x, drive=1.5): + norm = 1.0 / _tanh(drive) + return [_tanh(drive * v) * norm for v in x] + + +def compress(left, right, thresh_db=-12.0, ratio=2.0, attack=0.01, release=0.15, knee_db=6.0, block=64): + """Stereo-linked RMS bus compressor at control rate (one gain per block, interpolated).""" + n = len(left) + pw = [a * a + b * b for a, b in zip(left, right)] + ca = math.exp(-block / (attack * SR)) + cr = math.exp(-block / (release * SR)) + slope = 1.0 / ratio - 1.0 + half = knee_db / 2 + gr = 0.0 + gains = [] + # warm the detector on the first second so the start isn't uncompressed + for warm in (True, False): + for s in range(0, n if not warm else min(n, SR), block): + p = sum(pw[s:s + block]) / (2 * block) + db = 10 * math.log10(p + 1e-12) + over = db - thresh_db + if over <= -half: + want = 0.0 + elif over < half: + want = slope * (over + half) ** 2 / (2 * knee_db) + else: + want = slope * over + c = ca if want < gr else cr + gr = c * gr + (1 - c) * want + if not warm: + gains.append(10 ** (gr / 20)) + ramp = [k / block for k in range(block)] + g = [] + prev = gains[0] + for cur in gains: + d = cur - prev + g.extend([prev + d * r for r in ramp]) + prev = cur + return [a * b for a, b in zip(left, g)], [a * b for a, b in zip(right, g)] + + +def mono_below(left, right, fc=120.0): + """Collapse the side signal below fc (24 dB/oct), so the low end is mono.""" + mid = [(a + b) * 0.5 for a, b in zip(left, right)] + side = [(a - b) * 0.5 for a, b in zip(left, right)] + c = hp(fc) + side = biquad(biquad(side, c), c) + return [m + s for m, s in zip(mid, side)], [m - s for m, s in zip(mid, side)] + + +# --------------------------------------------------------- glitch effects + + +def crush(x, bits=8, hold=2): + """Bit and sample-rate reduction (intentionally aliasing).""" + q = float(2 ** (bits - 1)) + return [round(x[i - i % hold] * q) / q for i in range(len(x))] + + +def stutter(x, start, slice_n, repeats, decay=0.9, edge=48): + """Beat-repeat in place: x[start:start+slice_n] repeated `repeats` times.""" + sl = x[start:start + slice_n] + if len(sl) < slice_n: + return + sl = fade(sl[:], edge, edge) + for r in range(repeats): + a = start + r * slice_n + if a + slice_n > len(x): + break + x[a:a + slice_n] = [v * decay ** r for v in sl] + + +def tapestop(x, start, n, curve=1.6): + """Tape stop in place over x[start:start+n]: playback slows to zero.""" + seg = x[start:start + n] + n = len(seg) + if n < 2: + return + out = [] + pos = 0.0 + for i in range(n): + j = int(pos) + if j + 1 >= n: + out.append(0.0) + else: + f = pos - j + out.append(seg[j] + (seg[j + 1] - seg[j]) * f) + pos += (1 - i / n) ** curve + fade(out, 0, min(n, 480)) + x[start:start + n] = out diff --git a/sfx/loudness.py b/sfx/loudness.py new file mode 100644 index 0000000..6dce897 --- /dev/null +++ b/sfx/loudness.py @@ -0,0 +1,72 @@ +"""Integrated loudness (ITU-R BS.1770-4, EBU R128 gating) for 48 kHz stereo.""" + +import math + +# K-weighting at 48 kHz: high shelf, then high-pass (coefficients from BS.1770). +_SHELF = ((1.53512485958697, -2.69169618940638, 1.19839281085285), (-1.69065929318241, 0.73248077421585)) +_HIGHPASS = ((1.0, -2.0, 1.0), (-1.99004745483398, 0.99007225036621)) + + +def _biquad(x, coeffs): + (b0, b1, b2), (a1, a2) = coeffs + y = [0.0] * len(x) + x1 = x2 = y1 = y2 = 0.0 + for i, xi in enumerate(x): + yi = b0 * xi + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2 + x2, x1, y2, y1 = x1, xi, y1, yi + y[i] = yi + return y + + +def _kernels(taps=8): + out = [] + for frac in (0.25, 0.5, 0.75): + k = [] + for j in range(-taps + 1, taps + 1): + d = j - frac + k.append((j, math.sin(math.pi * d) / (math.pi * d) * 0.5 * (1 + math.cos(math.pi * d / taps)))) + out.append(k) + return out + + +_TP_KERNELS = _kernels() + + +def true_peak(x, near=0.7): + """Linear true peak: 4x windowed-sinc interpolation around samples above near × sample peak.""" + peak = max(map(abs, x)) or 0.0 + lim = near * peak + tp = peak + for i in range(8, len(x) - 8): + if abs(x[i]) < lim and abs(x[i + 1]) < lim: + continue + for kernel in _TP_KERNELS: + v = abs(sum(c * x[i + j] for j, c in kernel)) + if v > tp: + tp = v + return tp + + +def integrated_lufs(left, right, sr=48000): + """Integrated loudness in LUFS; -inf for silence.""" + if sr != 48000: + raise ValueError("K-weighting coefficients here are for 48 kHz") + kl = _biquad(_biquad(left, _SHELF), _HIGHPASS) + kr = _biquad(_biquad(right, _SHELF), _HIGHPASS) + + cs = [0.0] + acc = 0.0 + for a, b in zip(kl, kr): + acc += a * a + b * b + cs.append(acc) + + block, hop = int(0.4 * sr), int(0.1 * sr) + z = [(cs[i + block] - cs[i]) / block for i in range(0, len(kl) - block + 1, hop)] + lufs = lambda power: -0.691 + 10 * math.log10(power) + + above_abs = [p for p in z if p > 0 and lufs(p) > -70] + if not above_abs: + return float("-inf") + relative = lufs(sum(above_abs) / len(above_abs)) - 10 + gated = [p for p in above_abs if lufs(p) > relative] + return lufs(sum(gated) / len(gated)) diff --git a/sfx/mix.py b/sfx/mix.py new file mode 100644 index 0000000..358294b --- /dev/null +++ b/sfx/mix.py @@ -0,0 +1,111 @@ +"""Mixer: place sounds in time, master to a loudness target, write a WAV.""" + +import math +import os +import random +import struct +import wave + +from .loudness import integrated_lufs, true_peak +from .synth import SR, key + +DRIVES = (1.2, 1.5, 1.8, 2.0, 2.2, 2.5, 3.0, 4.0) + + +class Mix: + def __init__(self, duration, seed=11): + random.seed(seed) + self.duration = duration + self.n = int(SR * duration) + self.left = [0.0] * self.n + self.right = [0.0] * self.n + self.count = 0 + self._out = None + + def put(self, t, samples, gain=1.0, pan=0.0): + """Place mono samples at t seconds. pan: -1 left, 0 centre, +1 right (equal power).""" + ang = (pan + 1) * math.pi / 4 + gl, gr = gain * math.cos(ang), gain * math.sin(ang) + i0 = int(t * SR) + for k, s in enumerate(samples): + i = i0 + k + if 0 <= i < self.n: + self.left[i] += s * gl + self.right[i] += s * gr + self.count += 1 + + def put_stereo(self, t, left, right, gain=1.0): + """Place a stereo pair (e.g. from synth.pad) at t seconds.""" + i0 = int(t * SR) + for k, (a, b) in enumerate(zip(left, right)): + i = i0 + k + if 0 <= i < self.n: + self.left[i] += a * gain + self.right[i] += b * gain + self.count += 1 + + def typing(self, start, end, chars, gain=(0.16, 0.26), jitter=0.006, spread=0.3): + """One keystroke per character, evenly spaced from start to end, humanized.""" + for k in range(chars): + tk = start + (end - start) * k / chars + self.put(tk + random.uniform(-jitter, jitter), key(), random.uniform(*gain), random.uniform(-spread, spread)) + + def master(self, target_lufs=-14.0, ceiling_db=-2.0, fade_out=0.25): + """Soft-clip and set gain so the mix hits target_lufs with true peak <= ceiling_db. + + Drive only rises when the ceiling would otherwise be crossed. The ceiling + leaves room for AAC overshoot, so the muxed MP4 stays under -1 dBTP. If no + drive reaches the target within the ceiling, the mix comes out quieter + rather than crushed. + """ + peak = max(max(map(abs, self.left)), max(map(abs, self.right))) or 1.0 + fade_n = int(fade_out * SR) + fade = [1.0 if i < self.n - fade_n else (self.n - i) / fade_n for i in range(self.n)] + ceiling = 10 ** (ceiling_db / 20) + + best = None + for drive in DRIVES: + norm = math.tanh(drive) + left = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.left, fade)] + right = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.right, fade)] + gain = 10 ** ((target_lufs - integrated_lufs(left, right)) / 20) + if gain > ceiling: + continue + tp = max(true_peak(left), true_peak(right)) + fit = min(gain, ceiling / tp) + if best is None or fit / gain > best[0]: + best = (fit / gain, drive, left, right, fit, tp) + if gain * tp <= ceiling: + break + if best is None: + drive = DRIVES[0] + norm = math.tanh(drive) + left = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.left, fade)] + right = [math.tanh(drive * x / peak) / norm * f for x, f in zip(self.right, fade)] + tp = max(true_peak(left), true_peak(right)) + best = (0, drive, left, right, ceiling / tp, tp) + _, drive, left, right, gain, tp = best + + self._out = ([x * gain for x in left], [x * gain for x in right]) + lufs = integrated_lufs(*self._out) + if lufs < target_lufs - 0.5: + print( + f"warning: {lufs:.1f} LUFS, short of {target_lufs}: the mix is too sparse to get louder " + "without clipping. Add sustained sound (a pad, longer tails) or accept it quieter." + ) + return {"lufs": lufs, "peak_db": 20 * math.log10(gain * tp), "drive": drive} + + def write(self, path): + """Write 16-bit stereo WAV; masters with defaults first if master() wasn't called.""" + if self._out is None: + self.master() + os.makedirs(os.path.dirname(path) or ".", exist_ok=True) + left, right = self._out + with wave.open(path, "wb") as wf: + wf.setnchannels(2) + wf.setsampwidth(2) + wf.setframerate(SR) + frames = bytearray() + for a, b in zip(left, right): + frames += struct.pack("")` from `sfx.synth`. + +| File | Use | Author | Source | +|---|---|---|---| +| fs-447909-keyboard-typing.ogg | keyboard, 3.8 s | Breviceps | https://freesound.org/people/Breviceps/sounds/447909/ | +| fs-323432-typing.ogg | keyboard, 4 s | Alivvie | https://freesound.org/people/Alivvie/sounds/323432/ | +| fs-79388-keyboard-typing-wav.ogg | keyboard, 4 s | j1987 | https://freesound.org/people/j1987/sounds/79388/ | +| fs-416777-digital-typing-wav.ogg | digital typing, 1 s | Sky_Motion | https://freesound.org/people/Sky_Motion/sounds/416777/ | +| fs-329533-room-tone-in-an-apartment-livi.ogg | room tone, 17 s | leonelmail | https://freesound.org/people/leonelmail/sounds/329533/ | +| fs-426767-apartment-room-tone-wav.ogg | room tone, 20 s | cMilan | https://freesound.org/people/cMilan/sounds/426767/ | +| fs-329569-roomtone-bedroom-yew.ogg | room tone, 20 s | leonelmail | https://freesound.org/people/leonelmail/sounds/329569/ | +| fs-258269-mouth-pop.ogg | mouth pop | jcallison | https://freesound.org/people/jcallison/sounds/258269/ | +| fs-447910-plop.ogg | plop | Breviceps | https://freesound.org/people/Breviceps/sounds/447910/ | +| fs-824189-pop-in-sfx.ogg | pop-in | Sadiquecat | https://freesound.org/people/Sadiquecat/sounds/824189/ | +| fs-349504-triangle-open-04.ogg | triangle ding, 4 s | cabled_mess | https://freesound.org/people/cabled_mess/sounds/349504/ | +| fs-339521-vhs-rewind-forward-and-eject.ogg | VHS rewind and eject, 4 s | lucaslima | https://freesound.org/people/lucaslima/sounds/339521/ | + diff --git a/sfx/samples/fs-258269-mouth-pop.ogg b/sfx/samples/fs-258269-mouth-pop.ogg new file mode 100644 index 0000000..269f578 Binary files /dev/null and b/sfx/samples/fs-258269-mouth-pop.ogg differ diff --git a/sfx/samples/fs-323432-typing.ogg b/sfx/samples/fs-323432-typing.ogg new file mode 100644 index 0000000..3a13e88 Binary files /dev/null and b/sfx/samples/fs-323432-typing.ogg differ diff --git a/sfx/samples/fs-329533-room-tone-in-an-apartment-livi.ogg b/sfx/samples/fs-329533-room-tone-in-an-apartment-livi.ogg new file mode 100644 index 0000000..aa2f3a9 Binary files /dev/null and b/sfx/samples/fs-329533-room-tone-in-an-apartment-livi.ogg differ diff --git a/sfx/samples/fs-329569-roomtone-bedroom-yew.ogg b/sfx/samples/fs-329569-roomtone-bedroom-yew.ogg new file mode 100644 index 0000000..8a95cf2 Binary files /dev/null and b/sfx/samples/fs-329569-roomtone-bedroom-yew.ogg differ diff --git a/sfx/samples/fs-339521-vhs-rewind-forward-and-eject.ogg b/sfx/samples/fs-339521-vhs-rewind-forward-and-eject.ogg new file mode 100644 index 0000000..0db8f8b Binary files /dev/null and b/sfx/samples/fs-339521-vhs-rewind-forward-and-eject.ogg differ diff --git a/sfx/samples/fs-349504-triangle-open-04.ogg b/sfx/samples/fs-349504-triangle-open-04.ogg new file mode 100644 index 0000000..4fd791a Binary files /dev/null and b/sfx/samples/fs-349504-triangle-open-04.ogg differ diff --git a/sfx/samples/fs-416777-digital-typing-wav.ogg b/sfx/samples/fs-416777-digital-typing-wav.ogg new file mode 100644 index 0000000..ab86f2e Binary files /dev/null and b/sfx/samples/fs-416777-digital-typing-wav.ogg differ diff --git a/sfx/samples/fs-426767-apartment-room-tone-wav.ogg b/sfx/samples/fs-426767-apartment-room-tone-wav.ogg new file mode 100644 index 0000000..c10315f Binary files /dev/null and b/sfx/samples/fs-426767-apartment-room-tone-wav.ogg differ diff --git a/sfx/samples/fs-447909-keyboard-typing.ogg b/sfx/samples/fs-447909-keyboard-typing.ogg new file mode 100644 index 0000000..9c3e272 Binary files /dev/null and b/sfx/samples/fs-447909-keyboard-typing.ogg differ diff --git a/sfx/samples/fs-447910-plop.ogg b/sfx/samples/fs-447910-plop.ogg new file mode 100644 index 0000000..fda1ba2 Binary files /dev/null and b/sfx/samples/fs-447910-plop.ogg differ diff --git a/sfx/samples/fs-79388-keyboard-typing-wav.ogg b/sfx/samples/fs-79388-keyboard-typing-wav.ogg new file mode 100644 index 0000000..5f52d61 Binary files /dev/null and b/sfx/samples/fs-79388-keyboard-typing-wav.ogg differ diff --git a/sfx/samples/fs-824189-pop-in-sfx.ogg b/sfx/samples/fs-824189-pop-in-sfx.ogg new file mode 100644 index 0000000..9388203 Binary files /dev/null and b/sfx/samples/fs-824189-pop-in-sfx.ogg differ diff --git a/sfx/score_kit.py b/sfx/score_kit.py new file mode 100644 index 0000000..ad22991 --- /dev/null +++ b/sfx/score_kit.py @@ -0,0 +1,206 @@ +"""Shared pieces for the figure scores: a parameterised lo-fi bed and a handful of accents. + +A figure's score.py imports this (it sits next to the sfx engine on sys.path when run through +run_sfx.py) and adds its own accents on the tour's seconds. +""" + +import math +import os +import random + +from sfx.dsp import add, reverb, svf, zeros +from sfx.synth import SR, bandnoise, bass, blip, epiano, hat, kick, snare + + +def env_fade(x, fin, fout): + n = len(x) + a = max(1, int(fin * SR)) + b = max(1, int(fout * SR)) + for i in range(min(a, n)): + x[i] *= i / a + for i in range(min(b, n)): + x[n - 1 - i] *= i / b + return x + + +def bed(dur, bpm, chords, motif=(), motif_voice="epiano", bass_pattern=((0, 1.15, 0.9), (2.5, 0.85, 0.6)), + kicks=(0, 2.75), snares=(1, 3), hats=8, swing=0.12, drums_from=1, keys_lp=4200, crackle_level=0.0, keys_vel=0.9): + """A looping bed: e-piano chords (one per bar), a bass line, soft drums and an optional motif every other bar. + + chords: [([note Hz, ...], root Hz), ...]. bass_pattern: (beat, length in beats, velocity). Returns stereo keys + plus mono bass and drum stems, all faded in and out. + """ + if os.environ.get("FIG_VARIANT"): + # the second-upload variant: three semitones up, a touch faster, the other motif voice + up = 2 ** (3 / 12) + chords = [([f * up for f in notes], root * up) for notes, root in chords] + motif = [(bt, f * up) for bt, f in motif] + motif_voice = "blip" if motif_voice == "epiano" else "epiano" + bpm *= 1.06 + beat = 60 / bpm + bar = 4 * beat + n = int(dur * SR) + keys, low, drums = zeros(n), zeros(n), zeros(n) + bars = int(dur / bar) + 1 + for b in range(bars): + t = 0.12 + b * bar + notes, root = chords[b % len(chords)] + for i, f in enumerate(notes): + add(keys, epiano(f, 2.9 * 84 / bpm + 0.4, keys_vel), int((t + 0.012 * i) * SR)) + if i >= 2: + add(keys, epiano(f, 1.3, keys_vel * 0.5), int((t + 1.5 * beat + 0.01 * i) * SR)) + if b % 2 == 1: + for bt, f in motif: + v = epiano(f, 1.1, 0.34, 0.6) if motif_voice == "epiano" else blip(f, 0.32, 0.11) + add(keys, v, int((t + bt * beat) * SR), 1.0 if motif_voice == "epiano" else 0.5) + for bt, length, vel in bass_pattern: + add(low, bass(root, length * beat, vel), int((t + bt * beat) * SR)) + if drums_from <= b < bars - 2: + for bt in kicks: + add(drums, kick(1.0 if bt == 0 else 0.75), int((t + bt * beat) * SR)) + for bt in snares: + add(drums, snare(0.55), int((t + bt * beat) * SR)) + for e in range(hats): + sw = swing * beat if (hats == 8 and e % 2) else 0.0 + add(drums, hat(0.5 if e % 2 == 0 else 0.32), int((t + e * 4 * beat / hats + sw) * SR)) + keys = svf(keys, keys_lp, 0.6, "lp") + wl, wr = reverb(keys, size=0.6, damp=0.5, scale=0.9) + left = [k * 0.8 + w * 0.36 for k, w in zip(keys, wl)] + right = [k * 0.8 + w * 0.36 for k, w in zip(keys, wr)] + low = svf(low, 900, 0.7, "lp") + drums = svf(drums, 7000, 0.6, "lp") + for buf in (left, right, low, drums): + env_fade(buf, 1.0, 2.2) + return left, right, low, drums + + +def thud(f=95, decay=0.12, dur=0.4): + """A soft body hitting something: a plush toy landing, a knock.""" + n = int(dur * SR) + return [math.sin(2 * math.pi * f * k / SR) * math.exp(-k / (decay * SR)) * min(1, k / 40) for k in range(n)] + + +def motor(dur, f0=220, grit_hz=1400, wobble=17): + """A small electric motor: a buzzy tone plus brush noise, faded at both ends.""" + n = int(dur * SR) + grit = bandnoise(n, lambda k: grit_hz, q=0.8) + out = [] + for k in range(n): + t = k / SR + m = 1 + 0.15 * math.sin(2 * math.pi * wobble * t) + s = sum(math.sin(2 * math.pi * f0 * h * t) / h for h in (1, 2, 3, 4)) + out.append(m * (0.35 * s + 0.5 * grit[k])) + return env_fade(out, 0.06, 0.1) + + +def airy(dur, f0, f1, level=1.0): + """Moving air: band noise sweeping from f0 to f1 with a soft swell.""" + n = int(dur * SR) + x = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=0.7) + return [x[k] * level * 1.4 * math.sin(math.pi * k / n) for k in range(n)] + + +def bang(level=1.0, seed=0): + """A small explosion: a low punch and a burst of dark noise.""" + rnd = random.Random(seed) + n = int(0.42 * SR) + noise = bandnoise(n, lambda k: 700 + 1600 * math.exp(-k / (0.03 * SR)), q=0.5) + out = [] + ph = 0.0 + for k in range(n): + t = k / SR + f = 48 + 90 * math.exp(-t / 0.03) + ph += 2 * math.pi * f / SR + s = math.sin(ph) * math.exp(-t / 0.12) * 1.1 + noise[k] * 1.8 * math.exp(-t / 0.05) + out.append(level * math.tanh(1.5 * s) * (0.92 + 0.08 * rnd.random())) + return out + + +def puff(level=1.0): + """A breath of gas out of a pipe.""" + n = int(0.3 * SR) + x = bandnoise(n, lambda k: 900, q=0.6) + return [level * x[k] * 1.6 * math.sin(math.pi * min(1, k / (0.06 * SR)) / 2) * math.exp(-k / (0.09 * SR)) for k in range(n)] + + +def rumble(dur, f_at, level=1.0): + """An engine's low hum whose pitch follows f_at(t).""" + n = int(dur * SR) + out = [] + ph = 0.0 + for k in range(n): + f = f_at(k / SR) + ph += 2 * math.pi * f / SR + out.append(level * (math.sin(ph) + 0.4 * math.sin(2 * ph) + 0.2 * math.sin(3 * ph))) + return env_fade(out, 0.3, 0.4) + + +_SEMI = {"C": -9, "D": -7, "E": -5, "F": -4, "G": -2, "A": 0, "B": 2} + + +def hz(name): + """Note name to frequency: "A4" = 440, "F#3", "Bb2".""" + base, rest = name[0], name[1:] + shift = 0 + while rest and rest[0] in "#b": + shift += 1 if rest[0] == "#" else -1 + rest = rest[1:] + return 440.0 * 2 ** ((_SEMI[base] + shift + 12 * (int(rest) - 4)) / 12) + + +def chords(*specs): + """chords("Fmaj7:F3 A3 C4 E4/F2", ...) -> bed() chord list; the part after / is the bass root.""" + out = [] + for spec in specs: + notes, root = spec.split(":", 1)[1].split("/") + out.append(([hz(n) for n in notes.split()], hz(root.strip()))) + return out + + +def beep(freq, dur=0.12, level=1.0): + """A clean electronic beep: a keypad, a timer, a piezo horn.""" + n = int(dur * SR) + a = max(1, int(0.004 * SR)) + return [level * math.sin(2 * math.pi * freq * k / SR) * min(1, k / a, (n - k) / a) for k in range(n)] + + +def rattle(dur, rate=18.0, f=3200, seed=0, level=1.0): + """Many small hard things settling: coins in a box, shavings, capsules.""" + rnd = random.Random(seed) + n = int(dur * SR) + out = zeros(n) + t = 0.0 + while t < dur: + k = int(t * SR) + tick = [math.sin(2 * math.pi * f * (0.7 + 0.6 * rnd.random()) * j / SR) * math.exp(-j / (0.004 * SR)) for j in range(int(0.03 * SR))] + add(out, tick, k, level * (0.4 + 0.6 * rnd.random()) * math.sin(math.pi * min(1.0, t / dur))) + t += rnd.expovariate(rate) + return out + + +def hiss(dur, fc=5200, level=1.0): + """Steam or air escaping: bright band noise with a soft swell.""" + n = int(dur * SR) + x = bandnoise(n, lambda k: fc, q=0.5) + return [x[k] * level * 1.3 * min(1, k / (0.15 * SR), (n - k) / (0.25 * SR)) for k in range(n)] + + +def spans(tl, field, pred): + """Intervals (t0, t1) in seconds where pred(sampled value of field) holds, from a timeline made with --sample.""" + i = tl["fields"].index(field) + rate, out, start = tl["rate"], [], None + for k, row in enumerate(tl["samples"]): + on = bool(pred(row[i])) + if on and start is None: + start = k / rate + elif not on and start is not None: + out.append((start, k / rate)) + start = None + if start is not None: + out.append((start, len(tl["samples"]) / rate)) + return out + + +def rising(tl, field, pred): + """Moments where pred(sampled value) turns true.""" + return [a for a, _ in spans(tl, field, pred)] diff --git a/sfx/synth.py b/sfx/synth.py new file mode 100644 index 0000000..28089ce --- /dev/null +++ b/sfx/synth.py @@ -0,0 +1,294 @@ +"""Sound generators. + +Every generator returns mono samples (a list of floats, roughly -1..1) at SR. +The first line of each docstring says what it's for; `python run_sfx.py --list` +prints them. To add a sound, write a function here in the same shape. +Use the module-level `random` for noise so renders stay reproducible. +""" + +import array +import bisect +import math +import os +import random +import subprocess + +SR = 48000 +FFMPEG = r"C:\Users\user_\.claude\bin\ffmpeg.exe" +SAMPLES = os.path.join(os.path.dirname(os.path.abspath(__file__)), "samples") + + +def sample(name, start=0.0, dur=None): + """Recorded sound from sfx/samples (or any path): keyboards, room tone. start/dur trim it in seconds.""" + path = name if os.path.isabs(name) else os.path.join(SAMPLES, name) + cmd = [FFMPEG, "-v", "error", "-ss", str(start), "-i", path] + if dur is not None: + cmd += ["-t", str(dur)] + cmd += ["-ac", "1", "-ar", str(SR), "-f", "s16le", "-"] + raw = subprocess.run(cmd, check=True, capture_output=True).stdout + pcm = array.array("h") + pcm.frombytes(raw[: len(raw) // 2 * 2]) + return [x / 32768 for x in pcm] + + +def bandnoise(n, fc_at, q=0.8): + """Building block: white noise through a band-pass, fc_at(k) is the cutoff in Hz at sample k.""" + low = band = 0.0 + out = [] + for k in range(n): + f = 2 * math.sin(math.pi * min(fc_at(k), SR / 6) / SR) + x = random.uniform(-1, 1) + low += f * band + high = x - low - q * band + band += f * high + out.append(band) + return out + + +def click(freq=1800, dur=0.05): + """UI click: a control snapping to a step, a toggle, a tick. Higher freq sounds smaller.""" + n = int(dur * SR) + out = [] + for k in range(n): + tt = k / SR + s = math.sin(2 * math.pi * freq * tt) * math.exp(-tt / 0.012) + s += random.uniform(-1, 1) * math.exp(-tt / 0.0015) * 0.6 + out.append(s) + return out + + +def key(): + """One keystroke; every call is slightly different. For typing use Mix.typing().""" + n = int(0.018 * SR) + fc = random.uniform(2400, 4200) + noise = bandnoise(n, lambda k: fc, q=0.5) + thock = random.uniform(160, 220) + return [ + noise[k] * math.exp(-k / (0.0025 * SR)) * 2.2 + + math.sin(2 * math.pi * thock * k / SR) * math.exp(-k / (0.006 * SR)) * 0.5 + for k in range(n) + ] + + +def blip(freq, dur=0.35, tau=0.12): + """Soft tonal blip: a word or element landing, one note of a sequence. Keep freq in key.""" + n = int(dur * SR) + out = [] + ph = 0.0 + for k in range(n): + tt = k / SR + ph += 2 * math.pi * freq / SR + a = min(1, tt / 0.003) * math.exp(-tt / tau) + out.append(a * (math.sin(ph) + 0.25 * math.sin(2 * ph) + 0.08 * math.sin(3 * ph))) + return out + + +def pop(f0, f1, dur=0.16): + """Pitched pop: a badge, chip or callout popping in. Sweeps f0 to f1; raise f0 across a sequence.""" + n = int(dur * SR) + out = [] + ph = 0.0 + for k in range(n): + tt = k / SR + f = f0 * (f1 / f0) ** min(1, tt / 0.06) + ph += 2 * math.pi * f / SR + a = min(1, tt / 0.002) * math.exp(-tt / 0.045) + out.append(a * math.sin(ph)) + return out + + +def chime(freqs, dur=1.8, tau=0.7): + """Bell chord: success, arrival, a payoff. Pass freqs from the video's key.""" + n = int(dur * SR) + out = [0.0] * n + for j, f in enumerate(freqs): + ph1 = ph2 = 0.0 + g = 1.0 / (1 + j * 0.35) + for k in range(n): + tt = k / SR + ph1 += 2 * math.pi * f / SR + ph2 += 2 * math.pi * f * 2.76 / SR + a = min(1, tt / 0.004) * math.exp(-tt / tau) + out[k] += g * a * (math.sin(ph1) + 0.18 * math.sin(ph2) * math.exp(-tt / 0.15)) + return out + + +def whoosh(dur, f0, f1, peak=0.6, q=0.9): + """Air whoosh: movement, reveals, transitions. f0 to f1 sets direction, peak (0..1) where it's loudest.""" + n = int(dur * SR) + p = math.log(0.5) / math.log(peak) + noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=q) + return [noise[k] * math.sin(math.pi * (k / n) ** p) ** 2 * 1.6 for k in range(n)] + + +def riser(dur, f0=260, f1=5200): + """Build-up into a payoff. End it exactly on the hit; one big riser per video.""" + n = int(dur * SR) + noise = bandnoise(n, lambda k: f0 * (f1 / f0) ** (k / n), q=0.6) + out = [] + ph = 0.0 + for k in range(n): + x = k / n + ph += 2 * math.pi * (180 * (4.0 ** x)) / SR + tail = min(1, (n - k) / (0.02 * SR)) + out.append((noise[k] * 1.3 + 0.35 * math.sin(ph)) * x ** 2.2 * tail) + return out + + +def impact(dur=1.2): + """Low impact for the hero moment. One per video.""" + n = int(dur * SR) + out = [] + ph = 0.0 + lp = 0.0 + for k in range(n): + tt = k / SR + f = 38 + 60 * math.exp(-tt / 0.07) + ph += 2 * math.pi * f / SR + lp += 0.08 * (random.uniform(-1, 1) - lp) + s = math.sin(ph) * math.exp(-tt / 0.38) + s += lp * math.exp(-tt / 0.05) * 3.0 + out.append(math.tanh(1.6 * s)) + return out + + +def scratch(dur): + """Pencil on paper: a sketch or line drawing itself on.""" + n = int(dur * SR) + noise = bandnoise(n, lambda k: 3800 + 1400 * math.sin(k / SR * 23), q=0.35) + out = [] + for k in range(n): + tt = k / SR + stroke = max(0.0, math.sin(tt * 2 * math.pi * 7.5)) ** 3 + env = math.sin(math.pi * k / n) + out.append(noise[k] * stroke * env * 1.4) + return out + + +def envelope(points): + """Helper: piecewise-linear gain curve from [(t, value), ...], for pad volume and ducking.""" + pts = sorted(points) + ts = [p[0] for p in pts] + + def at(t): + i = bisect.bisect_right(ts, t) + if i == 0: + return pts[0][1] + if i == len(pts): + return pts[-1][1] + (t0, v0), (t1, v1) = pts[i - 1], pts[i] + return v0 + (v1 - v0) * (t - t0) / (t1 - t0) + + return at + + +def pad(duration, chords, volume=None, detune=0.6, tremolo=0.23, xfade=0.35): + """Music bed under everything; returns (left, right) for Mix.put_stereo. chords = [(start_s, [freqs]), ...].""" + n = int(duration * SR) + left = [0.0] * n + right = [0.0] * n + for ci, (t0, freqs) in enumerate(chords): + t_next = chords[ci + 1][0] if ci + 1 < len(chords) else None + i0 = int(t0 * SR) + i1 = n if t_next is None else min(n, int((t_next + xfade) * SR)) + phl = [0.0] * len(freqs) + phr = [0.0] * len(freqs) + for i in range(i0, i1): + t = i / SR + w = 1.0 if ci == 0 else min(1.0, (t - t0) / xfade) + if t_next is not None and t > t_next: + w *= max(0.0, 1 - (t - t_next) / xfade) + v = w * (volume(t) if volume else 1.0) * (0.85 + 0.15 * math.sin(2 * math.pi * tremolo * t)) + sl = sr = 0.0 + for j, f in enumerate(freqs): + phl[j] += 2 * math.pi * (f - detune) / SR + phr[j] += 2 * math.pi * (f + detune) / SR + g = 1 / (1 + j * 0.5) + sl += g * math.sin(phl[j]) + sr += g * math.sin(phr[j]) + left[i] += sl * v + right[i] += sr * v + return left, right + + +# ---------------------------------------------------------------- a small band, for music beds +# Added 2026-10-18 for the coffee-machine film. Soft, warm, low in the mix: the bed sits under the picture, +# the accents (clicks, hiss) sit on top of it. + + +def epiano(freq, dur=2.6, vel=1.0, decay=1.1): + """Electric-piano note (tine and warm body), for lo-fi chords. Keep freq in key; vel 0..1.""" + n = int(dur * SR) + out = [0.0] * n + w1 = 2 * math.pi * freq / SR + w2 = 2 * w1 + wt = 2 * math.pi * freq * 6.98 / SR + wtrem = 2 * math.pi * 4.6 / SR + sin = math.sin + exp = math.exp + for k in range(n): + t = k / SR + a = (t / 0.006 if t < 0.006 else 1.0) * exp(-t / decay) + body = sin(w1 * k) + 0.28 * sin(w2 * k) * exp(-t / 0.5) + tine = 0.16 * sin(wt * k) * exp(-t / 0.09) + out[k] = vel * a * (body + tine) * (1 + 0.1 * sin(wtrem * k)) + tail = min(n, int(0.08 * SR)) + for i in range(tail): + out[n - 1 - i] *= i / tail + return out + + +def bass(freq, dur=0.9, vel=1.0): + """Round bass note: sine plus a little second harmonic, gently saturated. Roots under the chords.""" + n = int(dur * SR) + out = [0.0] * n + w = 2 * math.pi * freq / SR + sin = math.sin + exp = math.exp + for k in range(n): + t = k / SR + a = (t / 0.012 if t < 0.012 else 1.0) * exp(-t / 0.45) + out[k] = math.tanh(1.4 * vel * a * (sin(w * k) + 0.22 * sin(2 * w * k))) + tail = min(n, int(0.05 * SR)) + for i in range(tail): + out[n - 1 - i] *= i / tail + return out + + +def kick(vel=1.0): + """Soft kick: a sine dropping from 110 to 46 Hz. Lo-fi, not club.""" + n = int(0.32 * SR) + out = [0.0] * n + ph = 0.0 + for k in range(n): + t = k / SR + f = 46 + 64 * math.exp(-t / 0.035) + ph += 2 * math.pi * f / SR + out[k] = vel * math.sin(ph) * math.exp(-t / 0.11) * min(1.0, t / 0.002) + return out + + +def snare(vel=1.0): + """Brushed snare: band-passed noise with a short body tone, for beats 2 and 4.""" + n = int(0.22 * SR) + noise = bandnoise(n, lambda k: 2100, q=0.55) + return [vel * (noise[k] * 1.6 * math.exp(-k / (0.06 * SR)) + 0.25 * math.sin(2 * math.pi * 190 * k / SR) * math.exp(-k / (0.025 * SR))) for k in range(n)] + + +def hat(vel=1.0): + """Closed hat tick: high band noise, very short. Swing the off-beats.""" + n = int(0.05 * SR) + noise = bandnoise(n, lambda k: 7600, q=0.4) + return [vel * noise[k] * 1.8 * math.exp(-k / (0.011 * SR)) for k in range(n)] + + +def crackle(dur, density=7.0, hiss=0.012): + """Vinyl crackle bed: sparse clicks over a faint hiss. density is clicks per second.""" + n = int(dur * SR) + out = [random.uniform(-1, 1) * hiss for _ in range(n)] + for _ in range(int(dur * density)): + at = random.randrange(n) + g = random.uniform(0.05, 0.35) * random.choice((-1, 1)) + for i in range(min(40, n - at)): + out[at + i] += g * math.exp(-i / 6.0) + return out diff --git a/sheet.mjs b/sheet.mjs new file mode 100644 index 0000000..ef335ca --- /dev/null +++ b/sheet.mjs @@ -0,0 +1,127 @@ +#!/usr/bin/env node +// Contact sheets from any rendered video: the review loop's eyes, and the way to +// read a clip before writing timecodes about it. +// +// node sheet.mjs --video f.mp4 --timeline timeline.json every beat, settled (+0.3s) +// node sheet.mjs --video f.mp4 2.3 4.5 6.9 exact timestamps +// node sheet.mjs --video f.mp4 --every 1 one frame per second +// node sheet.mjs --video f.mp4 --from 3 --to 5 --every 0.2 scrub a transition +// +// Options: --offset 0.3 --cols 4 --rows 2 --size 540 --name beats +// Sheets land next to the video in