← PicsartCONTENT HISTORY

Update to Picsart

Snapshot Nov 11, 2026 · 00:08 UTC · version 2.5.0

Collection source: downloaded plugin package.

WHAT CHANGED

Instructions updated for edit-on-your-computer

Skill instructions — Now says: reference, since no single hue figure survives a frame whose colours sit either side of red. At the look stage the same reading, with `YLOW` (the black...

Observed in instructions or declared skills. Runtime behavior has not been tested.

Save Picsart and check future changes in Following.

Up to 3 plugins free · no card required.

All fields and original values.

Skill instructions

Before

Nov 7, 2026 · 00:09 UTC

reference, since no single hue figure survives a frame whose colours sit either side of red. A

After

Nov 11, 2026 · 00:08 UTC

reference, since no single hue figure survives a frame whose colours sit either side of red. At the look stage the same reading, with `YLOW` (the black point) and `YHIGH` (the white point) added to the `grep`, is taken on the board's sti...

Supporting files

Before

Nov 7, 2026 · 00:09 UTC

[{"relative_path":"scripts/captions_ass.py","size_in_bytes":3079},{"relative_path":"scripts/gyro.py","size_in_bytes":3337},{"relative_path":"scripts/log_lut.py","size_in_bytes":4420},{"relative_path":"scripts/log_profile.py","size_in_byt...

After

Nov 11, 2026 · 00:08 UTC

[{"relative_path":"scripts/captions_ass.py","size_in_bytes":3079},{"relative_path":"scripts/gyro.py","size_in_bytes":3337},{"relative_path":"scripts/log_lut.py","size_in_bytes":4420},{"relative_path":"scripts/log_profile.py","size_in_byt...

Compare saved observations

Download comparison JSON

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -314,7 +314,9 @@
 set the two side by side. The grade has drifted when either differs by more than about a tenth of
 the reference's value: a draft clearly darker or flatter than the reference. Hue is judged by eye:
 look at a frame of each side by side for a draft warmer, cooler or tinted another way than the
-reference, since no single hue figure survives a frame whose colours sit either side of red. A
+reference, since no single hue figure survives a frame whose colours sit either side of red. At the look stage the same reading, with `YLOW` (the black point) and `YHIGH` (the white point)
+added to the `grep`, is taken on the board's stills and on the same frames in the chosen look;
+edit-footage's `scripts/look_check.py` compares them. A
 drift is fixed at the look, before the review, and said in one line when it is the user's own
 choice; a figure that could not be read is `open`, never a pass. Where ffmpeg is not here, the use
 case compares stills of both by eye instead.
Full technical diff · 2 changed fields

changed /included_files

BEFORE
[
  {
    "relative_path": "scripts/captions_ass.py",
    "size_in_bytes": 3079
  },
  {
    "relative_path": "scripts/gyro.py",
    "size_in_bytes": 3337
  },
  {
    "relative_path": "scripts/log_lut.py",
    "size_in_bytes": 4420
  },
  {
    "relative_path": "scripts/log_profile.py",
    "size_in_bytes": 4128
  }
]
AFTER
[
  {
    "relative_path": "scripts/captions_ass.py",
    "size_in_bytes": 3079
  },
  {
    "relative_path": "scripts/gyro.py",
    "size_in_bytes": 3337
  },
  {
    "relative_path": "scripts/log_lut.py",
    "size_in_bytes": 4420
  },
  {
    "relative_path": "scripts/log_profile.py",
    "size_in_bytes": 5532
  }
]

changed /skill_md_contents

BEFORE
"---\nname: edit-on-your-computer\ndescription: Edit footage on the user's own computer - proxies uploaded instead of the originals, a project folder, and a full-resolution conform with ffmpeg. Use only when the footage is a folder on this machine and you can run commands.\n---\n\n# Edit on your computer\n\nAn edit runs the same way wherever its footage is: the stages, the record and the checks are the\nedit-pipeline skill's. This skill adds only what changes when the footage is on this computer and\nyou can run commands here. Originals are large, and they are the user's masters: they never\nleave this computer and are never changed. What the server reads is small copies.\n\nLoad this skill only when the footage is a folder or paths on disk and the host runs commands.\nFootage given as Picsart Drive files, links or attached files is edited without it. When you\ncannot run commands here after all, open `picsart_drive_upload_ask` for the footage and go on\nwithout this skill; never ask the user to upload it by hand.\n\n## The project folder\n\nKeep everything for one edit in one folder beside the footage, never inside it:\n\n| Path | Holds |\n|---|---|\n| `edit-footage.json` | the record, kept by edit-pipeline's `scripts/record.py` |\n| `proxy/` | the proxies and `manifest.csv` |\n| `work/` | copies you change (a graded file, a conformed master), never an original |\n| `exports/` | each version's draft, and the final files; a new file goes beside an old one |\n\nQuote every path you pass to a command; folder names often have spaces.\n\n## ffmpeg first\n\nEverything below runs on `ffmpeg` and `ffprobe`. Before the proxies, check both:\n`command -v ffmpeg ffprobe`. When either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) how to go on. Recommended first:\n\"Install ffmpeg-full, the full ffmpeg with subtitle support\", saying exactly what: on a Mac with\nHomebrew, `brew install ffmpeg-full` (Homebrew's own formula, with libass for the captions; it\ninstalls beside any other ffmpeg without replacing it, so run it as\n`\"$(brew --prefix ffmpeg-full)/bin/ffmpeg\"` and `.../bin/ffprobe`); elsewhere, a build linked from\nhttps://ffmpeg.org/download.html whose `ffmpeg -filters` lists `subtitles`. The other option: \"Edit\nwithout it: you upload the footage, and the finish is a full-quality export\". **Never install\nanything without the user's yes to this question.** A yes goes into `approvals` with the scope\n`install:ffmpeg` and covers exactly that package, which the captions need too (below), so it is\nnever asked twice. In unattended pace, the assumed answer is the upload, but the upload needs the\nuser: write it to `openDecisions` and stop there. When the install fails or needs an administrator\npassword, say so, offer the upload, and never retry it unasked. On the upload, open\n`picsart_drive_upload_ask` for the footage, leave the `proxies` stage out of the record's pipeline,\nset `finish` to `export`, and go on without this skill.\n\n## Proxies, before anything is analysed\n\nMake a small copy of each source and analyse only those. Read each original's curve first (Log\nfootage, below): a log source's proxy is made through its conversion, not with this command.\n\n\n```\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf scale=-2:720 -c:v libx264 -preset veryfast -crf 23 \\\n  -c:a aac -b:a 128k -fps_mode passthrough -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nA source with no picture, such as a voice-over, needs no proxy: upload it as it is. Each proxy\nkeeps the original's fps, frame count and start timecode. Check that with `ffprobe` on\nboth files.\n\n**Which way is up** is judged here, before the proxy, from one still in the middle of the\noriginal (`ffmpeg -ss <middle> -i \"<original>\" -frames:v 1 \"proxy/<name>.mid.jpg\"`), as the use\ncase's log says. A turned source's proxy is made turned, so everything after it sees it upright:\nits transpose goes first in `-vf`, before the scale (`transpose=1` for `rot90`, `transpose=2`\nfor `rot270`, `hflip,vflip` for `rot180`). Its `upright` goes into its `sources` row; the build\nlays such a proxy as it is and never turns it again. When `upright` is turned but the\nmanifest's `turn` is empty (found after the proxies), the build turns the clip layer instead;\nnever remake the proxy, whose new URL would make the log stale. The original is never changed:\nthe conform turns it.\n\nWrite one row per source into `proxy/manifest.csv`: copy, original, fps, frames, start, turn. The cut list and the conform point back to the originals through it. In the record, a\nsource gets its `file` (the original) and its `proxy`.\n\nUpload the proxies, never the originals, with `picsart_upload_local_files`, and use the URLs it\nreturns in every tool after. Then go on with the log as the use case says.\n\n## Log footage, read before the proxies\n\nA camera shooting a log profile (S-Log3, V-Log, C-Log, D-Log...) records a flat, grey picture meant\nto be converted before anyone judges it. The scene has no camera LUT, so a log proxy stays milky in\nevery preview, contact sheet, describe and check, and a grade built on it is built on the wrong\npicture. Read each original's curve before making its proxy:\n\n```\nffprobe -v error -show_streams -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/log_profile.py --file \"<original>\" --probe \"proxy/<name>.probe.json\"\n```\n\n**When `python3` is missing** (on a Mac without the command-line tools, it opens an install\ndialog and fails), never wait on it: make plain proxies, say in one line that the previews may\nlook flat if the footage is log, and put the log check in `openDecisions`. The same holds for\n`log_lut.py` below. Never install it unasked.\n\n`ffprobe` alone rarely knows: a Sony file reports its transfer as unknown and its range as full.\nThe script reads the camera's own metadata, inside the file and in a sidecar such as\n`<name>M01.XML`. Write what it prints into the source in the record as `log`\n(`gamma`, `gamut`, and `gamutAssumed` when the file names no gamut) and say the curve in one line.\n\n**When `builtInLut` is true** (S-Log3, with S-Gamut3.Cine or S-Gamut3), write the conversion once\nfor the edit and make the proxy through it, so everything after sees normal colour:\n\n```\npython3 scripts/log_lut.py \"work/<gamut>-709.cube\" --gamut <gamut>\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf \"scale=in_color_matrix=bt709:in_range=pc:out_range=pc,\\\nformat=rgb48le,lut3d='work/<gamut>-709.cube':interp=tetrahedral,scale=-2:720:out_color_matrix=bt709:out_range=tv,\\\nformat=yuv420p\" -c:v libx264 -preset veryfast -crf 23 -c:a aac -b:a 128k -fps_mode passthrough \\\n  -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nDecode with `in_range=pc` whatever the file's range flag says: the curve is defined on the\ncamera's own code values, and an expanded range lifts black and crushes grey. Write the LUT's path\ninto the source's `log.lut` and the proxy's `look: \"rec709\"` into `proxy/manifest.csv`: the conform\napplies the same file to the original, so the master matches what was approved. A scene grade on\nthese proxies is then the look only, never a conversion.\n\n**For any other log curve**, ask the user for the camera maker's LUT for that curve and gamut\n(Panasonic, Canon, DJI and Fujifilm publish theirs); never guess a conversion. Once it is given,\nmake the proxies through it in the same way. Until then, make plain proxies, say that previews\nwill look flat until then, and put the open LUT in `openDecisions`.\n\nCheck one converted frame by eye before making the rest, beside the same frame of a plain proxy:\nskin, a white shirt and a dark suit should read as they would to someone in the room.\n\n## Gyro data, read at the proxies\n\nMany cameras record their own motion beside the picture. Gyro stabilisation uses it and steadies a\nhandheld shot better than any picture analysis: a shake scan cannot tell the camera moving from\nthe subject moving, and gyro data records only the camera. While making the proxies, read each\noriginal's streams and run `scripts/gyro.py` on the reading:\n\n```\nffprobe -v error -show_streams -show_format -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/gyro.py \"proxy/<name>.probe.json\" --file \"<original>\"\n```\n\nIt finds Sony's `rtmd` stream (a data stream, \"Timed Metadata Media Handler\", as an FX3 writes),\nGoPro's `gpmd`, DJI's `djmd`, and Insta360's trailer at the end of the file. Write what it prints\ninto the source in the record: `gyro` (`true` or `false`) and, when true, `gyroKind`. A data\nstream it does not know is not gyro data; mention it and go on. When `python3` is missing, read\nthe same tags and handlers in the probe JSON yourself; the Insta360 trailer then stays unknown.\n\nA Sony `rtmd` stream does not prove motion samples: the camera writes it also in modes that record\nnone (an a7S III at 4K 120 fps), so the script prints `\"maybe\": true`. That is the probe's word\nonly, never written into the record, which keeps `gyro` and `gyroKind`. When Gyroflow is already\ninstalled, confirm such a source before asking: `gyroflow \"<original>\" --export-metadata\n\"3:<abs project>/work/<name>.camera.json\"`; a file with no gyroscope samples there is `gyro: false`,\nand a source left with none asks nothing.\n\n**When any source has gyro data**, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) once, before the log, whether to stabilise its handheld\nranges with it; when every such source is still `\"maybe\": true`, say they may have gyro data.\nRecommended first: \"Steady the handheld shots with the camera's gyro data: they\ncome out steadier, with the frame cropped slightly (often about a tenth) so the moving edges never\nshow. Your originals are not changed.\" The other option: \"Keep them as shot: no crop, the shake\nstays.\" A yes goes into `approvals` with the scope `stabilise:gyro`; a no goes into `rejected`.\nEither answer holds for the whole edit: never ask it again, also after a resume. In unattended\npace, the assumed answer is no: write it to `openDecisions` and keep the shots as shot. With gyro data,\nthe log's stabilising decision for each range reads the gyro data, not a shake scan.\n\n**When the user said yes and no stabiliser is installed**, check first: `gyroflow --version` (on\nmacOS also the binary inside `Gyroflow.app/Contents/MacOS/`). Gyroflow is free and\nopen source, reads Sony, GoPro, DJI and Insta360 motion data, and runs from the command line. When\nit is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately before installing it. Recommended first: \"Install Gyroflow, the\nfree open-source stabiliser\", saying how: `brew install gyroflow` on a Mac\nwith Homebrew, otherwise the download at https://gyroflow.xyz/download (the Microsoft Store on\nWindows; the `.tar.gz` or the Flatpak on Linux). The other option: \"Don't install: keep the shots\nas shot.\" **Never install anything without the user's yes to this question.** A yes goes into\n`approvals` with the scope `install:stabiliser` and is never asked twice; a yes to stabilising is\nnot a yes to installing. In unattended pace, the assumed answer is no: write it to\n`openDecisions` and keep the shots as shot. When the install fails or needs an administrator\npassword, say so, keep the shots as shot and go on; never retry it unasked.\n\n**Stabilised proxies.** Make one from each stabilised copy, as above, and upload it beside the\nplain proxy: the conform checks it (below), and when the user wants to see the stabilisation in\nreview before the finish, render the copies then. Keep the plain proxy for the log, since the\nanalysis measures what the camera saw.\n\n## Per-short windows\n\nA long episode cut into several shorts is uploaded as **one window per short**, not whole: from\nthe short's first clip to its last, plus a second each side. A whole episode is often past the\n100 MB upload limit, and a variable frame rate, B-frames or a stream that starts late can make the\nrender jump a frame. Each window is re-encoded at a constant 30 fps from 0, a keyframe a second:\n\n```\nffmpeg -ss <A> -to <B> -i \"<original>\" -vf fps=30,format=yuv420p -c:v libx264 -profile:v high \\\n  -crf 20 -g 30 -keyint_min 30 -sc_threshold 0 -c:a aac -b:a 128k -ar 48000 -ac 2 \\\n  -avoid_negative_ts make_zero -movflags +faststart \"proxy/win-<short>.mp4\"\n```\n\nCheck each window with `ffprobe` before uploading it: `r_frame_rate` 30/1, the video and audio\n`start_time` both 0, and the file under 100 MB (else narrow the window). Every time in that\nshort's cut is then in the window's seconds: a source second `s` is `s - A`. Write the window's\n`A` and `B` beside its row in `proxy/manifest.csv`, so the conform maps back to the original.\n\n## The conform, at the finish\n\nWhen the user chose the conform, rebuild the approved version from the originals at full\nresolution:\n\n1. Read the approved version's plan. Map each shot's proxy range to its original through the\n   manifest; the times are the same, since the frame counts match.\n2. When the user chose gyro stabilisation, stabilise each source with gyro data first (below),\n   keeping a stabilised range only when it is steadier, its choice in `stabilised.ranges`.\n3. Cut each range from the file its check chose, the original or its stabilised copy, into\n   `work/` at the master's frame rate. A source the log found turned (`upright` in its\n   `sources` row) is turned first, before its crop: `transpose=1` for `rot90`, `transpose=2`\n   for `rot270`, `hflip,vflip` for `rot180`. Count frames from each shot's scene start so the cuts\n   never drift, into an intermediate that keeps 10 bits (ProRes 422 HQ). Stabilise first, then the LUT: a log source\n   goes through the same LUT its proxy did (`log.lut`), decoded with `in_range=pc` as above, and\n   the look the approved scene carried is baked in there or applied right after it. One shot that\n   sits under or over the rest gets its own LUT with `log_lut.py --exposure`, never a lift of the\n   whole edit. Look at one frame of each shot before joining them.\n4. Join them in the plan's order over black, with the approved end card and captions (below), and\n   the approved audio (below).\n5. Check the master against the approved version, frame for frame: the same length, the same cut\n   points, the same words when both are transcribed.\n\nA master that differs is fixed in the conform, never delivered as it is. Deliver the master in the\nformat the brief or the reference names, at the originals' resolution; never add another size or\nversion nobody asked for.\n\n### Captions at full resolution\n\nThe scene's captions are burned in at the conform, in the same font, colour, size and place,\nscaled to the master. Write them as an `.ass` file with `scripts/captions_ass.py` (its usage says\nthe JSON it reads), and burn them with `subtitles='work/captions.ass':fontsdir='<brand font folder>'`,\nso the brand's own font file is used. Two things first:\n\n- **The font file is there.** libass quietly falls back to another font when the family is not in\n  `fontsdir`, so check that the folder holds a file of the caption's family (its name, or\n  `fc-scan` where present). When it does not, ask for the brand's font file with\n  `picsart_drive_upload_ask`, or keep the captions `open`; never burn them in a substitute.\n- **This ffmpeg has the filter** (`ffmpeg -hide_banner -filters | grep subtitles`); many builds\n  lack it and `drawtext` both. `python3` missing is the same case: no `.ass` can be written.\n\nWhen either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately how to finish. Recommended first: \"Install\nffmpeg-full, the full ffmpeg with subtitle support\", the same package and command as in ffmpeg\nfirst, above (`brew install ffmpeg-full` on a Mac). The other options: \"Deliver the free scene export with its captions instead\", which exports\nthe approved scene with `picsart_scene_export` at the delivery resolution (from the proxies, so\nbelow the originals' quality, and said so), and \"Don't install: the captions stay off the master\nfor now\". **Never install anything without the user's yes to this question.** A yes to installing\ngoes into `approvals` with the scope `install:ffmpeg` and is never asked twice: that scope\nalready approved means ffmpeg-full is installed, so use its binary rather than asking again. A yes to captions is not a yes to installing. In unattended pace, the assumed answer is the scene export: write it\nto `openDecisions` and deliver that. When the install fails or needs an administrator password,\nsay so and never retry it unasked. On \"stay off\", the captions are `open`: finish the rest of the\nmaster, say that its captions are not burned in, and stop before delivery. Never swap the brand\nfont for another one, and never deliver the master without its captions as if it were done.\n\n### The voice and sound at full resolution\n\nTake every voice from the original recording, never from a proxy or a scene export: cut its range,\nremove rumble below about 80 Hz, and set its loudness in two passes (measure with\n`loudnorm=print_format=json`, then apply the measured values with `linear=true`) to about -14 LUFS\nwith true peak under -1.5 dBTP. Place it at its scene start and pad it to the master's length with\nsilence, so it plays once and never repeats under the end card.\n\n### Stabilising with Gyroflow\n\nGyroflow renders next to the source by default, so always give it an absolute output path in\n`work/`; the original is read, never written, and a symlinked footage folder is resolved first so\nnothing lands in it. One source at a time:\n\n```\ngyroflow \"<original>\" -p \"{ 'codec': 'ProRes', 'codec_options': 'ProRes 422 HQ', 'audio_codec': 'Copy', 'output_path': '<abs project>/work/<name>.stab.mov' }\"\ngyroflow \"<original>\" --export-metadata \"3:<abs project>/work/<name>.camera.json\"\n```\n\nType the braces once, as here (Gyroflow's help prints them doubled). ProRes takes every source as\nit is; for an HEVC output instead (`'codec': 'H.265/HEVC'`), a 4:2:2 10-bit source needs\n`'pixel_format': 'P010LE'`. Never run `--export-project`: it writes a `.gyroflow` file beside the\noriginal, in the footage folder, whatever output path you give. When Gyroflow says the lens\nis unknown, pass the lens profile's JSON file as another input after the original, with no flag\n(`gyroflow \"<original>\" \"<lens profile>.json\" -p …`); never guess one. Settings saved as a preset go\nin with `--preset <file>`. It exits 0 on\nsuccess, 1 when the render failed and 2 on a bad argument: on 1 or 2, keep that source as shot,\nsay so, and go on. When it renders but its camera data holds no gyroscope samples (a Sony source\nthat was only `\"maybe\"`), it had no motion to use: keep that source as shot.\n\nThen check the copy with `ffprobe` against the original: the same fps, frame count and length.\nWrite into the source `stabilised`: its `file`, and its `crop`, the largest zoom Gyroflow applied\n(1.12 keeps the middle 1/1.12 of the frame on each axis). Read the zoom from the camera data's\n`zooming` fields; when they do not make it plain, measure it on one still pair: the distance\nbetween two fixed details in the stabilised frame over the same distance in the original.\n\n**Keep a stabilised range only when it is steadier.** Measure each used range on the stabilised\nproxy as on the plain one, on the same fixed detail with texture, as the edit-pipeline skill's gate\nrules say, never by a whole-frame scan: a moving subject reads as shake there. A range that is not\nsteadier (a gimbal shot already steady, say) stays as shot. Then run every framing and safe-zone\ncheck on that source, the footage-reframing skill's included, on the stabilised proxy itself, not\nonly against the middle 1/crop of the frame: roll and lens correction move points, so a face or a\ncaption inside that rectangle on the plain proxy can still leave the frame. A range that fails is\nkept as shot. Write each range's choice into the source's `stabilised.ranges`, never into its\n`ranges` (which the log wrote, so a change there would redo every stage after it): `in`, `out`,\n`use` (`stabilised` or `original`) and `shake`, the two measurements `[plain, stabilised]`. Cut\neach range from the file it chose.\n\n## Colour comparison, against the reference\n\nWhen the record holds a reference and ffmpeg is on this computer, compare the draft's colour with\nthe reference's by measurement first. Read one frame a second of each, the draft's `exports/`\nfile and the reference clip:\n\n```\nffmpeg -hide_banner -i \"<file>\" -vf \"fps=1,format=yuv420p,signalstats,metadata=mode=print:file=-\" -f null - 2>/dev/null \\\n  | grep -E \"lavfi.signalstats.(YAVG|SATAVG)=\"\n```\n\n`format=yuv420p` puts both files on the same 8-bit scale first: `signalstats` reads in the input's\nown bit depth, so a 10-bit draft would read about four times brighter than an 8-bit reference.\n`YAVG` is then the brightness (0 to 255) and `SATAVG` the saturation. Average each over the file and\nset the two side by side. The grade has drifted when either differs by more than about a tenth of\nthe reference's value: a draft clearly darker or flatter than the reference. Hue is judged by eye:\nlook at a frame of each side by side for a draft warmer, cooler or tinted another way than the\nreference, since no single hue figure survives a frame whose colours sit either side of red. A\ndrift is fixed at the look, before the review, and said in one line when it is the user's own\nchoice; a figure that could not be read is `open`, never a pass. Where ffmpeg is not here, the use\ncase compares stills of both by eye instead.\n\n## The final check, on this computer\n\nBesides the checks the use case runs on every finish, run quality-review's `qc.py` on the master's\n`ffprobe` and loudness reading (`ffmpeg -af loudnorm=print_format=json -f null -`): about -14 LUFS\nwith true peak under -1 dBTP.\n\n## Deliver\n\nPut the final files in `exports/` beside any earlier ones; an old file is removed only on a yes.\nThe cut list names each original, not its proxy.\n"
AFTER
"---\nname: edit-on-your-computer\ndescription: Edit footage on the user's own computer - proxies uploaded instead of the originals, a project folder, and a full-resolution conform with ffmpeg. Use only when the footage is a folder on this machine and you can run commands.\n---\n\n# Edit on your computer\n\nAn edit runs the same way wherever its footage is: the stages, the record and the checks are the\nedit-pipeline skill's. This skill adds only what changes when the footage is on this computer and\nyou can run commands here. Originals are large, and they are the user's masters: they never\nleave this computer and are never changed. What the server reads is small copies.\n\nLoad this skill only when the footage is a folder or paths on disk and the host runs commands.\nFootage given as Picsart Drive files, links or attached files is edited without it. When you\ncannot run commands here after all, open `picsart_drive_upload_ask` for the footage and go on\nwithout this skill; never ask the user to upload it by hand.\n\n## The project folder\n\nKeep everything for one edit in one folder beside the footage, never inside it:\n\n| Path | Holds |\n|---|---|\n| `edit-footage.json` | the record, kept by edit-pipeline's `scripts/record.py` |\n| `proxy/` | the proxies and `manifest.csv` |\n| `work/` | copies you change (a graded file, a conformed master), never an original |\n| `exports/` | each version's draft, and the final files; a new file goes beside an old one |\n\nQuote every path you pass to a command; folder names often have spaces.\n\n## ffmpeg first\n\nEverything below runs on `ffmpeg` and `ffprobe`. Before the proxies, check both:\n`command -v ffmpeg ffprobe`. When either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) how to go on. Recommended first:\n\"Install ffmpeg-full, the full ffmpeg with subtitle support\", saying exactly what: on a Mac with\nHomebrew, `brew install ffmpeg-full` (Homebrew's own formula, with libass for the captions; it\ninstalls beside any other ffmpeg without replacing it, so run it as\n`\"$(brew --prefix ffmpeg-full)/bin/ffmpeg\"` and `.../bin/ffprobe`); elsewhere, a build linked from\nhttps://ffmpeg.org/download.html whose `ffmpeg -filters` lists `subtitles`. The other option: \"Edit\nwithout it: you upload the footage, and the finish is a full-quality export\". **Never install\nanything without the user's yes to this question.** A yes goes into `approvals` with the scope\n`install:ffmpeg` and covers exactly that package, which the captions need too (below), so it is\nnever asked twice. In unattended pace, the assumed answer is the upload, but the upload needs the\nuser: write it to `openDecisions` and stop there. When the install fails or needs an administrator\npassword, say so, offer the upload, and never retry it unasked. On the upload, open\n`picsart_drive_upload_ask` for the footage, leave the `proxies` stage out of the record's pipeline,\nset `finish` to `export`, and go on without this skill.\n\n## Proxies, before anything is analysed\n\nMake a small copy of each source and analyse only those. Read each original's curve first (Log\nfootage, below): a log source's proxy is made through its conversion, not with this command.\n\n\n```\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf scale=-2:720 -c:v libx264 -preset veryfast -crf 23 \\\n  -c:a aac -b:a 128k -fps_mode passthrough -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nA source with no picture, such as a voice-over, needs no proxy: upload it as it is. Each proxy\nkeeps the original's fps, frame count and start timecode. Check that with `ffprobe` on\nboth files.\n\n**Which way is up** is judged here, before the proxy, from one still in the middle of the\noriginal (`ffmpeg -ss <middle> -i \"<original>\" -frames:v 1 \"proxy/<name>.mid.jpg\"`), as the use\ncase's log says. A turned source's proxy is made turned, so everything after it sees it upright:\nits transpose goes first in `-vf`, before the scale (`transpose=1` for `rot90`, `transpose=2`\nfor `rot270`, `hflip,vflip` for `rot180`). Its `upright` goes into its `sources` row; the build\nlays such a proxy as it is and never turns it again. When `upright` is turned but the\nmanifest's `turn` is empty (found after the proxies), the build turns the clip layer instead;\nnever remake the proxy, whose new URL would make the log stale. The original is never changed:\nthe conform turns it.\n\nWrite one row per source into `proxy/manifest.csv`: copy, original, fps, frames, start, turn. The cut list and the conform point back to the originals through it. In the record, a\nsource gets its `file` (the original) and its `proxy`.\n\nUpload the proxies, never the originals, with `picsart_upload_local_files`, and use the URLs it\nreturns in every tool after. Then go on with the log as the use case says.\n\n## Log footage, read before the proxies\n\nA camera shooting a log profile (S-Log3, V-Log, C-Log, D-Log...) records a flat, grey picture meant\nto be converted before anyone judges it. The scene has no camera LUT, so a log proxy stays milky in\nevery preview, contact sheet, describe and check, and a grade built on it is built on the wrong\npicture. Read each original's curve before making its proxy:\n\n```\nffprobe -v error -show_streams -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/log_profile.py --file \"<original>\" --probe \"proxy/<name>.probe.json\"\n```\n\n**When `python3` is missing** (on a Mac without the command-line tools, it opens an install\ndialog and fails), never wait on it: make plain proxies, say in one line that the previews may\nlook flat if the footage is log, and put the log check in `openDecisions`. The same holds for\n`log_lut.py` below. Never install it unasked.\n\n`ffprobe` alone rarely knows: a Sony file reports its transfer as unknown and its range as full.\nThe script reads the camera's own metadata, inside the file and in a sidecar such as\n`<name>M01.XML`. Write what it prints into the source in the record as `log`\n(`gamma`, `gamut`, and `gamutAssumed` when the file names no gamut) and say the curve in one line.\n\n**When `builtInLut` is true** (S-Log3, with S-Gamut3.Cine or S-Gamut3), write the conversion once\nfor the edit and make the proxy through it, so everything after sees normal colour:\n\n```\npython3 scripts/log_lut.py \"work/<gamut>-709.cube\" --gamut <gamut>\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf \"scale=in_color_matrix=bt709:in_range=pc:out_range=pc,\\\nformat=rgb48le,lut3d='work/<gamut>-709.cube':interp=tetrahedral,scale=-2:720:out_color_matrix=bt709:out_range=tv,\\\nformat=yuv420p\" -c:v libx264 -preset veryfast -crf 23 -c:a aac -b:a 128k -fps_mode passthrough \\\n  -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nDecode with `in_range=pc` whatever the file's range flag says: the curve is defined on the\ncamera's own code values, and an expanded range lifts black and crushes grey. Write the LUT's path\ninto the source's `log.lut` and the proxy's `look: \"rec709\"` into `proxy/manifest.csv`: the conform\napplies the same file to the original, so the master matches what was approved. A scene grade on\nthese proxies is then the look only, never a conversion.\n\n**For any other log curve**, ask the user for the camera maker's LUT for that curve and gamut\n(Panasonic, Canon, DJI and Fujifilm publish theirs); never guess a conversion. Once it is given,\nmake the proxies through it in the same way. Until then, make plain proxies, say that previews\nwill look flat until then, and put the open LUT in `openDecisions`.\n\nCheck one converted frame by eye before making the rest, beside the same frame of a plain proxy:\nskin, a white shirt and a dark suit should read as they would to someone in the room.\n\n## Gyro data, read at the proxies\n\nMany cameras record their own motion beside the picture. Gyro stabilisation uses it and steadies a\nhandheld shot better than any picture analysis: a shake scan cannot tell the camera moving from\nthe subject moving, and gyro data records only the camera. While making the proxies, read each\noriginal's streams and run `scripts/gyro.py` on the reading:\n\n```\nffprobe -v error -show_streams -show_format -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/gyro.py \"proxy/<name>.probe.json\" --file \"<original>\"\n```\n\nIt finds Sony's `rtmd` stream (a data stream, \"Timed Metadata Media Handler\", as an FX3 writes),\nGoPro's `gpmd`, DJI's `djmd`, and Insta360's trailer at the end of the file. Write what it prints\ninto the source in the record: `gyro` (`true` or `false`) and, when true, `gyroKind`. A data\nstream it does not know is not gyro data; mention it and go on. When `python3` is missing, read\nthe same tags and handlers in the probe JSON yourself; the Insta360 trailer then stays unknown.\n\nA Sony `rtmd` stream does not prove motion samples: the camera writes it also in modes that record\nnone (an a7S III at 4K 120 fps), so the script prints `\"maybe\": true`. That is the probe's word\nonly, never written into the record, which keeps `gyro` and `gyroKind`. When Gyroflow is already\ninstalled, confirm such a source before asking: `gyroflow \"<original>\" --export-metadata\n\"3:<abs project>/work/<name>.camera.json\"`; a file with no gyroscope samples there is `gyro: false`,\nand a source left with none asks nothing.\n\n**When any source has gyro data**, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) once, before the log, whether to stabilise its handheld\nranges with it; when every such source is still `\"maybe\": true`, say they may have gyro data.\nRecommended first: \"Steady the handheld shots with the camera's gyro data: they\ncome out steadier, with the frame cropped slightly (often about a tenth) so the moving edges never\nshow. Your originals are not changed.\" The other option: \"Keep them as shot: no crop, the shake\nstays.\" A yes goes into `approvals` with the scope `stabilise:gyro`; a no goes into `rejected`.\nEither answer holds for the whole edit: never ask it again, also after a resume. In unattended\npace, the assumed answer is no: write it to `openDecisions` and keep the shots as shot. With gyro data,\nthe log's stabilising decision for each range reads the gyro data, not a shake scan.\n\n**When the user said yes and no stabiliser is installed**, check first: `gyroflow --version` (on\nmacOS also the binary inside `Gyroflow.app/Contents/MacOS/`). Gyroflow is free and\nopen source, reads Sony, GoPro, DJI and Insta360 motion data, and runs from the command line. When\nit is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately before installing it. Recommended first: \"Install Gyroflow, the\nfree open-source stabiliser\", saying how: `brew install gyroflow` on a Mac\nwith Homebrew, otherwise the download at https://gyroflow.xyz/download (the Microsoft Store on\nWindows; the `.tar.gz` or the Flatpak on Linux). The other option: \"Don't install: keep the shots\nas shot.\" **Never install anything without the user's yes to this question.** A yes goes into\n`approvals` with the scope `install:stabiliser` and is never asked twice; a yes to stabilising is\nnot a yes to installing. In unattended pace, the assumed answer is no: write it to\n`openDecisions` and keep the shots as shot. When the install fails or needs an administrator\npassword, say so, keep the shots as shot and go on; never retry it unasked.\n\n**Stabilised proxies.** Make one from each stabilised copy, as above, and upload it beside the\nplain proxy: the conform checks it (below), and when the user wants to see the stabilisation in\nreview before the finish, render the copies then. Keep the plain proxy for the log, since the\nanalysis measures what the camera saw.\n\n## Per-short windows\n\nA long episode cut into several shorts is uploaded as **one window per short**, not whole: from\nthe short's first clip to its last, plus a second each side. A whole episode is often past the\n100 MB upload limit, and a variable frame rate, B-frames or a stream that starts late can make the\nrender jump a frame. Each window is re-encoded at a constant 30 fps from 0, a keyframe a second:\n\n```\nffmpeg -ss <A> -to <B> -i \"<original>\" -vf fps=30,format=yuv420p -c:v libx264 -profile:v high \\\n  -crf 20 -g 30 -keyint_min 30 -sc_threshold 0 -c:a aac -b:a 128k -ar 48000 -ac 2 \\\n  -avoid_negative_ts make_zero -movflags +faststart \"proxy/win-<short>.mp4\"\n```\n\nCheck each window with `ffprobe` before uploading it: `r_frame_rate` 30/1, the video and audio\n`start_time` both 0, and the file under 100 MB (else narrow the window). Every time in that\nshort's cut is then in the window's seconds: a source second `s` is `s - A`. Write the window's\n`A` and `B` beside its row in `proxy/manifest.csv`, so the conform maps back to the original.\n\n## The conform, at the finish\n\nWhen the user chose the conform, rebuild the approved version from the originals at full\nresolution:\n\n1. Read the approved version's plan. Map each shot's proxy range to its original through the\n   manifest; the times are the same, since the frame counts match.\n2. When the user chose gyro stabilisation, stabilise each source with gyro data first (below),\n   keeping a stabilised range only when it is steadier, its choice in `stabilised.ranges`.\n3. Cut each range from the file its check chose, the original or its stabilised copy, into\n   `work/` at the master's frame rate. A source the log found turned (`upright` in its\n   `sources` row) is turned first, before its crop: `transpose=1` for `rot90`, `transpose=2`\n   for `rot270`, `hflip,vflip` for `rot180`. Count frames from each shot's scene start so the cuts\n   never drift, into an intermediate that keeps 10 bits (ProRes 422 HQ). Stabilise first, then the LUT: a log source\n   goes through the same LUT its proxy did (`log.lut`), decoded with `in_range=pc` as above, and\n   the look the approved scene carried is baked in there or applied right after it. One shot that\n   sits under or over the rest gets its own LUT with `log_lut.py --exposure`, never a lift of the\n   whole edit. Look at one frame of each shot before joining them.\n4. Join them in the plan's order over black, with the approved end card and captions (below), and\n   the approved audio (below).\n5. Check the master against the approved version, frame for frame: the same length, the same cut\n   points, the same words when both are transcribed.\n\nA master that differs is fixed in the conform, never delivered as it is. Deliver the master in the\nformat the brief or the reference names, at the originals' resolution; never add another size or\nversion nobody asked for.\n\n### Captions at full resolution\n\nThe scene's captions are burned in at the conform, in the same font, colour, size and place,\nscaled to the master. Write them as an `.ass` file with `scripts/captions_ass.py` (its usage says\nthe JSON it reads), and burn them with `subtitles='work/captions.ass':fontsdir='<brand font folder>'`,\nso the brand's own font file is used. Two things first:\n\n- **The font file is there.** libass quietly falls back to another font when the family is not in\n  `fontsdir`, so check that the folder holds a file of the caption's family (its name, or\n  `fc-scan` where present). When it does not, ask for the brand's font file with\n  `picsart_drive_upload_ask`, or keep the captions `open`; never burn them in a substitute.\n- **This ffmpeg has the filter** (`ffmpeg -hide_banner -filters | grep subtitles`); many builds\n  lack it and `drawtext` both. `python3` missing is the same case: no `.ass` can be written.\n\nWhen either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately how to finish. Recommended first: \"Install\nffmpeg-full, the full ffmpeg with subtitle support\", the same package and command as in ffmpeg\nfirst, above (`brew install ffmpeg-full` on a Mac). The other options: \"Deliver the free scene export with its captions instead\", which exports\nthe approved scene with `picsart_scene_export` at the delivery resolution (from the proxies, so\nbelow the originals' quality, and said so), and \"Don't install: the captions stay off the master\nfor now\". **Never install anything without the user's yes to this question.** A yes to installing\ngoes into `approvals` with the scope `install:ffmpeg` and is never asked twice: that scope\nalready approved means ffmpeg-full is installed, so use its binary rather than asking again. A yes to captions is not a yes to installing. In unattended pace, the assumed answer is the scene export: write it\nto `openDecisions` and deliver that. When the install fails or needs an administrator password,\nsay so and never retry it unasked. On \"stay off\", the captions are `open`: finish the rest of the\nmaster, say that its captions are not burned in, and stop before delivery. Never swap the brand\nfont for another one, and never deliver the master without its captions as if it were done.\n\n### The voice and sound at full resolution\n\nTake every voice from the original recording, never from a proxy or a scene export: cut its range,\nremove rumble below about 80 Hz, and set its loudness in two passes (measure with\n`loudnorm=print_format=json`, then apply the measured values with `linear=true`) to about -14 LUFS\nwith true peak under -1.5 dBTP. Place it at its scene start and pad it to the master's length with\nsilence, so it plays once and never repeats under the end card.\n\n### Stabilising with Gyroflow\n\nGyroflow renders next to the source by default, so always give it an absolute output path in\n`work/`; the original is read, never written, and a symlinked footage folder is resolved first so\nnothing lands in it. One source at a time:\n\n```\ngyroflow \"<original>\" -p \"{ 'codec': 'ProRes', 'codec_options': 'ProRes 422 HQ', 'audio_codec': 'Copy', 'output_path': '<abs project>/work/<name>.stab.mov' }\"\ngyroflow \"<original>\" --export-metadata \"3:<abs project>/work/<name>.camera.json\"\n```\n\nType the braces once, as here (Gyroflow's help prints them doubled). ProRes takes every source as\nit is; for an HEVC output instead (`'codec': 'H.265/HEVC'`), a 4:2:2 10-bit source needs\n`'pixel_format': 'P010LE'`. Never run `--export-project`: it writes a `.gyroflow` file beside the\noriginal, in the footage folder, whatever output path you give. When Gyroflow says the lens\nis unknown, pass the lens profile's JSON file as another input after the original, with no flag\n(`gyroflow \"<original>\" \"<lens profile>.json\" -p …`); never guess one. Settings saved as a preset go\nin with `--preset <file>`. It exits 0 on\nsuccess, 1 when the render failed and 2 on a bad argument: on 1 or 2, keep that source as shot,\nsay so, and go on. When it renders but its camera data holds no gyroscope samples (a Sony source\nthat was only `\"maybe\"`), it had no motion to use: keep that source as shot.\n\nThen check the copy with `ffprobe` against the original: the same fps, frame count and length.\nWrite into the source `stabilised`: its `file`, and its `crop`, the largest zoom Gyroflow applied\n(1.12 keeps the middle 1/1.12 of the frame on each axis). Read the zoom from the camera data's\n`zooming` fields; when they do not make it plain, measure it on one still pair: the distance\nbetween two fixed details in the stabilised frame over the same distance in the original.\n\n**Keep a stabilised range only when it is steadier.** Measure each used range on the stabilised\nproxy as on the plain one, on the same fixed detail with texture, as the edit-pipeline skill's gate\nrules say, never by a whole-frame scan: a moving subject reads as shake there. A range that is not\nsteadier (a gimbal shot already steady, say) stays as shot. Then run every framing and safe-zone\ncheck on that source, the footage-reframing skill's included, on the stabilised proxy itself, not\nonly against the middle 1/crop of the frame: roll and lens correction move points, so a face or a\ncaption inside that rectangle on the plain proxy can still leave the frame. A range that fails is\nkept as shot. Write each range's choice into the source's `stabilised.ranges`, never into its\n`ranges` (which the log wrote, so a change there would redo every stage after it): `in`, `out`,\n`use` (`stabilised` or `original`) and `shake`, the two measurements `[plain, stabilised]`. Cut\neach range from the file it chose.\n\n## Colour comparison, against the reference\n\nWhen the record holds a reference and ffmpeg is on this computer, compare the draft's colour with\nthe reference's by measurement first. Read one frame a second of each, the draft's `exports/`\nfile and the reference clip:\n\n```\nffmpeg -hide_banner -i \"<file>\" -vf \"fps=1,format=yuv420p,signalstats,metadata=mode=print:file=-\" -f null - 2>/dev/null \\\n  | grep -E \"lavfi.signalstats.(YAVG|SATAVG)=\"\n```\n\n`format=yuv420p` puts both files on the same 8-bit scale first: `signalstats` reads in the input's\nown bit depth, so a 10-bit draft would read about four times brighter than an 8-bit reference.\n`YAVG` is then the brightness (0 to 255) and `SATAVG` the saturation. Average each over the file and\nset the two side by side. The grade has drifted when either differs by more than about a tenth of\nthe reference's value: a draft clearly darker or flatter than the reference. Hue is judged by eye:\nlook at a frame of each side by side for a draft warmer, cooler or tinted another way than the\nreference, since no single hue figure survives a frame whose colours sit either side of red. At the look stage the same reading, with `YLOW` (the black point) and `YHIGH` (the white point)\nadded to the `grep`, is taken on the board's stills and on the same frames in the chosen look;\nedit-footage's `scripts/look_check.py` compares them. A\ndrift is fixed at the look, before the review, and said in one line when it is the user's own\nchoice; a figure that could not be read is `open`, never a pass. Where ffmpeg is not here, the use\ncase compares stills of both by eye instead.\n\n## The final check, on this computer\n\nBesides the checks the use case runs on every finish, run quality-review's `qc.py` on the master's\n`ffprobe` and loudness reading (`ffmpeg -af loudnorm=print_format=json -f null -`): about -14 LUFS\nwith true peak under -1 dBTP.\n\n## Deliver\n\nPut the final files in `exports/` beside any earlier ones; an old file is removed only on a yes.\nThe cut list names each original, not its proxy.\n"
Full snapshot data
{
  "description": "Edit footage on the user's own computer - proxies uploaded instead of the originals, a project folder, and a full-resolution conform with ffmpeg. Use only when the footage is a folder on this machine and you can run commands.",
  "included_files": [
    {
      "relative_path": "scripts/captions_ass.py",
      "size_in_bytes": 3079
    },
    {
      "relative_path": "scripts/gyro.py",
      "size_in_bytes": 3337
    },
    {
      "relative_path": "scripts/log_lut.py",
      "size_in_bytes": 4420
    },
    {
      "relative_path": "scripts/log_profile.py",
      "size_in_bytes": 5532
    }
  ],
  "name": "edit-on-your-computer",
  "skill_md_contents": "---\nname: edit-on-your-computer\ndescription: Edit footage on the user's own computer - proxies uploaded instead of the originals, a project folder, and a full-resolution conform with ffmpeg. Use only when the footage is a folder on this machine and you can run commands.\n---\n\n# Edit on your computer\n\nAn edit runs the same way wherever its footage is: the stages, the record and the checks are the\nedit-pipeline skill's. This skill adds only what changes when the footage is on this computer and\nyou can run commands here. Originals are large, and they are the user's masters: they never\nleave this computer and are never changed. What the server reads is small copies.\n\nLoad this skill only when the footage is a folder or paths on disk and the host runs commands.\nFootage given as Picsart Drive files, links or attached files is edited without it. When you\ncannot run commands here after all, open `picsart_drive_upload_ask` for the footage and go on\nwithout this skill; never ask the user to upload it by hand.\n\n## The project folder\n\nKeep everything for one edit in one folder beside the footage, never inside it:\n\n| Path | Holds |\n|---|---|\n| `edit-footage.json` | the record, kept by edit-pipeline's `scripts/record.py` |\n| `proxy/` | the proxies and `manifest.csv` |\n| `work/` | copies you change (a graded file, a conformed master), never an original |\n| `exports/` | each version's draft, and the final files; a new file goes beside an old one |\n\nQuote every path you pass to a command; folder names often have spaces.\n\n## ffmpeg first\n\nEverything below runs on `ffmpeg` and `ffprobe`. Before the proxies, check both:\n`command -v ffmpeg ffprobe`. When either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) how to go on. Recommended first:\n\"Install ffmpeg-full, the full ffmpeg with subtitle support\", saying exactly what: on a Mac with\nHomebrew, `brew install ffmpeg-full` (Homebrew's own formula, with libass for the captions; it\ninstalls beside any other ffmpeg without replacing it, so run it as\n`\"$(brew --prefix ffmpeg-full)/bin/ffmpeg\"` and `.../bin/ffprobe`); elsewhere, a build linked from\nhttps://ffmpeg.org/download.html whose `ffmpeg -filters` lists `subtitles`. The other option: \"Edit\nwithout it: you upload the footage, and the finish is a full-quality export\". **Never install\nanything without the user's yes to this question.** A yes goes into `approvals` with the scope\n`install:ffmpeg` and covers exactly that package, which the captions need too (below), so it is\nnever asked twice. In unattended pace, the assumed answer is the upload, but the upload needs the\nuser: write it to `openDecisions` and stop there. When the install fails or needs an administrator\npassword, say so, offer the upload, and never retry it unasked. On the upload, open\n`picsart_drive_upload_ask` for the footage, leave the `proxies` stage out of the record's pipeline,\nset `finish` to `export`, and go on without this skill.\n\n## Proxies, before anything is analysed\n\nMake a small copy of each source and analyse only those. Read each original's curve first (Log\nfootage, below): a log source's proxy is made through its conversion, not with this command.\n\n\n```\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf scale=-2:720 -c:v libx264 -preset veryfast -crf 23 \\\n  -c:a aac -b:a 128k -fps_mode passthrough -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nA source with no picture, such as a voice-over, needs no proxy: upload it as it is. Each proxy\nkeeps the original's fps, frame count and start timecode. Check that with `ffprobe` on\nboth files.\n\n**Which way is up** is judged here, before the proxy, from one still in the middle of the\noriginal (`ffmpeg -ss <middle> -i \"<original>\" -frames:v 1 \"proxy/<name>.mid.jpg\"`), as the use\ncase's log says. A turned source's proxy is made turned, so everything after it sees it upright:\nits transpose goes first in `-vf`, before the scale (`transpose=1` for `rot90`, `transpose=2`\nfor `rot270`, `hflip,vflip` for `rot180`). Its `upright` goes into its `sources` row; the build\nlays such a proxy as it is and never turns it again. When `upright` is turned but the\nmanifest's `turn` is empty (found after the proxies), the build turns the clip layer instead;\nnever remake the proxy, whose new URL would make the log stale. The original is never changed:\nthe conform turns it.\n\nWrite one row per source into `proxy/manifest.csv`: copy, original, fps, frames, start, turn. The cut list and the conform point back to the originals through it. In the record, a\nsource gets its `file` (the original) and its `proxy`.\n\nUpload the proxies, never the originals, with `picsart_upload_local_files`, and use the URLs it\nreturns in every tool after. Then go on with the log as the use case says.\n\n## Log footage, read before the proxies\n\nA camera shooting a log profile (S-Log3, V-Log, C-Log, D-Log...) records a flat, grey picture meant\nto be converted before anyone judges it. The scene has no camera LUT, so a log proxy stays milky in\nevery preview, contact sheet, describe and check, and a grade built on it is built on the wrong\npicture. Read each original's curve before making its proxy:\n\n```\nffprobe -v error -show_streams -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/log_profile.py --file \"<original>\" --probe \"proxy/<name>.probe.json\"\n```\n\n**When `python3` is missing** (on a Mac without the command-line tools, it opens an install\ndialog and fails), never wait on it: make plain proxies, say in one line that the previews may\nlook flat if the footage is log, and put the log check in `openDecisions`. The same holds for\n`log_lut.py` below. Never install it unasked.\n\n`ffprobe` alone rarely knows: a Sony file reports its transfer as unknown and its range as full.\nThe script reads the camera's own metadata, inside the file and in a sidecar such as\n`<name>M01.XML`. Write what it prints into the source in the record as `log`\n(`gamma`, `gamut`, and `gamutAssumed` when the file names no gamut) and say the curve in one line.\n\n**When `builtInLut` is true** (S-Log3, with S-Gamut3.Cine or S-Gamut3), write the conversion once\nfor the edit and make the proxy through it, so everything after sees normal colour:\n\n```\npython3 scripts/log_lut.py \"work/<gamut>-709.cube\" --gamut <gamut>\nffmpeg -i \"<original>\" -map 0:v:0 -map 0:a? -vf \"scale=in_color_matrix=bt709:in_range=pc:out_range=pc,\\\nformat=rgb48le,lut3d='work/<gamut>-709.cube':interp=tetrahedral,scale=-2:720:out_color_matrix=bt709:out_range=tv,\\\nformat=yuv420p\" -c:v libx264 -preset veryfast -crf 23 -c:a aac -b:a 128k -fps_mode passthrough \\\n  -map_metadata 0 -timecode <start> \"proxy/<name>.mp4\"\n```\n\nDecode with `in_range=pc` whatever the file's range flag says: the curve is defined on the\ncamera's own code values, and an expanded range lifts black and crushes grey. Write the LUT's path\ninto the source's `log.lut` and the proxy's `look: \"rec709\"` into `proxy/manifest.csv`: the conform\napplies the same file to the original, so the master matches what was approved. A scene grade on\nthese proxies is then the look only, never a conversion.\n\n**For any other log curve**, ask the user for the camera maker's LUT for that curve and gamut\n(Panasonic, Canon, DJI and Fujifilm publish theirs); never guess a conversion. Once it is given,\nmake the proxies through it in the same way. Until then, make plain proxies, say that previews\nwill look flat until then, and put the open LUT in `openDecisions`.\n\nCheck one converted frame by eye before making the rest, beside the same frame of a plain proxy:\nskin, a white shirt and a dark suit should read as they would to someone in the room.\n\n## Gyro data, read at the proxies\n\nMany cameras record their own motion beside the picture. Gyro stabilisation uses it and steadies a\nhandheld shot better than any picture analysis: a shake scan cannot tell the camera moving from\nthe subject moving, and gyro data records only the camera. While making the proxies, read each\noriginal's streams and run `scripts/gyro.py` on the reading:\n\n```\nffprobe -v error -show_streams -show_format -of json \"<original>\" > \"proxy/<name>.probe.json\"\npython3 scripts/gyro.py \"proxy/<name>.probe.json\" --file \"<original>\"\n```\n\nIt finds Sony's `rtmd` stream (a data stream, \"Timed Metadata Media Handler\", as an FX3 writes),\nGoPro's `gpmd`, DJI's `djmd`, and Insta360's trailer at the end of the file. Write what it prints\ninto the source in the record: `gyro` (`true` or `false`) and, when true, `gyroKind`. A data\nstream it does not know is not gyro data; mention it and go on. When `python3` is missing, read\nthe same tags and handlers in the probe JSON yourself; the Insta360 trailer then stays unknown.\n\nA Sony `rtmd` stream does not prove motion samples: the camera writes it also in modes that record\nnone (an a7S III at 4K 120 fps), so the script prints `\"maybe\": true`. That is the probe's word\nonly, never written into the record, which keeps `gyro` and `gyroKind`. When Gyroflow is already\ninstalled, confirm such a source before asking: `gyroflow \"<original>\" --export-metadata\n\"3:<abs project>/work/<name>.camera.json\"`; a file with no gyroscope samples there is `gyro: false`,\nand a source left with none asks nothing.\n\n**When any source has gyro data**, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) once, before the log, whether to stabilise its handheld\nranges with it; when every such source is still `\"maybe\": true`, say they may have gyro data.\nRecommended first: \"Steady the handheld shots with the camera's gyro data: they\ncome out steadier, with the frame cropped slightly (often about a tenth) so the moving edges never\nshow. Your originals are not changed.\" The other option: \"Keep them as shot: no crop, the shake\nstays.\" A yes goes into `approvals` with the scope `stabilise:gyro`; a no goes into `rejected`.\nEither answer holds for the whole edit: never ask it again, also after a resume. In unattended\npace, the assumed answer is no: write it to `openDecisions` and keep the shots as shot. With gyro data,\nthe log's stabilising decision for each range reads the gyro data, not a shake scan.\n\n**When the user said yes and no stabiliser is installed**, check first: `gyroflow --version` (on\nmacOS also the binary inside `Gyroflow.app/Contents/MacOS/`). Gyroflow is free and\nopen source, reads Sony, GoPro, DJI and Insta360 motion data, and runs from the command line. When\nit is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately before installing it. Recommended first: \"Install Gyroflow, the\nfree open-source stabiliser\", saying how: `brew install gyroflow` on a Mac\nwith Homebrew, otherwise the download at https://gyroflow.xyz/download (the Microsoft Store on\nWindows; the `.tar.gz` or the Flatpak on Linux). The other option: \"Don't install: keep the shots\nas shot.\" **Never install anything without the user's yes to this question.** A yes goes into\n`approvals` with the scope `install:stabiliser` and is never asked twice; a yes to stabilising is\nnot a yes to installing. In unattended pace, the assumed answer is no: write it to\n`openDecisions` and keep the shots as shot. When the install fails or needs an administrator\npassword, say so, keep the shots as shot and go on; never retry it unasked.\n\n**Stabilised proxies.** Make one from each stabilised copy, as above, and upload it beside the\nplain proxy: the conform checks it (below), and when the user wants to see the stabilisation in\nreview before the finish, render the copies then. Keep the plain proxy for the log, since the\nanalysis measures what the camera saw.\n\n## Per-short windows\n\nA long episode cut into several shorts is uploaded as **one window per short**, not whole: from\nthe short's first clip to its last, plus a second each side. A whole episode is often past the\n100 MB upload limit, and a variable frame rate, B-frames or a stream that starts late can make the\nrender jump a frame. Each window is re-encoded at a constant 30 fps from 0, a keyframe a second:\n\n```\nffmpeg -ss <A> -to <B> -i \"<original>\" -vf fps=30,format=yuv420p -c:v libx264 -profile:v high \\\n  -crf 20 -g 30 -keyint_min 30 -sc_threshold 0 -c:a aac -b:a 128k -ar 48000 -ac 2 \\\n  -avoid_negative_ts make_zero -movflags +faststart \"proxy/win-<short>.mp4\"\n```\n\nCheck each window with `ffprobe` before uploading it: `r_frame_rate` 30/1, the video and audio\n`start_time` both 0, and the file under 100 MB (else narrow the window). Every time in that\nshort's cut is then in the window's seconds: a source second `s` is `s - A`. Write the window's\n`A` and `B` beside its row in `proxy/manifest.csv`, so the conform maps back to the original.\n\n## The conform, at the finish\n\nWhen the user chose the conform, rebuild the approved version from the originals at full\nresolution:\n\n1. Read the approved version's plan. Map each shot's proxy range to its original through the\n   manifest; the times are the same, since the frame counts match.\n2. When the user chose gyro stabilisation, stabilise each source with gyro data first (below),\n   keeping a stabilised range only when it is steadier, its choice in `stabilised.ranges`.\n3. Cut each range from the file its check chose, the original or its stabilised copy, into\n   `work/` at the master's frame rate. A source the log found turned (`upright` in its\n   `sources` row) is turned first, before its crop: `transpose=1` for `rot90`, `transpose=2`\n   for `rot270`, `hflip,vflip` for `rot180`. Count frames from each shot's scene start so the cuts\n   never drift, into an intermediate that keeps 10 bits (ProRes 422 HQ). Stabilise first, then the LUT: a log source\n   goes through the same LUT its proxy did (`log.lut`), decoded with `in_range=pc` as above, and\n   the look the approved scene carried is baked in there or applied right after it. One shot that\n   sits under or over the rest gets its own LUT with `log_lut.py --exposure`, never a lift of the\n   whole edit. Look at one frame of each shot before joining them.\n4. Join them in the plan's order over black, with the approved end card and captions (below), and\n   the approved audio (below).\n5. Check the master against the approved version, frame for frame: the same length, the same cut\n   points, the same words when both are transcribed.\n\nA master that differs is fixed in the conform, never delivered as it is. Deliver the master in the\nformat the brief or the reference names, at the originals' resolution; never add another size or\nversion nobody asked for.\n\n### Captions at full resolution\n\nThe scene's captions are burned in at the conform, in the same font, colour, size and place,\nscaled to the master. Write them as an `.ass` file with `scripts/captions_ass.py` (its usage says\nthe JSON it reads), and burn them with `subtitles='work/captions.ass':fontsdir='<brand font folder>'`,\nso the brand's own font file is used. Two things first:\n\n- **The font file is there.** libass quietly falls back to another font when the family is not in\n  `fontsdir`, so check that the folder holds a file of the caption's family (its name, or\n  `fc-scan` where present). When it does not, ask for the brand's font file with\n  `picsart_drive_upload_ask`, or keep the captions `open`; never burn them in a substitute.\n- **This ffmpeg has the filter** (`ffmpeg -hide_banner -filters | grep subtitles`); many builds\n  lack it and `drawtext` both. `python3` missing is the same case: no `.ass` can be written.\n\nWhen either is missing, ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) separately how to finish. Recommended first: \"Install\nffmpeg-full, the full ffmpeg with subtitle support\", the same package and command as in ffmpeg\nfirst, above (`brew install ffmpeg-full` on a Mac). The other options: \"Deliver the free scene export with its captions instead\", which exports\nthe approved scene with `picsart_scene_export` at the delivery resolution (from the proxies, so\nbelow the originals' quality, and said so), and \"Don't install: the captions stay off the master\nfor now\". **Never install anything without the user's yes to this question.** A yes to installing\ngoes into `approvals` with the scope `install:ffmpeg` and is never asked twice: that scope\nalready approved means ffmpeg-full is installed, so use its binary rather than asking again. A yes to captions is not a yes to installing. In unattended pace, the assumed answer is the scene export: write it\nto `openDecisions` and deliver that. When the install fails or needs an administrator password,\nsay so and never retry it unasked. On \"stay off\", the captions are `open`: finish the rest of the\nmaster, say that its captions are not burned in, and stop before delivery. Never swap the brand\nfont for another one, and never deliver the master without its captions as if it were done.\n\n### The voice and sound at full resolution\n\nTake every voice from the original recording, never from a proxy or a scene export: cut its range,\nremove rumble below about 80 Hz, and set its loudness in two passes (measure with\n`loudnorm=print_format=json`, then apply the measured values with `linear=true`) to about -14 LUFS\nwith true peak under -1.5 dBTP. Place it at its scene start and pad it to the master's length with\nsilence, so it plays once and never repeats under the end card.\n\n### Stabilising with Gyroflow\n\nGyroflow renders next to the source by default, so always give it an absolute output path in\n`work/`; the original is read, never written, and a symlinked footage folder is resolved first so\nnothing lands in it. One source at a time:\n\n```\ngyroflow \"<original>\" -p \"{ 'codec': 'ProRes', 'codec_options': 'ProRes 422 HQ', 'audio_codec': 'Copy', 'output_path': '<abs project>/work/<name>.stab.mov' }\"\ngyroflow \"<original>\" --export-metadata \"3:<abs project>/work/<name>.camera.json\"\n```\n\nType the braces once, as here (Gyroflow's help prints them doubled). ProRes takes every source as\nit is; for an HEVC output instead (`'codec': 'H.265/HEVC'`), a 4:2:2 10-bit source needs\n`'pixel_format': 'P010LE'`. Never run `--export-project`: it writes a `.gyroflow` file beside the\noriginal, in the footage folder, whatever output path you give. When Gyroflow says the lens\nis unknown, pass the lens profile's JSON file as another input after the original, with no flag\n(`gyroflow \"<original>\" \"<lens profile>.json\" -p …`); never guess one. Settings saved as a preset go\nin with `--preset <file>`. It exits 0 on\nsuccess, 1 when the render failed and 2 on a bad argument: on 1 or 2, keep that source as shot,\nsay so, and go on. When it renders but its camera data holds no gyroscope samples (a Sony source\nthat was only `\"maybe\"`), it had no motion to use: keep that source as shot.\n\nThen check the copy with `ffprobe` against the original: the same fps, frame count and length.\nWrite into the source `stabilised`: its `file`, and its `crop`, the largest zoom Gyroflow applied\n(1.12 keeps the middle 1/1.12 of the frame on each axis). Read the zoom from the camera data's\n`zooming` fields; when they do not make it plain, measure it on one still pair: the distance\nbetween two fixed details in the stabilised frame over the same distance in the original.\n\n**Keep a stabilised range only when it is steadier.** Measure each used range on the stabilised\nproxy as on the plain one, on the same fixed detail with texture, as the edit-pipeline skill's gate\nrules say, never by a whole-frame scan: a moving subject reads as shake there. A range that is not\nsteadier (a gimbal shot already steady, say) stays as shot. Then run every framing and safe-zone\ncheck on that source, the footage-reframing skill's included, on the stabilised proxy itself, not\nonly against the middle 1/crop of the frame: roll and lens correction move points, so a face or a\ncaption inside that rectangle on the plain proxy can still leave the frame. A range that fails is\nkept as shot. Write each range's choice into the source's `stabilised.ranges`, never into its\n`ranges` (which the log wrote, so a change there would redo every stage after it): `in`, `out`,\n`use` (`stabilised` or `original`) and `shake`, the two measurements `[plain, stabilised]`. Cut\neach range from the file it chose.\n\n## Colour comparison, against the reference\n\nWhen the record holds a reference and ffmpeg is on this computer, compare the draft's colour with\nthe reference's by measurement first. Read one frame a second of each, the draft's `exports/`\nfile and the reference clip:\n\n```\nffmpeg -hide_banner -i \"<file>\" -vf \"fps=1,format=yuv420p,signalstats,metadata=mode=print:file=-\" -f null - 2>/dev/null \\\n  | grep -E \"lavfi.signalstats.(YAVG|SATAVG)=\"\n```\n\n`format=yuv420p` puts both files on the same 8-bit scale first: `signalstats` reads in the input's\nown bit depth, so a 10-bit draft would read about four times brighter than an 8-bit reference.\n`YAVG` is then the brightness (0 to 255) and `SATAVG` the saturation. Average each over the file and\nset the two side by side. The grade has drifted when either differs by more than about a tenth of\nthe reference's value: a draft clearly darker or flatter than the reference. Hue is judged by eye:\nlook at a frame of each side by side for a draft warmer, cooler or tinted another way than the\nreference, since no single hue figure survives a frame whose colours sit either side of red. At the look stage the same reading, with `YLOW` (the black point) and `YHIGH` (the white point)\nadded to the `grep`, is taken on the board's stills and on the same frames in the chosen look;\nedit-footage's `scripts/look_check.py` compares them. A\ndrift is fixed at the look, before the review, and said in one line when it is the user's own\nchoice; a figure that could not be read is `open`, never a pass. Where ffmpeg is not here, the use\ncase compares stills of both by eye instead.\n\n## The final check, on this computer\n\nBesides the checks the use case runs on every finish, run quality-review's `qc.py` on the master's\n`ffprobe` and loudness reading (`ffmpeg -af loudnorm=print_format=json -f null -`): about -14 LUFS\nwith true peak under -1 dBTP.\n\n## Deliver\n\nPut the final files in `exports/` beside any earlier ones; an old file is removed only on a yes.\nThe cut list names each original, not its proxy.\n"
}

SHA-256 of public snapshot: f6f02bcf48a82b96969fef3f00f50047d01d441a1ac78ce14d73ac8af4ba7ce9