@higgsfield/video-editor-mcp 1.0.7 → 1.1.1-dev.0

package/node_modules/@higgsfield/higgsedit/README.md

@@ -1,3 +1,183 @@
 # higgsedit
 
-The `higgsedit` CLI bundled with @higgsfield/video-editor-mcp.
+Make videos in code. A higgsedit project is a folder with an `index.tsx` file: the scenes, clips, titles and
+music are elements in that file. `higgsedit` checks the project, previews any frame, edits it and renders it to MP4.
+
+```sh
+npx @higgsfield/higgsedit init my-video
+cd my-video && npm install
+npm run render            # writes renders/out.mp4
+```
+
+## Install
+
+```sh
+npm install -g @higgsfield/higgsedit     # adds the `higgsedit` command
+npx @higgsfield/higgsedit <command>      # or run it without installing
+```
+
+You need **Node 22.12+** and **ffmpeg** (`brew install ffmpeg` or `apt install ffmpeg`). Headless Chrome
+(about 100 MB) downloads by itself the first time you render. Run `higgsedit doctor` to check your setup.
+
+## A project
+
+`higgsedit init my-video` creates:
+
+```
+my-video/
+  index.tsx        the video
+  media/           your footage, music and pictures
+  package.json     npm run dev | check | typecheck | render
+  tsconfig.json
+  README.md
+```
+
+`index.tsx` looks like this:
+
+```tsx
+export default function Project() {
+  return (
+    <stage id="stage">
+      <scene id="scene" width={1080} height={1920} fps={30} fill="#0b0c0e">
+        <video id="clip" src="./media/intro.mp4" end={8} />
+        <text id="title" y={800} width={1080} end={5} fontSize={96} fontWeight={700} align="center" fill="#ffffff">
+          Hello
+        </text>
+      </scene>
+    </stage>
+  );
+}
+```
+
+Every element has an `id`, which is how the editor and `higgsedit edit` find it. Run `higgsedit stamp .` to
+add any that are missing.
+
+## Times
+
+Commands that take a time accept seconds (`2.5`), frames (`48f`) or minutes and seconds (`0:05`). Some, such as
+`media grab -t`, also take a negative frame count (`-1f`) for the end of the file.
+
+## Commands
+
+Run `higgsedit` with no arguments to print them all. `<dir>` is your project folder (`.` for the current one).
+
+### Start and check
+
+| Command | What it does |
+|---|---|
+| `higgsedit init <dir> [--size 1080x1920] [--fps 30]` | Create a new project. Existing files are kept. |
+| `higgsedit check <dir>` | Compile and load the project, then report errors. |
+| `higgsedit outline <dir>` | Print the element tree: ids, timing and props. |
+| `higgsedit stamp <dir>` | Add an `id` to every element that lacks one. |
+| `higgsedit doctor` | Check ffmpeg, Chrome, Node and the optional tools. |
+| `higgsedit version` | Print the version. |
+
+### Preview
+
+| Command | What it does |
+|---|---|
+| `higgsedit frame <dir> <time> -o frame.png` | Render one frame to a PNG. |
+| `higgsedit sheet <dir> --times 0,15f,0:05 -o sheet.png [--columns 4] [--width 480]` | Render several frames side by side on one image. |
+| `higgsedit dev <dir> [--port 4173]` | Start the editor server for the project. It reloads when you save `index.tsx`, and edits made in the editor are written back into the file. |
+
+### Render
+
+```sh
+higgsedit render <dir> -o out.mp4
+```
+
+| Option | Default | |
+|---|---|---|
+| `--from <time>`, `--to <time>` | whole video | Render only part of it. |
+| `--crf <n>` | `18` | Quality: lower is better and bigger. |
+| `--preset <name>` | `fast` | Encoder speed preset. |
+| `--encoder x265\|x264\|videotoolbox\|webcodecs` | | Which encoder to use. |
+| `--depth 10` | | 10-bit color. |
+
+`higgsedit verify <dir>` checks that every frame renders the same however it is visited: in order, or shuffled.
+
+### Edit from the command line
+
+`higgsedit edit` changes `index.tsx` for you, finding the element by its `id`.
+
+```sh
+higgsedit edit . title set-text "Summer trip"
+higgsedit edit . title set-prop '{"fill": "#ffcc00"}'
+higgsedit edit . clip retime '{"start": "0:02", "end": "0:10"}'
+higgsedit edit . scene insert '{"tag": "rect", "props": {"width": 200, "height": 200, "fill": "#ff0000"}}'
+#   ok  index.tsx:8 (rect-3ckv)  new id rect-3ckv
+higgsedit edit . rect-3ckv move '{"parent": "scene", "before": "title"}'
+higgsedit edit . rect-3ckv remove '{}'
+```
+
+| Operation | JSON |
+|---|---|
+| `set-text` | the new text, as a bare word or a JSON string |
+| `set-prop` | `{"<prop>": value}` or `{"name": "<prop>", "value": value}` |
+| `retime` | `{"start": time, "end": time}` (either one) |
+| `insert` | `{"tag": "rect", "props": {...}, "text"?: "...", "before"?: "<id>"}`, inserted into the element you name. It prints the new element's `id`. |
+| `move` | `{"parent": "<id>", "before"?: "<id>"}` |
+| `remove` | `{}` |
+
+Values marked with `@inspect` in the source are changed by name: `higgsedit edit <dir> <name> set-const <value>`.
+`higgsedit outline` lists the names.
+
+### Footage
+
+| Command | What it does |
+|---|---|
+| `higgsedit media probe <file>` | Show the container, duration and codecs. |
+| `higgsedit media grab <file> -t 0,1.5,-1f` | Save frames as contact sheets. Use `-c 6` for 6 evenly spaced frames, or `-S` for one PNG each. |
+| `higgsedit media filmstrip <file> [-s <time>] [-e <time>]` | Make a thumbnail strip with a timecode ruler. |
+| `higgsedit media waveform <file> [--silence-db -40]` | Draw the loudness and list the silent parts, to find cut points. |
+| `higgsedit transcribe <file> -o words.json [--language en]` | Make a word-timed transcript for captions. Needs `mlx_whisper` installed. |
+
+Add `--json` to any `media` command for machine-readable output. `higgsedit media help` lists every option.
+
+### Cut out objects (masks)
+
+| Command | What it does |
+|---|---|
+| `higgsedit segment <file> --point x,y -o person.mask` | Track an object you click on through the clip (SAM 2.1). The model downloads on first use. |
+| `higgsedit select <file> --at <time> --text "dog, ball"` | Find objects in one frame by name or by point. Needs a select server (`HIGGSEDIT_SELECT_URL`). |
+
+Narrow the selection with more `--point x,y`, `--exclude x,y` or `--box x0,y0,x1,y1`, and set the range with
+`--start <time>` and `--end <time>`. Use the result as a mask: `mask={{ src: "./media/person.mask" }}`.
+
+### Fonts and presets
+
+| Command | What it does |
+|---|---|
+| `higgsedit fonts [name] [--category serif] [--cached]` | Search Google Fonts for `<text fontFamily>`. Downloaded fonts also render offline. |
+| `higgsedit presets` | List installed motion presets. The editor's Presets panel inserts them. |
+| `higgsedit presets install <pack-dir>` | Install a preset pack. |
+
+If a font can't be loaded, `frame`, `sheet`, `render` and `verify` stop with an error. Add
+`--allow-font-fallback` to render with a fallback font instead.
+
+The dev editor saves Undo/Redo across restarts in `.higgsedit-cache/history.json`. History retains up
+to 100 edits and 16 MiB in total, trimming oldest entries; a single edit larger than that limit is
+refused. Keep one dev server per project. Undo refuses files changed outside the editor; reopen the
+project if another editor has changed its history.
+
+Requires Node 22.12+ and ffmpeg. Headless Chrome (~100 MB) downloads into `~/.higgsedit-next/chrome` on first
+use (`HIGGSEDIT_HOME` moves that folder, `HIGGSEDIT_NEXT_CHROME` points at a browser of your own).
+
+## Settings
+
+| Variable | |
+|---|---|
+| `HIGGSEDIT_HOME` | Where Chrome, models and presets are kept. Default: `~/.higgsedit-next`. |
+| `HIGGSEDIT_NEXT_CHROME` | Use your own Chrome instead of downloading one. |
+| `HIGGSEDIT_FFMPEG`, `HIGGSEDIT_FFPROBE` | Paths to ffmpeg and ffprobe if they aren't on your `PATH`. |
+| `HIGGSEDIT_PRESETS_DIR` | Where `dev` and `presets` look for presets. |
+| `HIGGSEDIT_SELECT_URL`, `HIGGSEDIT_SELECT_TOKEN` | The server `select` uses. |
+
+
+Media imports stream to a private temporary file, then publish atomically without replacing existing
+files. Both direct HTTP imports and the MCP editor use the same limits: 8 GiB per file, four active
+uploads, a 60 second idle timeout and a 30 minute total timeout. Override these with positive integers
+in `HIGGSEDIT_MEDIA_MAX_BYTES`, `HIGGSEDIT_MEDIA_MAX_CONCURRENT`, `HIGGSEDIT_MEDIA_IDLE_MS` and
+`HIGGSEDIT_MEDIA_TOTAL_MS`. Failed, cancelled and timed-out uploads are removed. On drives without hard
+links (for example exFAT), imports use a unique `media/import-XXXXXX/` directory; the editor lists them
+alongside ordinary media files. Symlinked media directories are refused.