THE TOOLS
=========

These tools work on TAKES: many versions of the same shot, made with the same
prompt and frames but different seeds. No camera crew can give you thirteen takes
that are identical except for how something moves. The AI can, in minutes.
The tools then do with those takes what no editor would do by hand.

How every tool works:
  1. Put the takes of ONE shot in a folder (same size, same length).
  2. Copy the tool (the .bat file) into that folder and double-click it.
     Or leave it where it is and drag the folder onto it. Both work.
     (A copied tool finds the kit by itself, once START.bat has run one time.)
  3. The first time, the tool writes a recipe (a .txt) in the folder and uses it.
  4. The result goes into a new folder inside yours, with a .txt beside it
     that says exactly how it was made.
  5. Open the recipe, change a word or a number, save, drag the folder again.
     Ask the chat to write a recipe for you if you like: it is just text.

  The first take by name is the BASE. It gives the sound.
  Several recipes in one file, separated by a line of ---, make several results.


ASPERO   (cut between takes)                               folder -> aspero\
--------------------------------------------------------------------------
The base take plays. On certain frames, a frame from another take jumps in.
Same shot, same light, a different performance for a moment: the picture flinches.

Where the jumps land is a PATTERN, the same idea as a rhythm:
  fib          1, 2, 3, 5, 8, 13, 21 ... dense at the start, calm later. A gesture.
  revfib       the same, backwards: calm first, dense at the end.
  tresillo, cinquillo, habanera, son, rumba, bossa, shiko, gahu, fourfloor, backbeat
               rhythms by name. A pulse.
  euclid 5 16  5 hits spread evenly over 16 steps (any two numbers).
  steps x..x.x..   write your own rhythm: x = hit, . = rest.
  even 12, phi 11, prime, list 12 30 45   more ways to place them.

  step:    how many frames one step of a rhythm lasts (6 = 4 steps per second)
  length:  how many frames each jump lasts (1 = a single frame)
  window:  only cut between these seconds, e.g. 2 5. Less is often more:
           touch every frame and the shot loses its soul.
Try it on: examples\S01A_takes


CRAB                                               folder -> crab\
------------------------------------------------------------------
N frames forward, M frames back, again and again. Nothing new is made: every frame
on screen is a real frame of the take. Only the ORDER is invented.
The shot keeps advancing but keeps flinching backwards. It is longer than the take.

  forward: 3   back: 1   the classic crab
  from: tail   walk backwards through the shot
  salad: back  the steps back land in OTHER takes: the right moment of a
               performance that never happened
It works best on water: a wave that cannot decide. On a person it reads as undoing.
One take is enough.
Try it on: examples\S07E2_surf_takes


VELVET   (the opposite of aspero)                         folder -> velvet\
--------------------------------------------------------------------------
Every frame is the AVERAGE of that frame in all the takes.
Where the takes agree, the picture stays sharp. Where they disagree, it turns soft
and ghostly: several waves, several hands at once. The difference between the takes
becomes the picture.

  mode: mean     everything averaged
        median   only what most takes agree on survives
        ramp     starts as one take, becomes all of them by the end
        breathe  mostly velvet; on a rhythm's hits it falls to ONE take and swells back
        quantum  the footage decides: one take where they disagree, all where they agree
        trail    the average, leaving a wake behind what moves

It needs takes that agree somewhere. First-and-last-frame takes (workflow 03) are
ideal: they all start and end on the same frame, so the velvet blooms in the middle.
Takes with different framings just turn into mud (try VELVET on S01A to see that).
Try it on: examples\S07E2_surf_takes


MELT                                       video or folder -> melt\
------------------------------------------------------------------
A different kind of tool: this one uses diffusion (a small image model, on the GPU).
Every frame is redrawn, and before it is redrawn it is mixed with the frame the
model drew last. The picture never resets, so it dissolves continuously, like the
old Deforum films. LTX cannot do this; MELT does it afterwards.

  prompt:    describe what is IN the video. A wrong prompt looks absurd.
  strength:  how much each frame is redrawn (0.25 barely, 0.42 photographic, 0.58 invents)
  feedback:  how much of the last frame flows into the next (0.6-0.75 = melting)
  frames:    try a setting on the first 48 frames before doing the whole video
A good pair: ASPERO first, then MELT the cut. Close ComfyUI first (both want the GPU).
About a minute for 6 seconds of video.


INDEX                                                folder -> index.html
--------------------------------------------------------------------------
Every video in the folder and its subfolders on one page, with proper names:
the takes first, then each result folder (aspero, velvet, crab, your scripts).
Click to play, F for full screen, arrows for the next one; "how it was made"
under each result. RUN.bat opens it by itself at the end.


RUN  (scripts from a chat)                                   folder -> index.html
--------------------------------------------------------------------------
Copy RUN.bat and one or more .py scripts (tools\scripts, or written by a chat)
into a folder of takes. Double-click RUN: every .py runs, then INDEX opens.
How to make a new script with a chat: scripts\FOR_THE_CHAT.txt


VIEW                                                 folder -> view.html
------------------------------------------------------------------------
Two ways to look at a folder:
  GRID  everything at once, playing: the takes, then every result, grouped,
        each with its recipe underneath.
  PAGE  your study: the text you write in study.txt flows around the videos while
        they play. A line like  @ velvet/01_mean.mp4  puts that video there in the
        text. Drag a video anywhere, drag its corner to resize it: the text moves out
        of the way. (Text layout by Pretext, github.com/chenglou/pretext, MIT.)
  PULSE (on the page): the text jolts on a rhythm and settles again.
        from the cut  the text around an ASPERO result jolts on the exact frames
                      where that video cuts (read from its .txt record)
        tresillo, son, fib ...   the same rhythms as the tools
        Write  pulse: cut  (or  pulse: tresillo) in study.txt to start with it on.
  The first time, VIEW writes a study.txt to start from. Run VIEW again after editing it.
  See examples\S07E2_surf_takes\view.html.
  click         sound on that one
  double-click  big
  All from the start   restarts every video together (to compare takes frame by frame)
Run VIEW again after new results. You can also drop any folder onto the open page.


MY-TOOL   (make your own)
-------------------------
A working example to copy. Read HOW-TO-MAKE-A-TOOL.txt: you can build a new tool
by pasting the code into Claude or ChatGPT in the browser and describing your idea.
