Skip to content
Back to search

cinetic

Cinematic launch films and motion design from code, directed by your coding agent.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Leonxlnx/cinetic with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Leonxlnx/cinetic'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leonxlnx--cinetic/badge.svg)](/listings/leonxlnx--cinetic)

HTML

<a href="/listings/leonxlnx--cinetic"><img src="/api/listings/leonxlnx--cinetic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add Leonxlnx/cinetic

Then ask your agent for a film, for example: "Make a 25-second launch film with music for our database branching tool. Invent the brand." It works with Claude Code, Codex, Cursor and the other agents the skills CLI supports.

Before the first film, check your machine with [a first test render](docs/setup.md#4-a-first-test-render). It needs Node 22+, ffmpeg 6+, Python 3.11+ and a headless Chromium, plus [earshot](https://github.com/Leonxlnx/earshot) 0.4 for the sound; see [Requirements](#requirements).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "cinetic",
  4. "owner": {
  5. "name": "Leonxlnx",
  6. "url": "https://github.com/Leonxlnx"
  7. },
  8. "description": "Cinematic launch films and motion design from code, directed by your coding agent.",
  9. "plugins": [
  10. {
  11. "name": "cinetic",
  12. "source": "./",
  13. "description": "Direct and render launch films, update videos, product videos, feature loops, logo stings and UI walkthroughs with Remotion or HyperFrames: a direction per film, real imagery, brand kits and a licensed music track."
  14. }
  15. ]
  16. }
README.md · README · 408 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/brand/lockup-dark.svg">
  4. <img src="docs/brand/lockup-light.svg" alt="cinetic" width="340">
  5. </picture>
  6. </h1>
  7. <p align="center">Cinematic launch films, update videos and motion design from code, directed by your coding agent.</p>
  8. <p align="center">
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-1f2328" alt="License: MIT"></a>
  10. <a href="#install"><img src="https://img.shields.io/badge/npx%20skills%20add-Leonxlnx%2Fcinetic-1f2328" alt="npx skills add Leonxlnx/cinetic"></a>
  11. <a href="https://github.com/Leonxlnx/cinetic/releases/latest"><img src="https://img.shields.io/github/v/release/Leonxlnx/cinetic?color=1f2328" alt="Latest release"></a>
  12. </p>
  13. <!-- EXAMPLE E1 (hero), for the owner to fill: the approved 1.5 launch film as a GIF excerpt linking to its MP4 on the media branch, with alt text, and one caption line under it (length, format, "made by an agent with cinetic 1.5 from the brief below"). No media is committed to this branch. -->
  14. cinetic (cinema + kinetic) is an agent skill that makes your coding agent direct a short film instead of arranging animation components. It is built for the two films a product team makes most: the **launch film** and the **update video** ("v2 is out", with the three things that changed).
  15. - **Clear copy first.** Before any picture, the agent writes a script a stranger understands in 5 seconds: what the product is by 3 s, then one thing it does a line, then the name and what to do, in 2–7 plain words a line. `copy-check.py` reads it the way a stranger would and fails vague words, slogans and keyword piles.
  16. - **One line at a time, each with its own animation.** Every line of the script arrives its own way, from twenty-three tested text animations and a book of 466 devices, while the camera keeps the picture moving. A hero line lands solid and leaves at speed, and seams carry the object and the speed into the next shot.
  17. - **Templates for the films teams make most.** `new-film.sh --template` lays down a whole film's structure: an update video, a UI walkthrough, a capability reel, a camera teaser, a prompt run, a social ad or a type explainer. For a film whose idea is its own device, the agent is dealt an art direction instead.
  18. - **The product, built in code.** Its screens come back as live components at film size: dense screens with one readable line, panels tilted in one light, a camera that moves through depth, portraits instead of grey silhouettes, and data that adds up on every frame.
  19. - **Real marks of the products it works with.** `logos.mjs` fetches the official colour marks of a product's integrations, sources and models from open collections and records source, licence and trademark owner. The kit sets them as app-icon tiles, chips, marks inside a line, walls and rings. Generic glyphs are Phosphor Icons.
  20. - **Type in one step.** Inter at its display cut by default, or a free face dealt from a set by look (neutral, tight, geometric, friendly, technical); two measured type families, calm or bold, set with one command; and `font-match.mjs` picks the free face closest to a brand face that cannot ship.
  21. - **Your brand, or one it makes.** Hand it a brand kit (logo, colours, fonts, screenshots) and `brand.py` writes it into the film. Without one, it designs a brand from three personality words. A clip you supply can lend the film its grammar, never its content.
  22. - **Music-led sound.** Every film is cut to its own licensed, human-made instrumental track, found by mood, tempo and length, with a sound cast for each action from an [earshot](https://github.com/Leonxlnx/earshot) kit and a library of real effects. No music is generated, nothing copyrighted enters a repository, and credits never appear in the picture.
  23. - **Finished and measured.** True motion blur, no banding, BT.709 and a sync-checked mux, then gates that fail motion that snaps, freezes or stops dead, floors against a flat picture, checks against filler shapes and unmotivated light, pixel forensics, an audio-sync audit, contact sheets and critic passes against a ship gate.
  24. It builds with Remotion (React) by default, or HyperFrames (HTML and GSAP).
  25. [Quick start](#quick-start) · [Examples](#examples) · [Start a film](#start-a-film) · [Install](#install) · [Requirements](#requirements) · [Use](#use) · [How it works](#how-it-works) · [Sound](#sound) · [Look](#look) · [What's inside](#whats-inside) · [Evaluation](#evaluation)
  26. ## Quick start
  27. ```bash
  28. npx skills add Leonxlnx/cinetic
  29. ```
  30. Then ask your agent for a film, for example: "Make a 25-second launch film with music for our database branching tool. Invent the brand." It works with Claude Code, Codex, Cursor and the other agents the skills CLI supports.
  31. Before the first film, check your machine with [a first test render](docs/setup.md#4-a-first-test-render). It needs Node 22+, ffmpeg 6+, Python 3.11+ and a headless Chromium, plus [earshot](https://github.com/Leonxlnx/earshot) 0.4 for the sound; see [Requirements](#requirements).
  32. ## Examples
  33. <!--
  34. EXAMPLES, for the owner to fill with the approved 1.5 films. No media is committed to this branch: each film
  35. lives on the repo's `media` branch (or as a release asset) and its cell links there; list the same files in
  36. DEMOS in .github/workflows/release.yml so the release attaches them.
  37. One cell per film, in this order:
  38. E2 the update video ("v1.5 is out", three changes)
  39. E3 the launch film built from a supplied brand kit
  40. E4 the film made with clip match
  41. E5 the sign-off sting
  42. Each cell: a GIF excerpt linking to its MP4, alt text, a bold title, two or three sentences on its idea and
  43. its template or devices, and "Download MP4 (length, sound, size in MB)".
  44. Then the briefs, word for word, in a <details> block.
  45. -->
  46. Every film here was made by an agent with cinetic 1.5 from a one-paragraph brief and cut to a licensed music track. The brands are invented unless the brief supplied one. Clicking a GIF downloads its MP4. The films live on the repo's `media` branch, so installs stay small.
  47. ## Start a film
  48. The agent scaffolds the project itself at intake. These are the commands it runs, and you can run them too (`<skill>` is where the skill is installed, for example `~/.claude/skills/cinetic`):
  49. ```bash
  50. # a launch film from the starter, for an idea that is its own device
  51. bash <skill>/scripts/new-film.sh films/acme --fps 60 --size 1920x1080
  52. # a film template laid over the starter
  53. bash <skill>/scripts/new-film.sh films/acme-walk --template ui-walkthrough
  54. # an update video in a supplied brand, cut to a track found with music.mjs
  55. bash <skill>/scripts/new-film.sh films/acme-2 --template update --brand ./brand \
  56. --music ./audio/track.mp3 --record ./audio/track.licence.json
  57. ```
  58. `new-film.sh` copies the starter (and the template), sets the grid, copies every cinetic script into the project so it runs on its own, and installs its dependencies. Other flags: `--type calm|bold` (the type family), `--like <clip>` (a clip's grammar), `--pace crisp`, `--engine hyperframes`, `--font <name>` and `--link-modules <dir>`; `--format update` is the same as `--template update`. `new-film.sh --help` lists them all.
  59. ### Which template
  60. | Template | Length | Use it when |
  61. |---|---|---|
  62. | none (the starter) | 15–45 s | a launch film whose idea is its own device: most films |
  63. | `update` | 15–23 s | "vX is out": 2–4 changes to show, each as a product moment |
  64. | `ui-walkthrough` | 25–40 s | the product's flow is the story: an input goes in, the product does visible work, an output comes out |
  65. | `capability-reel` | 15–25 s | the product's breadth is the story (sources, formats, integrations), or a launch film needs its close |
  66. | `camera-teaser` | 20–25 s | a dark, fast teaser of the product's screens where the camera does the moving |
  67. | `prompt-run` | 18–20 s | the product does work from a request (an agent, an assistant, a generator) and returns it done |
  68. | `social-ad` | 15 s | a short ad for a feed, cut on the product's own pictures |
  69. | `type-explainer` | 20–30 s | the idea is simple to say and the words carry it, on a white page with little product UI |
  70. The test is to say the film in one sentence. "You give it X and get Y" is a walkthrough; "it works with everything and returns anything" is a reel; "here is what changed" is an update; "ask it, it does the steps, here is the result" is a prompt run. When none fits, start from the starter.
  71. A template is the floor, never the film. It carries the structure, shot types, timing, transitions and choreography; the product, the words, the brand and the direction are yours. Its pace, tempo and type family become the film's defaults. Every string on screen comes from one content file whose placeholder marker fails the lint until the product's own words and data are in, and a fresh scaffold passes `tsc`, `grid-check` and `lint-film` with only those markers left. Its acts sit on whole bars, so once the track is in, every act line lands on a downbeat. Templates are for Remotion. Details: [references/templates.md](skills/cinetic/references/templates.md).
  72. ### Directions and devices
  73. A film from the starter is dealt, not left to the agent's habits.
  74. **The direction deck.** In Step 1 the agent runs
  75. ```bash
  76. python3 scripts/deck.py --brief "a docs map for scattered teams" --format launch --pace calm --options 3
  77. ```
  78. and gets three complete directions from 35, each fitted to the format: its space, light, camera language, cut grammar, type behaviour, story shape, lockup, palette proportions and one signature shot, and for an update film its hook, change and payoff beats. Type-led and graphic directions come up most; the 9 imagery-led ones are dealt only when the film has the product's own photographs or footage (`--have photos` or `--have footage`). The agent writes an idea sentence for each, keeps the one a competitor could not claim, and deals the full sheet for it, which becomes the art direction in `TREATMENT.md`.
  79. **The device book.** `references/devices/` holds 466 devices in 25 family files (type arrivals and exits, lines and swaps, marks and markers, icons and glyphs, colour and light, glass, glow and spectral, texture and grids, photos and footage, collage and composition, camera, camera transitions, cuts and seams, morphs and handoffs, wipes, masks and irises, speed and rush, depth and 3D, UI choreography, micro-interactions, cursor, loaders, data and numbers, logo and end card, sound and timing, cadence and grammar), with an index that picks by job: opening hook, reveal, emphasis, transition, proof, product moment, update change, lockup. Each entry gives what it is and when it earns its place, its anatomy, house timing at 60 fps, the sound that goes with it, and how to build it: a tested primitive in the starter's `src/fx/` with its props, or a recipe in plain layers.
  80. **The draw.** `pick.py` draws the film's devices from 724 entries in 27 families, and one text animation for each line of the script:
  81. ```bash
  82. python3 scripts/pick.py --format launch --energy high --seconds 25 --lines 6 --json out/qa/picks.json
  83. ```
  84. That is about one device per beat, in the order the format needs them, from many families (a variety rule keeps one family from filling a film), weighted toward the house's workhorses and the film's energy, and a different text animation on every line. The agent builds the picks its direction can carry, retold in the film's own objects, and rerolls or drops the rest with a reason written into the treatment. The seed is printed, so a plan can be reproduced.
  85. <details>
  86. <summary>An example device</summary>
  87. **Velocity handoff: cut on the fastest frame, next shot already moving** (`references/devices/cuts-and-seams.md`)
  88. *`dv-velocity-handoff-cut` · workhorse · energy medium · any format · primitive: camera-moves*
  89. The outgoing shot accelerates (a push with roll, a whip, a rise, a zoom-out) and is cut on its fastest frame; the incoming shot opens moving the same way, at about half to one-and-a-half times that speed, and decelerates to rest. Every cut hands over a carrier: velocity, scale direction, shape or position. **When:** the default for every cut in a film. **Avoid:** cutting between two parked frames, or into a move in the opposite direction.
  90. - **Anatomy:** exit ease-in over 4-29 f (about x1.13-1.3 a frame); entry at 0.5-1.5x the exit speed (22-52 px/f on frame one), settling in 20-60 f; a 4 f pre-roll drift can announce the next shot's direction.
  91. - **Timing:** exit 8-58 f; entry 20-72 f; cut speeds 15-200 px/f at 1080p.
  92. - **Sound:** a whoosh, kick or pop on the cut, within ±30 ms of the beat.
  93. - **Build:** `carriedCut()` / `handoffShot()` from `lib/handoff`; declare the seam in `timeline.ts`.
  94. </details>
  95. Browse the book in [references/devices/INDEX.md](skills/cinetic/references/devices/INDEX.md) and the drawable library in [references/technique-library.md](skills/cinetic/references/technique-library.md). The house rules behind them (shot lengths, easing, text timing, transitions, camera, UI in motion, colour over time) are in [references/craft-rules.md](skills/cinetic/references/craft-rules.md).
  96. ## Install
  97. ### Skills CLI (recommended)
  98. ```bash
  99. npx skills add Leonxlnx/cinetic
  100. ```
  101. Global install for Claude Code, without prompts:
  102. ```bash
  103. npx skills add Leonxlnx/cinetic -g -a claude-code -y
  104. ```
  105. Pin a version:
  106. ```bash
  107. npx skills add Leonxlnx/cinetic#v1.5.1
  108. ```
  109. For Claude Code the skill lands in `.claude/skills/cinetic` (project) or `~/.claude/skills/cinetic` (with `-g`). The same command installs it for the other agents the skills CLI supports, such as Codex and Cursor; choose them with `-a`.
  110. ### Claude Code plugin marketplace
  111. ```text
  112. /plugin marketplace add Leonxlnx/cinetic
  113. /plugin install cinetic@cinetic
  114. ```
  115. Claude Code can then load the skill on its own when you ask for a video, because the request matches the skill's description, or you can call it directly as `/cinetic:cinetic`. To update, run `/plugin marketplace update cinetic`, then open `/plugin` > Installed > cinetic > Update now (details in [docs/setup.md](docs/setup.md#claude-code-plugin)).
  116. ### Manual
  117. Download `cinetic.skill` from the [latest release](https://github.com/Leonxlnx/cinetic/releases/latest). It is a zip whose top folder is `cinetic/`:
  118. ```bash
  119. curl -L -o cinetic.skill https://github.com/Leonxlnx/cinetic/releases/latest/download/cinetic.skill
  120. mkdir -p ~/.claude/skills
  121. unzip cinetic.skill -d ~/.claude/skills/
  122. ```
  123. Or copy the folder from a clone (use `<project>/.claude/skills/` instead for a single project):
  124. ```bash
  125. git clone --depth 1 https://github.com/Leonxlnx/cinetic
  126. mkdir -p ~/.claude/skills && cp -R cinetic/skills/cinetic ~/.claude/skills/
  127. ```
  128. To update a manual install, remove `~/.claude/skills/cinetic` first, then repeat.
  129. ## Requirements
  130. - **macOS, Linux, or Windows with Git Bash.** The scripts are bash (3.2 or newer, so macOS's built-in bash works); they were developed on Linux, and macOS is less tested. On Windows they run in Git Bash, with `PYTHON` set to the interpreter of an environment that has the packages below; WSL2 with the [Ubuntu steps](docs/setup.md#ubuntu-and-debian-apt) is another route, not yet tested.
  131. - **Node 22+** (Remotion 4; `music.mjs`, `logos.mjs`, `assets.mjs`, `font-match.mjs` and the checks)
  132. - **ffmpeg 6+** with libx264, and ffprobe
  133. - **Python 3.11+** with numpy, scipy, soundfile, pyloudnorm, opencv-python and librosa; fonttools, brotli and uharfbuzz for outlined SVG logos and supplied fonts; pillow for banding-free gradient PNGs
  134. - **[earshot](https://github.com/Leonxlnx/earshot) 0.4+** in its own virtual environment, with `EARSHOT_PYTHON` pointing at its interpreter: it renders the film's sound kit (the `launch` preset, levelled over the music), ranks the sounds cast for each action and listens to the soundtrack. A film keeps its rendered takes in `audio/kit/`, so it rebuilds where earshot is not installed. Details: [Sound from earshot](docs/setup.md#sound-from-earshot).
  135. - **A licensed music track per film.** The agent finds one with `music.mjs` in free catalogs whose licence needs no credit, or you choose it; it stays in the film's git-ignored `audio/music/` beside its licence record. Details: [Music](docs/setup.md#music).
  136. - **Chromium or a Chrome headless shell.** Remotion downloads its own if allowed; set `REMOTION_BROWSER` or `CHROMIUM_PATH` to use a local one.
  137. - **A Remotion licence if you need one.** cinetic is MIT, but Remotion, the default engine, has its own licence: free for individuals and companies of up to 3 people, a company licence from 4. HyperFrames is Apache-2.0.
  138. Install the Python packages in a virtual environment:
  139. ```bash
  140. python3 -m venv ~/.venvs/cinetic
  141. source ~/.venvs/cinetic/bin/activate
  142. pip install numpy scipy soundfile pyloudnorm opencv-python librosa fonttools brotli uharfbuzz pillow
  143. ```
  144. Every script finds Python through `scripts/py.mjs`: `$PYTHON` when it is set, else the first of `python3`, `python` and `py -3` that runs Python 3.10 or newer and imports numpy, so the Microsoft Store alias is never run (`node scripts/py.mjs --which` prints the one it uses). Set `PYTHON` to the environment's interpreter, activate the environment before you start the agent, or put `~/.venvs/cinetic/bin` first on your `PATH`. A virtual environment also avoids the `externally-managed-environment` error that recent Debian, Ubuntu and Homebrew Pythons raise on a global `pip install`. Details: [Python packages](docs/setup.md#python-packages).
  145. You don't need a Remotion project first: the agent scaffolds one with `scripts/new-film.sh` and installs its dependencies. Renders are CPU-heavy. Motion blur multiplies render time by the number of sub-frames (typically 3–8x a sharp render); `render.sh --blur` prints an estimate before the sub-frame render, and `--budget` caps it. Renders run in parts, so a render stopped by a time limit or a crash resumes where it stopped. Full setup steps: [docs/setup.md](docs/setup.md).
  146. ## Use
  147. Describe the film in a sentence or two. Paste one of these and swap in your product:
  148. ```text
  149. Make a 25-second launch film with music for our database branching tool, for the announcement on X. Invent the brand.
  150. ```
  151. ```text
  152. Branchly 2.0 is out. Make a 15-second update video with music: offline mode, a command palette and shared branches. Use our brand kit in ./brand.
  153. ```
  154. ```text
  155. Make a 30-second walkthrough of our app: you paste a meeting link and get a finished brief. It works with Zoom, Google Meet and Slack, so show their marks.
  156. ```
  157. ```text
  158. Make our launch film feel like this clip (./ref/launch.mp4), but with our product and our own idea.
  159. ```
  160. ```text
  161. Make a 15-second ad for Reels from the product photos in ./photos.
  162. ```
  163. ```text
  164. Animate our new export feature as a 10-second loop for the landing page. It autoplays muted, so it has to read without sound.
  165. ```
  166. ```text
  167. Design a logo for our budgeting app and make a 6-second sting with music, plus a transparent version for our editors.
  168. ```
  169. ```text
  170. Make 9:16 and 1:1 versions of the launch film for Reels and LinkedIn.
  171. ```
  172. ```text
  173. Review this Remotion film: find the weakest three seconds, check the sync and fix what fails.
  174. ```
  175. **What the agent does.** If the brief names the product, the message and the length, it starts; otherwise it asks at most three questions, and it asks for the products yours works with, whose marks it can show. It works in files you can read and edit: `BRIEF.md` (the spec line, the hard bans and any brand exceptions), a film project scaffolded from the starter or a template at intake, then `TREATMENT.md` (the dealt direction, the script with its word count, the beat sheet with a device and a text animation per line, the music and any pictures). It runs `copy-check.py` on the script before any picture work, chooses and records the music before it writes the timeline, renders style stills and checks them before it animates, critiques previews on contact sheets, and renders the motion-blurred master once, after the last review round. Stings, loops and short clips take a scaled-down path: a one-page treatment, one or two acts and one review round.
  176. **Plan for a long run.** A full launch film takes the agent one to two hours and several hundred thousand tokens: dealing the direction, writing and checking the script, finding the music, building the brand and the product's screens, rendering motion blur and running review rounds.
  177. **What you get**, by format:
  178. | Format | Length | Deliverables |
  179. |---|---|---|
  180. | Launch film or teaser | 15–45 s | 16:9 master cut to its track, 9:16 and 1:1 re-layouts, poster, credits for the post, brand kit if invented |
  181. | Update video | 8–20 s | master opening on the name and the version, the changes as product moments, the end card with the version, poster, 9:16 |
  182. | Product or feature video | 8–30 s | master, poster |
  183. | Feature loop | 4–15 s | MP4, WebM and GIF, with a checked loop seam |
  184. | Logo sting | 3–8 s | MP4, ProRes 4444 alpha versions (held and cleared), poster, brand kit if invented |
  185. | UI walkthrough | 20–90 s | master, SRT captions |
  186. Social versions are re-laid out from the same timeline, never cropped from the master. The brand kit for an invented brand holds the mark and lockups as SVG and transparent PNG for light and dark grounds, favicon sizes, a 400x400 avatar and, on request, a 1500x500 header for X. The delivery folder keeps the deliverables at the top level, `CREDITS.md` and a paste-ready description when a licence asks for a credit, and the QA material (sheets, reports, a manifest with probe facts) in `qa/`. The film stays source code: change a line of copy, the accent or the track, and render again.
  187. ## How it works
  188. Every step writes a file and ends at a gate the agent actually runs. It starts from `BRIEF.md`, the brief plus a spec line such as `1920x1080@60, 25s, pace: calm, format: launch, audio: licensed track + launch kit`.
  189. | # | Step | Writes | What happens | Key script or template |
  190. |---|---|---|---|---|
  191. | 0 | Brief | `BRIEF.md`, the project | The format, the engine and the pace; what is supplied (a brand kit, a clip, pictures, the products it works with); the project scaffolded from the starter or a template | `new-film.sh` |
  192. | 1 | Direction | `TREATMENT.md`, `out/direction.json` | Three dealt directions, an idea sentence each, one chosen with its signature shot | `deck.py` |
  193. | 1b | Script | `TREATMENT.md` (Script) | What it is by 3 s, one thing it does a line, the name and what to do; 2–7 plain words a line, checked before any picture work | `copy-check.py` |
  194. | 2 | Brand and look | `src/brand/` | A supplied kit taken in, or a brand from three personality words; the type family; a clip's grammar measured; style stills | `brand.py`, `palette.py`, `type-family.mjs`, `like.py` |
  195. | 3 | Music | `audio/music/`, `src/music.ts` | The track found by mood, tempo and length, licensed, analysed and edited at bar lines; its grid written for the timeline | `music.mjs`, `track.py` |
  196. | 4 | Pictures (optional) | `public/assets/graded/` | Only the product's own pictures, or one that carries the idea, graded into one look | `assets.mjs` |
  197. | 5 | Beat sheet and timeline | `TREATMENT.md`, `src/timeline.ts` | One sentence per beat; the devices drawn, one text animation per line; acts, cues, copy and declarations on the music's bars | `pick.py`, `grid-check.ts` |
  198. | 6 | Build | `src/acts/` | Acts built from motion tokens and tested primitives (`TypeLine`, `Chain`, `Lit`, `DepthStack`…), the product rebuilt with the kit and one data module, real marks fetched; layout, covered text and text speed audited | `lint-film.mjs`, `layout-audit.sh`, `logos.mjs` |
  199. | 7 | Checks | `out/qa/` | On a preview: the floors against a flat film, the motion gates, the grammar score | `look-audit.py`, `forensics.py`, `grammar-score.mjs` |
  200. | 8 | Sound | `public/audio/soundtrack.wav` | Sync frames computed from the picture code; a sound cast for each action, levelled over the bed, with stop-downs before the payoff; mastered to −14 LUFS; earshot listens to the result | `export-cues.ts`, `kit.py`, `plan.py`, `score.py` |
  201. | 9 | Render | `out/film.mp4` | Preview, sharp or motion-blurred master in resumable parts: blur as the film declares it, optical-flow speeds set the sub-frames, averaged in float and quantized once to BT.709; sync and spec gates | `render.sh` |
  202. | 10 | Review | `out/qa/round-N/` | Contact sheets and feed-size strips, the measurements, an onset-by-onset audio audit, critic lenses and a verifier, a scored rubric and a ship gate | `sheet.py`, `av-audit.py`, `listen.py` |
  203. | 11 | Deliver | `out/deliver/` | Poster from a clean still, GIF and WebM loops, alpha stings, social variants, credits for the post, a manifest; the brand kit | `deliver.sh`, `credits.py`, `brand-kit.sh` |
  204. Everything hangs off one grid. With a track, `track.py grid` writes `src/music.ts` from the edit, and every frame number in the film comes from one helper on the music's own bars, so the picture, the cue export and the audits can't drift apart:
  205. ```ts
  206. export const b = (n: number, beat = 0, sub = 0) => // bar, beat, 16ths
  207. MUSIC ? Math.round(bar(n, beat, sub)) // the track's measured bars
  208. : Math.round(((n - 1) * 4 + beat) * BEAT + sub * (BEAT / 4));
  209. ```
  210. Sounds are never placed by hand. `export-cues.ts` runs the project's `src/sync.ts`, which computes the contact frames of springs, the settle frames of arrivals and the velocity peaks of launches from the same constants the acts animate with, and `score.py` places the effects on those frames.
  211. ## Sound
  212. **The music.** Every film plays its own licensed, human-made, instrumental track. `music.mjs search` looks through free catalogs whose licence needs no credit (Mixkit, and CC0 recordings on Wikimedia Commons, ccMixter and Openverse) and ranks them by the brief's mood words, tempo, length and energy curve; `sheet --measure` lists three to audition; `get` reads the licence page again and downloads the file with its licence record. `music.mjs pick` ranks a curated library of analysed tracks instead. No film reuses a track an earlier film used. `track.py` then analyses tempo, bars, phrases, entries, stops, the ending and the key, edits the track at bar lines to the film's length with the reveal on a strong bar, writes the film-time grid the timeline uses and measures every join. The track and anything mixed from it are git-ignored; the record, the analysis and the edit are committed (JSON, no audio). A licence that asks for a credit gets it in the delivery folder and the post description, never in the picture.
  213. **The effects.** Every effect plays an action: a card landing, a toggle, typing, a swipe, a logo lock, a transition through a shape. `kit.py cast` gives each action in the film its own sound from the bank of [earshot](https://github.com/Leonxlnx/earshot), a separate tool that designs sounds in code and checks them by measurement, ranked by earshot's ears and checked for masking against the track. Where the bank sounds an action weakly, a real effect that needs no credit comes in (`music.mjs search --kind sfx`, `kit.py real`) and joins a sound library (`library.py`) that the cast draws from beside the bank, so no two films share one set. With a track, each role sits at its level over the bed. `plan.py` lays the effects out; `score.py` renders the bed and the effects, applies the stop-downs (a few before the hit, the drop or the swell that matter, never a duck under every effect) and masters to −14 LUFS. Tuned effects never become a melody: at most two pitched effects in any 4 s.
  214. The house style is restraint: one soft sound per line of text, near-silence while it is read, a big hit only for the one reveal, and a lockup that is a stop-down and one clean element. `scripts/audio/listen.py` gives the review loop ears: earshot's per-cue sync, an annotated sound sheet and a critique, in one process.
  215. Without earshot or a rendered kit the soundtrack fails its gate; `score.py --draft` plays placeholder voices for a timing check, and a draft build is never delivered.
  216. ## Look
  217. Neutral grounds and surfaces (cool greys, a mid slate for dark stages), ink, and one accent with a meaning, on what matters, at its share of the frame, with an optional support hue beside it in 10–30 % of the film. Type reads large and frontal on clean fields; the product's own UI and graphic effects carry the picture, and pictures are an accent. The picture is never flat or frozen: `look-audit.py` fails a render under the floors (the camera or the ground moving through most of the body, two planes at different rates, carried seams, a designed moment every 3 s, a light event in every act, scale changes across cuts, clean flat ground and colour mass in the frame), `forensics.py` fails motion that snaps, freezes, settles too fast or stops dead, and `grammar-score.mjs` scores the film against the house grammar or a clip's. Every element in frame has a job, and light is motivated and subtle: a ground is flat or keyed gently from one side, and `look-audit.py` fails faint shapes that carry no text, icon or mark and a pool or haze of light over the ground, which `lint-film.mjs` also flags in the source.
  218. When the agent invents the look, none of these appear:
  219. - **Words:** a film that does not say what the product is by 3 s; vague, fancy or metaphor copy and slogan shapes ("X, reimagined"); keyword piles; two lines on screen at once; a line over 7 words; eyebrow or kicker labels, stacked taglines, "Introducing…", text walls and filler (decorative mono captions, fake metrics, lorem ipsum)
  220. - **Type:** serif typefaces; italic or oblique styles, including a skew that fakes one; overshoot on copy; letters moving one by one outside a line's own text animation
  221. - **Colour:** orange, amber, beige, cream, tan or sand; purple, violet or indigo; neon; a monochrome wash of the accent; glassmorphism as a UI style
  222. - **Decoration:** emoji and stock icons; sparkles standing for "AI", confetti and code rain; bouncy overshoot on anything that isn't landing
  223. - **Filler:** faint plates and blank cards that carry nothing, floating at depth or round a line; a light pool, white haze or fog vignette with no source in the picture; a veil over the product
  224. - **Pictures:** stock as the base of a film; low-resolution or mixed-grade pictures
  225. Light, glow, glass, spectral and iridescent colour and multi-hue gradients are allowed as part of a device with a job (every gradient baked and dithered, no banding), never as a look laid over everything. Other products' marks keep their own colours. `lint-film.mjs` checks tokens and styles (colours by OKLCH region, declared device palettes), `palette.py` refuses a banned accent or ground, and the critics check the rendered frames.
  226. **A brand you supply always wins.** If your identity includes a serif wordmark or an orange, it is used as given, recorded in `BRIEF.md` and `brand/brand.json` so the critics don't flag it, and marked in code with `// cinetic:brand-supplied <what>` so the lint accepts it; supplied colours are checked only for contrast and the one-accent rule.
  227. ## What's inside
  228. | Path | Contents |
  229. |---|---|
  230. | `skills/cinetic/SKILL.md` | The director: formats and defaults, the laws, the workflow from brief to delivery (Steps 0–11) with its gates plus a scaled-down path for stings and loops, taste rules, the timing and motion systems, engine rules, the ship gate |
  231. | `skills/cinetic/references/` | 27 guides, each read when its step comes up (concept and the direction deck, film templates, copy and type, brand and colour, brand kits, timing grid, motion tokens, camera, lighting, transitions, product UI, imagery, music, sound, update films, clip match, formats, finishing, checks, review loop, a catalogue of cheap-looking tells, both engines, Chromium rendering traps, the craft rules, a worked example, the library index), the device book in `devices/` and the drawable library in `library/` |
  232. | `skills/cinetic/assets/templates/` | Seven film templates: `update`, `ui-walkthrough`, `capability-reel`, `camera-teaser`, `prompt-run`, `social-ad` and `type-explainer` |
  233. | `skills/cinetic/assets/directions/` | The direction deck: `directions.json` and the imagery-led `imagery.json` |
  234. | `skills/cinetic/assets/library/` | `techniques.json`, the 724 entries `pick.py` draws from |
  235. | `skills/cinetic/scripts/` | 51 scripts: scaffold (`new-film.sh`), the direction deal (`deck.py`), the draw (`pick.py`), the script check (`copy-check.py`), brand intake (`brand.py`), clip match (`like.py`), type (`type-family.mjs`, `font-match.mjs`, `add-font.mjs`, with the face set by look in `faces.json`), imagery (`assets.mjs`), other products' marks (`logos.mjs`), the music finder (`music.mjs`) and the track (`track.py`), the sound kit and its cast (`kit.py`, `actions.py`, `library.py`), the effects plan, score and master, credits, listening, lint, grid and layout audits, palette, cue export, render and motion blur, probe and sync gates, the look floors and the grammar score, forensics, A/V audit, contact sheets, delivery, brand kit, and the Python finder (`py.mjs`). Each is documented in its header comment and, except the internal `brand-svg.ts` and `hf-preflight.cjs` helpers, in its `--help`. Their regression tests are in `scripts/test/`. |
  236. | `skills/cinetic/assets/` | The Remotion starter (default, with its demo, the tested primitives in `src/fx/` and the product kit in `src/kit/`), the HyperFrames starter, the treatment template and five critic prompts (director, art/copy/UI, sound-sync, forensics, verifier) |
  237. | [`evals/evals.json`](evals/evals.json) | The briefs and the written expectations each film is graded against |
  238. | `docs/` | [Setup](docs/setup.md) and the [evaluation](docs/evaluation.md) |
  239. | `.claude-plugin/` | `marketplace.json` and `plugin.json` for the Claude Code plugin marketplace |
  240. | `.github/workflows/` | `ci.yml` (checks) and `release.yml` (packages `cinetic.skill` for each version tag, with notes from the changelog) |
  241. | [`CHANGELOG.md`](CHANGELOG.md) | What each version changed |
  242. The Remotion starter's demo is a 15-second film in seven bars, every act opening on a bar line, built to be replaced: "plinth cuts" and "to music." build around an accent dot that lands as the line's full stop, the line launches left into a picture slot (a stand-in drawn in code until the film's own picture goes in, or the shot is rebuilt without one), the picture contracts into the gap of "Cuts land.", and the mark lands as a relief under a turning key before the name rises whole through its slot. Its `audio/score.json` plays the track you add (`audio/music/README.md`).
  243. ## Evaluation
  244. Each round ran the briefs with cinetic and with the same agent without it but with the official Remotion agent skills. A grader checked each brief's written expectations (size, frame rate, duration, loudness and true peak measured by script; sync and the visual checks judged from frames and audio), and blind judging agents compared each pair with the labels randomized: a neutral senior creative director in every round, a second judge applying a house style guide equal to the hard bans from round 3, and from round 6 the neutral judge again, comparing each new film with the one 0.5.0 made for the same brief.
  245. | Round | Version | Briefs | Expectations met (cinetic vs baseline) | Neutral judge: cinetic wins | House-style judge: cinetic wins | Against 0.5.0's films |
  246. |---|---|---|---|---|---|---|
  247. | 1 | 0.1.0 | 3 | 97.7% vs 80.3% | 0 of 3 | not run | not run |
  248. | 3 | 0.3.0 | 4 | 100% vs 74.8% | 2 of 4 | 4 of 4 | not run |
  249. | 4 | 0.4.0 | 4 | 55/56 (98%) vs 39/56 (70%) | 0 of 4 | 4 of 4 | not run |
  250. | 5 | 0.5.0 | 4 | 54/56 (96%) vs 41/56 (73%) | 2 of 4 | 4 of 4 | not run |
  251. | 6 | 1.0.0, first snapshot | 4 | 53/56 (95%) vs 41/56 (73%) | 1 of 4 | 4 of 4 | 2 of 4 |
  252. | 7 | 1.0.0, second snapshot | 4 | 54/56 (96%) vs 41/56 (73%) | 2 of 4 | 4 of 4 | 3 of 4 |
  253. Round 2 was invalidated by a harness problem and is not reported.
  254. cinetic met more of the written expectations in every round and won every house-style comparison. The neutral judge was split, and its craft notes became rules: in round 7 it credited the baselines' warmer, richer pictures while preferring cinetic's ideas and product story. Version 1.5 answers that note with a plain script shown one line at a time, film templates, the product's screens built in code in a lit place with depth, music on every film, and gates that fail a flat or frozen film; 1.1.0 and 1.5.0 have not had a judged round of their own yet. A cinetic run costs about three times the time and tokens of the baseline (round 7 average: 95 vs 33 minutes, 626k vs 231k tokens). The method and the full results are in [docs/evaluation.md](docs/evaluation.md).
  255. ## Origin
  256. The process was first worked out while making Tessel, a 33-second launch film built in code ([source and film](https://github.com/Leonxlnx/claude-launchvideo)). Its [worked example](skills/cinetic/references/worked-example.md) ships with the skill.
  257. ## Contributing
  258. Issues and pull requests are welcome. Before you open a PR, run the regression tests (they need Node 22.18+ and Python 3 with numpy, scipy, soundfile, pyloudnorm and librosa; the tests that load the starter's TypeScript, such as grid-check, the primitives and the type and kit tests, need `npm install` in `skills/cinetic/assets/remotion-starter`):
  259. ```bash
  260. node skills/cinetic/scripts/test/tokens.test.mjs
  261. node skills/cinetic/scripts/test/mirror.test.mjs
  262. node skills/cinetic/scripts/test/lint-film.test.mjs --part static
  263. node skills/cinetic/scripts/test/grid-check.test.mjs
  264. node skills/cinetic/scripts/test/scripts-docs.test.mjs
  265. node skills/cinetic/scripts/test/add-font.test.mjs
  266. node skills/cinetic/scripts/test/provenance.test.mjs
  267. node skills/cinetic/scripts/test/assets.test.mjs
  268. node skills/cinetic/scripts/test/logos.test.mjs
  269. node skills/cinetic/scripts/test/logo-kit.test.mjs
  270. node skills/cinetic/scripts/test/music.test.mjs
  271. node skills/cinetic/scripts/test/primitives.test.mjs
  272. node skills/cinetic/scripts/test/continuity.test.mjs
  273. node skills/cinetic/scripts/test/handoff.test.mjs
  274. node skills/cinetic/scripts/test/transitions.test.mjs
  275. node skills/cinetic/scripts/test/depth-light.test.mjs
  276. node skills/cinetic/scripts/test/kit-dense.test.mjs
  277. node skills/cinetic/scripts/test/moment.test.mjs
  278. node skills/cinetic/scripts/test/wordmark.test.mjs
  279. node skills/cinetic/scripts/test/type-presets.test.mjs
  280. node skills/cinetic/scripts/test/type-moves.test.mjs
  281. node skills/cinetic/scripts/test/type-family.test.mjs
  282. python3 skills/cinetic/scripts/test/copy-check.test.py
  283. python3 skills/cinetic/scripts/test/pick.test.py
  284. python3 skills/cinetic/scripts/test/deck.test.py
  285. python3 skills/cinetic/scripts/test/brand.test.py
  286. python3 skills/cinetic/scripts/test/like.test.py
  287. python3 skills/cinetic/scripts/test/track.test.py
  288. python3 skills/cinetic/scripts/test/score.test.py
  289. python3 skills/cinetic/scripts/test/cast.test.py
  290. python3 skills/cinetic/scripts/test/library.test.py
  291. python3 skills/cinetic/scripts/test/render-parts.test.py
  292. python3 skills/cinetic/scripts/test/encode-tags.test.py # runs its encodes when ffmpeg is on PATH
  293. python3 skills/cinetic/scripts/test/bash32.test.py
  294. ```
  295. CI runs all of these but the slow `cast.test.py` (provenance in release mode; lint-film, pick, deck, brand, like, assets, logos, music, copy-check, library and track; tokens, mirror and grid-check; the starter's primitive, continuity, handoff, transitions, depth and light, kit, moment, wordmark, logo-kit and type tests; type-family, score, scripts-docs, add-font, render-parts, bash32 and encode-tags), plus the forensics self-test, with the Remotion starter installed and type-checked, and also checks the SKILL.md frontmatter, the JSON and plugin manifests, that the skills CLI discovers the skill, Python, Node and shell syntax, and that no audio or video with sound is tracked by git. The shell scripts are also parsed with bash 3.2 (macOS's `/bin/bash`), in a container and on a macOS runner, which also runs the encode-tags test on a current ffmpeg. Bash 3.2 cannot parse a heredoc inside `$( )`: put such a heredoc in a shell function (`bash32.test.py` finds them). A change to a lint or text-flow rule needs a fixture in `skills/cinetic/scripts/test/lint-fixtures/`, and a change to a timeline check one in `grid-fixtures/`, that declares what it must produce. A change to the library goes into `techniques.json`; regenerate the readable pages with `python3 skills/cinetic/scripts/pick.py --write-docs skills/cinetic/references` (the index and each family's file in `references/library/`; `--markdown`, with `--family <name>` for one family, prints them); `pick.test.py` checks that they match.
  296. ## License
  297. [MIT](LICENSE), copyright (c) 2026 Leonxlnx.
skills/cinetic/scripts/assets.mjs · Bundled script · 2,351 lines · 1 finding marked
  1. #!/usr/bin/env node
  2. /**
  3. * assets.mjs: real photographs, footage, textures and art for a film, under licences that need no credit.
  4. *
  5. * A film made only of drawn shapes on a flat ground looks like a demo. Open collections hold the subject's
  6. * world (its places, materials, weather, tools, history) in photographs and footage that anyone may use,
  7. * and several of them ask for no credit at all. This finds them, lets you look before you choose, downloads
  8. * the chosen ones into the film, keeps a private licence record, and grades a set into one look.
  9. *
  10. * node scripts/assets.mjs search "<query>" [--kind photo|video|texture|art] [--source all|<list>]
  11. * [--orientation landscape|portrait|square] [--min-width 1600] [--colour blue|teal|mono|#2f6f8f]
  12. * [--people | --no-people] [--clean] [--fit 4:5] [--no-vet]
  13. * [--limit 8] [--allow-credit] [--out out/assets/<name>.json] [--json] [--no-check]
  14. * node scripts/assets.mjs sheet <results.json | image files | folders> [--pick 1,4,7] [--scan 6] [--cols 4] [--cell 400] [--out x.png]
  15. * node scripts/assets.mjs get <ref|#n>[,<ref|#n>...] --to <film>/public/assets [--from results.json] [--name stem]
  16. * [--width 2400] [--res 1080] [--trim start,seconds] [--max-mb 150] [--allow-credit] [--record path]
  17. * node scripts/assets.mjs grade <files...> [--look natural] [--strength 1] [--accent #hex] [--split-hue deg|#hex] [--focus x,y]
  18. * [--aspect 16:9|none] [--width 2400] [--grain 0.3] [--out dir] [--trim start,seconds] [--speed 1] [--scrub] [--dry-run] [--no-check]
  19. * node scripts/assets.mjs check <graded files...> [--accent #hex]
  20. * node scripts/assets.mjs probe <files...> [--json]
  21. * node scripts/assets.mjs looks | licences [--to <film>/public/assets]
  22. * node scripts/assets.mjs recipe [<input in your words>] [--run] [--kind video|photo] [--limit 6] [--out file] [--json] [--verify]
  23. *
  24. * Recipes. The first picture beat of a launch film shows the product's core transformation literally (input ->
  25. * output), with a real person where the input is human: a voice memo app opens on someone speaking into a phone, not
  26. * on a waveform alone. assets/footage-recipes.json holds 40 such inputs (speaking into a phone, typing on a laptop,
  27. * a meeting, paying at a counter, a parcel at the door, a doctor's visit ...), each with its framing, the screen that
  28. * takes the product's UI as a plate built in code, its searches (footage first, then photos) and, for most, the clips
  29. * and photos already looked at on a contact sheet (an input without them runs its searches at once).
  30. * `recipe "voice memo app"` finds the closest input, prints it and saves its picks as a results file (sheet and get #n
  31. * work at once; get reads each licence again at its source); --run searches every line again and adds the fresh hits
  32. * after the picks; --verify reads every pick again.
  33. *
  34. * Sources without keys: Burst (Shopify's free stock photos: people, products, lifestyle, places; its licence
  35. * needs no credit, read on each photo's page), ISO Republic (CC0 photos, read on each photo's page), Coverr (free
  36. * stock video of people, places and work; Coverr+ and AI-generated clips are refused), Mixkit stock video (its free
  37. * licence; items under its restricted licence are refused), Openverse (cc0 and public-domain marks only: StockSnap,
  38. * the WordPress photo directory, rawpixel, Flickr, museums), Wikimedia Commons (public domain and CC0 only, stills
  39. * and video), NASA's image and video library (public domain), the Art Institute of Chicago and The Metropolitan
  40. * Museum of Art open access (CC0). With a key in the environment: PEXELS_API_KEY (photos and video),
  41. * UNSPLASH_ACCESS_KEY (photos), PIXABAY_API_KEY (photos and video). Keys are read from the environment only and
  42. * never printed or written anywhere. Checked and dropped (2026-10-28): StockSnap's own API and Kaboompics answer a
  43. * script with a bot check, and Pexels, Pixabay and Unsplash pages without a key do too; Openverse still indexes
  44. * StockSnap. Nothing here solves or works round a login, key or bot check.
  45. *
  46. * Vet. After the size check, search reads each candidate's thumbnail (the sheet reuses them): people (the record's
  47. * own words, and frontal faces where the Python's OpenCV has a face model), readable text or a watermark (like.py's
  48. * text reader) and detail (soft or noisy thumbnails sink). --people keeps pictures with people, --no-people drops
  49. * them, --clean drops pictures with text, signs, logos or a watermark, --fit 4:5 keeps pictures that still hold
  50. * --min-width px after a crop to that shape. --no-vet skips the thumbnail reads (words only).
  51. *
  52. * Licences. The default takes only licences that need no credit: cc0, public domain, the Pexels, Unsplash and
  53. * Pixabay licences and Mixkit's free video licence, so a film never has to show credits. --allow-credit adds
  54. * CC BY (any version) and then writes the credit line into the record. Share-alike, non-commercial,
  55. * no-derivatives, Mixkit's restricted licence and unknown licences are always refused. `get` writes
  56. * <film>/assets/licences.json (source, licence, author, page, the licence as read): a private record kept
  57. * outside public/, never shown on screen.
  58. *
  59. * Grade. `natural` is the default and the film's look: every picture keeps its own colour and range; black
  60. * level and contrast move a quarter of the way toward the set's (never stretched past x1.3) and only the
  61. * strongest colours are held back a little, so the accent stays free for live data. `matte`, `silver` and
  62. * `night` (the median luma to about 0.18, warm colours drained) are whole-film looks too; `tint`, `duotone`
  63. * and `deep` are device looks for one shot (a whole film in one wash reads as a filter). --strength is how far
  64. * toward the look (0 = the picture as it is, 1 = the look); --chroma scales the colour after it.
  65. * After grading, the set is measured (`check` runs the same on any set): the share of neutral pixels (OKLCH
  66. * C < .03) must be at least 30 %, and no picture may show a banned colour region (orange/amber, beige/cream,
  67. * purple/violet, neon: the film's banned-hue test) on 0.5 % of a frame, or grade exits 3 with what to change
  68. * (natural tones, skin of every shade, hair, wood, sand, never count: they are the world's colour, not designed);
  69. * frames more than half saturated, the pictures' own share of the accent's hue, a set under the film's
  70. * saturated floor (4.5 %), pictures that do not match the set and readable text or logos in the pictures
  71. * are reported as notes.
  72. *
  73. * Needs Node 18+ (built-in fetch); ffmpeg and ffprobe for sheet, grade, probe and --trim.
  74. * Exit codes: 0 done, 1 nothing usable / a step failed, 2 bad arguments, 3 the graded set is a colour wash.
  75. */
  76. import { spawnSync } from 'node:child_process';
  77. import crypto from 'node:crypto';
  78. import fs from 'node:fs';
  79. import os from 'node:os';
  80. import path from 'node:path';
  81. import { fileURLToPath, pathToFileURL } from 'node:url';
  82. export const UA = 'cinetic-assets/1.2 (film imagery search; +https://github.com/Leonxlnx/cinetic)';
  83. const AIC_HEADERS = { 'AIC-User-Agent': UA };
  84. const CHECKED = '2026-10-24';
  85. const CHECKED_NEW = '2026-10-28'; // Burst, Coverr and ISO Republic: licence pages read on this day
  86. // ------------------------------------------------------------------------------------------------ licences
  87. /**
  88. * Every licence the tool knows. `credit` = the licence asks for a credit; `refuse` = never usable in a film
  89. * (with the reason); `seen` = the licence as read on its own page (a short quote, kept in the record).
  90. */
  91. export const LICENCES = {
  92. cc0: { name: 'CC0 1.0 (public domain dedication)', url: 'https://creativecommons.org/publicdomain/zero/1.0/', credit: false,
  93. seen: { quote: 'You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.', url: 'https://creativecommons.org/publicdomain/zero/1.0/' } },
  94. pd: { name: 'public domain', url: 'https://creativecommons.org/publicdomain/mark/1.0/', credit: false,
  95. seen: { quote: 'This work has been identified as being free of known restrictions under copyright law.', url: 'https://creativecommons.org/publicdomain/mark/1.0/' } },
  96. pexels: { name: 'Pexels License', url: 'https://www.pexels.com/license/', credit: false,
  97. limits: 'identifiable people never in a bad light; no unaltered resale; no endorsement or trademark use',
  98. seen: { quote: 'All photos and videos on Pexels are free to use. Attribution is not required.', url: 'https://www.pexels.com/license/' } },
  99. unsplash: { name: 'Unsplash License', url: 'https://unsplash.com/license', credit: false,
  100. limits: 'no unaltered resale; never compile the photos into a similar or competing service',
  101. seen: { quote: 'free, including for commercial purposes, without permission from or attributing the photographer or Unsplash', url: 'https://unsplash.com/license' } },
  102. pixabay: { name: 'Pixabay Content License', url: 'https://pixabay.com/service/license-summary/', credit: false,
  103. limits: 'no standalone resale; recognisable people, logos and brands need their own clearance',
  104. seen: { quote: 'Use Content without having to attribute the author (although giving credit is always appreciated by our community!)', url: 'https://pixabay.com/service/license-summary/' } },
  105. burst: { name: 'Burst Some Rights Reserved', url: 'https://www.shopify.com/stock-photos/licenses/shopify-some-rights-reserved', credit: false,
  106. limits: 'never sell the photo as a file; never compile the photos into a similar or competing service; recognisable people and brands need their own clearance',
  107. seen: { quote: 'You are free to adapt and use this Licensed Photo for free for commercial and noncommercial purposes ... You do not need to provide attribution to the photographer, Shopify or Burst', url: 'https://www.shopify.com/stock-photos/licenses/shopify-some-rights-reserved', date: CHECKED_NEW } },
  108. coverr: { name: 'Coverr License (free clips)', url: 'https://coverr.co/license', credit: false,
  109. limits: 'free clips only; never compile the clips into a similar service; never use them to train AI; people, brands and landmarks in a clip need their own clearance',
  110. seen: { quote: "You may use Coverr.co's videos and music for both commercial and non-commercial purposes at no cost ... You are not required to add an attribution credit to the original creator or to Coverr.co", url: 'https://coverr.co/license', date: CHECKED_NEW } },
  111. 'coverr-plus': { name: 'Coverr+ (subscription)', credit: false, refuse: 'a Coverr+ clip: subscribers only' },
  112. 'mixkit-video': { name: 'Mixkit Stock Video Free License', url: 'https://mixkit.co/license/#videoFree', credit: false,
  113. limits: 'no standalone redistribution of the clip; the limits in Mixkit\'s user terms apply',
  114. seen: { quote: 'Items under the Mixkit Stock Video Free License can be used in your commercial and non-commercial projects, for free ... Attribution is not required', url: 'https://mixkit.co/license/modal/videoFree/' } },
  115. by: { name: 'CC BY', url: 'https://creativecommons.org/licenses/by/4.0/', credit: true },
  116. 'by-sa': { name: 'CC BY-SA', credit: true, refuse: 'share-alike: a graded or combined film would have to carry the same licence' },
  117. 'by-nc': { name: 'CC BY-NC', credit: true, refuse: 'non-commercial only: a launch or product film is commercial' },
  118. 'by-nd': { name: 'CC BY-ND', credit: true, refuse: 'no derivatives: grading, cropping or cutting it is not allowed' },
  119. 'by-nc-sa': { name: 'CC BY-NC-SA', credit: true, refuse: 'non-commercial and share-alike' },
  120. 'by-nc-nd': { name: 'CC BY-NC-ND', credit: true, refuse: 'non-commercial, no derivatives' },
  121. 'mixkit-restricted': { name: 'Mixkit Stock Video Restricted License', credit: false, refuse: 'personal projects only: never advertising, a company\'s posts or a film' },
  122. unknown: { name: 'unknown licence', credit: true, refuse: 'no licence a film can rely on' },
  123. };
  124. /** A source whose own page states the public-domain terms (read once; kept in the record instead of the generic mark). */
  125. export const SOURCE_SEEN = {
  126. isorepublic: { licence: 'cc0', quote: 'All photo and video downloads on ISORepublic.com are free for both personal and commercial use and come with a CC0 license.', url: 'https://isorepublic.com/license/', date: CHECKED_NEW },
  127. nasa: { licence: 'pd', quote: 'NASA content - images, audio, video, and media files ... generally are not subject to copyright in the United States.', url: 'https://www.nasa.gov/nasa-brand-center/images-and-media/',
  128. limits: 'no NASA insignia or logos, nothing that implies NASA endorses the product, identifiable people need their own clearance' },
  129. };
  130. /** The licences a film may use without showing a credit (the default). */
  131. export const NO_CREDIT = ['cc0', 'pd', 'pexels', 'unsplash', 'pixabay', 'mixkit-video', 'burst', 'coverr'];
  132. /** May this licence go into the film? { ok, why } with --allow-credit adding CC BY. */
  133. export function licenceAllowed(id, { allowCredit = false } = {}) {
  134. const L = LICENCES[id] || LICENCES.unknown;
  135. if (L.refuse) return { ok: false, why: L.refuse };
  136. if (!L.credit) return { ok: true, why: '' };
  137. if (id === 'by' && allowCredit) return { ok: true, why: 'credit required: the record carries the credit line' };
  138. return { ok: false, why: 'needs a credit on screen (pass --allow-credit to take CC BY and keep the credit line)' };
  139. }
  140. /** A Creative Commons code (cc0, pdm, by, by-sa-4.0, cc-by-nc ...) to a licence id. */
  141. export function ccLicence(code) {
  142. const s = String(code || '').toLowerCase().trim().replace(/^cc[-_ ]?/, '').replace(/[ _]/g, '-');
  143. if (!s) return 'unknown';
  144. if (/^(0|zero)\b/.test(s) || s === 'cc0') return 'cc0';
  145. if (/^(pdm|pd|public-?domain)\b/.test(s)) return 'pd';
  146. const m = s.match(/^by(-nc)?(-sa|-nd)?(?:-[\d.]+)?$/);
  147. if (m) return `by${m[1] || ''}${m[2] || ''}`;
  148. return 'unknown';
  149. }
  150. /** Wikimedia Commons extmetadata (License, LicenseShortName, Restrictions) to { id, notes }. */
  151. export function commonsLicence(meta = {}) {
  152. const l = String(meta.License || '').toLowerCase();
  153. const s = String(meta.LicenseShortName || '').toLowerCase();
  154. const notes = [];
  155. if (meta.Restrictions) notes.push(`restrictions named on the page (${String(meta.Restrictions).replace(/<[^>]+>/g, '').trim()}): read it before use`);
  156. let id = 'unknown';
  157. if (/^cc0|^cc-zero/.test(l) || /^cc0|cc zero/.test(s)) id = 'cc0';
  158. else if (/no (known )?(copyright )?restrictions/.test(s) || /no restrictions/.test(l)) {
  159. id = 'unknown';
  160. notes.push('"no known copyright restrictions" is a statement, not a licence: refused');
  161. } else if (/^pd\b|^pd-/.test(l) || /public domain/.test(s)) {
  162. id = 'pd';
  163. if (/^pd-us|pd-usgov/.test(l)) notes.push('public domain in the United States (a US government or pre-1930 work)');
  164. } else {
  165. const cc = l.match(/^cc-(by(?:-nc)?(?:-sa|-nd)?)(?:-|$)/) || s.match(/^cc (by(?:-nc)?(?:-sa|-nd)?)\b/);
  166. if (cc) id = cc[1];
  167. }
  168. return { id, notes };
  169. }
  170. /** NASA records: public domain unless the record names a third party's copyright. */
  171. export function nasaLicence(d = {}) {
  172. const text = [d.description, d.photographer, d.secondary_creator, d.title, d.description_508].filter(Boolean).join(' ');
  173. if (/©|\(c\)\s*\d{4}|copyright|all rights reserved/i.test(text)) return { id: 'unknown', notes: ['the record names a copyright holder other than NASA: refused'] };
  174. const notes = ['public domain (US government work). In a promotional film: no NASA logos or insignia, no NASA people, nothing that implies endorsement'];
  175. if (/astronaut|crew member|portrait|\bcrew\b/i.test([d.title, ...(d.keywords || [])].join(' '))) notes.push('shows people: identifiable people need their own clearance in a commercial film');
  176. return { id: 'pd', notes };
  177. }
  178. // ------------------------------------------------------------------------------------------------ helpers
  179. const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  180. export const short = (s, n) => { const t = String(s ?? ''); return t.length > n ? `${t.slice(0, n - 1).replace(/[\s,;:.-]+$/, '')}…` : t; };
  181. const noQuery = (u) => (u ? String(u).split('?')[0] : u);
  182. export function text(v) {
  183. if (v === undefined || v === null) return '';
  184. return String(v).replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, ' ').replace(/<[^>]*>/g, ' ').replace(/&nbsp;/g, ' ').replace(/&quot;/g, '"')
  185. .replace(/&#0?39;|&apos;|&#x27;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
  186. .replace(/&amp;/g, '&').replace(/[​-‍]/g, '').replace(/\s+/g, ' ').trim();
  187. }
  188. export function slug(s, words = 7) {
  189. return String(s || '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
  190. .split('-').slice(0, words).join('-').slice(0, 60).replace(/-+$/, '');
  191. }
  192. export const shapeOf = (w, h) => (!w || !h ? null : w / h >= 1.15 ? 'landscape' : w / h <= 0.87 ? 'portrait' : 'square');
  193. const size = (b) => (b >= 1048576 ? `${(b / 1048576).toFixed(1)} MB` : `${Math.max(1, Math.round(b / 1024))} KB`);
  194. const clock = (s) => (s || s === 0 ? `${Math.floor(Math.round(s) / 60)}:${String(Math.round(s) % 60).padStart(2, '0')}` : '');
  195. async function mapLimit(items, n, fn) {
  196. const out = new Array(items.length); let next = 0;
  197. await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => { while (next < items.length) { const k = next++; out[k] = await fn(items[k], k); } }));
  198. return out;
  199. }
  200. const QWORDS_SKIP = new Set(['the', 'a', 'an', 'of', 'in', 'on', 'at', 'and', 'or', 'for', 'with', 'from', 'to', 'by']);
  201. export const queryWords = (q) => String(q).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w && !QWORDS_SKIP.has(w));
  202. /** How many of the query's words a record's own text carries (a plural also matches its singular). */
  203. export function wordHits(words, about) {
  204. const hay = String(about).toLowerCase();
  205. return words.filter((w) => hay.includes(w) || (w.length > 4 && hay.includes(w.replace(/(es|s)$/, '')))).length;
  206. }
  207. /** Does a record's own text carry the query (all words, or all but one of three or more)? */
  208. export function onSubject(words, about) {
  209. if (!words.length) return true;
  210. return wordHits(words, about) >= (words.length >= 3 ? words.length - 1 : words.length);
  211. }
  212. /** Never let a key reach a message: strip key-like query parameters and Authorization values. */
  213. export const redact = (s) => String(s).replace(/([?&](key|client_id|api_key|access_key)=)[^&\s]+/gi, '$1<hidden>').replace(/(Client-ID\s+)\S+/g, '$1<hidden>');
    • Note: Usual in code (tag names in paths and patterns): Contains a <hidden> block, a common wrapper for instructions hidden in a tool description
    • Line 221 on GitHub
  214. async function http(url, { ms = 25000, headers = {}, json = true } = {}) {
  215. for (let attempt = 1; ; attempt++) {
  216. let r;
  217. try { r = await fetch(url, { headers: { 'User-Agent': UA, Accept: json ? 'application/json' : 'text/html,*/*', ...headers }, signal: AbortSignal.timeout(ms), redirect: 'follow' }); }
  218. catch (e) {
  219. const timedOut = e.name === 'TimeoutError' || e.name === 'AbortError';
  220. if (!timedOut && attempt < 2) { await sleep(800); continue; }
  221. throw new Error(timedOut ? `no answer within ${Math.round(ms / 1000)} s` : `could not connect (${e.cause?.code || 'network error'})`);
  222. }
  223. if ([502, 503, 504].includes(r.status) && attempt < 2) { await sleep(1200); continue; }
  224. if (r.status === 429) {
  225. const asked = Number(r.headers.get('retry-after')) || 0; // seconds; an HTTP date reads as 0
  226. // A long Retry-After (Burst asks ~9 min after a run of reads) fails at once with the wait it names, instead of
  227. // sleeping into the 60 s search cap and reading as "no complete answer".
  228. if (asked > 30) { r.body?.cancel().catch(() => {}); throw new Error(`rate limited (HTTP 429): the site asks for ${Math.ceil(asked / 60)} min; search another --source meanwhile`); }
  229. const wait = asked || 8 * attempt;
  230. if (attempt < 3) { r.body?.cancel().catch(() => {}); await sleep(wait * 1000); continue; }
  231. throw new Error('rate limited (HTTP 429): wait a minute or search another --source');
  232. }
  233. if (r.status === 401 || r.status === 403) throw new Error(`refused (HTTP ${r.status})${headers.Authorization ? ': check the key in the environment' : ''}`);
  234. if (!r.ok) throw new Error(`HTTP ${r.status}`);
  235. if (!json) return r.text();
  236. try { return await r.json(); } catch { throw new Error('the answer was not JSON'); }
  237. }
  238. }
  239. const getJson = (url, o = {}) => http(url, { ...o, json: true });
  240. const getText = (url, o = {}) => http(url, { ...o, json: false });
  241. // ------------------------------------------------------------------------------------------------ files
  242. const IMAGE_TYPES = { jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif', avif: 'image/avif' };
  243. const VIDEO_TYPES = { mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime' };
  244. /** The real type of a file from its first bytes: { ext, media } or null. */
  245. export function sniff(b) {
  246. if (!b || b.length < 12) return null;
  247. if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return { ext: 'jpg', media: 'image' };
  248. if (b[0] === 0x89 && b.toString('ascii', 1, 4) === 'PNG') return { ext: 'png', media: 'image' };
  249. if (b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP') return { ext: 'webp', media: 'image' };
  250. if (b.toString('ascii', 0, 3) === 'GIF') return { ext: 'gif', media: 'image' };
  251. if (b.toString('ascii', 4, 8) === 'ftyp') {
  252. const brand = b.toString('ascii', 8, 12);
  253. if (/^avi[fs]/.test(brand)) return { ext: 'avif', media: 'image' };
  254. if (brand === 'qt ') return { ext: 'mov', media: 'video' };
  255. return { ext: 'mp4', media: 'video' };
  256. }
  257. if (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) return { ext: 'webm', media: 'video' };
  258. return null;
  259. }
  260. /** Width and height from the head of a JPEG, PNG, GIF or WebP. */
  261. export function dims(b) {
  262. if (!b || b.length < 26) return {};
  263. if (b[0] === 0x89 && b.toString('ascii', 1, 4) === 'PNG') return { w: b.readUInt32BE(16), h: b.readUInt32BE(20) };
  264. if (b.toString('ascii', 0, 3) === 'GIF') return { w: b.readUInt16LE(6), h: b.readUInt16LE(8) };
  265. if (b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP' && b.length >= 30) {
  266. const f = b.toString('ascii', 12, 16);
  267. if (f === 'VP8X') return { w: 1 + b.readUIntLE(24, 3), h: 1 + b.readUIntLE(27, 3) };
  268. if (f === 'VP8L') { const bits = b.readUInt32LE(21); return { w: 1 + (bits & 0x3fff), h: 1 + ((bits >>> 14) & 0x3fff) }; }
  269. if (f === 'VP8 ') return { w: b.readUInt16LE(26) & 0x3fff, h: b.readUInt16LE(28) & 0x3fff };
  270. }
  271. if (b[0] === 0xff && b[1] === 0xd8) {
  272. let i = 2;
  273. while (i + 9 < b.length) {
  274. if (b[i] !== 0xff) { i++; continue; }
  275. const m = b[i + 1];
  276. if (m === 0xff) { i++; continue; }
  277. if (m === 0x01 || (m >= 0xd0 && m <= 0xd8)) { i += 2; continue; }
  278. if (m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc) return { w: b.readUInt16BE(i + 7), h: b.readUInt16BE(i + 5) };
  279. i += 2 + b.readUInt16BE(i + 2);
  280. }
  281. }
  282. return {};
  283. }
  284. const imageHeaders = (url) => ({ 'User-Agent': UA, Accept: 'image/avif,image/webp,image/*,video/*,*/*;q=0.8', ...(/artic\.edu\//.test(url) ? AIC_HEADERS : {}) });
  285. /** Range-read the head of a file: does it load, its real type, size and pixel dimensions. */
  286. async function probeUrl(url, ms = 15000) {
  287. const ac = new AbortController(); const t = setTimeout(() => ac.abort(), ms);
  288. try {
  289. const r = await fetch(url, { headers: { ...imageHeaders(url), Range: 'bytes=0-262143' }, signal: ac.signal, redirect: 'follow' });
  290. if (!r.ok) { r.body?.cancel().catch(() => {}); return { ok: false, why: `HTTP ${r.status}` }; }
  291. const reader = r.body.getReader(); const chunks = []; let n = 0;
  292. while (n < 262144) { const { done, value } = await reader.read(); if (done) break; chunks.push(value); n += value.length; }
  293. reader.cancel().catch(() => {});
  294. const head = Buffer.concat(chunks);
  295. const kind = sniff(head);
  296. if (!kind) return { ok: false, why: 'not an image or video file' };
  297. const bytes = r.status === 206 ? Number((r.headers.get('content-range') || '').split('/')[1]) || null : Number(r.headers.get('content-length')) || null;
  298. return { ok: true, ...kind, bytes, ...(kind.media === 'image' ? dims(head) : {}) };
  299. } catch (e) { return { ok: false, why: e.name === 'AbortError' ? 'timed out' : 'could not load' }; }
  300. finally { clearTimeout(t); }
  301. }
  302. // ------------------------------------------------------------------------------------------------ items
  303. /** One candidate, the same shape from every source. */
  304. export function item(source, id, fields = {}) {
  305. return { ref: `${source}:${id}`, source, provider: SOURCES[source]?.name ?? source, kind: 'photo', title: '', author: '', authorUrl: null, page: null,
  306. thumb: null, image: null, width: null, height: null, bytes: null, duration: null, fps: null, licence: 'unknown', licenceVersion: null, notes: [], tags: [], ...fields };
  307. }
  308. export const SOURCES = {
  309. burst: { name: 'Burst', kinds: ['photo', 'texture'], keyless: true },
  310. isorepublic: { name: 'ISO Republic', kinds: ['photo', 'texture'], keyless: true },
  311. coverr: { name: 'Coverr', kinds: ['video'], keyless: true },
  312. openverse: { name: 'Openverse', kinds: ['photo', 'texture', 'art'], keyless: true },
  313. commons: { name: 'Wikimedia Commons', kinds: ['photo', 'texture', 'video'], keyless: true },
  314. nasa: { name: 'NASA Image and Video Library', kinds: ['photo', 'texture', 'video'], keyless: true },
  315. aic: { name: 'Art Institute of Chicago', kinds: ['art'], keyless: true },
  316. met: { name: 'The Metropolitan Museum of Art', kinds: ['art'], keyless: true },
  317. mixkit: { name: 'Mixkit', kinds: ['video'], keyless: true },
  318. pexels: { name: 'Pexels', kinds: ['photo', 'texture', 'video'], env: 'PEXELS_API_KEY' },
  319. unsplash: { name: 'Unsplash', kinds: ['photo', 'texture'], env: 'UNSPLASH_ACCESS_KEY' },
  320. pixabay: { name: 'Pixabay', kinds: ['photo', 'texture', 'video'], env: 'PIXABAY_API_KEY' },
  321. };
  322. const OPENVERSE_PROVIDERS = { flickr: 'Flickr', wikimedia: 'Wikimedia Commons', stocksnap: 'StockSnap', wordpress: 'WordPress Photo Directory', rawpixel: 'rawpixel',
  323. met: 'The Metropolitan Museum of Art', nypl: 'New York Public Library', clevelandmuseum: 'Cleveland Museum of Art', brooklynmuseum: 'Brooklyn Museum',
  324. smithsonian: 'Smithsonian', sciencemuseum: 'Science Museum Group', europeana: 'Europeana', nappy: 'Nappy', geographorguk: 'Geograph' };
  325. const hasKey = (src) => !SOURCES[src].env || Boolean(process.env[SOURCES[src].env]);
  326. const key = (src) => process.env[SOURCES[src].env] || '';
  327. // ---------- Openverse
  328. export function openverseUrl(q, o) {
  329. const lic = (o.allowCredit ? ['cc0', 'pdm', 'by'] : ['cc0', 'pdm']).join(',');
  330. const p = new URLSearchParams({ q, license: lic, page_size: String(Math.min(20, Math.max(12, o.limit * 3))), mature: 'false' }); // anonymous calls take at most 20
  331. p.set('category', o.kind === 'art' ? 'digitized_artwork,illustration' : 'photograph');
  332. if (o.orientation) p.set('aspect_ratio', { landscape: 'wide', portrait: 'tall', square: 'square' }[o.orientation]);
  333. if (o.minWidth >= 1000) p.set('size', 'large');
  334. return `https://api.openverse.org/v1/images/?${p}`;
  335. }
  336. export function parseOpenverse(j, o = {}) {
  337. return (j?.results || []).map((r) => {
  338. const via = String(r.source || r.provider || '');
  339. return item('openverse', r.id, {
  340. kind: o.kind || 'photo', provider: `Openverse / ${OPENVERSE_PROVIDERS[via] || (via.startsWith('smithsonian') ? 'Smithsonian' : via.replace(/_/g, ' ') || 'Openverse')}`,
  341. title: text(r.title).replace(/^File:/, '').replace(/\.(jpe?g|png|tiff?|gif|webp)$/i, '') || 'Untitled', author: text(r.creator), authorUrl: r.creator_url || null,
  342. page: r.foreign_landing_url || r.detail_url || null, thumb: r.thumbnail || null, image: r.url || null, width: r.width || null, height: r.height || null,
  343. bytes: r.filesize || null, licence: ccLicence(r.license), licenceVersion: r.license_version || null, tags: (r.tags || []).map((t) => t.name).slice(0, 12),
  344. });
  345. }).filter((it) => it.image);
  346. }
  347. async function searchOpenverse(q, o) {
  348. const items = parseOpenverse(await getJson(openverseUrl(q, o), { ms: 40000 }), o);
  349. await commonsSizes(items.filter((it) => /upload\.wikimedia\.org/.test(it.image || '')), o.width);
  350. return items;
  351. }
  352. // Openverse points at Wikimedia originals (often huge or TIFF): use a web-sized rendition instead.
  353. async function commonsSizes(items, width) {
  354. if (!items.length) return;
  355. const title = (it) => { let n = noQuery(it.image).split('/').pop(); try { n = decodeURIComponent(n); } catch { /* keep */ } return `File:${n.replace(/_/g, ' ')}`; };
  356. const j = await getJson(commonsApi({ titles: items.map(title).join('|'), prop: 'imageinfo', iiprop: 'url|size|mime', iiurlwidth: String(width) })).catch(() => null);
  357. const pages = new Map((j?.query?.pages || []).map((pg) => [pg.title, pg.imageinfo?.[0]]));
  358. const norm = new Map((j?.query?.normalized || []).map((x) => [x.from, x.to]));
  359. for (const it of items) { const ii = pages.get(norm.get(title(it)) || title(it)); if (ii?.thumburl) { it.image = noQuery(ii.thumburl); it.thumb = commonsThumb(ii.thumburl); } }
  360. }
  361. // ---------- Wikimedia Commons
  362. export function commonsApi(params) { return `https://commons.wikimedia.org/w/api.php?${new URLSearchParams({ action: 'query', format: 'json', formatversion: '2', origin: '*', ...params })}`; }
  363. const COMMONS_META = 'ObjectName|Artist|LicenseShortName|License|LicenseUrl|Restrictions|DateTimeOriginal|ImageDescription';
  364. /** Licence templates a credit-free file carries: one search each (most files on Commons are share-alike). */
  365. export const COMMONS_TEMPLATES = ['Cc-zero', 'PD-self', 'PD-USGov', 'PD-old'];
  366. export function commonsUrl(q, o, template = null) {
  367. const video = o.kind === 'video';
  368. let s = `${q} filetype:${video ? 'video' : 'bitmap'}`;
  369. if (!video && o.minWidth > 1) s += ` filew:>${o.minWidth - 1}`;
  370. if (template) s += ` hastemplate:${template}`;
  371. return commonsApi({ generator: 'search', gsrnamespace: '6', gsrsearch: s, gsrlimit: template ? '20' : '40', prop: video ? 'imageinfo|videoinfo' : 'imageinfo',
  372. iiprop: 'url|size|mime|extmetadata', iiurlwidth: String(video ? 1280 : o.width || 2400), iiextmetadatafilter: COMMONS_META, iiextmetadatalanguage: 'en', ...(video ? { viprop: 'derivatives' } : {}) });
  373. }
  374. /**
  375. * A Commons ref is the page id search prints (commons:12345) or the file's title, as a film often knows a
  376. * famous file by name (commons:File:Waves_009.jpg, commons:"File:Waves 009.jpg"; underscores or spaces).
  377. */
  378. export function commonsRefParam(id) {
  379. const v = decodeURIComponent(String(id)).trim();
  380. if (/^\d+$/.test(v)) return { pageids: v };
  381. const t = v.replace(/^(file|image):/i, '').replace(/_/g, ' ').trim();
  382. if (!t) throw new Usage('a Commons ref is commons:<page id> or commons:File:<name>');
  383. return { titles: `File:${t}` };
  384. }
  385. /** Commons serves fixed thumbnail steps; 500 px is one of them (the sheet's preview size). */
  386. export const commonsThumb = (u) => {
  387. if (!u) return null;
  388. const v = noQuery(u);
  389. if (/\/\d+px-[^/]+$/.test(v)) return v.replace(/\/(\d+)px-([^/]+)$/, '/500px-$2');
  390. const m = v.match(/^(https:\/\/upload\.wikimedia\.org\/wikipedia\/commons)\/([0-9a-f]\/[0-9a-f]{2})\/([^/]+\.(?:jpe?g|png|webp|gif))$/i);
  391. return m ? `${m[1]}/thumb/${m[2]}/${m[3]}/500px-${m[3]}` : v; // an original: its 500 px thumbnail
  392. };
  393. export function parseCommons(j, o = {}) {
  394. const pages = (j?.query?.pages || []).slice().sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
  395. return pages.map((pg) => {
  396. const ii = pg?.imageinfo?.[0]; if (!ii) return null;
  397. const m = (k) => text(ii.extmetadata?.[k]?.value);
  398. const lic = commonsLicence({ License: m('License'), LicenseShortName: m('LicenseShortName'), Restrictions: m('Restrictions') });
  399. const video = /^video\//.test(ii.mime || '') || o.kind === 'video';
  400. const it = item('commons', pg.pageid, {
  401. kind: video ? 'video' : o.kind || 'photo', title: m('ObjectName').replace(/\s*\b(?:title|label) QS:.*$/s, '').replace(/^"|"$/g, '') || String(pg.title || '').replace(/^File:/, '').replace(/\.[a-z0-9]+$/i, ''),
  402. author: short(m('Artist'), 80), page: ii.descriptionurl || null, width: ii.width || null, height: ii.height || null, bytes: ii.size || null,
  403. duration: Number(ii.duration) || null, licence: lic.id, notes: lic.notes,
  404. });
  405. if (video) {
  406. const ders = (pg.videoinfo?.[0]?.derivatives || []).map((d) => ({ url: noQuery(d.src), type: String(d.type || '').split(';')[0], w: Number(d.width) || null, h: Number(d.height) || null }));
  407. const pick = pickRendition(ders.filter((d) => /video\/(mp4|webm)/.test(d.type)), o.res || 1080);
  408. if (!pick) return null;
  409. Object.assign(it, { image: pick.url, renditions: ders, thumb: ii.thumburl ? noQuery(ii.thumburl) : null });
  410. } else {
  411. const tw = Number(String(ii.thumburl || '').match(/\/(\d+)px-[^/]+$/)?.[1]) || 0;
  412. it.image = ii.thumburl && tw && tw < (ii.width || 0) ? noQuery(ii.thumburl) : noQuery(ii.url);
  413. it.thumb = commonsThumb(ii.thumburl || ii.url);
  414. }
  415. return it;
  416. }).filter(Boolean);
  417. }
  418. /** Of a list of renditions, the largest whose short side is at most `res` (else the smallest). */
  419. export function pickRendition(list, res = 1080) {
  420. const side = (r) => (r.w && r.h ? Math.min(r.w, r.h) : Infinity);
  421. const fit = list.filter((r) => r.url && side(r) <= res).sort((a, b) => side(b) - side(a));
  422. return fit[0] || list.filter((r) => r.url).sort((a, b) => side(a) - side(b))[0] || null;
  423. }
  424. async function searchCommons(q, o) {
  425. const temps = o.allowCredit ? [null] : COMMONS_TEMPLATES;
  426. const all = await Promise.all(temps.map((t) => getJson(commonsUrl(q, o, t)).then((j) => parseCommons(j, o)).catch(() => [])));
  427. const seen = new Set();
  428. return interleave(all, 40).map(({ n, ...it }) => it).filter((it) => !seen.has(it.ref) && seen.add(it.ref));
  429. }
  430. // ---------- NASA
  431. export const nasaSearchUrl = (q, o) => `https://images-api.nasa.gov/search?${new URLSearchParams({ q, media_type: o.kind === 'video' ? 'video' : 'image', page_size: String(Math.min(100, o.limit * 4 + 8)) })}`;
  432. export function parseNasaSearch(j, o = {}) {
  433. const words = queryWords(o.query || '');
  434. return (j?.collection?.items || []).map((x) => {
  435. const d = x?.data?.[0]; if (!d?.nasa_id) return null;
  436. if (!onSubject(words, [d.title, d.description, ...(d.keywords || [])].join(' '))) return null;
  437. const lic = nasaLicence(d);
  438. return item('nasa', encodeURIComponent(d.nasa_id), {
  439. kind: d.media_type === 'video' ? 'video' : o.kind === 'video' ? 'video' : o.kind || 'photo', title: text(d.title) || d.nasa_id,
  440. author: text(d.photographer || d.secondary_creator) || `NASA${d.center ? ` ${d.center}` : ''}`, page: `https://images.nasa.gov/details/${encodeURIComponent(d.nasa_id)}`,
  441. thumb: (x.links || []).find((l) => /thumb|preview/.test(`${l.rel} ${l.href}`))?.href || x.links?.[0]?.href || null, manifest: x.href || null,
  442. licence: lic.id, notes: lic.notes, tags: (d.keywords || []).slice(0, 12), date: String(d.date_created || '').slice(0, 10) || null,
  443. });
  444. }).filter(Boolean);
  445. }
  446. const nasaHref = (u) => (u ? encodeURI(String(u).replace(/^http:/, 'https:')).replace(/%25([0-9a-f]{2})/gi, '%$1') : null);
  447. /** A NASA asset manifest (a list of file URLs) to the renditions of one item. */
  448. export function parseNasaManifest(files, kind = 'photo') {
  449. const list = (Array.isArray(files) ? files : (files?.collection?.items || []).map((f) => f.href)).map(String);
  450. const find = (s) => nasaHref(list.find((f) => f.endsWith(s)));
  451. if (kind === 'video') {
  452. const r = [['~orig.mp4', null, null], ['~large.mp4', 1920, 1080], ['~medium.mp4', 1280, 720], ['~small.mp4', 640, 360], ['~mobile.mp4', 320, 180]]
  453. .map(([s, w, h]) => ({ url: find(s), type: 'video/mp4', w, h, orig: s === '~orig.mp4' })).filter((x) => x.url);
  454. return { renditions: r, poster: find('~large.jpg') || find('~medium.jpg') || find('~thumb.jpg') };
  455. }
  456. return { orig: find('~orig.jpg') || find('~orig.png'), large: find('~large.jpg'), medium: find('~medium.jpg'), small: find('~small.jpg'), thumb: find('~thumb.jpg') };
  457. }
  458. async function searchNasa(q, o) {
  459. const items = parseNasaSearch(await getJson(nasaSearchUrl(q, o)), { ...o, query: q }).slice(0, o.limit * 2 + 4);
  460. await mapLimit(items, 6, async (it) => {
  461. const m = await getJson(nasaHref(it.manifest), { ms: 15000 }).catch(() => null);
  462. if (!m) return;
  463. const r = parseNasaManifest(m, it.kind);
  464. if (it.kind === 'video') { const pick = pickRendition(r.renditions.filter((x) => !x.orig), o.res || 1080); if (pick) Object.assign(it, { image: pick.url, renditions: r.renditions, thumb: r.poster || it.thumb, width: pick.w, height: pick.h }); }
  465. else { it.image = (o.width > 1600 ? r.orig : null) || r.large || r.medium; it.original = r.orig; it.thumb = r.small || r.thumb || it.thumb; }
  466. });
  467. return items.filter((it) => it.image);
  468. }
  469. // ---------- Art Institute of Chicago
  470. const AIC_FIELDS = ['id', 'title', 'artist_title', 'artist_display', 'date_display', 'image_id', 'thumbnail', 'medium_display', 'artwork_type_title', 'is_public_domain'];
  471. export function aicUrl(q, o) {
  472. const words = queryWords(q);
  473. return `https://api.artic.edu/api/v1/artworks/search?params=${encodeURIComponent(JSON.stringify({
  474. query: { bool: { must: [{ multi_match: { query: words.join(' ') || q, type: 'cross_fields', operator: 'and', fields: ['title^3', 'subject_titles^2', 'term_titles^2', 'classification_titles', 'medium_display', 'artist_title', 'place_of_origin'] } }],
  475. filter: [{ term: { is_public_domain: true } }, { exists: { field: 'image_id' } }] } }, fields: AIC_FIELDS, limit: Math.min(40, o.limit * 3) }))}`;
  476. }
  477. export function parseAic(j, o = {}) {
  478. const iiif = j?.config?.iiif_url || 'https://www.artic.edu/iiif/2';
  479. return (j?.data || []).map((d) => {
  480. if (!d?.image_id || d.is_public_domain === false) return null;
  481. const W = d.thumbnail?.width || null; const H = d.thumbnail?.height || null;
  482. const cap = W ? Math.min(W, 3000) : 3000; const w = Math.min(o.width || 2400, cap);
  483. return item('aic', d.id, { kind: 'art', title: text(d.title) || 'Untitled', author: text(d.artist_title) || text(String(d.artist_display || '').split('\n')[0]),
  484. page: `https://www.artic.edu/artworks/${d.id}`, thumb: `${iiif}/${d.image_id}/full/400,/0/default.jpg`, image: `${iiif}/${d.image_id}/full/${w},/0/default.jpg`,
  485. width: W && H ? w : null, height: W && H ? Math.round((H * w) / W) : null, full: W && H ? [W, H] : null, licence: 'cc0', tags: [text(d.artwork_type_title), text(d.medium_display)].filter(Boolean) });
  486. }).filter(Boolean);
  487. }
  488. async function searchAic(q, o) { return parseAic(await getJson(aicUrl(q, o), { headers: AIC_HEADERS }), o); }
  489. /**
  490. * AIC's IIIF server renders a width it has ready and answers any other with a redirect to its 843 px default, so a
  491. * plain fetch saves 843 px whatever the record says. The widths to try, largest first: the asked width within the
  492. * original, AIC's 1686 px large size, 843. Pure.
  493. */
  494. export const aicWidths = (asked, original = null) => {
  495. const top = Math.max(1, Math.round(Math.min(asked, original || asked)));
  496. return [...new Set([top, 1686, 843])].filter((w) => w <= top).sort((a, b) => b - a);
  497. };
  498. /**
  499. * The largest width AIC serves for an item, asked without following its redirect; sets the item's image, width and
  500. * height to it and returns the width (null when no answer came: the item is left as it was). `f` is fetch.
  501. */
  502. export async function aicServe(it, asked, f = fetch) {
  503. const base = String(it.image || '').replace(/\/full\/[^/]+\/0\/default\.jpg$/, '');
  504. const [W, H] = it.full || [null, null];
  505. for (const w of aicWidths(asked, W)) {
  506. const url = `${base}/full/${w},/0/default.jpg`;
  507. const r = await f(url, { headers: imageHeaders(url), redirect: 'manual', signal: AbortSignal.timeout(30000) }).catch(() => null);
  508. if (r?.body) r.body.cancel().catch(() => {});
  509. if (r && r.status >= 200 && r.status < 300) {
  510. Object.assign(it, { image: url, width: w, height: W && H ? Math.round((H * w) / W) : it.height });
  511. return w;
  512. }
  513. }
  514. return null;
  515. }
  516. // ---------- The Met
  517. export const metSearchUrl = (q, o) => `https://collectionapi.metmuseum.org/public/collection/v1.1/search?${new URLSearchParams({ q, hasImages: 'true', limit: String(Math.min(40, o.limit * 4 + 8)), offset: '0' })}`;
  518. export const metObjectUrl = (id) => `https://collectionapi.metmuseum.org/public/collection/v1/objects/${encodeURIComponent(id)}`;
  519. export function parseMetObject(x, o = {}) {
  520. if (!x || !x.isPublicDomain || !x.primaryImage) return null;
  521. const words = queryWords(o.query || '');
  522. const about = [x.title, x.objectName, x.medium, x.classification, x.culture, x.period, x.artistDisplayName, x.department, ...(x.tags || []).map((t) => t.term)].filter(Boolean).join(' ');
  523. if (o.query && !onSubject(words, about)) return null;
  524. const fix = (u) => (u ? encodeURI(u).replace(/%25([0-9a-f]{2})/gi, '%$1') : null);
  525. return item('met', x.objectID, { kind: 'art', title: text(x.title) || text(x.objectName) || 'Untitled', author: text(x.artistDisplayName) || (x.culture ? `${text(x.culture)} maker` : ''),
  526. page: x.objectURL || null, thumb: fix(x.primaryImageSmall) || fix(x.primaryImage), image: fix(x.primaryImage), licence: 'cc0', tags: (x.tags || []).map((t) => t.term).slice(0, 12) });
  527. }
  528. async function searchMet(q, o) {
  529. const s = await getJson(metSearchUrl(q, o));
  530. const ids = (s.objectIDs || []).slice(0, o.limit * 4 + 8);
  531. const objs = await mapLimit(ids, 8, (id) => getJson(metObjectUrl(id), { ms: 15000 }).catch(() => null));
  532. return objs.map((x) => parseMetObject(x, { ...o, query: q })).filter(Boolean);
  533. }
  534. // ---------- Mixkit (stock video, scraped from its public pages: it has no API)
  535. export const mixkitUrl = (q, page = 1) => `https://mixkit.co/free-stock-video/discover/${slug(q, 6)}/${page > 1 ? `?page=${page}` : ''}`;
  536. /** Mixkit's grid page to items (id, title, preview); the licence is read from each item's own page. */
  537. export function parseMixkitList(html) {
  538. const out = []; const seen = new Set();
  539. const re = /data-item-grid--video-player-item-id-value="(\d+)"[\s\S]*?<img src="([^"]+)"[^>]*alt="([^"]*)"[\s\S]*?<video src="([^"]+)"[\s\S]*?<a href="(\/free-stock-video\/[^"]+)"/g;
  540. let m;
  541. while ((m = re.exec(html))) {
  542. const [, id, thumb, alt, preview, href] = m;
  543. if (seen.has(id)) continue; seen.add(id);
  544. out.push(item('mixkit', id, { kind: 'video', title: text(alt).replace(/\.$/, ''), page: `https://mixkit.co${href}`, thumb: thumb.replace('-thumb-360-0', '-thumb-720-0'),
  545. preview, image: preview.replace(/-360\.mp4$/, '-720.mp4'), licence: 'unknown', notes: ['licence not read yet'] }));
  546. }
  547. return out;
  548. }
  549. /**
  550. * A Mixkit item page: its licence (free or restricted) with the page's own licence line, its length and its
  551. * renditions. The files are named as the page names its 720p file (the contentUrl): newer clips live under
  552. * active_storage/video_items/<id>/<stamp>/<id>-video-<p>.mp4, older ones under videos/<id>/<id>-<p>.mp4, so an address
  553. * built from the id alone is refused (HTTP 403). `known`: another file of the clip (the grid's preview) when the page
  554. * names none; with neither there is no rendition. `page`: the item page's address, kept with the licence line.
  555. */
  556. export function parseMixkitItem(html, id, { known = null, page = null } = {}) {
  557. const h = String(html);
  558. const notice = (h.match(/"copyrightNotice":"([^"]*)"/) || [])[1] || '';
  559. const link = (h.match(/href="\/license\/#(video[A-Za-z]+)"/) || [])[1] || '';
  560. let licence = 'unknown';
  561. if (/restricted/i.test(notice) || link === 'videoRestricted') licence = 'mixkit-restricted';
  562. else if (/^free$/i.test(notice) || link === 'videoFree' || /Mixkit Stock Video Free License/.test(h)) licence = 'mixkit-video';
  563. const dur = (h.match(/"duration":"PT(\d+)M(\d+)S"/) || []);
  564. const res = [...h.matchAll(/download-resolution">\s*(\d+)\s*x\s*(\d+)/g)].map((m) => [Number(m[1]), Number(m[2])]);
  565. const big = [...res].sort((x, y) => y[0] * y[1] - x[0] * x[1])[0] || [1920, 1080];
  566. const portrait = big[1] > big[0];
  567. const longest = Math.max(0, ...res.map(([x, y]) => Math.max(x, y)));
  568. const sizes = [...new Set([720, ...[...h.matchAll(/type=(\d{3,4})p/g)].map((m) => Number(m[1])), ...(longest >= 1920 ? [1080] : []), ...(longest >= 3840 ? [2160] : [])])]
  569. .filter((p) => p >= 360 && p <= 2160).sort((x, y) => x - y);
  570. const base = (h.match(new RegExp(`"contentUrl":"(https://assets\\.mixkit\\.co/[^"]*?/${id}(?:-video)?-)\\d{3,4}\\.mp4"`)) || [])[1]
  571. || (String(known || '').match(new RegExp(`^(https://assets\\.mixkit\\.co/[^"?#\\s]*?/${id}(?:-video)?-)\\d{3,4}\\.mp4$`)) || [])[1] || null;
  572. // the long side the page lists for a size (its 4K is 4096 wide), else 16:9 (it labels the 720p file 1080x720)
  573. const long = (p) => Math.max(...(res.find(([x, y]) => Math.min(x, y) === p && Math.max(x, y) >= Math.round((p * 16) / 9)) || [Math.round((p * 16) / 9)]));
  574. const renditions = base ? sizes.map((p) => ({ url: `${base}${p}.mp4`, type: 'video/mp4', w: portrait ? p : long(p), h: portrait ? long(p) : p })) : [];
  575. // the sentence beside the download button (its link's attributes hold a '>', so tags are read with their quotes)
  576. const line = text(((h.match(/<p[^>]*download-copy[^>]*>([\s\S]*?)<\/p>/) || [])[1] || '').replace(/<(?:[^>"']|"[^"]*"|'[^']*')*>/g, '')).replace(/^Free Download\s*/i, '');
  577. const seen = licence === 'unknown' ? null : { quote: short(line, 220) || [notice && `copyrightNotice "${notice}"`, link && `licence link /license/#${link}`].filter(Boolean).join(', '),
  578. url: page, date: new Date().toISOString().slice(0, 10) };
  579. return { licence, seen, duration: dur.length ? Number(dur[1]) * 60 + Number(dur[2]) : null, renditions, title: text((h.match(/<h1[^>]*>([\s\S]*?)<\/h1>/) || [])[1] || '') };
  580. }
  581. /** A phrase Mixkit's search holds no page for finds nothing: its words one at a time (at most three), ranked by how
  582. * many of the words a clip's title carries. */
  583. export async function mixkitWords(q, fetchList) {
  584. const words = queryWords(q); const seen = new Set(); const out = []; let err = null;
  585. for (const [k, w] of words.slice(0, 3).entries()) {
  586. if (k) await sleep(400); // gentle on a site without an API
  587. try { for (const it of await fetchList(w)) if (!seen.has(it.ref)) { seen.add(it.ref); out.push(it); } } catch (e) { err = e; }
  588. }
  589. if (!out.length && err) throw err;
  590. return out.map((it, k) => [wordHits(words, it.title), k, it]).sort((x, y) => y[0] - x[0] || x[1] - y[1]).map((x) => x[2]);
  591. }
  592. async function searchMixkit(q, o) {
  593. const list = async (w) => parseMixkitList(await getText(mixkitUrl(w)));
  594. let items = await list(q);
  595. if (!items.length && queryWords(q).length > 1) items = await mixkitWords(q, list);
  596. items = items.slice(0, o.limit + 4);
  597. await mapLimit(items, 2, async (it, k) => {
  598. await sleep(300 * (k % 2)); // gentle on a site without an API
  599. const html = await getText(it.page, { ms: 20000 }).catch(() => null);
  600. if (!html) return;
  601. const r = parseMixkitItem(html, it.ref.split(':')[1], { known: it.preview, page: it.page });
  602. const pick = pickRendition(r.renditions, o.res || 1080);
  603. Object.assign(it, { licence: r.licence, seen: r.seen, duration: r.duration, renditions: r.renditions, image: pick?.url || null, width: pick?.w || null, height: pick?.h || null,
  604. notes: pick ? [] : ['the page names no file of this clip'] });
  605. });
  606. return items;
  607. }
  608. // ---------- Burst (Shopify's free stock photos, read from its public pages: no API, no key)
  609. export const burstUrl = (q) => `https://burst.shopify.com/photos/search?${new URLSearchParams({ q })}`;
  610. /** A Burst CDN address at a width (the site's own download link serves the same file at its full size). */
  611. export const burstImage = (slug, width) => `https://burst.shopifycdn.com/photos/${slug}.jpg?width=${Math.round(width)}&format=pjpg&exif=0&iptc=0`;
  612. const attr = (tag, name) => { const m = tag.match(new RegExp(`\\s${name}="([^"]*)"`)); return m ? text(m[1]) : ''; };
  613. /** Burst's search grid to items (slug, title, preview); the licence is read from each photo's own page. */
  614. export function parseBurstList(html, o = {}) {
  615. const out = []; const seen = new Set();
  616. for (const tag of String(html).match(/<img\b[^>]*data-photo-id="[^"]*"[^>]*>/g) || []) {
  617. const src = attr(tag, 'src') || attr(tag, 'data-src');
  618. const slug = (src.match(/burst\.shopifycdn\.com\/photos\/([a-z0-9-]+)\.jpe?g/i) || [])[1];
  619. if (!slug || seen.has(slug)) continue; seen.add(slug);
  620. const alt = attr(tag, 'alt');
  621. out.push(item('burst', slug, { kind: o.kind || 'photo', title: attr(tag, 'data-photo-title') || alt || slug.replace(/-/g, ' '), page: `https://burst.shopify.com/photos/${slug}`,
  622. thumb: burstImage(slug, 500), image: burstImage(slug, o.width || 2400), licence: 'unknown', notes: ['licence not read yet'], tags: alt ? [alt] : [], burstId: attr(tag, 'data-photo-id') || null }));
  623. }
  624. return out;
  625. }
  626. /** A Burst photo page: its licence (the link the page names), photographer and title. */
  627. export function parseBurstItem(html) {
  628. const h = String(html);
  629. const lic = (h.match(/rel="[^"]*license[^"]*"\s+href="[^"]*\/licenses\/([a-z0-9-]+)"/i) || h.match(/href="[^"]*\/licenses\/([a-z0-9-]+)"/i) || [])[1] || '';
  630. let licence = 'unknown';
  631. if (lic === 'shopify-some-rights-reserved') licence = 'burst';
  632. else if (/cc0|creative-commons-zero|public-domain/.test(lic)) licence = 'cc0';
  633. const author = text((h.match(/Photo by\s*(?:<[^>]+>\s*)*<a[^>]*>([^<]+)<\/a>/i) || h.match(/href="\/stock-photos\/@[^"]+">([^<]+)<\/a>/) || [])[1] || '');
  634. const title = text((h.match(/<h1[^>]*>([\s\S]*?)<\/h1>/) || [])[1] || '').replace(/\s+Photo$/i, '');
  635. return { licence, licenceSlug: lic || null, author, title };
  636. }
  637. async function searchBurst(q, o) {
  638. const items = parseBurstList(await getText(burstUrl(q), { ms: 30000 }), o).slice(0, o.limit + 2);
  639. await mapLimit(items, 1, async (it, k) => {
  640. if (k) await sleep(400); // one page at a time: the site answers a quick run of reads with HTTP 429
  641. const html = await getText(it.page, { ms: 20000 }).catch(() => null);
  642. if (!html) { it.notes = ['the photo page did not load, so its licence was not read: search again in a minute']; return; }
  643. const r = parseBurstItem(html);
  644. Object.assign(it, { licence: r.licence, author: r.author || it.author, title: r.title || it.title, notes: r.licence === 'unknown' ? [`licence "${r.licenceSlug || 'none named'}" is not one the tool knows`] : [] });
  645. });
  646. return items;
  647. }
  648. // ---------- ISO Republic (CC0 photos, read from its public pages: no API, no key)
  649. export const isoUrl = (q) => `https://isorepublic.com/?${new URLSearchParams({ s: q })}`;
  650. /** A WordPress rendition address (name-WxH.jpg) to the original upload's. */
  651. export const isoOriginal = (u) => String(u).replace(/-\d+x\d+(\.(?:jpe?g|png|webp))$/i, '$1');
  652. /** ISO Republic's search grid to photo items (page, title, thumbnail); videos are left out. */
  653. export function parseIsoList(html, o = {}) {
  654. const out = []; const seen = new Set();
  655. const re = /<a href="(https:\/\/isorepublic\.com\/photo\/([a-z0-9-]+)\/)"[^>]*class="photo-grid-item"[\s\S]*?<\/a>/g;
  656. let m;
  657. while ((m = re.exec(String(html)))) {
  658. const [block, page, slug] = m;
  659. if (seen.has(slug)) continue; seen.add(slug);
  660. const thumb = (block.match(/data-src="([^"]+)"/) || block.match(/<img src="(https:[^"]+)"/) || [])[1] || null;
  661. const tw = Number((block.match(/data-eio-rwidth="(\d+)"/) || block.match(/\swidth="(\d+)"/) || [])[1]) || null;
  662. const th = Number((block.match(/data-eio-rheight="(\d+)"/) || block.match(/\sheight="(\d+)"/) || [])[1]) || null;
  663. const title = text((block.match(/itemprop="name">([^<]*)</) || [])[1] || (block.match(/title="([^"]*)"/) || [])[1] || slug.replace(/-/g, ' '));
  664. out.push(item('isorepublic', slug, { kind: o.kind || 'photo', title, page, thumb, image: thumb ? isoOriginal(thumb) : null, aspect: tw && th ? tw / th : null, licence: 'unknown', notes: ['licence not read yet'] }));
  665. }
  666. return out;
  667. }
  668. /** An ISO Republic photo page: the licence statement, the download link and the renditions (largest within `width`). */
  669. export function parseIsoItem(html, width = 2400) {
  670. const h = String(html);
  671. const cc0 = /isorepublic\.com\/license\/[^>]*>\s*CC0/i.test(h) || /CC0 Creative Commons/i.test(h);
  672. const download = (h.match(/<a href="(https:\/\/isorepublic\.com\/wp-content\/uploads\/[^"]+)"[^>]*btn-download/) || [])[1] || null;
  673. const rends = [...new Set(h.match(/https:\/\/isorepublic\.com\/wp-content\/uploads\/[^"' )]+?-\d+x\d+\.jpe?g/g) || [])]
  674. .filter((u) => !download || isoOriginal(u) === download)
  675. .map((u) => { const [, w, hh] = u.match(/-(\d+)x(\d+)\.jpe?g$/); return { url: u, w: Number(w), h: Number(hh) }; });
  676. const fit = rends.filter((r) => Math.max(r.w, r.h) <= width).sort((a, b) => b.w - a.w)[0] || null;
  677. const title = text((h.match(/<h1[^>]*>([\s\S]*?)<\/h1>/) || [])[1] || '').replace(/\s+(free\s+)?(stock\s+)?(photo|image|picture)$/i, '');
  678. return { licence: cc0 ? 'cc0' : 'unknown', download, rendition: fit, renditions: rends, title };
  679. }
  680. /**
  681. * The file to take from a parsed ISO Republic page: the largest rendition whose long side is within the width, when
  682. * that side is at least 1600 px (or the width); else the original upload (often 4000-6000 px and 5-10 MB).
  683. */
  684. export const isoPick = (r, width = 2400) => {
  685. const pick = r.rendition && Math.max(r.rendition.w, r.rendition.h) >= Math.min(1600, width) ? r.rendition : null;
  686. return { image: pick?.url || r.download || null, width: pick?.w ?? null, height: pick?.h ?? null };
  687. };
  688. async function searchIso(q, o) {
  689. const items = parseIsoList(await getText(isoUrl(q), { ms: 30000 }), o).slice(0, o.limit + 4);
  690. await mapLimit(items, 2, async (it, k) => {
  691. await sleep(250 * (k % 2));
  692. const html = await getText(it.page, { ms: 20000 }).catch(() => null);
  693. if (!html) return;
  694. const r = parseIsoItem(html, o.width);
  695. const p = isoPick(r, o.width);
  696. Object.assign(it, { licence: r.licence, title: r.title || it.title, image: p.image || it.image, width: p.width, height: p.height, original: r.download, notes: r.licence === 'cc0' ? [] : ['the page does not state CC0'] });
  697. });
  698. return items;
  699. }
  700. // ---------- Coverr (free stock video; its pages carry the clip records as JSON: no API key used)
  701. export const coverrUrl = (q) => `https://coverr.co/s?${new URLSearchParams({ q })}`;
  702. /**
  703. * The clip records in a Coverr page's embedded state (objects with a baseFilename and urls). search: only the
  704. * search's own hits (the state also carries the site's promoted and AI-app clips), else every record (a clip page).
  705. */
  706. export function coverrRecords(html, { search = false } = {}) {
  707. const m = String(html).match(/<script id="ng-state" type="application\/json">([\s\S]*?)<\/script>/);
  708. if (!m) return [];
  709. let j; try { j = JSON.parse(m[1]); } catch { return []; }
  710. if (search) j = j?.search_coverr_videos?.hits || Object.values(j || {}).filter((v) => /\/videos(\?|$)/.test(String(v?.u || '')));
  711. const out = []; const seen = new Set();
  712. const walk = (v, depth = 0) => {
  713. if (!v || typeof v !== 'object' || depth > 14) return;
  714. if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
  715. if (typeof v.baseFilename === 'string' && v.urls && typeof v.id === 'string') { if (!seen.has(v.id)) { seen.add(v.id); out.push(v); } return; }
  716. for (const k of Object.keys(v)) walk(v[k], depth + 1);
  717. };
  718. walk(j);
  719. return out;
  720. }
  721. /** A Coverr clip record to an item: free clips only (Coverr+ is refused), AI-generated clips flagged (search drops them). */
  722. export function parseCoverrRecord(r, o = {}) {
  723. const [aw, ah] = String(r.aspectRatio || '16:9').split(':').map(Number);
  724. const ratio = aw > 0 && ah > 0 ? aw / ah : 16 / 9;
  725. const variants = (r.defaultVariant?.renditions || []).filter((x) => x?.url && /\.mp4/.test(x.url));
  726. let renditions = variants.filter((x) => !x.isPlus && x.type !== 'original').map((x) => ({ url: noQuery(x.url), type: 'video/mp4', w: Number(x.width) || null, h: Number(x.height) || null, bytes: Number(x.size) || null }));
  727. if (!renditions.length && r.urls?.mp4) {
  728. const tall = Boolean(r.isVertical) || ratio < 1;
  729. const one = (url, side) => ({ url: noQuery(url), type: 'video/mp4', w: tall ? side : Math.round(side * ratio), h: tall ? Math.round(side / ratio) : side });
  730. renditions = [one(r.urls.mp4, 1080), ...(r.urls.mp4Preview ? [one(r.urls.mp4Preview, 360)] : [])];
  731. }
  732. const pick = pickRendition(renditions, o.res || 1080);
  733. if (!pick) return null;
  734. const ai = Boolean(r.isAiGenerated);
  735. return item('coverr', r.id, {
  736. kind: 'video', title: text(r.title) || String(r.baseFilename).replace(/^coverr-/, '').replace(/-\d+$/, '').replace(/-/g, ' '), page: r.slug ? `https://coverr.co/videos/${r.slug}` : null,
  737. thumb: r.thumbnail || r.poster || null, preview: r.urls?.mp4Preview ? noQuery(r.urls.mp4Preview) : null, image: pick.url, renditions, width: pick.w, height: pick.h, bytes: pick.bytes || null,
  738. duration: Number(r.duration) || null, fps: Number(r.fps) || null, licence: r.isPremium ? 'coverr-plus' : 'coverr', ai, tags: (r.searchKeywords || r.tags || []).slice(0, 12).map(String),
  739. description: text(r.description), notes: ai ? ['AI-generated, not real footage: refused'] : [],
  740. });
  741. }
  742. async function searchCoverr(q, o) {
  743. // Coverr's search is loose (a "pottery wheel" search returns steering wheels and yoga): keep hits whose own words
  744. // carry the query, the closest first
  745. const words = queryWords(q);
  746. return coverrRecords(await getText(coverrUrl(q), { ms: 45000 }), { search: true }).map((r) => parseCoverrRecord(r, o)).filter(Boolean)
  747. .map((it) => ({ it, n: wordHits(words, [it.title, it.description, ...it.tags].join(' ')) })).filter((x) => x.n > 0).sort((a, b) => b.n - a.n).map((x) => x.it);
  748. }
  749. // ---------- keyed sources (only with their key in the environment)
  750. export const pexelsUrl = (q, o) => (o.kind === 'video'
  751. ? `https://api.pexels.com/videos/search?${new URLSearchParams({ query: q, per_page: String(Math.min(40, o.limit * 2)), ...(o.orientation ? { orientation: o.orientation } : {}), size: 'large' })}`
  752. : `https://api.pexels.com/v1/search?${new URLSearchParams({ query: q, per_page: String(Math.min(40, o.limit * 2)), ...(o.orientation ? { orientation: o.orientation } : {}), ...(o.colour ? { color: o.colour.native } : {}), size: o.minWidth >= 1600 ? 'large' : 'medium' })}`);
  753. export function parsePexels(j, o = {}) {
  754. if (o.kind === 'video') {
  755. return (j?.videos || []).map((v) => {
  756. const files = (v.video_files || []).filter((f) => f.file_type === 'video/mp4').map((f) => ({ url: f.link, type: 'video/mp4', w: f.width, h: f.height, fps: f.fps }));
  757. const pick = pickRendition(files, o.res || 1080);
  758. return pick && item('pexels', v.id, { kind: 'video', title: slug(String(v.url || '').split('/').filter(Boolean).pop() || `pexels ${v.id}`).replace(/-\d+$/, '').replace(/-/g, ' '),
  759. author: v.user?.name || '', authorUrl: v.user?.url || null, page: v.url, thumb: v.image, image: pick.url, renditions: files, width: pick.w, height: pick.h, fps: pick.fps || null, duration: v.duration || null, licence: 'pexels' });
  760. }).filter(Boolean);
  761. }
  762. return (j?.photos || []).map((p) => {
  763. const w = o.width || 2400;
  764. const image = p.src?.original ? `${noQuery(p.src.original)}?auto=compress&cs=tinysrgb&w=${w}` : p.src?.large2x;
  765. return item('pexels', p.id, { kind: o.kind || 'photo', title: p.alt || `pexels ${p.id}`, author: p.photographer || '', authorUrl: p.photographer_url || null, page: p.url,
  766. thumb: p.src?.medium || p.src?.small, image, width: p.width, height: p.height, licence: 'pexels', colour: p.avg_color || null });
  767. });
  768. }
  769. async function searchPexels(q, o) { return parsePexels(await getJson(pexelsUrl(q, o), { headers: { Authorization: key('pexels') } }), o); }
  770. const UNSPLASH_COLOURS = ['black_and_white', 'black', 'white', 'yellow', 'orange', 'red', 'purple', 'magenta', 'green', 'teal', 'blue'];
  771. export const unsplashUrl = (q, o) => `https://api.unsplash.com/search/photos?${new URLSearchParams({ query: q, per_page: String(Math.min(30, o.limit * 2)), content_filter: 'high',
  772. ...(o.orientation ? { orientation: o.orientation === 'square' ? 'squarish' : o.orientation } : {}), ...(o.colour && UNSPLASH_COLOURS.includes(o.colour.unsplash) ? { color: o.colour.unsplash } : {}) })}`;
  773. export function parseUnsplash(j, o = {}) {
  774. return (j?.results || []).map((p) => item('unsplash', p.id, { kind: o.kind || 'photo', title: p.alt_description || p.description || `unsplash ${p.id}`, author: p.user?.name || '',
  775. authorUrl: p.user?.links?.html || null, page: p.links?.html || null, thumb: p.urls?.small || p.urls?.thumb, image: p.urls?.raw ? `${p.urls.raw}&w=${o.width || 2400}&q=85&fm=jpg&fit=max` : p.urls?.full,
  776. width: p.width, height: p.height, licence: 'unsplash', colour: p.color || null, downloadLocation: p.links?.download_location || null }));
  777. }
  778. async function searchUnsplash(q, o) { return parseUnsplash(await getJson(unsplashUrl(q, o), { headers: { Authorization: `Client-ID ${key('unsplash')}`, 'Accept-Version': 'v1' } }), o); }
  779. export const pixabayUrl = (q, o, k = '') => (o.kind === 'video'
  780. ? `https://pixabay.com/api/videos/?${new URLSearchParams({ key: k, q, per_page: String(Math.min(50, Math.max(3, o.limit * 2))), safesearch: 'true' })}`
  781. : `https://pixabay.com/api/?${new URLSearchParams({ key: k, q, image_type: 'photo', per_page: String(Math.min(50, Math.max(3, o.limit * 2))), safesearch: 'true', min_width: String(o.minWidth || 0),
  782. ...(o.orientation === 'landscape' ? { orientation: 'horizontal' } : o.orientation === 'portrait' ? { orientation: 'vertical' } : {}), ...(o.colour?.pixabay ? { colors: o.colour.pixabay } : {}) })}`);
  783. export function parsePixabay(j, o = {}) {
  784. if (o.kind === 'video') {
  785. return (j?.hits || []).map((h) => {
  786. const files = ['large', 'medium', 'small', 'tiny'].map((k) => h.videos?.[k]).filter((v) => v?.url).map((v) => ({ url: v.url, type: 'video/mp4', w: v.width, h: v.height, bytes: v.size }));
  787. const pick = pickRendition(files, o.res || 1080);
  788. return pick && item('pixabay', h.id, { kind: 'video', title: h.tags || `pixabay ${h.id}`, author: h.user || '', page: h.pageURL, thumb: h.videos?.medium?.thumbnail || h.videos?.small?.thumbnail || null,
  789. image: pick.url, renditions: files, width: pick.w, height: pick.h, bytes: pick.bytes || null, duration: h.duration || null, licence: 'pixabay' });
  790. }).filter(Boolean);
  791. }
  792. return (j?.hits || []).map((h) => item('pixabay', h.id, { kind: o.kind || 'photo', title: h.tags || `pixabay ${h.id}`, author: h.user || '', page: h.pageURL, thumb: h.webformatURL || h.previewURL,
  793. image: h.largeImageURL || h.webformatURL, width: h.imageWidth, height: h.imageHeight, licence: 'pixabay' }));
  794. }
  795. async function searchPixabay(q, o) { return parsePixabay(await getJson(pixabayUrl(q, o, key('pixabay'))), o); }
  796. const RUNNERS = { burst: searchBurst, isorepublic: searchIso, coverr: searchCoverr, openverse: searchOpenverse, commons: searchCommons, nasa: searchNasa, aic: searchAic, met: searchMet, mixkit: searchMixkit, pexels: searchPexels, unsplash: searchUnsplash, pixabay: searchPixabay };
  797. // ------------------------------------------------------------------------------------------------ colour
  798. const HUES = { red: 25, yellow: 100, green: 145, teal: 190, cyan: 200, blue: 250, pink: 355 };
  799. /** A --colour value to native filters and a target for thumbnail scoring. */
  800. export function colourOf(v) {
  801. if (!v) return null;
  802. const s = String(v).toLowerCase().trim();
  803. if (['mono', 'bw', 'black_and_white', 'grey', 'gray', 'greyscale', 'grayscale'].includes(s)) return { name: 'mono', mono: true, native: 'gray', unsplash: 'black_and_white', pixabay: 'grayscale' };
  804. if (/^#?[0-9a-f]{6}$/.test(s)) { const hex = s.startsWith('#') ? s : `#${s}`; const [, C, h] = hexToOklch(hex); return { name: hex, hue: h, chroma: C, native: hex.slice(1), unsplash: nearestNamed(h), pixabay: nearestPixabay(h) }; }
  805. if (HUES[s] !== undefined) return { name: s, hue: HUES[s], native: s, unsplash: s === 'cyan' ? 'teal' : s, pixabay: s === 'teal' || s === 'cyan' ? 'turquoise' : s };
  806. throw new Error(`--colour ${v}: use mono, red, yellow, green, teal, cyan, blue, pink or a #hex`);
  807. }
  808. const nearestNamed = (h) => Object.entries({ red: 25, yellow: 100, green: 145, teal: 190, blue: 250 }).sort((a, b) => hueDist(a[1], h) - hueDist(b[1], h))[0][0];
  809. const nearestPixabay = (h) => ({ red: 'red', yellow: 'yellow', green: 'green', teal: 'turquoise', blue: 'blue' })[nearestNamed(h)];
  810. const hueDist = (a, b) => { const d = Math.abs(a - b) % 360; return d > 180 ? 360 - d : d; };
  811. /** Share of an RGB pixel grid that carries the colour (or reads as mono). */
  812. export function colourScore(rgb, target) {
  813. let hit = 0; let n = 0;
  814. for (let i = 0; i + 2 < rgb.length; i += 3) {
  815. const [, C, h] = rgbToOklch(rgb[i], rgb[i + 1], rgb[i + 2]); n++;
  816. if (target.mono ? C < 0.035 : C >= 0.04 && hueDist(h, target.hue) <= 35) hit++;
  817. }
  818. return n ? hit / n : 0;
  819. }
  820. // sRGB <-> OKLab / OKLCH (for grades and colour scoring)
  821. const toLin = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
  822. const toGam = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
  823. export function rgbToOklab(r, g, b) {
  824. const R = toLin(r); const G = toLin(g); const B = toLin(b);
  825. const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
  826. const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
  827. const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
  828. return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
  829. }
  830. export function rgbToOklch(r, g, b) { const [L, a, bb] = rgbToOklab(r, g, b); return [L, Math.hypot(a, bb), ((Math.atan2(bb, a) * 180) / Math.PI + 360) % 360]; }
  831. export function oklabToRgb(L, a, b) {
  832. const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3; const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3; const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
  833. const R = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s; const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s; const B = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
  834. return [R, G, B].map((c) => toGam(c));
  835. }
  836. /** OKLCH to sRGB 0..1, chroma reduced until it fits the gamut. */
  837. export function oklchToRgb(L, C, h) {
  838. for (let c = C; c >= 0; c -= 0.002) {
  839. const rgb = oklabToRgb(L, c * Math.cos((h * Math.PI) / 180), c * Math.sin((h * Math.PI) / 180));
  840. if (rgb.every((v) => v >= -0.0005 && v <= 1.0005)) return rgb.map((v) => Math.min(1, Math.max(0, v)));
  841. }
  842. return oklabToRgb(L, 0, 0).map((v) => Math.min(1, Math.max(0, v)));
  843. }
  844. export function hexToOklch(hex) { const n = parseInt(String(hex).replace('#', ''), 16); return rgbToOklch((n >> 16) & 255, (n >> 8) & 255, n & 255); }
  845. export const rgbHex = (rgb) => `#${rgb.map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('')}`;
  846. // ------------------------------------------------------------------------------------------------ search
  847. export function parseArgs(argv) {
  848. const VALUED = new Set(['kind', 'source', 'orientation', 'min-width', 'colour', 'color', 'limit', 'out', 'pick', 'cols', 'cell', 'to', 'from', 'name', 'width', 'res', 'trim', 'max-mb',
  849. 'record', 'look', 'accent', 'split-hue', 'focus', 'aspect', 'grain', 'speed', 'fps', 'suffix', 'strength', 'chroma', 'scan', 'fit']);
  850. const FLAGS = new Set(['allow-credit', 'json', 'no-check', 'dry-run', 'help', 'force', 'keep', 'scrub', 'brand-supplied', 'arc', 'no-text', 'people', 'no-people', 'clean', 'no-vet', 'run', 'verify']);
  851. const args = { _: [] };
  852. for (let i = 0; i < argv.length; i++) {
  853. const a = argv[i];
  854. if (a === '-h') { args.help = true; continue; }
  855. if (!a.startsWith('--')) { args._.push(a); continue; }
  856. const eq = a.indexOf('=');
  857. const k = a.slice(2, eq === -1 ? undefined : eq);
  858. if (VALUED.has(k)) {
  859. const v = eq === -1 ? argv[++i] : a.slice(eq + 1);
  860. if (v === undefined || v === '' || (eq === -1 && v.startsWith('--'))) throw new Usage(`--${k} needs a value`);
  861. args[k === 'color' ? 'colour' : k] = v;
  862. } else if (FLAGS.has(k)) args[k] = true;
  863. else throw new Usage(`unknown option --${k}`);
  864. }
  865. return args;
  866. }
  867. export class Usage extends Error {}
  868. const num = (args, k, def, lo, hi) => {
  869. if (args[k] === undefined) return def;
  870. const n = Number(args[k]);
  871. if (!Number.isFinite(n) || n < lo || n > hi) throw new Usage(`--${k} must be a number from ${lo} to ${hi}`);
  872. return n;
  873. };
  874. /**
  875. * Search options from the arguments (kind, sources, filters). A named source without a search for the kind is
  876. * skipped with a note in `skipped` (--kind art --source met,aic,commons searches the museums); only when no named
  877. * source is left is it a usage error.
  878. */
  879. export function searchOptions(args, env = process.env) {
  880. const kind = String(args.kind || 'photo').toLowerCase();
  881. if (!['photo', 'video', 'texture', 'art'].includes(kind)) throw new Usage('--kind is photo, video, texture or art');
  882. const orientation = args.orientation ? ({ landscape: 'landscape', wide: 'landscape', portrait: 'portrait', tall: 'portrait', square: 'square' }[String(args.orientation).toLowerCase()]) : null;
  883. if (args.orientation && !orientation) throw new Usage('--orientation is landscape, portrait or square');
  884. const usable = Object.keys(SOURCES).filter((s) => SOURCES[s].kinds.includes(kind) && (!SOURCES[s].env || Boolean(env[SOURCES[s].env])));
  885. let sources = usable; const skipped = [];
  886. if (args.source && args.source !== 'all') {
  887. const named = String(args.source).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
  888. for (const s of named) if (!SOURCES[s]) throw new Usage(`unknown source ${s}: ${Object.keys(SOURCES).join(', ')}`);
  889. sources = named.filter((s) => SOURCES[s].kinds.includes(kind));
  890. for (const s of named) if (!sources.includes(s)) skipped.push(`${SOURCES[s].name} has no ${kind} search (it serves ${SOURCES[s].kinds.join(', ')})`);
  891. if (!sources.length) throw new Usage(skipped.join('; '));
  892. for (const s of sources) if (SOURCES[s].env && !env[SOURCES[s].env]) throw new Usage(`${SOURCES[s].name} needs ${SOURCES[s].env} in the environment`);
  893. }
  894. return { kind, sources, skipped, orientation, minWidth: num(args, 'min-width', kind === 'video' ? 1280 : 1600, 0, 20000), limit: Math.round(num(args, 'limit', 8, 1, 30)),
  895. width: Math.round(num(args, 'width', 2400, 400, 4000)), res: Math.round(num(args, 'res', 1080, 240, 2160)), allowCredit: Boolean(args['allow-credit']),
  896. colour: colourOf(args.colour), check: !args['no-check'], ...vetOptions(args) };
  897. }
  898. /**
  899. * The vet's options from the arguments: people (true keep only pictures with people, false drop them, null either),
  900. * clean (drop text, signs, logos, watermarks), fit (a w/h a crop must keep at --min-width px), vet (read thumbnails).
  901. */
  902. export function vetOptions(args) {
  903. if (args.people && args['no-people']) throw new Usage('--people and --no-people: choose one');
  904. let fit = null;
  905. if (args.fit !== undefined) {
  906. const [a, b] = String(args.fit).split(/[:/x]/).map(Number);
  907. if (!(a > 0 && b > 0)) throw new Usage('--fit is w:h (4:5, 16:9, 1:1): the shape the picture is cropped to');
  908. fit = a / b;
  909. }
  910. return { people: args.people ? true : args['no-people'] ? false : null, clean: Boolean(args.clean), fit, vet: !args['no-vet'] };
  911. }
  912. /** Words in a record that say people are in the picture (its title, description and tags). */
  913. export const PEOPLE_WORDS = /\b(person|people|persons|man|men|woman|women|girl|girls|boy|boys|child|children|kid|kids|baby|portrait|selfie|face|faces|model|couple|family|friends|team|crowd|businessman|businesswoman|student|students|worker|workers|chef|barista|athlete|dancer|doctor|nurse|teacher|hands?|smiling|smile|lady|guy|teen|teenager|mother|father)\b/i;
  914. /** Words that say a picture carries text, a sign, a logo or a watermark. */
  915. export const TEXT_WORDS = /\b(text|sign|signs|signage|logo|logos|watermark|typography|lettering|letters|quote|poster|billboard|label|menu|neon sign|headline|newspaper|screen ?shot)\b/i;
  916. const recordWords = (it) => [it.title, it.description, ...(it.tags || [])].filter(Boolean).join(' ');
  917. export const peopleWords = (it) => PEOPLE_WORDS.test(recordWords(it));
  918. export const textWords = (it) => TEXT_WORDS.test(recordWords(it));
  919. /** The width a picture keeps after a crop to the shape `fit` (w/h). Pure. */
  920. export const fitWidth = (w, h, fit) => Math.min(w, h * fit);
  921. /** A texture search asks for the surface itself. */
  922. export const searchQuery = (q, kind) => (kind === 'texture' && !/\b(texture|macro|surface|pattern|close[- ]?up|detail)\b/i.test(q) ? `${q} texture` : q);
  923. /** Keep what a film may use: licence, size, shape; one picture per near-duplicate title. Returns { keep, skipped }. */
  924. export function filterItems(items, o) {
  925. const skipped = { licence: 0, small: 0, shape: 0, alike: 0, ai: 0, fit: 0, reasons: {} };
  926. const titles = new Map(); const seen = new Set();
  927. const keep = items.filter((it) => {
  928. const lic = licenceAllowed(it.licence, o);
  929. if (!lic.ok) { skipped.licence++; const r = `${LICENCES[it.licence]?.name || it.licence}: ${lic.why}`; skipped.reasons[r] = (skipped.reasons[r] || 0) + 1; return false; }
  930. const k = String(it.image || it.ref).toLowerCase().split('?')[0];
  931. if (seen.has(k)) return false; seen.add(k);
  932. if (it.ai) { skipped.ai++; return false; } // generated, not photographed or filmed
  933. if (it.width && it.width < o.minWidth) { skipped.small++; return false; }
  934. if (o.fit && it.width && it.height && fitWidth(it.width, it.height, o.fit) < o.minWidth) { skipped.fit++; return false; }
  935. if (o.orientation && it.width && it.height && shapeOf(it.width, it.height) !== o.orientation) { skipped.shape++; return false; }
  936. const t = String(it.title).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().slice(0, 32);
  937. const n = (titles.get(t) || 0) + 1; titles.set(t, n);
  938. if (t && n > 2) { skipped.alike++; return false; }
  939. return true;
  940. });
  941. return { keep, skipped };
  942. }
  943. /** Interleave the sources (one from each in turn) so a sheet shows the range, and number them from 1. */
  944. export function interleave(groups, limit) {
  945. const lists = groups.map((g) => g.slice(0, limit)); const out = [];
  946. for (let i = 0; lists.some((l) => i < l.length); i++) for (const l of lists) if (i < l.length) out.push(l[i]);
  947. return out.map((it, k) => ({ n: k + 1, ...it }));
  948. }
  949. /** What to do when a search shows nothing, from what happened: no source answered, everything found was dropped, or
  950. * nothing matched. */
  951. export function emptyHint(o, report) {
  952. const rs = o.sources.map((s) => [s, report[s] || { found: 0, skipped: {} }]);
  953. const errs = rs.filter(([, r]) => r.error).map(([s, r]) => `${SOURCES[s]?.name || s}: ${r.error}`);
  954. if (errs.length && errs.length === rs.length) return `Nothing usable: no source answered (${errs.join('; ')}). Wait a minute and search again, or name another --source.`;
  955. if (rs.some(([, r]) => r.found)) {
  956. const sk = {}; for (const [, r] of rs) for (const [k, v] of Object.entries(r.skipped || {})) if (typeof v === 'number') sk[k] = (sk[k] || 0) + v;
  957. const tips = [(sk.small || sk.fit) && 'a smaller --min-width', sk.fit && 'another --fit', sk.shape && 'no --orientation',
  958. (sk.people || sk.text) && 'no --people, --no-people or --clean', sk.dead && 'searching again later (files did not load)',
  959. (sk.licence || sk.alike || sk.ai) && 'another --source or other words'].filter(Boolean);
  960. return `Nothing usable: everything found was dropped (the counts above say why). Try ${tips.join(', ') || 'other words'}.`;
  961. }
  962. return `Nothing found${errs.length ? ` (${errs.join('; ')})` : ''}. Name the subject's own things ("basalt", "tide pool", "kiln"), use fewer words, or another --kind.`;
  963. }
  964. /**
  965. * One search, gathered: every source of `o` asked at once, each answer filtered (licence, size, shape), the stills'
  966. * files checked, the thumbnails vetted into <out>.thumbs and, with a colour, ranked by it. Returns { q, groups, report,
  967. * vetNote }: one list per source, in the source's order, and what was dropped and why.
  968. */
  969. async function gatherSearch(query, o, out) {
  970. const q = searchQuery(query, o.kind);
  971. const cap = (ms, msg) => new Promise((_, rej) => setTimeout(() => rej(new Error(msg)), ms).unref());
  972. const results = await Promise.all(o.sources.map(async (s) => {
  973. try { return { s, items: await Promise.race([RUNNERS[s](q, o), cap(60000, 'no complete answer within 60 s')]) }; }
  974. catch (e) { return { s, items: [], error: redact(e.message) }; }
  975. }));
  976. const groups = []; const report = {};
  977. for (const r of results) {
  978. const { keep, skipped } = filterItems(r.items, o);
  979. report[r.s] = { found: r.items.length, kept: keep.length, skipped, error: r.error || null };
  980. groups.push(keep.slice(0, o.limit + 3));
  981. }
  982. if (o.check) {
  983. await Promise.race([mapLimit(groups.flat().filter((it) => it.kind !== 'video' && (!it.width || ['nasa', 'openverse', 'aic'].includes(it.source))), 6, async (it) => {
  984. if (it.source === 'aic') { await aicServe(it, o.width); return; } // the width AIC really serves (it redirects others to 843 px)
  985. const p = await probeUrl(it.image, 12000); it.checked = p.ok ? 'ok' : p.why;
  986. if (p.ok && p.w) { it.width = p.w; it.height = p.h; }
  987. if (p.ok && p.bytes) it.bytes = p.bytes;
  988. }), sleep(40000)]);
  989. for (const g of groups) for (let i = g.length - 1; i >= 0; i--) {
  990. const it = g[i];
  991. if (it.checked && it.checked !== 'ok') { report[it.source].skipped.dead = (report[it.source].skipped.dead || 0) + 1; g.splice(i, 1); }
  992. else if (it.width && it.width < o.minWidth) { report[it.source].skipped.small++; g.splice(i, 1); }
  993. }
  994. }
  995. fs.mkdirSync(path.dirname(out), { recursive: true });
  996. const vetNote = await vetGroups(groups, report, o, `${out.replace(/\.json$/i, '')}.thumbs`);
  997. if (o.colour && ffmpegOk()) {
  998. const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cinetic-assets-'));
  999. await mapLimit(groups.flat().filter((it) => it.thumb), 6, async (it) => { const f = await fetchThumb(it, tmp); if (f) it.colourScore = Number(colourScore(pixelGrid(f, 24), o.colour).toFixed(3)); });
  1000. fs.rmSync(tmp, { recursive: true, force: true });
  1001. for (const g of groups) g.sort((a, b) => (b.colourScore ?? 0) - (a.colourScore ?? 0));
  1002. }
  1003. return { q, groups, report, vetNote };
  1004. }
  1005. /** What each source of a search showed and dropped, one line each. */
  1006. function printReport(o, report, items) {
  1007. for (const s of o.sources) {
  1008. const r = report[s]; const sk = r.skipped;
  1009. const dropped = [sk.licence && `${sk.licence} licence`, sk.ai && `${sk.ai} AI-generated`, sk.small && `${sk.small} too small`, sk.fit && `${sk.fit} too small at the --fit shape`, sk.shape && `${sk.shape} other shape`, sk.alike && `${sk.alike} alike`, sk.dead && `${sk.dead} did not load`, sk.people && `${sk.people} ${o.people ? 'without' : 'with'} people`, sk.text && `${sk.text} with text or a logo`].filter(Boolean);
  1010. console.log(` ${SOURCES[s].name.padEnd(32)} ${r.error ? `could not search (${r.error})` : `${items.filter((it) => it.source === s).length} shown of ${r.found}${dropped.length ? ` (dropped: ${dropped.join(', ')})` : ''}`}`);
  1011. }
  1012. }
  1013. /** The numbered list of a results file's items (ref, size, length, licence, title, flags, notes). */
  1014. function printItems(items) {
  1015. const noteCount = {}; for (const it of items) for (const n of it.notes || []) noteCount[n] = (noteCount[n] || 0) + 1;
  1016. const shared = Object.keys(noteCount).filter((n) => noteCount[n] > 2);
  1017. for (const it of items) {
  1018. const px = it.width && it.height ? `${it.width}x${it.height}` : 'size ?';
  1019. const extra = it.kind === 'video' ? ` ${it.duration ? `${Math.round(it.duration)}s` : ''}` : '';
  1020. const flags = [it.people && (it.faces ? `${it.faces} face${it.faces > 1 ? 's' : ''}` : 'people'), it.textLines && 'text?', it.soft && 'soft'].filter(Boolean).join(', ');
  1021. console.log(`#${String(it.n).padEnd(3)} ${it.ref.padEnd(Math.min(48, Math.max(...items.map((x) => x.ref.length))))} ${px.padEnd(10)}${extra.padEnd(5)} ${(it.licence).padEnd(13)} ${short(it.title, 60)}${it.colourScore !== undefined ? ` [colour ${it.colourScore}]` : ''}${flags ? ` [${flags}]` : ''}`);
  1022. if (it.author && ['pexels', 'unsplash', 'pixabay', 'burst'].includes(it.source)) console.log(` by ${short(it.author, 50)} on ${SOURCES[it.source].name}`);
  1023. if (it.shows) console.log(` shows: ${it.shows}`);
  1024. for (const n of it.notes || []) if (!shared.includes(n)) console.log(` note: ${n}`);
  1025. }
  1026. for (const n of shared) console.log(`note (${noteCount[n]} items): ${n}`);
  1027. }
  1028. async function cmdSearch(args) {
  1029. const query = args._.join(' ').trim();
  1030. if (!query) throw new Usage('search needs a query, e.g. search "basalt cliff"');
  1031. const o = searchOptions(args);
  1032. for (const n of o.skipped) console.error(`note: ${n}; skipped, searching ${o.sources.map((s) => SOURCES[s].name).join(', ')}`);
  1033. const out = path.resolve(args.out || path.join('out', 'assets', `${slug(query, 5) || 'search'}-${o.kind}.json`));
  1034. const { q, groups, report, vetNote } = await gatherSearch(query, o, out);
  1035. const items = interleave(groups, o.limit);
  1036. const doc = { query, searched: q, kind: o.kind, created: new Date().toISOString(), options: { sources: o.sources, orientation: o.orientation, minWidth: o.minWidth, limit: o.limit, allowCredit: o.allowCredit, colour: o.colour?.name || null, people: o.people, clean: o.clean, fit: o.fit, vet: o.vet }, report, items };
  1037. fs.writeFileSync(out, JSON.stringify(doc, null, 1));
  1038. try { fs.writeFileSync(path.join(path.dirname(out), '.last'), out); } catch { /* optional */ }
  1039. if (args.json) { console.log(JSON.stringify(doc, null, 1)); return items.length ? 0 : 1; }
  1040. console.log(`ASSETS · ${o.kind} · "${q}" · ${o.allowCredit ? 'no-credit licences + CC BY' : 'licences that need no credit'} · at least ${o.minWidth}px${o.orientation ? ` · ${o.orientation}` : ''}${o.fit ? ` · fits ${args.fit}` : ''}${o.colour ? ` · colour ${o.colour.name}` : ''}${o.people === true ? ' · people' : o.people === false ? ' · no people' : ''}${o.clean ? ' · clean' : ''}`);
  1041. if (vetNote) console.log(` (${vetNote})`);
  1042. printReport(o, report, items);
  1043. const keyed = Object.keys(SOURCES).filter((s) => SOURCES[s].env && SOURCES[s].kinds.includes(o.kind) && !hasKey(s));
  1044. if (keyed.length) console.log(` (more with a key: ${keyed.map((s) => SOURCES[s].env).join(', ')})`);
  1045. console.log('');
  1046. printItems(items);
  1047. console.log('');
  1048. console.log(`Saved ${path.relative(process.cwd(), out) || out}`);
  1049. if (!items.length) { console.log(emptyHint(o, report)); return 1; }
  1050. console.log(`Next. Look before you choose: node scripts/assets.mjs sheet ${path.relative(process.cwd(), out) || out}`);
  1051. console.log(`Then: node scripts/assets.mjs get ${items.slice(0, 2).map((it) => `#${it.n}`).join(',')} --to public/assets (the numbers you chose; the private licence record goes to assets/licences.json)`);
  1052. return 0;
  1053. }
  1054. // ------------------------------------------------------------------------------------------------ vet
  1055. /** The project's Python as a command list (py.mjs --which: PYTHON, then python3, python, py -3), or null. */
  1056. export function pythonCmd() {
  1057. const pyjs = path.join(path.dirname(fileURLToPath(import.meta.url)), 'py.mjs');
  1058. if (!fs.existsSync(pyjs)) return null;
  1059. const py = spawnSync(process.execPath, [pyjs, '--which'], { encoding: 'utf8' });
  1060. const which = (py.stdout || '').trim();
  1061. if (py.status !== 0 || !which) return null;
  1062. return fs.existsSync(which) ? [which] : which.split(/\s+/).filter(Boolean); // a path with spaces, or "py -3"
  1063. }
  1064. /** The thumbnail reader: per file { faces, face, lines, lap } (frontal faces where OpenCV has a face model, like.py's text lines, Laplacian variance at 480 px). */
  1065. const VET_PY = [
  1066. 'import sys, json, os, importlib.util',
  1067. 'import cv2',
  1068. "spec = importlib.util.spec_from_file_location('like_mod', sys.argv[1]); m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m); m.need()",
  1069. "casc = None",
  1070. "d = getattr(getattr(cv2, 'data', None), 'haarcascades', '') or ''",
  1071. "p = os.path.join(d, 'haarcascade_frontalface_default.xml')",
  1072. "if d and os.path.exists(p): casc = cv2.CascadeClassifier(p)",
  1073. 'out = []',
  1074. 'for f in sys.argv[2:]:',
  1075. ' im = cv2.imread(f)',
  1076. ' if im is None:',
  1077. ' out.append(None); continue',
  1078. ' h, w = im.shape[:2]; s = 480.0 / max(1, w)',
  1079. ' im = cv2.resize(im, (480, max(2, int(round(h * s)))), interpolation=cv2.INTER_AREA)',
  1080. ' g = cv2.cvtColor(im, cv2.COLOR_BGR2GRAY)',
  1081. ' faces = None; face = 0.0',
  1082. ' if casc is not None:',
  1083. ' r = casc.detectMultiScale(g, 1.1, 5, minSize=(22, 22))',
  1084. ' faces = int(len(r)); face = float(max([a[2] * a[3] for a in r] or [0])) / float(g.shape[0] * g.shape[1])',
  1085. " out.append({'faces': faces, 'face': round(face, 4), 'lines': m.text_regions(g), 'lap': round(float(cv2.Laplacian(g, cv2.CV_64F).var()), 1)})",
  1086. 'print(json.dumps(out))',
  1087. ].join('\n');
  1088. /** Read thumbnails with the Python reader: [{ faces, face, lines, lap } | null] in order, or null when it cannot run. */
  1089. export function vetFiles(files) {
  1090. const like = path.join(path.dirname(fileURLToPath(import.meta.url)), 'like.py');
  1091. const cmd = pythonCmd();
  1092. if (!cmd || !fs.existsSync(like) || !files.length) return null;
  1093. const r = spawnSync(cmd[0], [...cmd.slice(1), '-c', VET_PY, like, ...files], { encoding: 'utf8', maxBuffer: 16 << 20 });
  1094. if (r.status !== 0) return null;
  1095. try { return JSON.parse(r.stdout.trim().split('\n').pop()); } catch { return null; }
  1096. }
  1097. /** Under this Laplacian variance (480 px thumbnail) a picture reads soft: shown last and marked on the sheet. */
  1098. export const VET = { soft: 45 };
  1099. /**
  1100. * One item's vet from its record and its thumbnail read (or null): people (words, or a frontal face), faces,
  1101. * textLines (steady text-like lines, or text words in the record), soft. Pure.
  1102. */
  1103. export function vetItem(it, read) {
  1104. const lines = read ? steadyText([read.lines || []]).length : 0;
  1105. return { people: peopleWords(it) || Boolean(read?.faces), faces: read?.faces ?? null, textLines: lines + (textWords(it) ? 1 : 0), soft: read ? read.lap < VET.soft : false, detail: read?.lap ?? null };
  1106. }
  1107. /** Keep an item under the vet options? (people true/false/null, clean). Pure. */
  1108. export const vetKeeps = (v, o) => !((o.people === true && !v.people) || (o.people === false && v.people) || (o.clean && v.textLines > 0));
  1109. /**
  1110. * The vet stage of a search: thumbnails into `cache` (the sheet reuses them), the Python reader when it can run,
  1111. * the people / clean filters, soft pictures last in each source. Returns a note for the summary line, or ''.
  1112. */
  1113. async function vetGroups(groups, report, o, cache) {
  1114. const want = o.vet || o.people !== null || o.clean;
  1115. if (!want) return '';
  1116. const all = groups.flat();
  1117. let reads = null; let note = '';
  1118. if (o.vet && all.length) {
  1119. fs.mkdirSync(cache, { recursive: true });
  1120. const files = await mapLimit(all, 6, (it) => fetchThumb(it, cache));
  1121. const have = files.map((f, i) => (f ? i : -1)).filter((i) => i >= 0);
  1122. const res = vetFiles(have.map((i) => files[i]));
  1123. if (res) { reads = new Array(all.length).fill(null); have.forEach((i, k) => { reads[i] = res[k]; }); }
  1124. else note = 'thumbnails not read: the project\'s Python needs numpy and opencv-python (pip install -r scripts/requirements.txt, then node scripts/py.mjs --check); people and text are judged from the records\' words';
  1125. if (res && !res.some((r) => r && r.faces !== null)) note = 'faces: this OpenCV has no face model, so people are judged from the records\' words; look at the sheet';
  1126. }
  1127. const at = new Map(all.map((it, i) => [it, reads?.[i] ?? null]));
  1128. for (const g of groups) {
  1129. for (let i = g.length - 1; i >= 0; i--) {
  1130. const it = g[i]; const v = vetItem(it, at.get(it));
  1131. Object.assign(it, v);
  1132. if (!vetKeeps(v, o)) {
  1133. const sk = report[it.source].skipped;
  1134. if (o.clean && v.textLines > 0) sk.text = (sk.text || 0) + 1; else sk.people = (sk.people || 0) + 1;
  1135. g.splice(i, 1);
  1136. }
  1137. }
  1138. g.sort((a, b) => Number(a.soft) - Number(b.soft)); // stable: soft pictures sink, the order is otherwise the source's
  1139. }
  1140. return note;
  1141. }
  1142. // ------------------------------------------------------------------------------------------------ sheet
  1143. /**
  1144. * Contact-sheet geometry: n cells of cellW x round(cellW / aspect) in `cols` columns, a label strip under
  1145. * each, a gutter around everything. Pure (tested).
  1146. */
  1147. export function sheetLayout(n, { cols = 4, cellW = 400, aspect = 16 / 9, gutter = 12, label = 30 } = {}) {
  1148. const c = Math.max(1, Math.min(cols, n || 1));
  1149. const rows = Math.max(1, Math.ceil((n || 0) / c));
  1150. const cellH = Math.round(cellW / aspect);
  1151. const W = gutter + c * (cellW + gutter); const H = gutter + rows * (cellH + label + gutter);
  1152. const cells = Array.from({ length: n }, (_, i) => ({ i, col: i % c, row: Math.floor(i / c), x: gutter + (i % c) * (cellW + gutter), y: gutter + Math.floor(i / c) * (cellH + label + gutter), w: cellW, h: cellH, labelY: gutter + Math.floor(i / c) * (cellH + label + gutter) + cellH + 6 }));
  1153. return { cols: c, rows, cellW, cellH, W: W + (W % 2), H: H + (H % 2), cells };
  1154. }
  1155. const FONTS = ['C:/Windows/Fonts/arial.ttf', 'C:/Windows/Fonts/segoeui.ttf', '/System/Library/Fonts/Supplemental/Arial.ttf', '/Library/Fonts/Arial.ttf', '/System/Library/Fonts/Helvetica.ttc',
  1156. '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', '/usr/share/fonts/dejavu/DejaVuSans.ttf', '/usr/share/fonts/TTF/DejaVuSans.ttf'];
  1157. const labelFont = () => FONTS.find((f) => { try { return fs.statSync(f).isFile(); } catch { return false; } }) || null;
  1158. const ffEsc = (s) => String(s).replace(/\\/g, '/').replace(/:/g, '\\:').replace(/'/g, '');
  1159. const labelText = (s, max = 52) => String(s).replace(/[^A-Za-z0-9 #.x/+-]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
  1160. let FF = null;
  1161. export function ffmpegOk() { if (FF === null) FF = spawnSync('ffmpeg', ['-hide_banner', '-version'], { encoding: 'utf8' }).status === 0; return FF; }
  1162. function ff(argv, what) {
  1163. const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', ...argv], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
  1164. if (r.status !== 0) throw new Error(`${what}: ffmpeg failed (${short((r.stderr || '').trim().split('\n').pop(), 200)})`);
  1165. return r;
  1166. }
  1167. /** N times spread across a clip of `dur` seconds (0.3 s margins; one frame = the middle, at most 1 s in). Pure. */
  1168. export const scanTimes = (dur, n) => {
  1169. if (n <= 1) return [Math.min(1, dur / 2)];
  1170. const a = Math.min(0.3, dur / 4);
  1171. const b = Math.max(a, dur - a);
  1172. return Array.from({ length: n }, (_, i) => a + ((b - a) * i) / (n - 1));
  1173. };
  1174. /** Mean colours of a w x w grid of an image (via ffmpeg), as a flat RGB byte array. */
  1175. export function pixelGrid(file, w = 24) {
  1176. const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-i', file, '-vf', `scale=${w}:${w}:flags=area`, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'], { maxBuffer: 1 << 20 });
  1177. return r.status === 0 ? r.stdout : Buffer.alloc(0);
  1178. }
  1179. async function fetchThumb(it, dir) {
  1180. const url = it.thumb || it.image; if (!url) return null;
  1181. const file = path.join(dir, `${slug(it.ref.replace(':', '-'), 12) || 'x'}.img`);
  1182. if (fs.existsSync(file)) return file;
  1183. try {
  1184. const r = await fetch(url, { headers: imageHeaders(url), signal: AbortSignal.timeout(30000) });
  1185. if (!r.ok) return null;
  1186. const b = Buffer.from(await r.arrayBuffer());
  1187. if (!sniff(b) || sniff(b).media !== 'image') return null;
  1188. fs.writeFileSync(file, b); return file;
  1189. } catch { return null; }
  1190. }
  1191. function listLocal(paths) {
  1192. const out = [];
  1193. for (const p of paths) {
  1194. const st = fs.existsSync(p) ? fs.statSync(p) : null;
  1195. if (!st) throw new Usage(`no such file or folder: ${p}`);
  1196. if (st.isDirectory()) for (const f of fs.readdirSync(p).sort()) { if (/\.(jpe?g|png|webp|avif|mp4|webm|mov)$/i.test(f)) out.push(path.join(p, f)); }
  1197. else out.push(p);
  1198. }
  1199. return out;
  1200. }
  1201. async function cmdSheet(args) {
  1202. if (!ffmpegOk()) throw new Error('sheet needs ffmpeg on the PATH');
  1203. if (!args._.length) throw new Usage('sheet needs a results file from search, or image/video files or folders');
  1204. const fromResults = args._.length === 1 && /\.json$/i.test(args._[0]);
  1205. let cells = []; let out;
  1206. const cellW = Math.round(num(args, 'cell', 400, 120, 960));
  1207. if (fromResults) {
  1208. const doc = JSON.parse(fs.readFileSync(args._[0], 'utf8'));
  1209. let items = doc.items || [];
  1210. if (args.pick) { const want = new Set(String(args.pick).split(',').map((s) => Number(s.replace('#', '')))); items = items.filter((it) => want.has(it.n)); }
  1211. if (!items.length) throw new Usage('nothing to show (an empty search, or --pick matched none)');
  1212. const cache = `${args._[0].replace(/\.json$/i, '')}.thumbs`; fs.mkdirSync(cache, { recursive: true });
  1213. const files = await mapLimit(items, 6, (it) => fetchThumb(it, cache));
  1214. const scan = Math.round(num(args, 'scan', 1, 1, 8));
  1215. const label = (it) => `#${it.n} ${it.source} ${it.width ? `${it.width}x${it.height}` : ''} ${it.kind === 'video' ? `video ${it.duration ? `${Math.round(it.duration)}s` : ''}` : ''} ${it.licence}${it.people ? ' P' : ''}${it.textLines ? ' T' : ''}${it.soft ? ' soft' : ''}${it.title ? ` ${it.title}` : ''}`; // the title last: the cell clips it
  1216. // --scan N on a video search: N frames read straight from each clip's preview stream (nothing is downloaded whole)
  1217. const scanned = scan > 1 ? await mapLimit(items, 2, async (it, k) => {
  1218. const url = it.kind === 'video' ? it.preview || it.image : null;
  1219. if (!url) return null;
  1220. return scanTimes(it.duration || 10, scan).map((t, j) => {
  1221. const f = path.join(cache, `${slug(it.ref.replace(':', '-'), 12)}-s${j}.jpg`);
  1222. if (!fs.existsSync(f)) { try { ff(['-ss', t.toFixed(2), '-i', url, '-frames:v', '1', '-vf', 'scale=480:-2', f], 'scan'); } catch { return { file: k === 0 && j === 0 ? files[k] : null, label: '' }; } }
  1223. return { file: f, label: j === 0 ? label(it) : `#${it.n} ${t.toFixed(1)}s` };
  1224. });
  1225. }) : [];
  1226. cells = items.flatMap((it, k) => scanned[k] || [{ file: files[k], label: label(it) }]);
  1227. out = args.out || `${args._[0].replace(/\.json$/i, '')}.sheet.png`;
  1228. } else {
  1229. const files = listLocal(args._);
  1230. if (!files.length) throw new Usage('no images or videos in those paths');
  1231. // a clip shows one frame, or --scan N frames spread across it (choose the seconds before trimming)
  1232. const scan = Math.round(num(args, 'scan', 1, 1, 12));
  1233. cells = files.flatMap((f, k) => {
  1234. if (!/\.(mp4|webm|mov)$/i.test(f)) return [{ file: f, label: `${k + 1} ${path.basename(f)}` }];
  1235. const dur = probeFile(f)?.duration || 2;
  1236. return scanTimes(dur, scan).map((t, j) => {
  1237. const tmp = path.join(os.tmpdir(), `cinetic-sheet-${process.pid}-${k}-${j}.png`);
  1238. try { ff(['-ss', t.toFixed(2), '-i', f, '-frames:v', '1', '-vf', 'scale=640:-2', tmp], 'frame'); } catch { return { file: null, label: '' }; }
  1239. return { file: tmp, label: `${k + 1} ${path.basename(f).slice(0, 28)} ${t.toFixed(1)}s` };
  1240. });
  1241. });
  1242. out = args.out || path.join(path.dirname(files[0]), 'sheet.png');
  1243. }
  1244. const L = sheetLayout(cells.length, { cols: Math.round(num(args, 'cols', 4, 1, 8)), cellW });
  1245. const font = labelFont();
  1246. const inputs = []; const chains = [`color=c=0x15171a:s=${L.W}x${L.H}:d=1[bg]`]; let last = 'bg'; let k = 0;
  1247. cells.forEach((c, i) => {
  1248. if (!c.file) return;
  1249. inputs.push('-i', c.file);
  1250. const cl = L.cells[i];
  1251. chains.push(`[${k}:v]scale=${cl.w}:${cl.h}:force_original_aspect_ratio=decrease,pad=${cl.w}:${cl.h}:(ow-iw)/2:(oh-ih)/2:color=0x0b0c0e,setsar=1,format=rgb24[c${k}]`);
  1252. chains.push(`[${last}][c${k}]overlay=${cl.x}:${cl.y}[o${k}]`); last = `o${k}`; k++;
  1253. });
  1254. if (font) {
  1255. const draws = cells.map((c, i) => `drawtext=fontfile='${ffEsc(font)}':text='${labelText(c.label, Math.floor(L.cellW / 8.6))}':x=${L.cells[i].x + 2}:y=${L.cells[i].labelY}:fontsize=16:fontcolor=0xd8dade`).join(',');
  1256. chains.push(`[${last}]${draws}[out]`); last = 'out';
  1257. }
  1258. fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true }); // --out sheets/x.png into a folder not made yet
  1259. ff([...inputs, '-filter_complex', chains.join(';'), '-map', `[${last}]`, '-frames:v', '1', out], 'sheet');
  1260. console.log(`Sheet ${out} · ${cells.length} cells (${cells.filter((c) => !c.file).length} missing) · ${L.cols} x ${L.rows}${font ? '' : ' · no label font found: cells run left to right, top to bottom'}`);
  1261. console.log('Look at it. Choose for light, depth and one idea, not for the subject alone; refuse stock gestures. Labels: P people, T text or a logo, soft.');
  1262. return 0;
  1263. }
  1264. // ------------------------------------------------------------------------------------------------ get
  1265. /** Where the private licence record of a download folder lives: <film>/assets/licences.json, outside public/. */
  1266. export function recordPath(to, override) {
  1267. if (override) return path.resolve(override);
  1268. const abs = path.resolve(to); const parts = abs.split(path.sep);
  1269. const i = parts.lastIndexOf('public');
  1270. if (i > 0) return path.join(parts.slice(0, i).join(path.sep) || path.sep, 'assets', 'licences.json');
  1271. return path.join(abs, 'licences.json');
  1272. }
  1273. /** A file's path inside the nearest public/ folder (what staticFile() takes), or null. */
  1274. export function publicPath(file) {
  1275. const parts = path.resolve(file).split(path.sep); const i = parts.lastIndexOf('public');
  1276. return i >= 0 ? parts.slice(i + 1).join('/') : null;
  1277. }
  1278. export function readRecord(file) {
  1279. try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); return Array.isArray(j.items) ? j : { items: [] }; } catch { return { items: [] }; }
  1280. }
  1281. /** One record entry (the shape scripts/audio/track.py keeps for music, for imagery). */
  1282. export function recordEntry(it, f) {
  1283. const L = LICENCES[it.licence] || LICENCES.unknown;
  1284. // the licence line the item's own page gave when it was read (Mixkit), else the licence page's own words
  1285. const seen = it.seen?.quote ? it.seen : SOURCE_SEEN[it.source]?.licence === it.licence ? SOURCE_SEEN[it.source] : L.seen;
  1286. const credit = L.credit ? `${it.kind === 'video' ? 'Footage' : 'Photo'}: "${short(it.title, 80)}"${it.author ? ` by ${short(it.author, 60)}` : ''}, ${L.name}${it.licenceVersion ? ` ${it.licenceVersion}` : ''}, via ${it.provider}` : null;
  1287. return {
  1288. file: f.file, sha256: f.sha256, bytes: f.bytes, kind: it.kind, width: f.width ?? it.width ?? null, height: f.height ?? it.height ?? null,
  1289. ...(it.kind === 'video' ? { duration: f.duration ?? it.duration ?? null, fps: f.fps ?? it.fps ?? null } : {}),
  1290. title: it.title, author: it.author || null, source: SOURCES[it.source]?.name || it.source, provider: it.provider, ref: it.ref, page: it.page, file_url: it.image,
  1291. licence: L.name, licence_id: it.licence, licence_url: L.url || null, credit_required: Boolean(L.credit), credit,
  1292. licence_seen: seen ? { quote: seen.quote, url: seen.url, date: seen.date || CHECKED } : null,
  1293. limits: (it.source === 'nasa' ? SOURCE_SEEN.nasa.limits : L.limits) || null, notes: it.notes || [], checked: new Date().toISOString().slice(0, 10),
  1294. modifications: f.modifications || null, shown_on_screen: false,
  1295. };
  1296. }
  1297. export function writeRecord(file, entry) {
  1298. const doc = readRecord(file);
  1299. doc.about = 'Private licence record of this film\'s imagery (scripts/assets.mjs). Never shown on screen. Licences marked credit_required false need no credit.';
  1300. doc.items = [...doc.items.filter((x) => x.file !== entry.file), entry];
  1301. fs.mkdirSync(path.dirname(file), { recursive: true });
  1302. fs.writeFileSync(file, JSON.stringify(doc, null, 1));
  1303. return doc;
  1304. }
  1305. /** Split a ref list on the commas that start a new ref (#n, n, or <source>:), so a file title may hold commas. */
  1306. export const splitRefs = (s) => String(s).split(/,(?=\s*(?:#?\d+\s*(?:,|$)|[a-z]+:))/).map((x) => x.trim()).filter(Boolean);
  1307. /** Resolve "#n" refs against a results file (or the last search), else keep "<source>:<id>". */
  1308. export function resolveRefs(list, doc) {
  1309. return list.map((r) => {
  1310. const m = String(r).match(/^#?(\d+)$/);
  1311. if (!m) return { ref: r, hint: doc?.items?.find((it) => it.ref === r) || null };
  1312. const it = doc?.items?.find((x) => x.n === Number(m[1]));
  1313. if (!it) throw new Usage(`#${m[1]} is not in the results${doc ? '' : ' (no results file: pass --from <results.json>)'}`);
  1314. return { ref: it.ref, hint: it };
  1315. });
  1316. }
  1317. /**
  1318. * The item a saved search found for a ref (the results files in `dir`, newest first), or null: a ref given as
  1319. * search printed it, after another search, still finds its page (Mixkit has no lookup by id).
  1320. */
  1321. export function findSaved(ref, dir = path.join('out', 'assets')) {
  1322. let files;
  1323. try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => path.join(dir, f)); } catch { return null; }
  1324. const mtime = (f) => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
  1325. for (const f of files.sort((a, b) => mtime(b) - mtime(a))) {
  1326. try { const it = JSON.parse(fs.readFileSync(f, 'utf8'))?.items?.find?.((x) => x?.ref === ref); if (it) return it; } catch { /* not a results file */ }
  1327. }
  1328. return null;
  1329. }
  1330. /** Fresh metadata and licence for one ref, read from its source (never trusted from a results file). */
  1331. async function lookup(ref, o, hint) {
  1332. const m = String(ref).match(/^([a-z]+):(.+)$/);
  1333. if (!m || !SOURCES[m[1]]) throw new Error(`a ref looks like <source>:<id> (${Object.keys(SOURCES).join(', ')}), as search prints it`);
  1334. const [, src, id] = m;
  1335. if (SOURCES[src].env && !hasKey(src)) throw new Error(`${SOURCES[src].name} needs ${SOURCES[src].env} in the environment`);
  1336. let kind = hint?.kind || o.kind || 'photo';
  1337. if (!SOURCES[src].kinds.includes(kind)) kind = SOURCES[src].kinds[0]; // the last search was another kind: a stills site serves stills
  1338. if (src === 'openverse') { const it = parseOpenverse({ results: [await getJson(`https://api.openverse.org/v1/images/${encodeURIComponent(id)}/`, { ms: 40000 })] }, { kind })[0]; await commonsSizes(it && /upload\.wikimedia/.test(it.image) ? [it] : [], o.width); return it; }
  1339. if (src === 'commons') {
  1340. const j = await getJson(commonsApi({ ...commonsRefParam(id), prop: 'imageinfo|videoinfo', iiprop: 'url|size|mime|extmetadata', iiurlwidth: String(o.width), iiextmetadatafilter: COMMONS_META, iiextmetadatalanguage: 'en', viprop: 'derivatives' }));
  1341. const pg = j?.query?.pages?.[0]; const video = /^video\//.test(pg?.imageinfo?.[0]?.mime || '');
  1342. return parseCommons({ query: { pages: [pg] } }, { kind: video ? 'video' : kind, width: o.width, res: o.res })[0];
  1343. }
  1344. if (src === 'nasa') {
  1345. const nid = decodeURIComponent(id);
  1346. const j = await getJson(`https://images-api.nasa.gov/search?${new URLSearchParams({ nasa_id: nid })}`);
  1347. const it = parseNasaSearch(j, { kind })[0]; if (!it) return null;
  1348. const man = parseNasaManifest(await getJson(nasaHref(it.manifest)), it.kind);
  1349. if (it.kind === 'video') { const pick = pickRendition(man.renditions.filter((x) => !x.orig), o.res); Object.assign(it, { image: pick?.url, width: pick?.w, height: pick?.h }); }
  1350. else it.image = (o.width > 1600 ? man.orig : null) || man.large || man.medium;
  1351. return it;
  1352. }
  1353. if (src === 'aic') {
  1354. const j = await getJson(`https://api.artic.edu/api/v1/artworks/${encodeURIComponent(id)}?fields=${AIC_FIELDS.join(',')}`, { headers: AIC_HEADERS });
  1355. const it = parseAic({ data: [j.data], config: j.config }, o)[0]; if (!it) return null;
  1356. const w = await aicServe(it, o.width);
  1357. if (w && w < Math.min(o.width, it.full?.[0] || o.width)) it.notes = [...it.notes, `AIC serves this work at ${w} px wide only (asked ${o.width}${it.full ? `, the original is ${it.full[0]}` : ''}): use it small or behind a defocus, or choose another work`];
  1358. return it;
  1359. }
  1360. if (src === 'met') return parseMetObject(await getJson(metObjectUrl(id)), {});
  1361. if (src === 'burst') {
  1362. const sl = decodeURIComponent(id);
  1363. if (!/^[a-z0-9-]+$/i.test(sl)) throw new Error('a Burst ref is burst:<photo slug>, as search prints it');
  1364. const page = hint?.page || `https://burst.shopify.com/photos/${sl}`;
  1365. const r = parseBurstItem(await getText(page));
  1366. return item('burst', sl, { kind, title: r.title || hint?.title || sl.replace(/-/g, ' '), author: r.author, page, thumb: burstImage(sl, 500), image: burstImage(sl, o.width), licence: r.licence,
  1367. notes: r.licence === 'unknown' ? [`licence "${r.licenceSlug || 'none named'}" is not one the tool knows`] : [] });
  1368. }
  1369. if (src === 'isorepublic') {
  1370. const sl = decodeURIComponent(id);
  1371. if (!/^[a-z0-9-]+$/i.test(sl)) throw new Error('an ISO Republic ref is isorepublic:<photo slug>, as search prints it');
  1372. const page = hint?.page || `https://isorepublic.com/photo/${sl}/`;
  1373. const r = parseIsoItem(await getText(page), o.width); const p = isoPick(r, o.width);
  1374. return item('isorepublic', sl, { kind, title: r.title || hint?.title || sl.replace(/-/g, ' '), page, image: p.image, width: p.width, height: p.height, licence: r.licence });
  1375. }
  1376. if (src === 'coverr') {
  1377. // a Coverr page address needs the clip's name, which only a search records; the record is read again there
  1378. if (!hint?.page) throw new Error(`no saved search holds ${ref}: pass --from <the results.json that found it> (Coverr pages need their name, and the licence is read there)`);
  1379. const rec = coverrRecords(await getText(hint.page, { ms: 45000 })).find((x) => x.id === id);
  1380. return rec ? parseCoverrRecord(rec, { res: o.res }) : null;
  1381. }
  1382. if (src === 'mixkit') {
  1383. // a Mixkit page address needs the clip's name, which only a search records (an id alone lands on a search page)
  1384. if (!hint?.page) throw new Error(`no saved search holds ${ref}: pass --from <the results.json that found it> (Mixkit pages need their name, and the licence is read there)`);
  1385. const { page } = hint;
  1386. const html = await getText(page);
  1387. const r = parseMixkitItem(html, id, { known: hint.preview || hint.image, page }); const pick = pickRendition(r.renditions, o.res);
  1388. return item('mixkit', id, { kind: 'video', title: r.title || hint?.title || `mixkit ${id}`, page, image: pick?.url || null, width: pick?.w || null, height: pick?.h || null, duration: r.duration, licence: r.licence, seen: r.seen });
  1389. }
  1390. if (src === 'pexels') {
  1391. const video = kind === 'video';
  1392. const j = await getJson(video ? `https://api.pexels.com/videos/videos/${id}` : `https://api.pexels.com/v1/photos/${id}`, { headers: { Authorization: key('pexels') } });
  1393. return parsePexels(video ? { videos: [j] } : { photos: [j] }, { kind, width: o.width, res: o.res })[0];
  1394. }
  1395. if (src === 'unsplash') { const j = await getJson(`https://api.unsplash.com/photos/${encodeURIComponent(id)}`, { headers: { Authorization: `Client-ID ${key('unsplash')}`, 'Accept-Version': 'v1' } }); return parseUnsplash({ results: [j] }, { kind, width: o.width })[0]; }
  1396. if (src === 'pixabay') {
  1397. const video = kind === 'video';
  1398. const j = await getJson(`https://pixabay.com/api/${video ? 'videos/' : ''}?${new URLSearchParams({ key: key('pixabay'), id })}`);
  1399. return parsePixabay(j, { kind, res: o.res })[0];
  1400. }
  1401. return null;
  1402. }
  1403. async function download(url, file, capBytes) {
  1404. const r = await fetch(url, { headers: imageHeaders(url), signal: AbortSignal.timeout(900000), redirect: 'follow' });
  1405. if (!r.ok) throw new Error(`the file did not load (HTTP ${r.status})`);
  1406. const out = fs.createWriteStream(file); const hash = crypto.createHash('sha256'); let n = 0; const head = [];
  1407. try {
  1408. const reader = r.body.getReader();
  1409. for (;;) {
  1410. const { done, value } = await reader.read(); if (done) break;
  1411. n += value.length;
  1412. if (n > capBytes) { reader.cancel().catch(() => {}); throw new Error(`over the ${Math.round(capBytes / 1048576)} MB cap: pass a larger --max-mb, a smaller --res, or choose a shorter clip`); }
  1413. if (n <= 262144 + value.length) head.push(value);
  1414. hash.update(value);
  1415. if (!out.write(value)) await new Promise((res) => out.once('drain', res));
  1416. }
  1417. await new Promise((res, rej) => out.end((e) => (e ? rej(e) : res())));
  1418. } catch (e) { out.destroy(); try { fs.unlinkSync(file); } catch { /* gone */ } throw e; }
  1419. return { bytes: n, sha256: hash.digest('hex'), head: Buffer.concat(head) };
  1420. }
  1421. export function probeFile(file) {
  1422. const r = spawnSync('ffprobe', ['-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', file], { encoding: 'utf8', maxBuffer: 8 << 20 });
  1423. if (r.status !== 0) return null;
  1424. const j = JSON.parse(r.stdout); const v = (j.streams || []).find((s) => s.codec_type === 'video');
  1425. if (!v) return null;
  1426. const rate = (s) => { const [a, b] = String(s || '0/1').split('/').map(Number); return b ? a / b : 0; };
  1427. const isStill = /^(mjpeg|png|webp|gif|av1|bmp|tiff)$/.test(v.codec_name) && (!j.format?.duration || Number(j.format.duration) < 0.05 || /image2|png_pipe|jpeg_pipe|webp_pipe/.test(j.format?.format_name || ''));
  1428. return { width: v.width, height: v.height, codec: v.codec_name, pix_fmt: v.pix_fmt, still: isStill, duration: isStill ? null : Number(j.format?.duration || v.duration) || null,
  1429. fps: isStill ? null : Number(rate(v.avg_frame_rate || v.r_frame_rate).toFixed(3)) || null, frames: Number(v.nb_frames) || null, bitrate: Number(j.format?.bit_rate) || null, bytes: Number(j.format?.size) || null,
  1430. colour: [v.color_primaries, v.color_transfer, v.color_space].filter(Boolean).join('/') || null, audio: (j.streams || []).some((s) => s.codec_type === 'audio') };
  1431. }
  1432. /** The source line of a downloaded file for the kit (fx/Pictures PhotoCard, ArcRiver, FootageWindow; fx/Photo, fx/Footage). Pure. */
  1433. export const srcLine = (pub, f, media = 'image') => (media === 'video'
  1434. ? `{ src: staticFile('${pub}'), w: ${f.width}, h: ${f.height}${f.fps ? `, fps: ${f.fps}` : ''}${f.duration ? `, dur: ${Number(f.duration.toFixed(2))}` : ''} }`
  1435. : `{ src: staticFile('${pub}'), w: ${f.width}, h: ${f.height} } // add focus: [x, y] (0..1) on the subject`);
  1436. /** A saved image narrower than the record promised (within the asked width) by more than 10 %: what to say, or null. Pure. */
  1437. export function shortfall(saved, promised, asked) {
  1438. const want = promised ? Math.min(promised, asked || promised) : null;
  1439. if (!saved || !want || saved >= want * 0.9) return null;
  1440. return `saved ${saved} px wide, but the record promised ${want} px: the server sent a smaller rendition (use it small or behind a defocus, or choose another)`;
  1441. }
  1442. const parseTrim = (s) => { if (!s) return null; const [a, b] = String(s).split(',').map(Number); if (!(a >= 0) || !(b > 0)) throw new Usage('--trim is start,seconds (e.g. 3.5,6)'); return { start: a, dur: b }; };
  1443. async function cmdGet(args) {
  1444. const list = splitRefs(args._.join(','));
  1445. if (!list.length) throw new Usage('get needs one or more refs (openverse:<id>, mixkit:<id> ...) or #n from the last search');
  1446. if (!args.to) throw new Usage('get needs --to <film>/public/assets (where the files go)');
  1447. let doc = null;
  1448. const from = args.from || (() => { try { return fs.readFileSync(path.join('out', 'assets', '.last'), 'utf8').trim(); } catch { return null; } })();
  1449. if (from && fs.existsSync(from)) doc = JSON.parse(fs.readFileSync(from, 'utf8'));
  1450. const o = { kind: doc?.kind, width: Math.round(num(args, 'width', 2400, 400, 4000)), res: Math.round(num(args, 'res', 1080, 240, 2160)), allowCredit: Boolean(args['allow-credit']) };
  1451. const cap = num(args, 'max-mb', 150, 1, 2000) * 1048576; const trim = parseTrim(args.trim);
  1452. const to = path.resolve(args.to); const rec = recordPath(to, args.record);
  1453. fs.mkdirSync(to, { recursive: true });
  1454. let failed = 0; let written = 0;
  1455. for (const { ref, hint: known } of resolveRefs(list, doc)) {
  1456. try {
  1457. const hint = known || findSaved(ref) || recipeHint(ref);
  1458. const it = await lookup(ref, o, hint);
  1459. if (!it || !it.image) throw new Error('no usable file on the record (removed, or no rendition)');
  1460. const lic = licenceAllowed(it.licence, o);
  1461. if (!lic.ok) throw new Error(`refused: ${LICENCES[it.licence]?.name || it.licence}: ${lic.why}`);
  1462. if (it.ai) throw new Error('refused: an AI-generated clip, not real footage');
  1463. if (it.source === 'unsplash' && it.downloadLocation) await getJson(it.downloadLocation, { headers: { Authorization: `Client-ID ${key('unsplash')}` } }).catch(() => null); // the API's download event
  1464. const stem = slug(args.name && list.length === 1 ? args.name : it.title, 6) || slug(ref.replace(':', '-'), 6);
  1465. const part = path.join(to, `.${stem}.part`);
  1466. const d = await download(it.image, part, cap);
  1467. const kind = sniff(d.head);
  1468. if (!kind) { fs.unlinkSync(part); throw new Error('the file is not an image or a video'); }
  1469. if ((it.kind === 'video') !== (kind.media === 'video')) { fs.unlinkSync(part); throw new Error(`expected ${it.kind === 'video' ? 'a video' : 'an image'}, got ${kind.ext}`); }
  1470. let file = path.join(to, `${stem}.${kind.ext}`);
  1471. for (let k = 2; fs.existsSync(file) && readRecord(rec).items.find((x) => x.file === path.relative(path.dirname(rec), file).split(path.sep).join('/'))?.ref !== ref; k++) file = path.join(to, `${stem}-${k}.${kind.ext}`);
  1472. fs.renameSync(part, file);
  1473. const f = { bytes: d.bytes, sha256: d.sha256, ...(kind.media === 'image' ? (({ w, h }) => ({ width: w, height: h }))(dims(d.head)) : {}) };
  1474. if (kind.media === 'video' && ffmpegOk()) {
  1475. const p = probeFile(file); if (p) Object.assign(f, { width: p.width, height: p.height, duration: p.duration, fps: p.fps });
  1476. if (trim) {
  1477. const cut = file.replace(/\.[^.]+$/, `.cut.mp4`);
  1478. ff(['-ss', String(trim.start), '-i', file, '-t', String(trim.dur), '-an', '-c:v', 'libx264', '-crf', '17', '-preset', 'medium', '-pix_fmt', 'yuv420p',
  1479. '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-movflags', '+faststart', cut], 'trim');
  1480. fs.unlinkSync(file); file = file.replace(/\.[^.]+$/, '.mp4'); fs.renameSync(cut, file);
  1481. const b = fs.readFileSync(file); const p2 = probeFile(file);
  1482. Object.assign(f, { bytes: b.length, sha256: crypto.createHash('sha256').update(b).digest('hex'), duration: p2?.duration ?? trim.dur, fps: p2?.fps ?? f.fps, modifications: `trimmed to ${trim.dur} s from ${trim.start} s, audio removed` });
  1483. }
  1484. }
  1485. f.file = path.relative(path.dirname(rec), file).split(path.sep).join('/');
  1486. writeRecord(rec, recordEntry(it, f)); written++;
  1487. const small = kind.media === 'image' && f.width && f.width < 1920;
  1488. const short = kind.media === 'image' ? shortfall(f.width, it.width, o.width) : null;
  1489. if (short) console.error(`WARNING ${ref}: ${short}`);
  1490. console.log(`Saved ${path.relative(process.cwd(), file)} · ${f.width ? `${f.width}x${f.height}` : ''}${f.duration ? ` · ${f.duration.toFixed(1)} s @ ${f.fps} fps` : ''} · ${size(f.bytes)} · ${LICENCES[it.licence].name}${LICENCES[it.licence].credit ? ' (credit line in the record)' : ', no credit needed'}`);
  1491. console.log(` use ${publicPath(file) ? `staticFile('${publicPath(file)}')` : path.relative(process.cwd(), file)}`);
  1492. if (publicPath(file) && f.width) console.log(` src ${srcLine(publicPath(file), f, kind.media)}`);
  1493. if (small) console.log(' note under 1920 px wide: use it small, as a texture, or behind a defocus; never full frame sharp');
  1494. if (kind.media === 'video' && !trim && f.duration > 12) console.log(' note a long clip: keep only the seconds you use (--trim start,seconds) to keep the project lean');
  1495. for (const n of it.notes || []) console.log(` note ${n}`);
  1496. } catch (e) { failed++; console.error(`Could not get ${ref}: ${redact(e.message)}`); }
  1497. }
  1498. if (written) console.log(`Licence record: ${path.relative(process.cwd(), rec)} (private; nothing here is shown on screen)`);
  1499. return failed ? 1 : 0;
  1500. }
  1501. // ------------------------------------------------------------------------------------------------ grade
  1502. /**
  1503. * Named looks: one grade for a whole set, so stills from different sources read as one shoot. Every look
  1504. * normalises exposure (the 10th and 90th luma percentiles toward `lo` / `hi`, `recentre` of the way, the
  1505. * contrast change held to x0.77-1.3) and colour strength (mean saturation to `sat`; `keep` holds the picture's
  1506. * own, only pulling a mean above `satCap` down a little) first; `median` then puts the median luma there (night);
  1507. * `warm` drains reds and yellows (orange skies, tan wood); then colours: `vib` < 0 is a vibrance ceiling (strong colours
  1508. * lose more than weak ones, so a turquoise bay does not outshout the set), `mode` duotone maps luma between
  1509. * two colours at the accent hue (shadow and highlight as OKLCH L/C), `tint` keeps `keep` of the photo's own
  1510. * colour under a duotone wash, `split` pushes shadows a step toward the split hue (--split-hue, a cool teal-slate
  1511. * by default and never tied to the accent: a red accent must not redden celadon shadows, and the accent stays
  1512. * free for live data), `mono` is a neutral black and white. `device: true` marks a look for one shot, never a
  1513. * whole film.
  1514. */
  1515. export const LOOKS = {
  1516. natural: { about: 'the default: each picture keeps its own colour and range; black level and contrast a quarter of the way toward the whole set (never stretched past x1.3), only the strongest colours held back a little, a faint cool shadow', lo: 0.07, hi: 0.86, recentre: 0.25, keep: true, satCap: 0.36, vib: -0.1, mode: 'split', split: 0.02, grain: 0.18 },
  1517. matte: { about: 'editorial matte: lifted blacks, rolled highlights, colour at 55 %, shadows a step toward the split hue (cool by default)', lo: 0.12, hi: 0.84, black: 0.06, white: 0.94, sat: 0.55, vib: -0.25, mode: 'split', split: 0.05, grain: 0.25 },
  1518. silver: { about: 'neutral black and white, a firm curve and stronger grain (archives, a quiet film, the pieces of a collage)', lo: 0.05, hi: 0.9, sat: 0, mode: 'mono', grain: 0.4 },
  1519. night: { about: 'low key: the median luma to about 0.18 (a daylight picture reads as night, a dark one is not crushed), warm colours (orange skies, tan wood) drained, shadows a step toward the split hue (cool by default)', lo: 0.03, hi: 0.72, sat: 0.6, vib: -0.25, mode: 'split', split: 0.07, median: 0.18, warm: -0.8, grain: 0.3 },
  1520. tint: { device: true, about: 'a device look for one shot: 30 % of the photo\'s own colour under a one-hue wash at the accent hue', lo: 0.08, hi: 0.88, sat: 0.3, mode: 'tint', keep: 0.3, shadow: [0.2, 0.06], mid: [0.55, 0.085], highlight: [0.95, 0.025], grain: 0.25 },
  1521. duotone: { device: true, about: 'a device look for one shot: deep accent-hued shadows to a pale tinted white', lo: 0.06, hi: 0.9, sat: 0, mode: 'duotone', shadow: [0.2, 0.08], mid: [0.55, 0.075], highlight: [0.96, 0.03], grain: 0.3 },
  1522. deep: { device: true, about: 'a device look for one shot: the photo becomes a colour field, shadows at L .14, highlights at the accent lifted to L .82', lo: 0.05, hi: 0.86, sat: 0, mode: 'duotone', shadow: [0.14, 0.05], mid: [0.46, 0.1], highlight: [0.82, 0.1], grain: 0.3 },
  1523. };
  1524. /** The picture check's thresholds (OKLCH chroma): neutral below, saturated at or above (the look audit's line). */
  1525. export const PICTURE = { neutralC: 0.03, saturatedC: 0.06, accentDeg: 20, minNeutral: 0.3, maxSatFrames: 0.35, maxAccent: 0.1, banned: 0.005, minSaturated: 0.045, lumaGap: 0.25, chromaX: 2.5 };
  1526. /**
  1527. * The banned OKLCH regions, the same numbers as look-audit.py's banned_mask, lint-film.mjs and palette.py:
  1528. * neon, beige/cream, orange/amber, purple/violet. Counted on pixels of C >= .03 (as look-audit samples). Pure.
  1529. */
  1530. export function bannedRegion(L, C, h) {
  1531. if (C < 0.03) return false;
  1532. const yellow = h >= 96 && h < 118;
  1533. const neon = (yellow ? L >= 0.91 && C >= 0.15 : (L >= 0.85 && C >= 0.15) || (L >= 0.8 && C >= 0.18)) || C >= 0.27;
  1534. const beige = h >= 31 && h < 118 && L >= 0.7 && C >= 0.007 && C < 0.1;
  1535. const orange = h >= 31 && h < 96 && C >= 0.05;
  1536. const purple = h >= 270 && h < 340 && C >= 0.02;
  1537. return neon || beige || orange || purple;
  1538. }
  1539. const hueGap = (a, b) => { const d = Math.abs(a - b) % 360; return d > 180 ? 360 - d : d; };
  1540. /**
  1541. * Natural tones of a photograph: skin of every shade, hair, wood, sand, linen, paper (OKLCH hue 20-85, chroma
  1542. * .015-.13, L .18-.95); light wood, straw and the highlights of grass and skin (hue 85-118, C <= .075); olive and
  1543. * sunlit yellow-green foliage (hue 85-100, C <= .13, L <= .8); pale cool cloth, a lavender or lilac-grey shirt (hue
  1544. * 265-310, C <= .05); and the deep blue-violet of navy cloth, denim, night shadow and a dusk sky (hue 265-310,
  1545. * C <= .12, L <= .6). In a picture they are the world's colour, not designed colour, so the picture check never
  1546. * counts them as a banned region (look-audit leaves the pictures the layout audit logs out the same way); a
  1547. * saturated orange or amber object (C > .13), a cream-yellow field (hue >= 85, C > .075, L > .8), a lit violet or
  1548. * purple and neon still count. Pure.
  1549. */
  1550. export function naturalTone(L, C, h) {
  1551. return (h >= 20 && h <= 85 && C >= 0.015 && C <= 0.13 && L >= 0.18 && L <= 0.95)
  1552. || (h > 85 && h <= 118 && C >= 0.015 && C <= 0.075 && L >= 0.18 && L <= 0.95)
  1553. || (h > 85 && h <= 100 && C >= 0.015 && C <= 0.13 && L >= 0.18 && L <= 0.8)
  1554. || (h >= 265 && h <= 310 && C >= 0.015 && C <= 0.05)
  1555. || (h >= 265 && h <= 300 && C <= 0.12 && L <= 0.45)
  1556. || (h >= 265 && h <= 310 && C >= 0.015 && C <= 0.12 && L <= 0.6);
  1557. }
  1558. /**
  1559. * Shares of neutral, saturated, accent-hued and banned-region pixels in an rgb24 buffer (accent = a #hex or
  1560. * null), with the median OKLCH lightness and the mean chroma (for the set's match). Pure.
  1561. */
  1562. export function colourShares(buf, accent = null) {
  1563. const ah = accent ? hexToOklch(accent)[2] : null;
  1564. let n = 0; let neutral = 0; let saturated = 0; let acc = 0; let banned = 0; let natural = 0; let csum = 0;
  1565. const Ls = [];
  1566. for (let i = 0; i + 2 < buf.length; i += 3) {
  1567. const [L, C, h] = rgbToOklch(buf[i], buf[i + 1], buf[i + 2]);
  1568. n++; csum += C; Ls.push(L);
  1569. if (C < PICTURE.neutralC) neutral++;
  1570. if (C >= PICTURE.saturatedC) { saturated++; if (ah !== null && hueGap(h, ah) <= PICTURE.accentDeg) acc++; }
  1571. if (naturalTone(L, C, h)) natural++;
  1572. else if (bannedRegion(L, C, h)) banned++;
  1573. }
  1574. if (!n) return { neutral: 0, saturated: 0, accent: 0, banned: 0, natural: 0, L: 0, C: 0 };
  1575. Ls.sort((a, b) => a - b);
  1576. return { neutral: neutral / n, saturated: saturated / n, accent: acc / n, banned: banned / n, natural: natural / n, L: Ls[n >> 1], C: csum / n };
  1577. }
  1578. /**
  1579. * The verdict on a graded set from per-frame shares ([{ neutral, saturated, accent }], every still once, every
  1580. * clip three times): mean neutral share against the floor, the share of frames more than half saturated and
  1581. * the mean accent share against their ceilings. Only the neutral floor fails. Pure.
  1582. */
  1583. export function pictureVerdict(frames, o = {}) {
  1584. const P = { ...PICTURE, ...o };
  1585. const m = (k) => (frames.length ? frames.reduce((s, f) => s + (f[k] ?? 0), 0) / frames.length : 0);
  1586. const neutral = m('neutral'); const accent = m('accent'); const saturated = m('saturated');
  1587. const satFrames = frames.length ? frames.filter((f) => f.saturated > 0.5).length / frames.length : 0;
  1588. const bannedFrames = frames.filter((f) => (f.banned ?? 0) >= P.banned);
  1589. const bannedOk = P.allowBanned || !bannedFrames.length;
  1590. const notes = [];
  1591. if (neutral < P.minNeutral) notes.push(`neutral ${Math.round(neutral * 100)} % is under the ${Math.round(P.minNeutral * 100)} % floor: the set reads as one colour wash and the accent will not read on live data; grade matte (colour at 55 %) or silver, or --chroma 0.7; keep tint, duotone and deep for one shot`);
  1592. if (bannedFrames.length) notes.push(`${bannedFrames.length} frame(s) show a banned colour region (orange/amber, beige/cream, purple/violet or neon) on ${Math.round(Math.max(...bannedFrames.map((f) => f.banned)) * 1000) / 10} % of the frame at most (the film's banned-hue test fails at ${P.banned * 100} %)${bannedFrames[0].file ? `: ${[...new Set(bannedFrames.map((f) => f.file))].slice(0, 4).join(', ')}` : ''}: crop it out, grade night or silver, or pick another picture${P.allowBanned ? ' (passed: --brand-supplied)' : '; the brand\'s own colour? --brand-supplied, and declare it in the tokens'}`);
  1593. if (satFrames > P.maxSatFrames) notes.push(`${Math.round(satFrames * 100)} % of frames are more than half saturated (ceiling ${Math.round(P.maxSatFrames * 100)} %): --chroma 0.8, matte, or pictures with grey, white or dark in them`);
  1594. if (frames.length && saturated < P.minSaturated) notes.push(`saturated pixels ${Math.round(saturated * 1000) / 10} % of the set, under the film's saturated floor (${P.minSaturated * 100} %): the pictures read grey; grade natural (it keeps their colour), raise --chroma, or let the accent and a support hue carry larger masses`);
  1595. if (accent > P.maxAccent) notes.push(`the pictures themselves carry the accent's hue on ${Math.round(accent * 100)} % of their pixels (ceiling ${Math.round(P.maxAccent * 100)} %): the accent will not stand out on them; --chroma 0.8, matte, or move the accent's hue away from the pictures'`);
  1596. return { neutral, satFrames, accent, saturated, banned: bannedFrames.length, ok: neutral >= P.minNeutral && bannedOk, notes };
  1597. }
  1598. /**
  1599. * Pictures that do not read as one shoot: per file the median OKLCH lightness and the mean chroma (of its
  1600. * frames) against the set's medians; a file more than `lumaGap` lighter or darker, or with more than `chromaX`
  1601. * times (or under 1 / chromaX of) the set's colour strength, is an outlier. o.arc: the set tells a day (morning to
  1602. * night, a light that changes on purpose): lightness is the story, not a mismatch, so each file's colour strength
  1603. * is held against the files of its own light (within `lumaGap` of its L, 3 or more of them) and lightness is not
  1604. * judged. rows = [{ file, L, C }]. Pure.
  1605. */
  1606. export function setOutliers(rows, o = {}) {
  1607. const P = { ...PICTURE, ...o };
  1608. if (rows.length < 3) return [];
  1609. const med = (a) => { const b = [...a].sort((x, y) => x - y); return b[b.length >> 1]; };
  1610. const mL = med(rows.map((r) => r.L)); const mC = med(rows.map((r) => r.C));
  1611. const out = [];
  1612. for (const r of rows) {
  1613. const why = [];
  1614. const peers = P.arc ? rows.filter((q) => Math.abs(q.L - r.L) <= P.lumaGap) : rows;
  1615. if (P.arc && peers.length < 3) continue;
  1616. const pC = P.arc ? med(peers.map((q) => q.C)) : mC;
  1617. if (!P.arc && Math.abs(r.L - mL) > P.lumaGap) why.push(`${r.L > mL ? 'lighter' : 'darker'} (median L ${r.L.toFixed(2)} vs ${mL.toFixed(2)})`);
  1618. if (pC > 0.02 && (r.C > pC * P.chromaX || r.C < pC / P.chromaX)) why.push(`${r.C > pC ? 'more' : 'less'} colour (C ${r.C.toFixed(3)} vs ${pC.toFixed(3)}${P.arc ? ' in its light' : ''})`);
  1619. if (why.length) out.push({ file: r.file, why: why.join(', ') });
  1620. }
  1621. return out;
  1622. }
  1623. /**
  1624. * Readable text or a logo in the pictures (someone else's brand on a bus, a shop sign): text-like lines that
  1625. * stay put. like.py's text reader finds the lines in each frame; a clip's line counts when it sits in the
  1626. * same place (box overlap >= 0.5) in at least two of its frames, a still's when two or more lines share a
  1627. * baseline band or one line is at least 4 x as wide as tall. regions = [[x, y, w, h], ...] per frame. Pure.
  1628. */
  1629. export function steadyText(framesRegions) {
  1630. const iou = (a, b) => {
  1631. const x = Math.max(0, Math.min(a[0] + a[2], b[0] + b[2]) - Math.max(a[0], b[0])); const y = Math.max(0, Math.min(a[1] + a[3], b[1] + b[3]) - Math.max(a[1], b[1]));
  1632. const i = x * y; return i / (a[2] * a[3] + b[2] * b[3] - i || 1);
  1633. };
  1634. if (framesRegions.length >= 2) {
  1635. const hits = [];
  1636. framesRegions.forEach((rs, i) => rs.forEach((a) => { if (framesRegions.some((other, j) => j !== i && other.some((b) => iou(a, b) >= 0.5))) hits.push(a); }));
  1637. return hits;
  1638. }
  1639. const rs = framesRegions[0] || [];
  1640. return rs.filter((a) => a[2] >= 4 * a[3] || rs.some((b) => b !== a && Math.abs(a[3] - b[3]) <= 0.25 * a[3] && Math.abs(a[1] + a[3] - (b[1] + b[3])) <= 0.5 * a[3]));
  1641. }
  1642. /** The crop of a w x h source at `aspect` (w/h), `zoom` x tighter, centred on focus (fx, fy in 0..1) and clamped inside. */
  1643. export function focusCrop(w, h, aspect, fx = 0.5, fy = 0.5, zoom = 1) {
  1644. let cw = w; let ch = Math.round(w / aspect);
  1645. if (ch > h) { ch = h; cw = Math.round(h * aspect); }
  1646. cw = Math.round(cw / Math.max(1, zoom)); ch = Math.round(ch / Math.max(1, zoom));
  1647. cw -= cw % 2; ch -= ch % 2;
  1648. const x = Math.round(Math.min(Math.max(fx * w - cw / 2, 0), w - cw)); const y = Math.round(Math.min(Math.max(fy * h - ch / 2, 0), h - ch));
  1649. return { x, y, w: cw, h: ch };
  1650. }
  1651. const f3 = (v) => Number(v).toFixed(3).replace(/\.?0+$/, '') || '0';
  1652. /** The most any look stretches or flattens a picture's range (x1.3 either way). */
  1653. export const STRETCH = 1.3;
  1654. /**
  1655. * Where the 10th / 90th luma percentiles go: toward the look's, the slope held to 1/1.3-1.3, re-centred
  1656. * `recentre` of the way to the look's middle (house 0.75; natural 0.25, so a bright still stays bright and a
  1657. * night one stays dark).
  1658. */
  1659. export function exposureMap(stats, L) {
  1660. const p10 = stats ? Math.min(0.45, Math.max(0.01, stats.lo)) : 0.1;
  1661. const p90 = stats ? Math.min(0.99, Math.max(p10 + 0.15, stats.hi)) : 0.9;
  1662. const slope = Math.min(STRETCH, Math.max(1 / STRETCH, (L.hi - L.lo) / (p90 - p10)));
  1663. const midIn = (p10 + p90) / 2;
  1664. const mid = midIn + (((L.lo + L.hi) / 2) - midIn) * (L.recentre ?? 0.75);
  1665. const lo = Math.max(0.005, mid - (slope * (p90 - p10)) / 2);
  1666. const hi = Math.min(0.995, mid + (slope * (p90 - p10)) / 2);
  1667. return { p10, p90, lo, hi, slope, black: L.black ?? 0, white: L.white ?? 1 };
  1668. }
  1669. /** The saturation factor that brings a source's colour strength to the look's (after the contrast change). */
  1670. export function satFactor(stats, target, slope = 1) {
  1671. if (!stats?.sat) return target;
  1672. return Math.min(1.25, Math.max(0.25, (0.16 * target) / (Math.max(0.02, stats.sat) * slope)));
  1673. }
  1674. /** natural's colour: the picture's own, a mean saturation above `cap` pulled down a little (never under x0.8). */
  1675. export function keepFactor(stats, cap = 0.36) {
  1676. if (!stats?.sat || stats.sat <= cap) return 1;
  1677. return Math.max(0.8, cap / stats.sat);
  1678. }
  1679. /** The gamma exponent that puts a median luma `m` (after the exposure map) at `target`, held to 0.7-2.8. */
  1680. export function medianGamma(m, target = 0.18) {
  1681. const x = Math.min(0.98, Math.max(0.02, m));
  1682. return Math.min(2.8, Math.max(0.7, Math.log(target) / Math.log(x)));
  1683. }
  1684. /** Curves points for a duotone: luma 0..1 mapped through OKLab from the shadow to the highlight colour (5 knots). */
  1685. export function duotoneCurves(hue, shadow, highlight, mid = null) {
  1686. const A = oklchToRgb(shadow[0], shadow[1], hue); const B = oklchToRgb(highlight[0], highlight[1], hue);
  1687. const la = rgbToOklab(...A.map((v) => v * 255)); const lb = rgbToOklab(...B.map((v) => v * 255));
  1688. // with a mid colour the ramp bends through it at t = 0.5 (the mid-tones keep colour mass instead of greying out)
  1689. const lm = mid ? rgbToOklab(...oklchToRgb(mid[0], mid[1], hue).map((v) => v * 255)) : la.map((v, i) => (v + lb[i]) / 2);
  1690. const at = (t) => (t <= 0.5 ? la.map((v, i) => v + (lm[i] - v) * (t / 0.5)) : lm.map((v, i) => v + (lb[i] - v) * ((t - 0.5) / 0.5)));
  1691. const knots = [0, 0.25, 0.5, 0.75, 1].map((t) => ({ t, rgb: oklabToRgb(...at(t)).map((v) => Math.min(1, Math.max(0, v))) }));
  1692. const ch = (i) => knots.map((k) => `${f3(k.t)}/${f3(k.rgb[i])}`).join(' ');
  1693. return { r: ch(0), g: ch(1), b: ch(2), shadowHex: rgbHex(A), highlightHex: rgbHex(B) };
  1694. }
  1695. /** The split-tone hue when none is asked for: the hue of #2f7d8c (OKLCH ~213, a cool teal-slate). */
  1696. export const SPLIT_HUE = 213;
  1697. /** A --split-hue value (degrees 0-360 or a #rrggbb colour) to degrees. */
  1698. export function hueOf(v) {
  1699. const s = String(v ?? '').trim();
  1700. if (/^#[0-9a-f]{6}$/i.test(s)) return hexToOklch(s)[2];
  1701. const n = Number(s);
  1702. if (s !== '' && Number.isFinite(n) && n >= 0 && n <= 360) return n;
  1703. throw new Usage('--split-hue is a hue in degrees (0-360, OKLCH) or a #rrggbb colour');
  1704. }
  1705. /**
  1706. * The ffmpeg filter chain of one file for a look. stats = { lo, hi, sat, med } of the source (luma percentiles,
  1707. * mean saturation and median luma, 0..1) or null; crop = focusCrop() or null; width = output width; accent =
  1708. * the wash hue of the device looks; splitHue = the shadow hue of the split looks (degrees, SPLIT_HUE when null);
  1709. * strength = how far toward the look (0 = the picture as it is, 1 = the look, up to 1.5); colour = a saturation
  1710. * multiplier after it (--chroma); hueSat = ffmpeg has the huesaturation filter (night's warm drain). Pure (tested).
  1711. */
  1712. export function gradeFilter(lookName, { accent = '#2f7d8c', splitHue = null, stats = null, crop = null, width = 2400, grain, video = false, speed = 1, colour = 1, strength = 1, hueSat = true } = {}) {
  1713. const L = LOOKS[lookName];
  1714. if (!L) throw new Usage(`unknown look ${lookName}: ${Object.keys(LOOKS).join(', ')}`);
  1715. const hue = hexToOklch(accent)[2];
  1716. const f = [];
  1717. if (crop) f.push(`crop=${crop.w}:${crop.h}:${crop.x}:${crop.y}`);
  1718. f.push(`scale=${width}:-2:flags=lanczos`);
  1719. if (speed !== 1) f.push(`setpts=PTS/${f3(speed)}`);
  1720. f.push('format=gbrp');
  1721. // how far toward the look: every move below is a blend from the picture (s = 0) to the look (s = 1)
  1722. const s = Math.min(1.5, Math.max(0, strength));
  1723. const toward = (from, to) => from + (to - from) * s;
  1724. const c01 = (v) => Math.min(1, Math.max(0, v));
  1725. // exposure: the source's 10th / 90th luma percentiles toward the look's, the contrast change held to
  1726. // x1/1.3-1.3; the ends continue the same line (no spline overshoot that crushes a bright still)
  1727. const ex = exposureMap(stats, L);
  1728. const lo = c01(toward(ex.p10, ex.lo)); const hi = c01(toward(ex.p90, ex.hi));
  1729. const k1 = (hi - lo) / (ex.p90 - ex.p10);
  1730. const y0 = Math.max(toward(0, ex.black), lo - k1 * ex.p10); const y1 = Math.min(toward(1, ex.white), hi + k1 * (1 - ex.p90));
  1731. const ident = Math.abs(lo - ex.p10) < 1e-4 && Math.abs(hi - ex.p90) < 1e-4 && y0 < 1e-4 && y1 > 1 - 1e-4;
  1732. if (!ident) f.push(`curves=all='0/${f3(y0)} ${f3(ex.p10)}/${f3(lo)} ${f3(ex.p90)}/${f3(hi)} 1/${f3(y1)}'`);
  1733. // night: the median to `median` (a monotonic curve moves the median exactly), held to gamma 0.7-2.8
  1734. if (L.median) {
  1735. const m = stats?.med ?? (stats ? (ex.p10 + ex.p90) / 2 : 0.45);
  1736. const g = toward(1, medianGamma(lo + k1 * (m - ex.p10), L.median));
  1737. if (Math.abs(g - 1) > 1e-3) f.push(`eq=gamma=${f3(1 / g)}`);
  1738. }
  1739. if (L.gamma) f.push(`eq=gamma=${f3(toward(1, L.gamma))}`);
  1740. if (L.mode === 'duotone' || L.mode === 'mono' || L.mode === 'tint') {
  1741. const luma = 'colorchannelmixer=rr=.2126:rg=.7152:rb=.0722:gr=.2126:gg=.7152:gb=.0722:br=.2126:bg=.7152:bb=.0722';
  1742. const amount = Math.min(1, s);
  1743. if (L.mode === 'mono') f.push(amount >= 1 ? luma : `eq=saturation=${f3(1 - amount)}`);
  1744. else {
  1745. const d = duotoneCurves(hue, L.shadow, L.highlight, L.mid);
  1746. const tone = `${luma},curves=r='${d.r}':g='${d.g}':b='${d.b}'`; // blend: the first input (the photo) on top
  1747. const keep = L.mode === 'duotone' ? 1 - amount : 1 - (1 - L.keep) * amount;
  1748. const sat = toward(1, satFactor(stats, 1, ex.slope)) * colour;
  1749. if (keep <= 1e-6) f.push(tone);
  1750. else f.push(`split[a][b];[b]${tone}[t];[a]eq=saturation=${f3(sat)}[k];[k][t]blend=all_mode=normal:all_opacity=${f3(keep)}`);
  1751. }
  1752. } else {
  1753. const look = L.keep ? keepFactor(stats, L.satCap) : satFactor(stats, L.sat, ex.slope);
  1754. const sat = Math.max(0, toward(1, look)) * colour;
  1755. if (Math.abs(sat - 1) > 1e-3) f.push(`eq=saturation=${f3(sat)}`);
  1756. if (L.vib && s > 0) f.push(`vibrance=intensity=${f3(L.vib * s)}`);
  1757. if (L.warm && s > 0) f.push(hueSat ? `huesaturation=saturation=${f3(Math.max(-1, L.warm * s))}:colors=r+y` : `eq=saturation=${f3(1 + L.warm * 0.4 * Math.min(1, s))}`);
  1758. const split = L.split * s;
  1759. if (split > 0) {
  1760. const [r, g, b] = oklchToRgb(0.5, 0.12, splitHue ?? SPLIT_HUE).map((v) => v - 0.5);
  1761. const k = split / Math.max(0.001, Math.max(Math.abs(r), Math.abs(g), Math.abs(b)));
  1762. f.push(`colorbalance=rs=${f3(r * k)}:gs=${f3(g * k)}:bs=${f3(b * k)}:rm=${f3(r * k * 0.3)}:gm=${f3(g * k * 0.3)}:bm=${f3(b * k * 0.3)}`);
  1763. }
  1764. }
  1765. const gr = (grain ?? L.grain) * Math.min(1, s);
  1766. if (gr > 0) f.push(`noise=alls=${Math.round(gr * 20)}:allf=${video ? 't+u' : 'u'}`);
  1767. f.push(video ? 'format=yuv420p' : 'format=rgb24');
  1768. return f.join(',');
  1769. }
  1770. /**
  1771. * The encoder arguments of a graded clip. scrub: every frame a key frame and no reordered frames, for a clip whose
  1772. * time the film drives (a clock, a ping-pong, a ramp): a renderer then lands on any frame exactly. Pure.
  1773. */
  1774. export const videoEncode = ({ scrub = false } = {}) => ['-c:v', 'libx264', '-crf', scrub ? '18' : '17', '-preset', 'medium', ...(scrub ? ['-g', '1', '-bf', '0'] : [])];
  1775. /** Luma percentiles and saturation of a file (ffmpeg signalstats on a small copy): { lo, hi, avg, sat } in 0..1. */
  1776. export function measure(file) {
  1777. const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'info', '-i', file, '-vf', 'scale=320:-2,signalstats,metadata=mode=print', '-frames:v', '1', '-f', 'null', '-'], { encoding: 'utf8' });
  1778. const g = (k) => Number((`${r.stderr}${r.stdout}`.match(new RegExp(`lavfi\\.signalstats\\.${k}=([\\d.]+)`)) || [])[1]);
  1779. if (!Number.isFinite(g('YLOW'))) return null;
  1780. const grid = frameGrid(file);
  1781. const ys = [];
  1782. for (let i = 0; i + 2 < grid.length; i += 3) ys.push((0.2126 * grid[i] + 0.7152 * grid[i + 1] + 0.0722 * grid[i + 2]) / 255);
  1783. ys.sort((a, b) => a - b);
  1784. return { lo: g('YLOW') / 255, hi: g('YHIGH') / 255, avg: g('YAVG') / 255, sat: g('SATAVG') / 181, med: ys.length ? ys[ys.length >> 1] : g('YAVG') / 255 };
  1785. }
  1786. let HUESAT = null;
  1787. /** ffmpeg has the huesaturation filter (5.1+): night drains warm colours with it, else with a plain desaturation. */
  1788. export function hasHueSat() { if (HUESAT === null) HUESAT = /\bhuesaturation\b/.test(spawnSync('ffmpeg', ['-hide_banner', '-filters'], { encoding: 'utf8' }).stdout || ''); return HUESAT; }
  1789. async function cmdGrade(args) {
  1790. if (!ffmpegOk()) throw new Error('grade needs ffmpeg and ffprobe on the PATH');
  1791. const files = listLocal(args._).filter((f) => !/\.(json|txt|md)$/i.test(f));
  1792. if (!files.length) throw new Usage('grade needs image or video files (or folders)');
  1793. const look = args.look || 'natural';
  1794. if (!LOOKS[look]) throw new Usage(`unknown look ${look}: ${Object.keys(LOOKS).join(', ')} (node scripts/assets.mjs looks)`);
  1795. const accent = args.accent || '#2f7d8c';
  1796. if (!/^#[0-9a-f]{6}$/i.test(accent)) throw new Usage('--accent is a #rrggbb colour (the film\'s accent from brand/tokens.ts)');
  1797. const width = Math.round(num(args, 'width', 2400, 320, 3840)); const grain = args.grain !== undefined ? num(args, 'grain', 0.3, 0, 1) : undefined;
  1798. const aspect = !args.aspect || args.aspect === 'none' ? (args.aspect === 'none' ? null : 16 / 9) : (() => { const [a, b] = String(args.aspect).split(/[:/x]/).map(Number); if (!(a > 0 && b > 0)) throw new Usage('--aspect is w:h (16:9) or none'); return a / b; })();
  1799. const [fx, fy] = args.focus ? String(args.focus).split(',').map(Number) : [0.5, 0.5];
  1800. const trim = parseTrim(args.trim); const speed = num(args, 'speed', 1, 0.1, 8); const strength = num(args, 'strength', 1, 0, 1.5); const colour = num(args, 'chroma', 1, 0.2, 1.5);
  1801. const hueSat = hasHueSat();
  1802. if (LOOKS[look].warm && !hueSat) console.log(`${look}: this ffmpeg has no huesaturation filter (5.1+): warm colours are drained with a plain desaturation instead.`);
  1803. const splitHue = args['split-hue'] !== undefined ? hueOf(args['split-hue']) : null;
  1804. if (LOOKS[look].device) console.log(`${look} is a device look: grade the one shot that uses it this way and the rest of the film natural (or matte, silver).`);
  1805. const graded = [];
  1806. const outDir = path.resolve(args.out || path.join(path.dirname(files[0]), 'graded'));
  1807. fs.mkdirSync(outDir, { recursive: true });
  1808. for (const file of files) {
  1809. const p = probeFile(file); if (!p) { console.error(`skip ${file}: not an image or video ffprobe can read`); continue; }
  1810. const video = !p.still;
  1811. const stats = measure(file);
  1812. const crop = aspect ? focusCrop(p.width, p.height, aspect, fx, fy) : null;
  1813. const w = Math.min(width, crop ? crop.w : p.width) - (Math.min(width, crop ? crop.w : p.width) % 2);
  1814. const vf = gradeFilter(look, { accent, splitHue, stats, crop, width: w, grain, video, speed, colour, strength, hueSat });
  1815. const out = path.join(outDir, `${path.basename(file).replace(/\.[^.]+$/, '')}.${args.suffix || look}.${video ? 'mp4' : 'jpg'}`);
  1816. const argv = video
  1817. ? [...(trim ? ['-ss', String(trim.start)] : []), '-i', file, ...(trim ? ['-t', String(trim.dur / speed)] : []), '-an', '-filter_complex', `[0:v]${vf}[v]`, '-map', '[v]', ...videoEncode({ scrub: Boolean(args.scrub) }),
  1818. '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-movflags', '+faststart', out]
  1819. : ['-i', file, '-filter_complex', `[0:v]${vf}[v]`, '-map', '[v]', '-frames:v', '1', '-q:v', '2', out];
  1820. if (args['dry-run']) { console.log(`ffmpeg ${argv.map((a) => (/[\s;'[\]]/.test(a) ? `"${a}"` : a)).join(' ')}`); continue; }
  1821. ff(argv, `grade ${path.basename(file)}`);
  1822. graded.push({ file: out, video });
  1823. console.log(`Graded ${path.relative(process.cwd(), out)} · ${look}${crop ? ` · crop ${crop.w}x${crop.h} at ${crop.x},${crop.y}` : ''} · source luma ${stats ? `${stats.lo.toFixed(2)}-${stats.hi.toFixed(2)}` : '?'}`);
  1824. }
  1825. if (args['dry-run'] || !graded.length) return 0;
  1826. console.log(`Check the set as one shoot: node scripts/assets.mjs sheet ${path.relative(process.cwd(), outDir) || outDir}`);
  1827. if (args['no-check']) return 0;
  1828. return pictureCheck(graded, args.accent ? accent : null, { allowBanned: Boolean(args['brand-supplied']), arc: Boolean(args.arc) });
  1829. }
  1830. /** Pixels of one frame (a still, or a clip at t seconds) as a small rgb24 grid at 16:9. */
  1831. export function frameGrid(file, t = null, w = 96, h = 54) {
  1832. const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', ...(t !== null ? ['-ss', String(t)] : []), '-i', file, '-vf', `scale=${w}:${h}:flags=area`, '-frames:v', '1', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'], { maxBuffer: 1 << 20 });
  1833. return r.status === 0 ? r.stdout : Buffer.alloc(0);
  1834. }
  1835. /**
  1836. * like.py's text reader over frames of the set (480 px wide): [{ file, t, regions }] or null when the project's
  1837. * Python cannot run it (it needs numpy and opencv-python). The frames go to a private temp folder, removed after.
  1838. */
  1839. export function readText(graded) {
  1840. const like = path.join(path.dirname(fileURLToPath(import.meta.url)), 'like.py');
  1841. if (!fs.existsSync(like)) return null;
  1842. const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cinetic-text-'));
  1843. try {
  1844. const jobs = [];
  1845. graded.forEach((g, i) => {
  1846. const times = g.video ? scanTimes(probeFile(g.file)?.duration || 1, 3) : [null];
  1847. times.forEach((t, j) => {
  1848. const png = path.join(tmp, `f${i}_${j}.png`);
  1849. const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', ...(t !== null ? ['-ss', String(t)] : []), '-i', g.file, '-vf', 'scale=480:-2', '-frames:v', '1', png]);
  1850. if (r.status === 0) jobs.push({ file: g.file, i, t, png });
  1851. });
  1852. });
  1853. const code = `import sys, json, importlib.util\nimport cv2\nspec = importlib.util.spec_from_file_location('like_mod', sys.argv[1]); m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m); m.need()\nprint(json.dumps([m.text_regions(cv2.cvtColor(cv2.imread(p), cv2.COLOR_BGR2GRAY)) for p in sys.argv[2:]]))`;
  1854. const py = spawnSync(process.execPath, [path.join(path.dirname(like), 'py.mjs'), '--which'], { encoding: 'utf8' });
  1855. const which = (py.stdout || '').trim();
  1856. const cmd = fs.existsSync(which) ? [which] : which.split(/\s+/).filter(Boolean); // a path with spaces, or "py -3"
  1857. if (py.status !== 0 || !cmd.length || !jobs.length) return null;
  1858. const r = spawnSync(cmd[0], [...cmd.slice(1), '-c', code, like, ...jobs.map((j) => j.png)], { encoding: 'utf8', maxBuffer: 16 << 20 });
  1859. if (r.status !== 0) return null;
  1860. const regions = JSON.parse(r.stdout.trim().split('\n').pop());
  1861. return jobs.map((j, k) => ({ file: j.file, t: j.t, regions: regions[k] || [] }));
  1862. } catch { return null; } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
  1863. }
  1864. /**
  1865. * Measures a set (every still once, every clip at three times) and prints the verdict: 3 when the set is a
  1866. * colour wash or shows a banned colour region (o.allowBanned: the banned colour is the brand's own). Notes: the
  1867. * saturated floor, frames over half saturated, the accent's hue in the pictures, pictures that do not match the
  1868. * set, and readable text or logos (o.text false skips the text reader).
  1869. */
  1870. export function pictureCheck(graded, accent = null, o = {}) {
  1871. const frames = []; const perFile = [];
  1872. console.log(`\nPicture check (OKLCH: neutral C < ${PICTURE.neutralC}, saturated C >= ${PICTURE.saturatedC}, banned regions on C >= .03${accent ? `, accent within ${PICTURE.accentDeg} deg of ${accent}` : ''}):`);
  1873. for (const g of graded) {
  1874. const times = g.video ? scanTimes(probeFile(g.file)?.duration || 1, 3) : [null];
  1875. const rows = times.map((t) => ({ ...colourShares(frameGrid(g.file, t), accent), file: path.basename(g.file) }));
  1876. frames.push(...rows);
  1877. const mean = (k) => rows.reduce((a, r) => a + r[k], 0) / rows.length;
  1878. perFile.push({ file: path.basename(g.file), L: mean('L'), C: mean('C') });
  1879. const m = (k) => String(Math.round(mean(k) * 100)).padStart(3);
  1880. const ban = Math.max(...rows.map((r) => r.banned));
  1881. console.log(` ${path.basename(g.file).padEnd(46)} neutral ${m('neutral')} % saturated ${m('saturated')} %${accent ? ` accent ${m('accent')} %` : ''}${ban >= PICTURE.banned ? ` BANNED ${(ban * 100).toFixed(1)} %` : ''}`);
  1882. }
  1883. const v = pictureVerdict(frames, { allowBanned: Boolean(o.allowBanned) });
  1884. for (const x of setOutliers(perFile, { arc: Boolean(o.arc) })) v.notes.push(`${x.file} does not read as the same shoot${o.arc ? ' as the pictures of its light' : ''}: ${x.why}; regrade it on its own (--strength, --chroma) or replace it${o.arc ? '' : ' (a set that tells a day, morning to night, on purpose: --arc)'}`);
  1885. if (o.text !== false) {
  1886. const read = readText(graded);
  1887. if (!read) v.notes.push('text and logos: not read (the project\'s Python needs numpy and opencv-python for like.py\'s reader); look at the sheet for signs, adverts and labels');
  1888. else {
  1889. const byFile = new Map();
  1890. for (const r of read) { if (!byFile.has(r.file)) byFile.set(r.file, []); byFile.get(r.file).push(r); }
  1891. for (const [file, rs] of byFile) {
  1892. const steady = steadyText(rs.map((r) => r.regions));
  1893. if (steady.length) v.notes.push(`${path.basename(file)} may show readable text or a logo (${steady.length} steady text-like line(s), e.g. ${steady[0].join(',')} at 480 px): someone else's brand never appears in a film; crop, defocus or replace it (the reader can mistake stripes for text: look)`);
  1894. }
  1895. }
  1896. }
  1897. const pc = (x) => Math.round(x * 100);
  1898. console.log(`Set: neutral ${pc(v.neutral)} % (floor ${pc(PICTURE.minNeutral)} %), saturated ${(v.saturated * 100).toFixed(1)} % (film floor ${PICTURE.minSaturated * 100} %), frames over half saturated ${pc(v.satFrames)} % (ceiling ${pc(PICTURE.maxSatFrames)} %)${accent ? `, accent ${pc(v.accent)} % (ceiling ${pc(PICTURE.maxAccent)} %)` : ''}, banned-colour frames ${v.banned}: ${v.ok ? (v.notes.length ? 'passes, with notes' : 'passes') : 'FAILS'}`);
  1899. for (const n of v.notes) console.log(` - ${n}`);
  1900. return v.ok ? 0 : 3;
  1901. }
  1902. // ------------------------------------------------------------------------------------------------ recipes
  1903. /**
  1904. * Footage recipes (assets/footage-recipes.json): the inputs a launch film most often has to show, because the first
  1905. * picture beat shows the product's core transformation literally, input -> output. Each input carries the shot that
  1906. * shows it (a person speaking into a phone, hands typing on a laptop, a parcel set down at a door), how to frame it,
  1907. * which screen takes the product's UI as a plate built in code, the searches that find it (footage first) and the
  1908. * clips and photos already looked at and kept for it. `recipe <input>` finds the closest input in your words and
  1909. * saves its picks as a results file, so `sheet` and `get #n` work at once; --run searches every line again.
  1910. */
  1911. export const RECIPES_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'footage-recipes.json');
  1912. export function loadRecipes(file = RECIPES_FILE) {
  1913. let j;
  1914. try { j = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`could not read the recipes (${path.basename(file)}): ${e.message}`); }
  1915. if (!Array.isArray(j?.inputs)) throw new Error(`${path.basename(file)} has no inputs list`);
  1916. return j;
  1917. }
  1918. const RECIPE_SKIP = new Set([...QWORDS_SKIP, 'app', 'apps', 'tool', 'tools', 'product', 'products', 'launch', 'film', 'video', 'my', 'our', 'your', 'new', 'that',
  1919. 'who', 'someone', 'into', 'something', 'is', 'it', 'its', 'their', 'user', 'users', 'shot']);
  1920. /** A word's stem, to match an input in the user's own words: lower case; a plural, then -ing or -ed, then a final e, dropped. Pure. */
  1921. export const recipeStem = (w) => {
  1922. let s = String(w).toLowerCase();
  1923. if (s.length > 4 && s.endsWith('ies')) s = `${s.slice(0, -3)}y`;
  1924. else if (s.length > 4 && /(ss|sh|ch|x|z)es$/.test(s)) s = s.slice(0, -2);
  1925. else if (s.length > 3 && s.endsWith('s') && !/(ss|us|is)$/.test(s)) s = s.slice(0, -1);
  1926. if (s.length > 5 && s.endsWith('ing')) s = s.slice(0, -3);
  1927. else if (s.length > 4 && s.endsWith('ed')) s = s.slice(0, -2);
  1928. if (s.length > 3 && /([bdgmnprt])\1$/.test(s)) s = s.slice(0, -1); // runn -> run, shopp -> shop
  1929. if (s.length > 3 && s.endsWith('e')) s = s.slice(0, -1); // hike / hik(ing), type / typ(ing)
  1930. return s;
  1931. };
  1932. const recipeStems = (t) => String(t).toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w && !RECIPE_SKIP.has(w)).map(recipeStem);
  1933. const stemHit = (a, b) => {
  1934. if (a === b) return true;
  1935. if (Math.min(a.length, b.length) >= 4 && (a.startsWith(b) || b.startsWith(a))) return true;
  1936. let k = 0; while (k < a.length && a[k] === b[k]) k++;
  1937. return k >= 7; // transcrib(e) ~ transcription
  1938. };
  1939. /**
  1940. * The recipes for an input in the user's words, best first: [{ recipe, score }]. An id or label typed exactly wins;
  1941. * otherwise each of the words found in a recipe's id or label counts 4, in its aliases 3, in its apps (the products
  1942. * that show this input) 2. Pure.
  1943. */
  1944. export function matchRecipes(input, inputs) {
  1945. const s = String(input || '').trim().toLowerCase();
  1946. const exact = inputs.find((r) => r.id === s || String(r.label || '').toLowerCase() === s);
  1947. if (exact) return [{ recipe: exact, score: 99 }];
  1948. const want = [...new Set(recipeStems(s))];
  1949. if (!want.length) return [];
  1950. return inputs.map((r, k) => {
  1951. const main = recipeStems([String(r.id).replace(/-/g, ' '), r.label].join(' '));
  1952. const alias = recipeStems((r.aliases || []).join(' '));
  1953. const apps = recipeStems((r.apps || []).join(' '));
  1954. let score = 0;
  1955. for (const w of want) { const hit = (l) => l.some((m) => stemHit(w, m)); score += hit(main) ? 4 : hit(alias) ? 3 : hit(apps) ? 2 : 0; }
  1956. return { recipe: r, score, k };
  1957. }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || a.k - b.k).map(({ recipe, score }) => ({ recipe, score }));
  1958. }
  1959. /** A recipe's pick as a results item (the shape search saves; get reads the licence again at its source). Pure. */
  1960. export function pickItem(p, r = null) {
  1961. const src = String(p.ref).split(':')[0];
  1962. return item(src, String(p.ref).slice(src.length + 1), {
  1963. kind: p.kind || 'photo', title: p.title || '', author: p.author || '', page: p.page || null, thumb: p.thumb || null, image: p.image || null,
  1964. preview: p.preview || null, width: p.w || null, height: p.h || null, duration: p.dur || null, licence: p.licence || 'unknown', shows: p.shows || '',
  1965. screen: p.screen || null, recipe: r?.id || null, verified: true,
  1966. });
  1967. }
  1968. /** The pick any recipe holds for a ref, as a hint for get (a Coverr or Mixkit page needs the clip's name), or null. */
  1969. export function recipeHint(ref, doc = null) {
  1970. let d = doc;
  1971. if (!d) { try { d = loadRecipes(); } catch { return null; } }
  1972. for (const r of d.inputs) for (const p of r.picks || []) if (p.ref === ref) return pickItem(p, r);
  1973. return null;
  1974. }
  1975. /** Read each pick again at its source: it still loads, its licence still needs no credit. Exit 1 when one does not. */
  1976. async function verifyRecipes(list) {
  1977. const o = { width: 2400, res: 1080, allowCredit: false };
  1978. let bad = 0; let n = 0; let unread = 0;
  1979. for (const r of list) {
  1980. for (const p of r.picks || []) {
  1981. n++;
  1982. const hint = pickItem(p, r); let it = null; let why = ''; let limited = false;
  1983. try { it = await lookup(p.ref, { ...o, kind: hint.kind }, hint); } catch (e) { why = redact(e.message); limited = /HTTP 429/.test(why); }
  1984. if (!why && (!it || !it.image)) why = 'no usable file on the record (removed, or no rendition)';
  1985. const lic = it ? licenceAllowed(it.licence, o) : { ok: true };
  1986. if (!why && !lic.ok) why = `${LICENCES[it.licence]?.name || it.licence}: ${lic.why}`;
  1987. if (!why && it.ai) why = 'AI-generated, not real footage';
  1988. if (limited) unread++; else if (why) bad++; // a rate limit says nothing about the pick: read it again later
  1989. console.log(`${limited ? 'WAIT' : why ? 'FAIL' : 'ok '} ${String(r.id).padEnd(18)} ${p.ref.padEnd(36)} ${(it?.licence || '').padEnd(13)} ${why || short(it.title || p.title, 50)}`);
  1990. await sleep(250); // gentle on the sites without an API
  1991. }
  1992. }
  1993. console.log(`\n${n - bad - unread} of ${n} picks load with a licence that needs no credit${bad ? `; ${bad} failed: search the recipe again (--run) and replace them` : ''}${unread ? `; ${unread} not read (the site rate-limited the run): --verify again later` : ''}`);
  1994. return bad || unread ? 1 : 0;
  1995. }
  1996. async function cmdRecipe(args) {
  1997. const doc = loadRecipes();
  1998. const input = args._.join(' ').trim();
  1999. const rel = (f) => path.relative(process.cwd(), f) || f;
  2000. if (!input) {
  2001. console.log(`RECIPES · ${doc.inputs.length} inputs a launch film shows (assets/footage-recipes.json, picks checked ${doc.checked || '?'})`);
  2002. for (const r of doc.inputs) {
  2003. const v = (r.picks || []).filter((p) => p.kind === 'video').length; const ph = (r.picks || []).length - v;
  2004. console.log(` ${String(r.id).padEnd(18)} ${short(r.label, 44).padEnd(45)} ${v + ph ? `${v} clip${v === 1 ? '' : 's'}, ${ph} photo${ph === 1 ? '' : 's'}` : 'searches only (recipe runs them)'}`);
  2005. }
  2006. console.log('\nnode scripts/assets.mjs recipe "<the input your product takes, in your words>" e.g. recipe "voice memo app", recipe "receipt scanner"');
  2007. return 0;
  2008. }
  2009. if (input === 'all' && args.verify) return verifyRecipes(doc.inputs);
  2010. const ranked = matchRecipes(input, doc.inputs);
  2011. if (!ranked.length) {
  2012. console.error(`No recipe matches "${input}". The inputs: ${doc.inputs.map((r) => r.id).join(', ')}.`);
  2013. console.error('Name the person, the action and the device yourself: search "woman speaking into phone" --kind video --source coverr,mixkit');
  2014. return 1;
  2015. }
  2016. const r = ranked[0].recipe;
  2017. if (args.json) { console.log(JSON.stringify(r, null, 1)); return 0; }
  2018. if (args.verify) return verifyRecipes([r]);
  2019. const kind = args.kind ? String(args.kind).toLowerCase() : null;
  2020. if (kind && !['video', 'photo'].includes(kind)) throw new Usage('recipe --kind is video or photo');
  2021. const out = path.resolve(args.out || path.join('out', 'assets', `recipe-${r.id}.json`));
  2022. fs.mkdirSync(path.dirname(out), { recursive: true });
  2023. const picks = (r.picks || []).filter((p) => !kind || p.kind === kind).map((p) => pickItem(p, r));
  2024. const lines = (r.queries || []).filter((l) => !kind || (l.kind || 'video') === kind);
  2025. const found = []; const ran = [];
  2026. const run = Boolean(args.run) || !picks.length; // an input with no picks yet runs its searches at once
  2027. if (run) {
  2028. for (const l of lines) {
  2029. const qa = { _: [], kind: l.kind || 'video', source: l.source || 'all', limit: String(args.limit || 6), ...(l.people ? { people: true } : {}),
  2030. ...(l.orientation ? { orientation: l.orientation } : {}), ...(args['no-vet'] ? { 'no-vet': true } : {}), ...(args['min-width'] ? { 'min-width': args['min-width'] } : {}) };
  2031. const o = searchOptions(qa);
  2032. const g = await gatherSearch(l.q, o, out);
  2033. const got = interleave(g.groups, o.limit).map(({ n, ...it }) => it);
  2034. found.push(got);
  2035. const errs = Object.entries(g.report).filter(([, x]) => x.error).map(([s, x]) => `${SOURCES[s].name}: ${x.error}`);
  2036. ran.push(` "${l.q}" · ${o.kind} · ${o.sources.map((s) => SOURCES[s].name).join(', ')}: ${got.length} kept of ${Object.values(g.report).reduce((a, x) => a + x.found, 0)}${errs.length ? ` (${errs.join('; ')})` : ''}`);
  2037. }
  2038. }
  2039. const seen = new Set(picks.map((it) => it.ref));
  2040. const fresh = interleave(found, 99).map(({ n, ...it }) => it).filter((it) => !seen.has(it.ref) && seen.add(it.ref));
  2041. const items = [...picks, ...fresh].map((it, k) => ({ n: k + 1, ...it }));
  2042. const res = { query: `recipe ${r.id}`, recipe: r.id, kind: kind || 'mixed', created: new Date().toISOString(), options: { run, limit: Number(args.limit || 6) }, items };
  2043. fs.writeFileSync(out, JSON.stringify(res, null, 1));
  2044. try { fs.writeFileSync(path.join(path.dirname(out), '.last'), out); } catch { /* optional */ }
  2045. console.log(`RECIPE · ${r.id} · ${r.label}`);
  2046. if (r.apps?.length) console.log(` for ${r.apps.join(', ')}`);
  2047. console.log(` shows ${r.action}`);
  2048. for (const [k, f] of (r.framing || []).entries()) console.log(` ${k ? ' ' : 'frame '} ${f}`);
  2049. if (r.screen) console.log(` screen ${r.screen}`);
  2050. const close = ranked.slice(1, 4).filter((x) => x.score >= ranked[0].score - 1 && ranked[0].score < 99).map((x) => x.recipe.id);
  2051. if (close.length) console.log(` (also close: ${close.join(', ')}: recipe <id>)`);
  2052. console.log('');
  2053. if (run && !picks.length && lines.length) console.log('No picks looked at yet for this input: its searches ran now.');
  2054. if (ran.length) { console.log('Searched again:'); for (const x of ran) console.log(x); console.log(''); }
  2055. if (picks.length) console.log(`#1-#${picks.length}: the picks, looked at on a contact sheet${doc.checked ? ` on ${doc.checked}` : ''} (licences that need no credit; get reads each one again at its source)`);
  2056. if (fresh.length) console.log(`#${picks.length + 1}-#${items.length}: fresh hits from the searches, not looked at yet`);
  2057. printItems(items);
  2058. console.log('');
  2059. if (!run && lines.length) {
  2060. console.log('The searches (footage first; --run runs them all into this results file):');
  2061. for (const l of lines) console.log(` node scripts/assets.mjs search "${l.q}" --kind ${l.kind || 'video'}${l.source ? ` --source ${l.source}` : ''}${l.people ? ' --people' : ''}${l.orientation ? ` --orientation ${l.orientation}` : ''}`);
  2062. console.log('');
  2063. }
  2064. console.log(`Saved ${rel(out)}`);
  2065. if (!items.length) { console.log('Nothing to show: search in other words (the person, the action, the device), or try again in a minute.'); return 1; }
  2066. console.log(`Next. Look before you choose: node scripts/assets.mjs sheet ${rel(out)} --cell 240${items.some((it) => it.kind === 'video') ? ' (then a clip you like through its length: --pick <n> --scan 4)' : ''}`);
  2067. console.log(`Then: node scripts/assets.mjs get ${items.slice(0, 2).map((it) => `#${it.n}`).join(',')} --to public/assets [--trim start,seconds] (the screen plate and the cut: references/imagery.md, "Show the core action")`);
  2068. return 0;
  2069. }
  2070. // ------------------------------------------------------------------------------------------------ check, probe, looks, licences
  2071. function cmdCheck(args) {
  2072. if (args.accent && !/^#[0-9a-f]{6}$/i.test(args.accent)) throw new Usage('--accent is a #rrggbb colour');
  2073. const files = listLocal(args._).filter((f) => !/\.(json|txt|md)$/i.test(f));
  2074. if (!files.length) throw new Usage('check needs graded image or video files (or folders)');
  2075. if (!ffmpegOk()) throw new Error('check needs ffmpeg and ffprobe on the PATH');
  2076. const graded = files.map((f) => ({ file: f, video: /\.(mp4|webm|mov)$/i.test(f) }));
  2077. return pictureCheck(graded, args.accent || null, { allowBanned: Boolean(args['brand-supplied']), text: !args['no-text'], arc: Boolean(args.arc) });
  2078. }
  2079. function cmdProbe(args) {
  2080. const files = listLocal(args._); if (!files.length) throw new Usage('probe needs files');
  2081. const all = files.map((f) => ({ file: f, ...(probeFile(f) || { error: 'not readable by ffprobe' }) }));
  2082. if (args.json) { console.log(JSON.stringify(all, null, 1)); return 0; }
  2083. for (const p of all) {
  2084. if (p.error) { console.log(`${p.file}: ${p.error}`); continue; }
  2085. console.log(`${p.file}: ${p.width}x${p.height} ${p.codec}${p.still ? ' still' : ` · ${p.duration?.toFixed(2)} s · ${p.fps} fps${p.frames ? ` · ${p.frames} frames` : ''}${p.audio ? ' · has audio' : ''}`}${p.colour ? ` · ${p.colour}` : ''}${p.bytes ? ` · ${size(p.bytes)}` : ''}`);
  2086. }
  2087. return 0;
  2088. }
  2089. function cmdLooks() {
  2090. for (const [k, L] of Object.entries(LOOKS)) console.log(`${k.padEnd(9)} ${L.about}`);
  2091. console.log('\nThe film grades natural (the default), which keeps the pictures\' colour; matte, silver and night are whole-film looks too; tint, duotone and deep are for one shot.');
  2092. console.log('--strength 0..1.5: how far toward the look (0 = the picture as it is); --chroma 0.2..1.5: the colour after it.');
  2093. console.log('node scripts/assets.mjs grade public/assets --accent "#2f7d8c" --out public/assets/graded');
  2094. return 0;
  2095. }
  2096. function cmdLicences(args) {
  2097. const rec = recordPath(args.to || path.join('public', 'assets'), args.record);
  2098. const doc = readRecord(rec);
  2099. if (!doc.items.length) { console.log(`No imagery recorded in ${rec} yet.`); return 1; }
  2100. for (const x of doc.items) console.log(`${x.file}: ${x.licence}${x.credit_required ? ` · CREDIT: ${x.credit}` : ' · no credit needed'} · ${x.source} · ${x.page}`);
  2101. const credits = doc.items.filter((x) => x.credit_required);
  2102. console.log(credits.length ? `\n${credits.length} item(s) need a credit (taken with --allow-credit).` : '\nNothing here needs a credit: the film shows none.');
  2103. return 0;
  2104. }
  2105. // ------------------------------------------------------------------------------------------------ main
  2106. // ------------------------------------------------------------------------------------------------ plates
  2107. /**
  2108. * Plates: the photograph or clip a world stands on (src/fx/world World: clouds, aerial, sky, sea, nightCity, studio,
  2109. * macro). A preset names what to look for and how to grade it for a world: the searches (keyless sources first,
  2110. * landscape, no people, no text), the focus the 16:9 crop keeps, and a grade that drains warm light toward the film's
  2111. * cool palette (the worlds never carry orange, amber or cream). `plate <name>` searches and saves a contact sheet;
  2112. * `plate <name> --pick n` (or `--from <a local photo or clip>`) gets that one and writes <to>/<name>.jpg (graded, 16:9
  2113. * on the focus, 2400 px) and <to>/<name>-soft.jpg (the same blurred about 40 px at 1080p: what frosted glass shows and
  2114. * the far depth, so the film never blurs a full frame). A clip is written as <name>.mp4 and <name>-soft.mp4 (960 px,
  2115. * blurred the same: decoding it costs less than blurring a frame). The grade is baked: the look's levels, the warm
  2116. * drained (reds and yellows desaturated), then saturation, gamma and contrast, then a cool balance (blue into the
  2117. * shadows and mids): the world sets the plate in with a light wash only.
  2118. * The same names and searches live in src/fx/world/worlds.ts PLATES (keep the two in step).
  2119. */
  2120. export const PLATES = {
  2121. clouds: { what: 'a sea of clouds from above, the horizon high in frame, cool morning light', kind: 'photo', focus: [0.5, 0.35], queries: ['above the clouds', 'sea of clouds aerial', 'clouds from above horizon', 'cloud layer from airplane'], grade: { look: 'natural', warm: -0.92, sat: 0.28, gamma: 1.04, contrast: 0.98, cool: 0.09, split: 222 } },
  2122. aerial: { what: 'land or coast from high above, soft and cool', kind: 'photo', focus: [0.5, 0.5], queries: ['aerial coastline', 'aerial landscape drone', 'aerial view fields', 'aerial forest fog'], grade: { look: 'natural', warm: -0.6, sat: 0.6, gamma: 1.05, contrast: 0.97, cool: 0.05, split: 215 } },
  2123. sky: { what: 'a pale blue sky with soft white clouds, looking up', kind: 'photo', focus: [0.5, 0.5], queries: ['blue sky white clouds', 'soft clouds sky', 'pale sky clouds', 'cumulus clouds blue sky'], grade: { look: 'natural', warm: -0.7, sat: 0.7, gamma: 1.06, contrast: 0.95, cool: 0.04, split: 230 } },
  2124. sea: { what: 'open water to a far horizon, grey-blue', kind: 'photo', focus: [0.5, 0.45], queries: ['calm sea horizon', 'ocean horizon', 'sea surface', 'open water'], grade: { look: 'matte', warm: -0.7, sat: 0.55, gamma: 1.04, contrast: 0.97, cool: 0.06, split: 215 } },
  2125. nightCity: { what: 'a city at night from above or across water, its lights soft', kind: 'photo', focus: [0.5, 0.55], queries: ['city at night', 'night city skyline', 'city lights night aerial', 'night street lights bokeh'], grade: { look: 'night', warm: -0.85, sat: 0.7, gamma: 1, contrast: 1.04, cool: 0.06, split: 225 } },
  2126. studio: { what: 'a seamless studio sweep under a softbox, light grey', kind: 'photo', focus: [0.5, 0.5], queries: ['studio backdrop', 'seamless paper backdrop', 'empty studio light', 'grey studio background'], grade: { look: 'matte', warm: -0.9, sat: 0.2, gamma: 1.02, contrast: 0.96, cool: 0.03, split: 230 } },
  2127. macro: { what: 'a close natural surface: leaves, water drops, moss, in soft light', kind: 'photo', focus: [0.5, 0.5], queries: ['leaf macro', 'water drops macro', 'moss macro', 'fern close up'], grade: { look: 'natural', warm: -0.3, sat: 0.85, gamma: 1.02, contrast: 1, cool: 0.02, split: 200 } },
  2128. };
  2129. /** The soft copy's blur: px at 1080p (scaled to the plate's width). */
  2130. export const PLATE_SOFT = 40;
  2131. /** A plate's name as the CLI takes it: clouds, night-city or nightCity. */
  2132. export const plateName = (s) => { const k = String(s || '').replace(/-([a-z])/g, (_, c) => c.toUpperCase()); return PLATES[k] ? k : null; };
  2133. /** The ffmpeg filter of a plate's grade: the look's filter, then the warm drain and the colour scale before the last format. Pure. */
  2134. /** The split hue a plate takes from the film's accent: the accent's own when it is a blue or teal (OKLCH 195-266, the
  2135. * worlds' plate window), else the preset's cool split, so a green, red or yellow brand never tints its sky. Pure. */
  2136. export function plateSplitHue(name, accent = null) {
  2137. const g = PLATES[name].grade;
  2138. if (!accent || !/^#[0-9a-f]{6}$/i.test(accent)) return g.split ?? null;
  2139. const [, C, h] = hexToOklch(accent);
  2140. return C >= 0.04 && h >= 195 && h < 266 ? h : (g.split ?? null);
  2141. }
  2142. export function plateFilter(name, { stats = null, crop = null, width = 2400, accent = '#2f7d8c', filmAccent = null, strength = 1, hueSat = true, video = false } = {}) {
  2143. const g = PLATES[name].grade;
  2144. const vf = gradeFilter(g.look, { accent, splitHue: plateSplitHue(name, filmAccent), stats, crop, width, grain: 0.12, video, strength, hueSat });
  2145. const extra = [];
  2146. if (g.warm) extra.push(hueSat ? `huesaturation=saturation=${f3(Math.max(-1, g.warm * strength))}:colors=r+y` : `eq=saturation=${f3(1 + g.warm * 0.3 * strength)}`);
  2147. const eq = [];
  2148. if (g.sat !== undefined && g.sat !== 1) eq.push(`saturation=${f3(1 + (g.sat - 1) * strength)}`);
  2149. if (g.gamma && g.gamma !== 1) eq.push(`gamma=${f3(1 + (g.gamma - 1) * strength)}`);
  2150. if (g.contrast && g.contrast !== 1) eq.push(`contrast=${f3(1 + (g.contrast - 1) * strength)}`);
  2151. if (eq.length) extra.push(`eq=${eq.join(':')}`);
  2152. if (g.cool) {
  2153. const c = g.cool * strength; // blue into the shadows, less into the mids, a trace into the highlights
  2154. extra.push(`colorbalance=rs=${f3(-c)}:bs=${f3(c)}:rm=${f3(-c * 0.75)}:bm=${f3(c * 0.6)}:rh=${f3(-c * 0.35)}:bh=${f3(c * 0.25)}`);
  2155. }
  2156. const tail = video ? ',format=yuv420p' : ',format=rgb24';
  2157. return `${vf.endsWith(tail) ? vf.slice(0, -tail.length) : vf}${extra.length ? `,${extra.join(',')}` : ''}${tail}`;
  2158. }
  2159. /**
  2160. * The source `plate <name> --pick` just fetched into `dir`: get names it from `--name <name>-source` as a slug (lower
  2161. * case: nightCity -> nightcity-source.jpg) and keeps an earlier pick of another picture beside it (sky-source-2.jpg), so
  2162. * the newest file of that stem is the pick to grade, never the first one found.
  2163. */
  2164. export function plateSource(dir, name) {
  2165. const stem = slug(`${name}-source`, 6);
  2166. const re = new RegExp(`^${stem}(?:-\\d+)?\\.(?:jpe?g|png|webp|avif|gif|mp4|webm|mov)$`, 'i');
  2167. const found = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => re.test(f)).map((f) => path.join(dir, f)) : [];
  2168. return found.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0] ?? null;
  2169. }
  2170. async function cmdPlate(args) {
  2171. const name = plateName(args._[0]);
  2172. if (!name) throw new Usage(`plate needs a preset: ${Object.keys(PLATES).join(', ')}`);
  2173. const P = PLATES[name];
  2174. const kind = args.kind === 'video' ? 'video' : P.kind;
  2175. const to = path.resolve(args.to || path.join('public', 'plates'));
  2176. const saved = path.join('out', 'assets', `plate-${name}${kind === 'video' ? '-video' : ''}.json`);
  2177. const self = fileURLToPath(import.meta.url);
  2178. const run = (argv) => spawnSync(process.execPath, [self, ...argv], { stdio: 'inherit' }).status ?? 1;
  2179. let file = args.from && !/\.json$/i.test(args.from) ? path.resolve(args.from) : null;
  2180. if (!file && !args.pick) {
  2181. const query = args._[1] || P.queries[0];
  2182. console.log(`plate ${name}: ${P.what}\n searching "${query}" (${kind}); other searches: ${P.queries.filter((q) => q !== query).map((q) => `"${q}"`).join(', ')}`);
  2183. const code = run(['search', query, '--kind', kind, '--orientation', 'landscape', '--min-width', '1900', '--no-people', '--clean', '--limit', args.limit || '8', '--out', saved]);
  2184. if (code !== 0) return code;
  2185. run(['sheet', saved, '--cols', '4', '--cell', '360', '--out', saved.replace(/\.json$/, '.png')]);
  2186. console.log(`\nLook at the sheet, choose for light and depth (a calm area where type and glass will sit), then:\n node scripts/assets.mjs plate ${name} --pick <n> --to ${path.relative(process.cwd(), to) || '.'}`);
  2187. return 0;
  2188. }
  2189. if (!file) {
  2190. const from = args.from || saved;
  2191. if (!fs.existsSync(from)) throw new Usage(`no saved search ${from}: run plate ${name} first`);
  2192. fs.mkdirSync(to, { recursive: true });
  2193. const code = run(['get', `#${String(args.pick).replace(/^#/, '')}`, '--from', from, '--to', to, '--name', `${name}-source`, ...(kind === 'video' ? ['--res', '1080'] : ['--width', '3200'])]);
  2194. if (code !== 0) return code;
  2195. file = plateSource(to, name);
  2196. if (!file) throw new Error(`get wrote no ${slug(`${name}-source`, 6)} file in ${to}`);
  2197. }
  2198. if (!ffmpegOk()) throw new Error('plate needs ffmpeg and ffprobe on the PATH');
  2199. const p = probeFile(file);
  2200. if (!p) throw new Error(`${file}: not an image or clip ffprobe can read`);
  2201. const video = !p.still;
  2202. const [fx, fy] = args.focus ? String(args.focus).split(',').map(Number) : P.focus;
  2203. const crop = focusCrop(p.width, p.height, 16 / 9, fx, fy);
  2204. const width = Math.min(Math.round(num(args, 'width', video ? 1920 : 2400, 640, 3840)), crop.w) & ~1;
  2205. const accent = args.accent && /^#[0-9a-f]{6}$/i.test(args.accent) ? args.accent : '#2f7d8c';
  2206. const vf = plateFilter(name, { stats: measure(file), crop, width, accent, filmAccent: args.accent ? accent : null, strength: num(args, 'strength', 1, 0, 1.5), hueSat: hasHueSat(), video });
  2207. fs.mkdirSync(to, { recursive: true });
  2208. const out = path.join(to, `${name}.${video ? 'mp4' : 'jpg'}`);
  2209. if (video) ff(['-i', file, '-an', '-filter_complex', `[0:v]${vf}[v]`, '-map', '[v]', ...videoEncode({}), '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-movflags', '+faststart', '-y', out], `plate ${name}`);
  2210. else ff(['-i', file, '-filter_complex', `[0:v]${vf}[v]`, '-map', '[v]', '-frames:v', '1', '-q:v', '2', '-y', out], `plate ${name}`);
  2211. const inPublic = publicPath(out) !== null;
  2212. const pub = publicPath(out) ?? `plates/${path.basename(out)}`;
  2213. console.log(`Plate ${path.relative(process.cwd(), out)} · ${PLATES[name].grade.look}, warm light drained · crop ${crop.w}x${crop.h} at ${crop.x},${crop.y}`);
  2214. if (!video) {
  2215. const soft = path.join(to, `${name}-soft.jpg`);
  2216. const sigma = (PLATE_SOFT * width) / 1920 / 2;
  2217. ff(['-i', out, '-vf', `gblur=sigma=${f3(sigma)}:steps=3`, '-frames:v', '1', '-q:v', '3', '-y', soft], `plate ${name} soft`);
  2218. console.log(` ${path.relative(process.cwd(), soft)} · blurred ${PLATE_SOFT} px at 1080p (frosted glass and the far depth)`);
  2219. if (!inPublic) console.log(` copy ${path.basename(out)} and ${path.basename(soft)} into public/plates (they are outside public/), then:`);
  2220. console.log(` use <World kind="${name}" src={staticFile('${pub}')} soft={staticFile('${publicPath(soft) ?? `plates/${path.basename(soft)}`}')}>`);
  2221. } else {
  2222. const soft = path.join(to, `${name}-soft.mp4`);
  2223. const sigma = PLATE_SOFT / 2 / 2; // at 960 px wide: the same blur as the photo's soft copy at 1080p
  2224. ff(['-i', out, '-an', '-vf', `scale=960:-2,gblur=sigma=${f3(sigma)}:steps=3,format=yuv420p`, ...videoEncode({}), '-movflags', '+faststart', '-y', soft], `plate ${name} soft`);
  2225. console.log(` ${path.relative(process.cwd(), soft)} · 960 px, blurred ${PLATE_SOFT} px at 1080p (frosted glass over a clip)`);
  2226. if (!inPublic) console.log(` copy ${path.basename(out)} and ${path.basename(soft)} into public/plates (they are outside public/), then:`);
  2227. console.log(` use <World kind="${name}" src={staticFile('${pub}')} soft={staticFile('${publicPath(soft) ?? `plates/${path.basename(soft)}`}')}>`);
  2228. }
  2229. if (args['no-check']) return 0;
  2230. return pictureCheck([{ file: out, video }], args.accent ? accent : null, {});
  2231. }
  2232. export const USAGE = `assets.mjs: photographs, footage, textures and art a film may use without credits.
  2233. search "<query>" [--kind photo|video|texture|art] [--source all|${Object.keys(SOURCES).join(',')}]
  2234. [--orientation landscape|portrait|square] [--min-width 1600] [--colour mono|blue|teal|#hex]
  2235. [--people | --no-people] [--clean] [--fit 4:5] [--no-vet]
  2236. [--limit 8] [--allow-credit] [--out out/assets/<name>.json] [--json] [--no-check]
  2237. (the vet reads every thumbnail: people, text or a watermark, soft pictures; --people keeps pictures with
  2238. people, --no-people drops them, --clean drops text, signs and logos, --fit keeps pictures that hold
  2239. --min-width px after a crop to that shape; the sheet marks P people, T text, soft)
  2240. sheet <results.json> [--pick 1,4,7] | <files or folders> [--scan 6] [--cols 4] [--cell 400] [--out sheet.png]
  2241. get <ref|#n>[,...] --to <film>/public/assets [--from results.json] [--name stem] [--width 2400]
  2242. [--res 1080] [--trim start,seconds] [--max-mb 150] [--allow-credit] [--record path]
  2243. recipe [<the product's input in your words>] [--run] [--kind video|photo] [--limit 6] [--out file] [--json] [--verify]
  2244. (the core action shown literally: 40 inputs, from speaking into a phone to a parcel at the door, each with
  2245. its framing, the screen that takes the UI plate and its searches; 34 also hold clips and photos already
  2246. looked at (the rest run their searches at once); saves them as a results file for sheet and get #n;
  2247. --run searches every line again; --verify reads each pick again at its source; no input lists them all;
  2248. recipe all --verify checks every pick)
  2249. plate <${Object.keys(PLATES).join('|')}> ["<query>"] [--kind photo|video] [--to public/plates] [--pick n | --from <file>]
  2250. [--accent #hex: a blue or teal accent tints the split] [--focus x,y] [--width 2400] [--strength 0..1.5] [--limit 8]
  2251. (the picture a world stands on: searches the preset and saves a sheet; --pick n or --from <photo or clip>
  2252. writes <name>.jpg graded for the world, warm light drained, 16:9 on the focus, and <name>-soft.jpg blurred
  2253. ${PLATE_SOFT} px at 1080p for frosted glass and the far depth)
  2254. grade <files or folders> [--look ${Object.keys(LOOKS).join('|')}] [--strength 0..1.5] [--chroma 0.2..1.5]
  2255. [--accent #hex] [--split-hue deg|#hex] [--focus x,y] [--aspect 16:9|none] [--width 2400] [--grain 0..1]
  2256. [--out dir] [--trim start,seconds] [--speed 1] [--scrub] [--dry-run] [--no-check] [--brand-supplied] [--arc]
  2257. (natural is the default and keeps the pictures' colour; --strength: how far toward the look, 0 = the
  2258. picture as it is; --chroma: the colour after it; a graded set keeps >= 30 % neutral pixels and no banned
  2259. colour region; --split-hue: the shadows' hue in natural, matte and night, cool by default and apart from
  2260. --accent; --scrub: every frame a key frame, for a clip the film's clock drives)
  2261. check <files or folders> [--accent #hex] [--brand-supplied] [--arc] [--no-text] (the picture check grade runs,
  2262. on any set: neutral floor, banned colours, saturated floor, the set's match, readable text and logos;
  2263. --arc: the set tells a day, morning to night, so each picture is matched with the pictures of its light)
  2264. probe <files> [--json] looks licences [--to <film>/public/assets]
  2265. Refs: #n from the last search, or <source>:<id> as search prints it (a ref is looked up in the saved searches
  2266. under out/assets/; a Mixkit or Coverr ref needs one, or --from); a known work by name or number also works:
  2267. commons:File:<file name>, met:<object id>, aic:<artwork id>, nasa:<nasa id>, burst:<slug>, isorepublic:<slug>.
  2268. Keyless: Burst and ISO Republic (stock photos: people, products, places), Coverr and Mixkit (stock video, free
  2269. clips only), Openverse (cc0 / public domain), Wikimedia Commons (public domain / CC0), NASA, the Art Institute of
  2270. Chicago and the Met (CC0). With a key in the environment: PEXELS_API_KEY, UNSPLASH_ACCESS_KEY, PIXABAY_API_KEY.
  2271. Default licences need no credit; --allow-credit adds CC BY. Refused: share-alike, non-commercial, no-derivatives,
  2272. Mixkit restricted, Coverr+, AI-generated clips, unknown.
  2273. --help, -h print this help`;
  2274. export async function main(argv) {
  2275. let args;
  2276. try { args = parseArgs(argv); } catch (e) { console.error(`${e.message}\n\n${USAGE}`); return 2; }
  2277. const cmd = args._.shift();
  2278. if (args.help || !cmd || cmd === 'help') { console.log(USAGE); return cmd || args.help ? 0 : 2; }
  2279. try {
  2280. switch (cmd) {
  2281. case 'search': return await cmdSearch(args);
  2282. case 'sheet': return await cmdSheet(args);
  2283. case 'get': return await cmdGet(args);
  2284. case 'grade': return await cmdGrade(args);
  2285. case 'probe': return cmdProbe(args);
  2286. case 'check': return cmdCheck(args);
  2287. case 'looks': return cmdLooks();
  2288. case 'licences': case 'licenses': return cmdLicences(args);
  2289. case 'recipe': case 'recipes': return await cmdRecipe(args);
  2290. case 'plate': case 'plates': return await cmdPlate(args);
  2291. default: throw new Usage(`unknown command ${cmd}: search, sheet, get, recipe, plate, grade, check, probe, looks, licences`);
  2292. }
  2293. } catch (e) {
  2294. if (e instanceof Usage) { console.error(`${e.message}\n\n${USAGE}`); return 2; }
  2295. console.error(`assets.mjs: ${redact(e.message)}`); return 1;
  2296. }
  2297. }
  2298. if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
  2299. main(process.argv.slice(2)).then((code) => process.exit(code));
  2300. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.