Properties and tags
The schema behind a library: property types, tags and their descriptions, who fills what, and how to edit them.
Properties describe clips the way you think about them. The same words are the vocabulary the AI is allowed to use and the words Ask plans against.
Five property types
| Type | Holds | Example |
|---|---|---|
| Multi-select | Any number of tags per clip | Exercise: Squat, Deadlift |
| Single-select | One tag per clip | Shot type: Wide |
| Yes / No | Yes, No, or not set | Face visible |
| Scale · 1 to 5 | A number, drawn as stars, hearts, flames, bolts, dumbbells, dots or a plain number | Rating |
| Text | A line, or a paragraph | Notes |
A select property can switch between multi and single at any time. The other types are fixed once created.
Built in
Two properties come with every library and cannot be removed:
- Tags, a multi-select bucket for loose keywords. A bare tag typed without a property lands here. Delete a property and its tags move here instead of disappearing.
- Rating, a 1 to 5 scale you rate yourself. The first scale property in the sidebar order is the one the cards draw as glyphs.
The Description is part of every clip and is the one field AI tagging always fills.
AI or manual
Each property is filled by the AI or by you. An AI property is filled by the model on every tagging pass, in place of what was there. A manual property is never read or written by the AI: only people and the command line change it. Scales default to manual.
Manual properties carry a small hand mark wherever they appear. Client, Location, Approved: anything only a person knows belongs here.
Descriptions steer the model
Every property and every tag has a description. It is shown as a tooltip, read by the meaning index, and sent to the model as the rule for when the tag applies. Write it as criteria, for a stranger:
- Good: "Any indoor training space with equipment in frame."
- Weak: "Gym stuff."
The model can only choose from the tags you defined. It cannot invent one.
The Properties tab
Library › Manage Properties… (⇧⌘T) opens Settings › Properties. Properties are on the left, the selected property's tags on the right.
| To | Do |
|---|---|
| Add a property | New Property… : name, type, manual or not, description, the scale's shape, one line or paragraph for text |
| Edit a property | Double-click it, or Edit… above its tags |
| Reorder properties | Reorder…, or drag in the list. This is the order in the sidebar and in every panel. |
| Delete a property | Delete. Its tags move to Tags; yes/no, scale and text values are dropped. |
| Add a tag | Type in the field under the table and press ↩ |
| Edit a tag | Double-click it, or Edit…: name, property, colour, description |
| Move tags | Drag them from the table onto a property on the left |
| Merge tags | Select two or more, click Merge…, pick the one to keep. Every clip carrying any of them ends up with the survivor. |
| Delete tags | Select them and press ⌫ or Delete. The dialog says how many clips lose the tag. |
The property's own description is a text box above its tags, saved as you type.
Properties as files
The menu at the top of the Properties tab has Export Properties… and Import Properties….
Export writes a folder with properties.jsonc and an INSTRUCTIONS.md: every property, its tags, every description, and the ids the app uses. Edit the file by hand or hand it to an agent.
Import reads an edited file and shows a preview of every rename, new tag, move, merge and deletion before it applies. A file that drops an id without saying what to do with it is refused, with every problem listed and a Copy Problems button.
The command line does the same with properties export and properties import --dry-run. See The command line.
Six ways to apply a tag
- Type in the inspector's Search or add… field. An unknown name is created on the fly in that property.
- Drag clips onto a tag in the sidebar.
- Drag clips onto a saved view. See Filters and views.
- Set it for a whole batch in the import sheet.
- Bulk edit a selection with ⌘E.
- From the terminal:
betterlibrary clips tag <id> --add "Property:Tag".
A single-select property keeps one tag per clip. Adding one removes the other.
The sidebar
Every property lists its tags with how many clips on the current shelf carry each. Click a tag to show those clips. A yes/no property lists Yes and No. A scale lists 5, 4 & up and 3 & up. Text properties have nothing to browse and do not appear.
Right-click a tag for Rename…, Color, Move to Property and Delete Tag, and, with clips selected, Tag N Selected Clips. Right-click a property for New Tag in…, Rename Property… and Delete Property.