git:20261012.07545cf to git:20261015.07749c7

- description: Grow and look after the user's BashCut library — make a missing preset, effect, transition, look, sticker or sound when nothing in the library fits (write it with library add, try it on a clip, undo, save), harvest what is worth keeping after an edit (a grade, an effect, a transition, a sound, a sticker), and fix, copy or prune saved items. Use when the user says something is missing ("thiếu hiệu ứng", "không có cái nào hợp", "tạo preset", "làm cho tôi một …"), asks to keep something for later ("lưu lại", "dùng lại lần sau", "để dành"), when an edit is finished ("xong rồi", "làm xong video"), or when the library has unused or duplicate items.

- Reply in the user's language. The library holds reusable items in eight kinds: `text-preset`, `sticker`,

- `effect-preset`, `transition-preset`, `look`, `audio`, `voice` and `clip` (footage). Items live in four scopes, searched in this

- order: the project (`.bashcut/library`), this Mac (`user`), plugin packs, built-ins. Built-in and plugin items are

- read-only.

- Scope rules:

- - `--scope user` (every project on this Mac) waits for the user's approval in the app. Offer it for things the

- user will clearly want again (their channel's grade, their outro sound), and say it needs their click.

- - With a `[Scope]` (Send to Agent), trying an item on the timeline stays inside the scoped items

- (`bc:edit-workflow`).

- The user wants an effect, transition, look, text style, sticker or sound, and nothing fits.

-

- 1. **Check first.** `bashcut library list --kind effect-preset --query "shake"` (also `--tag`, `--pack`).

- A close item with other numbers is not missing: apply it with `--set`, or copy it with

- `library update ID --as NEW_ID` and change the copy.

- 2. **Ask a plugin.** When a provider is installed: `bashcut library search "camera shutter" --kind audio` or

- `bashcut library generate "gold star burst" --kind sticker --request-id sticker-star-1` (jobs; `jobs wait`

- until done lists candidates with their preview, source and licence; a paid provider: `--dry-run` first). Show the candidates, check the licence, then

- `bashcut library add --from-result JOB:N`. No provider (`capabilities get library.generate --kind sticker` says why): say so; installing or turning one on

- is the user's job.

- 3. **Build it on the timeline, then save it.** This is the most reliable way: make the effect with the usual

- commands (`bc:effects`, `bc:color-grade`, `bc:audio-mix`, `bc:captions-text`), let the user approve, then

- `bashcut library save-selection --kind effect-preset --name "Food reveal" --item CLIP`.

- 4. **Write it with `library add`** when the item is a recipe you can describe in numbers (below), or from a

- file you were given or made (a `.cube` LUT, a PNG, an audio file).

- 5. **Try it before you call it done.** `library apply` or `library place` it on a real clip, read the result with

- `ui frame F` (several frames for motion), ask the user to listen for sound, then `timeline undo` unless they

- want to keep it. A wrong value: `library update ID --params '{...}'` (a new version).

- `library get ID` on a built-in shows a working example of every kind. Frames are timeline frames.

- **effect-preset**: a recipe of up to 32 steps run in order on the clip, with up to 16 named parameters the user

- can change on apply (`--set name=value`). A step value `"$name"` takes the parameter. Positions are `t` (0 = first

- frame, 1 = last, so the effect scales with the clip) or `frame` (negative counts from the end).

- | `motion` | `preset` (as `clip motion --preset`), or `focus` `[x, y, w, h]` (fractions of the picture) with `focusTo`, `ease` |

- | `keyframes` | `keys` `{property: [{t or frame, value, ease}]}`: zoom, pan, tilt, rotation, opacity; ease linear, in, out, inOut, hold |

- | `speed` / `speedCurve` | `speed`, `keepDuration`; `preset` or `points` `[[t, speed], …]` |

- **transition-preset**: `kind` (dissolve, whip, blink, zoom, spin, shutter, wipe, swing, glitch, halftone), `duration` in frames (1–600),

- `easing` (linear, in, out, inOut), `sfx` (an audio item ID) or the preset's own sound as `--file`.

- **look**: `{"color": {"exposure", "contrast", "saturation", "lutStrength"}}` with an optional `.cube` as `--file`

- (make one with `grade.py` in `bc:color-grade`; look at its preview first).

-

- ```sh

- bashcut library add --kind look --name "Warm market" --file /abs/project/luts-src/warm.cube --params '{"color": {"contrast": 1.05, "lutStrength": 0.85}}'

- ```

- **audio**: needs `--file`. `library add` measures the length and picks music or sfx by it; then

- `bashcut library analyze ID` (job) fills BPM and loudness. Tag mood and use (`calm`, `whoosh`, `outro`) after

- the user listened (`library preview ID`). Set `{"loopable": true}` only for a bed that loops without a click.

- **sticker**: an emoji (`{"emoji": "🎉", "textPreset": "bold-outline"}`), or a file: PNG/WebP with transparency,

- or a `.mov` with alpha (HEVC alpha or ProRes 4444), with optional `size` (width, 0.01–1 of the frame), `position`

- and `animation` (a clip motion preset). GIFs place as their first frame for now; Lottie is not supported. Pictures

- from the web: `bc:stock-images`.

- **clip**: footage kept for reuse, a B-roll shot or a still (`.mov`/`.mp4`/`.m4v` or an image) via `--file`;

- `library add` measures `seconds`, `width`, `height` and `hasAudio`, and any other params (a generator's `model`,

- `prompt`) are kept. `library place ID --track OVERLAY --at-frame F --duration N` copies it into the project's

- `clips/` and places it like `media place` (main layer by default). Generated ones come from `library generate

- "<shot>" --kind clip` when a provider serves it: `bc:stock-images`.

- **text-preset**: `{"textPreset": "<built-in renderer preset>", "text": "sample", "textStyle": {"size": 0.07,

- "positionY": 0.62, "strokeWidth": 6, "font": "Montserrat-ExtraBold", "fill": "#FFD400", "stroke": "#000000"},

- "animation": "pop-in"}`; `textStyle` (`size`, `positionY`, `strokeWidth`, `font`, `fill`, `stroke`, `highlight`,

- with the item property rules) and `animation` (a clip motion preset) are optional. `save-selection` keeps the item's

- size, position, outline, font, colours and its motion preset (hand-made keys are dropped); place and apply set them

- back. A font from a project's `fonts/` folder is not copied with the preset: `fonts import` it in the next project

- **brand**: a channel's kit, every field optional: `palette` {accent, background, text, secondary} `#RRGGBB`,

- `fonts` {heading, body}, `logo` and `mascot` {pose: id} as sticker items (add the user's own images as stickers

- first), `voice` {provider, voice}, `disclosure`. Only from what the user gave or approved (their colours, fonts,

- logo, character); never invent a mascot and present it as theirs. `library apply ID` (no `--item`) puts it on the

- whole project and restyles text whose `brandRoles` tie it to the kit.

- bashcut library apply acme --base-rev last

- Give every item a clear English `--name` (the ID comes from it), `--tags` for mood and use, `--pack` when it

- belongs to a set (the user's channel name); `--source` only when you have it.

- When the edit is done (after review, before or after export), look for work worth keeping. Do not save silently.

- 1. Read `timeline get` and list the candidates:

- - the same transition kind and length used at 3+ cuts → `transition-preset`;

- 2. Skip what came from the library already (you applied or placed it), one-off fixes (a crop for one bad

- shot) and anything the user complained about.

- 3. `bashcut library list --kind K` and `bashcut library stats --kind K`: skip a candidate that duplicates a saved

- item; when it improves one, propose `library update ID` instead of a new item.

- 4. Propose a short list (at most five), each with a name, kind, scope and why it is reusable, e.g.

- "Look *Warm market* (project): the grade you approved for all 14 clips." Then save only what they say yes to:

-

- ```sh

- bashcut library save-selection --kind look --name "Warm market" --item ADJUSTMENT --tags warm,food

- bashcut library save-selection --kind audio --name "Market ambience" --item CLIP --tags ambience,market

- bashcut library save-selection --kind transition-preset --name "Snap whip" --item CLIP --scope user

- ```

- - **Correction.** The user changed an item's result by hand, or undid it right after `library apply` /

- `library place`: propose `bashcut library update ID --params '{...}'` (a new version; the old one stays in its

- history). Built-in or plugin: `bashcut library update ID --as NEW_ID`, and record a preference to use the copy.

- - **Wrong place.** `bashcut library move ID --to user` (approval) or `--to project`.

- - **Prune.** `bashcut library stats` lists saved items nobody used and duplicates (same kind and content). At the

- end of a session offer to remove or merge them; never remove without a yes:

- `bashcut library remove ID` (user scope waits for approval). Removing keeps files the timeline still uses.

- - **Share.** `bashcut library export-pack --output /abs/packs/my-channel --pack "My channel"`; the other side runs

- `bashcut library import-pack /abs/packs/my-channel --scope user`.