jump-cut 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
jump_cut/__init__.py ADDED
@@ -0,0 +1,2 @@
1
+ """Jump Cut Editor: cut a raw talking-head take into a finished video."""
2
+ __version__ = "1.0.0"
jump_cut/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cut import main
2
+
3
+ main()
jump_cut/cut.py ADDED
@@ -0,0 +1,584 @@
1
+ """Turn a raw take into a postable cut, using the script to know what was meant.
2
+
3
+ jump-cut transcribe TAKE.mp4 WORK_DIR [--captions]
4
+ jump-cut plan WORK_DIR SCRIPT.txt
5
+ jump-cut render TAKE.mp4 WORK_DIR OUT.mp4 --shape 16:9|9:16 [--captions] [--zoom]
6
+
7
+ transcribe writes WORK_DIR/words.json (every spoken word with start and end).
8
+ plan writes WORK_DIR/plan.json (the words kept, line by line) and prints a report
9
+ of everything cut. Read the report before rendering; plan.json can be edited by hand.
10
+ render cuts, frames, captions and punches in, and writes OUT.mp4.
11
+ """
12
+ import difflib, json, os, re, shutil, subprocess, sys, tempfile
13
+
14
+ PAD = 0.08 # least air kept before and after each kept stretch
15
+ PUNCH = 1.15 # zoom on the peak line
16
+
17
+
18
+ def ffmpeg():
19
+ exe = shutil.which('ffmpeg')
20
+ if exe:
21
+ return exe
22
+ try:
23
+ import imageio_ffmpeg
24
+ return imageio_ffmpeg.get_ffmpeg_exe()
25
+ except ImportError:
26
+ sys.exit('ffmpeg not found: install ffmpeg, or pip install imageio-ffmpeg')
27
+
28
+
29
+ def audio16k(path):
30
+ """The take's sound as 16 kHz mono samples, decoded by ffmpeg. Passing samples instead of a file name keeps
31
+ faster-whisper away from its own decoder, which breaks with newer releases of the av library."""
32
+ import numpy as np
33
+ raw = subprocess.run([ffmpeg(), '-v', 'error', '-i', path, '-vn', '-ac', '1', '-ar', '16000', '-f', 'f32le', '-'],
34
+ check=True, capture_output=True).stdout
35
+ return np.frombuffer(raw, dtype=np.float32)
36
+
37
+
38
+ def norm(w):
39
+ return re.sub(r"[^\w']", '', w.lower().replace('’', "'"))
40
+
41
+
42
+ NUMBERS = {w: str(i) for i, w in enumerate(
43
+ 'zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen '
44
+ 'seventeen eighteen nineteen twenty'.split())}
45
+ NUMBERS.update({'thirty': '30', 'forty': '40', 'fifty': '50', 'sixty': '60', 'seventy': '70', 'eighty': '80',
46
+ 'ninety': '90', 'hundred': '100'})
47
+
48
+
49
+ def canon(word):
50
+ """A word as the tokens it sounds like, so the script and the take match however a number is written:
51
+ '4/10' and 'four out of ten', '15%' and 'fifteen percent', '6pm' and 'six p.m.'."""
52
+ w = word.lower().replace('’', "'").strip('"\'.,!?;:()[]')
53
+ m = re.fullmatch(r'(\d+)/(\d+)', w)
54
+ if m:
55
+ return [m.group(1), 'out', 'of', m.group(2)]
56
+ m = re.fullmatch(r'(\d+(?:\.\d+)?)%', w)
57
+ if m:
58
+ return [m.group(1), 'percent']
59
+ w = w.replace('.', '') if re.fullmatch(r'[ap]\.?m\.?', w) else w
60
+ m = re.fullmatch(r'(\d+)(?::(\d\d))?\s*([ap]m)', w)
61
+ if m:
62
+ return [m.group(1)] + ([m.group(2)] if m.group(2) else []) + [m.group(3)]
63
+ out = []
64
+ for part in re.split(r'[-–]', w):
65
+ part = norm(part)
66
+ if part == '%':
67
+ part = 'percent'
68
+ if part:
69
+ out.append(NUMBERS.get(part, part))
70
+ return out
71
+
72
+
73
+ def canon_list(texts):
74
+ """Canonical tokens for a list of words, each tagged with the index of the word it came from."""
75
+ toks, owner = [], []
76
+ for k, t in enumerate(texts):
77
+ for c in canon(t):
78
+ toks.append(c)
79
+ owner.append(k)
80
+ return toks, owner
81
+
82
+
83
+ # ---------- transcribe ----------
84
+
85
+ def transcribe(take, work, careful=False):
86
+ from faster_whisper import WhisperModel
87
+ os.makedirs(work, exist_ok=True)
88
+ # captions show every word, so they get the slower model that mishears less
89
+ model = WhisperModel(os.environ.get('CUT_MODEL', 'medium' if careful else 'small'), device='cpu', compute_type='int8')
90
+ segs, info = model.transcribe(audio16k(take), language=os.environ.get('CUT_LANG') or None, word_timestamps=True, vad_filter=False)
91
+ words = []
92
+ for s in segs:
93
+ for w in s.words:
94
+ if norm(w.word):
95
+ words.append({'i': len(words), 'text': w.word.strip(), 'start': round(w.start, 3), 'end': round(w.end, 3)})
96
+ words = unfold_repeats(model, take, words)
97
+ json.dump({'language': info.language, 'words': words}, open(os.path.join(work, 'words.json'), 'w', encoding='utf-8'), indent=1)
98
+ print(f'{len(words)} words, language {info.language}, written to {work}/words.json')
99
+
100
+
101
+ def unfold_repeats(model, take, words):
102
+ """Transcription tends to drop a phrase said twice in a row ('you see why Gyro is, you see why Gyro is in
103
+ the race'), folding the second go into one word that lasts far too long. Each such word, where the take
104
+ is still speech the whole time, is heard again on its own and the words it hid are put back."""
105
+ rms, speech = loudness(take)
106
+ out = []
107
+ for k, w in enumerate(words):
108
+ dur = w['end'] - w['start']
109
+ f0, f1 = int(w['start'] / 0.02), int(w['end'] / 0.02)
110
+ talking = f1 > f0 and (rms[f0:f1] > 0.4 * speech).mean() > 0.5
111
+ if dur > 0.6 + 0.12 * len(norm(w['text'])) and talking:
112
+ # heard alone, just the stretched word: with more around it the repeat gets dropped again
113
+ a = max(0.0, w['start'] - 0.1)
114
+ clip = os.path.join(tempfile.mkdtemp(), 'clip.wav')
115
+ subprocess.run([ffmpeg(), '-v', 'error', '-y', '-ss', f'{a:.3f}', '-to', f"{w['end'] + 0.15:.3f}", '-i', take,
116
+ '-vn', '-ac', '1', '-ar', '16000', clip], check=True)
117
+ segs, _ = model.transcribe(audio16k(clip), language=os.environ.get('CUT_LANG') or None, word_timestamps=True,
118
+ condition_on_previous_text=False, vad_filter=False)
119
+ hidden = [{'text': x.word.strip(), 'start': round(x.start + a, 3), 'end': round(x.end + a, 3)}
120
+ for s in segs for x in s.words if norm(x.word)]
121
+ nxt = words[k + 1]['start'] if k + 1 < len(words) else float('inf')
122
+ hidden = [x for x in hidden if x['start'] < nxt]
123
+ if len(hidden) > 1:
124
+ # the clip ends mid-sentence, so a full stop the model puts at its end is not theirs
125
+ hidden[-1]['text'] = hidden[-1]['text'].rstrip('.,!?…') or hidden[-1]['text']
126
+ out += hidden
127
+ continue
128
+ out.append(w)
129
+ for i, w in enumerate(out):
130
+ w['i'] = i
131
+ return out
132
+
133
+
134
+ # ---------- plan ----------
135
+
136
+ CUE = re.compile(r'\([^)]*\)|\[[^\]]*\]')
137
+
138
+
139
+ def read_script(path):
140
+ """Lines of the script as spoken sentences. Delivery cues in brackets are not spoken.
141
+ A line is the peak if it holds a word of three or more letters in ALL CAPS (so AI or TV is not one), follows a (beat)-style cue, or starts with *."""
142
+ text = open(path, encoding='utf-8').read()
143
+ lines, cue_before = [], False
144
+ for raw in text.splitlines():
145
+ raw = raw.strip()
146
+ if not raw or raw.lower().startswith('note:'):
147
+ continue
148
+ star = raw.startswith('*')
149
+ had_cue = bool(CUE.search(raw))
150
+ spoken = CUE.sub(' ', raw.lstrip('*')).strip()
151
+ for sent in re.split(r'(?<=[.!?])\s+', spoken):
152
+ toks = sent.split()
153
+ if not [t for t in toks if norm(t)]:
154
+ continue
155
+ caps = any(len(norm(t)) > 2 and norm(t).isalpha() and t.strip('.,!?;:"\'').isupper() for t in toks)
156
+ lines.append({'text': sent, 'tokens': toks, 'peak': star or caps or cue_before})
157
+ cue_before = False
158
+ if had_cue and not spoken:
159
+ cue_before = True
160
+ if lines and not any(l['peak'] for l in lines):
161
+ pass
162
+ return lines
163
+
164
+
165
+ def candidates(line, wc):
166
+ """Every place in the take where this line was attempted, scored by how much of it was said.
167
+ wc is the take as canonical tokens with the word each came from."""
168
+ s, _ = canon_list(line['tokens'])
169
+ w, owner = wc
170
+ n, out = len(s), []
171
+ if not n:
172
+ return out
173
+ heads = set(s[:2])
174
+ for i in range(len(w)):
175
+ if w[i] not in heads or (i and owner[i] == owner[i - 1]):
176
+ continue
177
+ window = w[i:i + n + max(4, n // 2)]
178
+ sm = difflib.SequenceMatcher(None, s, window, autojunk=False)
179
+ matched = sum(b.size for b in sm.get_matching_blocks())
180
+ cover = matched / n
181
+ if cover < 0.6:
182
+ continue
183
+ keep = []
184
+ for tag, a1, a2, b1, b2 in sm.get_opcodes():
185
+ if tag == 'equal' or (tag == 'replace' and (b2 - b1) <= (a2 - a1) + 1):
186
+ keep += [owner[i + b] for b in range(b1, b2)]
187
+ keep = sorted(set(keep))
188
+ if keep:
189
+ out.append({'start': keep[0], 'end': keep[-1], 'keep': keep, 'cover': round(cover, 3)})
190
+ return out
191
+
192
+
193
+ def plan(work, script):
194
+ words = json.load(open(os.path.join(work, 'words.json'), encoding='utf-8'))['words']
195
+ lines = read_script(script)
196
+ wc = canon_list([x['text'] for x in words])
197
+ cands = [candidates(l, wc) for l in lines]
198
+ # choose one attempt per line, in order, never overlapping: best coverage, then the latest take
199
+ n = len(lines)
200
+ best = {} # (line index, last word index) -> (score, choice list)
201
+
202
+ def solve(k, after):
203
+ if k == n:
204
+ return (0.0, [])
205
+ key = (k, after)
206
+ if key in best:
207
+ return best[key]
208
+ options = [(solve(k + 1, after)[0] - 1.0, [None] + solve(k + 1, after)[1])] # line missing from the take
209
+ for c in cands[k]:
210
+ if c['start'] > after:
211
+ sub = solve(k + 1, c['end'])
212
+ options.append((c['cover'] + 0.001 * c['start'] / max(1, len(words)) + sub[0], [c] + sub[1]))
213
+ best[key] = max(options, key=lambda o: o[0])
214
+ return best[key]
215
+
216
+ sys.setrecursionlimit(10000)
217
+ choice = solve(0, -1)[1]
218
+ # a line said well only in an earlier attempt sits out of take order: take its best attempt
219
+ # from anywhere, as long as it shares no words with a line already placed
220
+ used = set(i for c in choice if c for i in c['keep'])
221
+ for k, c in enumerate(choice):
222
+ if c is None:
223
+ free = [x for x in cands[k] if not used.intersection(x['keep'])]
224
+ if free:
225
+ choice[k] = max(free, key=lambda x: (x['cover'], x['start']))
226
+ used.update(choice[k]['keep'])
227
+ added = keep_adlibs(words, lines, choice)
228
+ kept = set()
229
+ out_lines = []
230
+ for line, c in zip(lines, choice):
231
+ if c is None:
232
+ out_lines.append({'text': line['text'], 'peak': line['peak'], 'missing': True, 'words': []})
233
+ continue
234
+ kept.update(c['keep'])
235
+ # captions use the script's spelling for each kept word, matched by position
236
+ # each kept word shows the script word it says ('four','out','of','ten' all show as one '4/10'),
237
+ # and a word the script does not have shows as heard
238
+ s_tokens = line['tokens']
239
+ sc, s_own = canon_list(s_tokens)
240
+ kc, k_own = canon_list([words[i]['text'] for i in c['keep']])
241
+ sm = difflib.SequenceMatcher(None, sc, kc, autojunk=False)
242
+ shown = [words[i]['text'] for i in c['keep']]
243
+ first = {} # script word -> the kept word that shows it
244
+ for tag, a1, a2, b1, b2 in sm.get_opcodes():
245
+ if tag == 'equal':
246
+ pairs = [(k_own[b1 + j], s_own[a1 + j]) for j in range(b2 - b1)]
247
+ elif tag == 'replace' and (a2 - a1 == b2 - b1 == 1 or sounds_alike(sc[a1:a2], kc[b1:b2])):
248
+ # one word for one word, or a misheard name: the heard words show the script's words, minus any script
249
+ # word at the edge they did not say ('poko loko' is 'Pocoloco', not 'and Pocoloco')
250
+ a1, a2 = trim_unsaid(sc, a1, a2, kc[b1:b2])
251
+ for j in range(b1, b2):
252
+ shown[k_own[j]] = ''
253
+ n_s, n_k = a2 - a1, b2 - b1
254
+ pairs = [(k_own[b1 + min(j * n_k // n_s, n_k - 1)], s_own[a1 + j]) for j in range(n_s)]
255
+ else:
256
+ continue # said differently from the script: it shows as heard
257
+ for kw, st in pairs:
258
+ if st in first:
259
+ if first[st] != kw:
260
+ shown[kw] = '' # one script word said as several ('four out of ten' for '4/10')
261
+ continue
262
+ shown[kw] = s_tokens[st] if kw not in first.values() else shown[kw] + ' ' + s_tokens[st]
263
+ first[st] = kw
264
+ out_lines.append({'text': line['text'], 'peak': line['peak'], 'cover': c['cover'],
265
+ 'words': [{'i': i, 'text': t, 'start': words[i]['start'], 'end': words[i]['end']}
266
+ for i, t in zip(c['keep'], shown)]})
267
+ json.dump({'lines': out_lines}, open(os.path.join(work, 'plan.json'), 'w', encoding='utf-8'), indent=1)
268
+
269
+ # report: what was cut, in take order, so a person can check nothing they meant was lost
270
+ print('KEPT, line by line:')
271
+ for l in out_lines:
272
+ mark = ' (peak)' if l['peak'] else ''
273
+ if l.get('missing'):
274
+ print(f" MISSING from the take: {l['text']}")
275
+ else:
276
+ print(f" {l['words'][0]['start']:6.2f}s {round(l['cover'] * 100)}%{mark} {' '.join(w['text'] for w in l['words'])}")
277
+ print('ADDED, said but not in the script, kept:')
278
+ for r in added:
279
+ print(f" {words[r[0]]['start']:6.2f}s {' '.join(words[i]['text'] for i in r)}")
280
+ print('CUT, in take order:')
281
+ run = []
282
+ for w in words + [None]:
283
+ if w is not None and w['i'] not in kept:
284
+ run.append(w)
285
+ continue
286
+ if run:
287
+ print(f" {run[0]['start']:6.2f}s {' '.join(x['text'] for x in run)}")
288
+ run = []
289
+ print(f'plan written to {work}/plan.json')
290
+
291
+
292
+ FILLER = {'um', 'umm', 'uh', 'uhh', 'er', 'erm', 'ah', 'hmm', 'mm', 'like', 'so', 'yeah', 'but', 'well', 'basically',
293
+ 'literally', 'okay', 'ok', 'right'}
294
+ META = re.compile(r"\b(let me (do|say|start|try|redo) (that|this|it)( one)?( again| over)?|one more time|start (again|over)|"
295
+ r"from the top|is (it|this) recording|hold on|take two|again sorry)\b|^(wait|sorry|okay|ok|cut|right|again)$")
296
+
297
+
298
+ def sounds_alike(a, b):
299
+ """Two runs of tokens that are one thing misheard ('stillbore on' for 'steel ball run', 'poko loko' for 'pocoloco')."""
300
+ return alike(a, b) >= 0.5
301
+
302
+
303
+ def alike(a, b):
304
+ return difflib.SequenceMatcher(None, ''.join(a), ''.join(b), autojunk=False).ratio()
305
+
306
+
307
+ def trim_unsaid(sc, a1, a2, heard):
308
+ """Drop script words from either end of a misheard stretch while that makes it sound more like what was heard."""
309
+ while a2 - a1 > 1:
310
+ now = alike(sc[a1:a2], heard)
311
+ if alike(sc[a1 + 1:a2], heard) > now:
312
+ a1 += 1
313
+ elif alike(sc[a1:a2 - 1], heard) > now:
314
+ a2 -= 1
315
+ else:
316
+ break
317
+ return a1, a2
318
+
319
+
320
+ def keep_adlibs(words, lines, choice):
321
+ """Words the plan did not give to a line are cut only when they are a retake, a false start, filler or
322
+ talk about the take. Anything else they said on purpose (an aside, a joke, their own wording of a line)
323
+ stays, in take order, inside the line it was said after. Returns the added runs, for the report."""
324
+ owner = {}
325
+ for k, c in enumerate(choice):
326
+ if c:
327
+ for i in c['keep']:
328
+ owner[i] = k
329
+ # stretches not given to a line, split at each sentence end and long pause, so a practice attempt
330
+ # breaks into its sentences and each is judged on its own
331
+ runs, cur = [], []
332
+ for w in words:
333
+ if w['i'] in owner:
334
+ if cur:
335
+ runs.append(cur)
336
+ cur = []
337
+ continue
338
+ if cur and (words[cur[-1]]['text'].endswith(('.', '?', '!')) or w['start'] - words[cur[-1]]['end'] > 1.5):
339
+ runs.append(cur)
340
+ cur = []
341
+ cur.append(w['i'])
342
+ if cur:
343
+ runs.append(cur)
344
+ in_take = set(owner) # what the plan chose, before anything is added
345
+ toks = [canon_list(l['tokens'])[0] for l in lines]
346
+ added = []
347
+ for run in runs:
348
+ rc = canon_list([words[i]['text'] for i in run])[0]
349
+ text = ' '.join(rc)
350
+ if not rc or all(t in FILLER for t in rc) or text in ('you know', 'i mean') or META.search(text):
351
+ continue
352
+ nxt = owner.get(run[-1] + 1)
353
+ if len(rc) <= 2 and nxt is not None:
354
+ after = canon(words[run[-1] + 1]['text'])
355
+ if after and rc[:len(after)] == after[:len(rc)] or (after and rc[0] == after[0]):
356
+ continue # a doubled word or a one-word false start: 'it, it was'
357
+ best, line_k = 0, None
358
+ for k, s in enumerate(toks):
359
+ sm = difflib.SequenceMatcher(None, rc, s, autojunk=False)
360
+ m = sum(b.size for b in sm.get_matching_blocks())
361
+ if m >= 2 and m / len(rc) > best:
362
+ best, line_k = m / len(rc), k
363
+ prev = owner.get(run[0] - 1)
364
+ c_prev = choice[prev] if prev is not None else None
365
+ # the end of a line, misheard so the plan stopped short ('during execution' for 'during executions')
366
+ tail = c_prev is not None and c_prev['cover'] < 1 and len(rc) <= max(2, round((1 - c_prev['cover']) * len(toks[prev])) + 1)
367
+ if best >= 0.6 and not tail:
368
+ if choice[line_k] is None: # a line the plan could not find, said but misheard: it is that line
369
+ choice[line_k] = {'start': run[0], 'end': run[-1], 'keep': list(run), 'cover': round(best, 3)}
370
+ for i in run:
371
+ owner[i] = line_k
372
+ continue
373
+ if not (prev is not None and prev == line_k):
374
+ continue # a retake or false start of a line kept elsewhere
375
+ if nxt == line_k:
376
+ # a restart inside the line ('you see why Gyro is, you see why Gyro is in the race'):
377
+ # the go they carried through is the later one, so the first go is cut
378
+ before = [i for i in choice[line_k]['keep'] if i < run[0]]
379
+ starts = [j for j, i in enumerate(before) if canon(words[i]['text'])[:1] == rc[:1]]
380
+ if starts:
381
+ for i in before[starts[-1]:]:
382
+ owner.pop(i, None)
383
+ choice[line_k]['keep'] = sorted((set(choice[line_k]['keep']) - set(before[starts[-1]:])) | set(run))
384
+ for i in run:
385
+ owner[i] = line_k
386
+ continue
387
+ # an aside belongs to the take that was used: it sits between kept words. Anything else is
388
+ # left over from a practice attempt
389
+ if not (run[0] - 1 in in_take or run[-1] + 1 in in_take) or prev is None:
390
+ continue
391
+ k = prev
392
+ choice[k]['keep'] = sorted(set(choice[k]['keep']) | set(run))
393
+ for i in run:
394
+ owner[i] = k
395
+ if not tail:
396
+ added.append(run)
397
+ return added
398
+
399
+
400
+ # ---------- render ----------
401
+
402
+ def loudness(take):
403
+ """The take's audio as 20 ms loudness frames, so a pause is only cut when it is really quiet.
404
+ Word timings from transcription can miss a word (a 'percent' folded into '15'), and the gap they
405
+ leave is speech, not silence."""
406
+ import numpy as np
407
+ raw = subprocess.run([ffmpeg(), '-v', 'error', '-i', take, '-vn', '-ac', '1', '-ar', '16000', '-f', 's16le', '-'],
408
+ capture_output=True, check=True).stdout
409
+ a = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768
410
+ n = len(a) // 320
411
+ rms = np.sqrt((a[:n * 320].reshape(n, 320) ** 2).mean(axis=1))
412
+ speech = np.median(rms[rms > np.percentile(rms, 60)]) if n else 0
413
+ return rms, speech
414
+
415
+
416
+ def quiet(rms_speech, t0, t1):
417
+ rms, speech = rms_speech
418
+ f0, f1 = int(t0 / 0.02), int(t1 / 0.02)
419
+ seg = rms[f0:f1]
420
+ # a breath or a rustle peaks briefly and low, a missed word stays loud for a few frames
421
+ return len(seg) == 0 or (seg > 0.4 * speech).sum() < 3
422
+
423
+
424
+ def breath(plan_lines):
425
+ """The person's own pause between words, taken from the kept lines. Pauses up to about twice
426
+ this stay in, so the cut breathes the way they talk."""
427
+ gaps = []
428
+ for l in plan_lines:
429
+ ws = sorted(l['words'], key=lambda x: x['i'])
430
+ gaps += [b['start'] - a['end'] for a, b in zip(ws, ws[1:]) if b['i'] == a['i'] + 1 and b['start'] - a['end'] > 0.15]
431
+ gaps.sort()
432
+ return min(0.8, max(0.3, gaps[len(gaps) // 2])) if gaps else 0.5
433
+
434
+
435
+ def stretches(plan_lines, rms_speech, all_words):
436
+ """Kept words become stretches of the take. Words that follow each other in the take stay in one
437
+ stretch, across line ends too, unless the pause between them is long and truly quiet. A long pause
438
+ is cut down to one breath, not to nothing."""
439
+ br = breath(plan_lines)
440
+ out, prev = [], None
441
+ for l in plan_lines:
442
+ for w in sorted(l['words'], key=lambda x: x['i']):
443
+ if (prev and w['i'] == prev['i'] + 1 and l['peak'] == out[-1]['peak']
444
+ and (w['start'] - prev['end'] <= 2 * br or not quiet(rms_speech, prev['end'] + 0.03, w['start'] - 0.03))):
445
+ out[-1]['end'] = w['end']
446
+ out[-1]['words'].append(w)
447
+ else:
448
+ out.append({'start': w['start'], 'end': w['end'], 'peak': l['peak'], 'words': [w]})
449
+ prev = w
450
+ starts = sorted(x['start'] for x in all_words)
451
+ ends = sorted(x['end'] for x in all_words)
452
+ for s in out:
453
+ before = max([e for e in ends if e <= s['start'] - 0.01], default=0.0)
454
+ after = min([b for b in starts if b >= s['end'] + 0.01], default=s['end'] + 1.0)
455
+ # half a breath each side, never reaching into a word that was cut
456
+ s['a'] = max(0.0, before + 0.02, s['start'] - max(PAD, br / 2))
457
+ s['b'] = min(after - 0.02, s['end'] + max(PAD, br / 2))
458
+ for x, y in zip(out, out[1:]): # never play the same pause twice
459
+ if x['b'] > y['a'] and y['start'] >= x['end']:
460
+ x['b'] = y['a'] = (x['end'] + y['start']) / 2
461
+ return out
462
+
463
+
464
+ def probe_size(take):
465
+ r = subprocess.run([ffmpeg(), '-hide_banner', '-i', take], capture_output=True, text=True, encoding='utf-8', errors='replace')
466
+ m = re.search(r'Video:.*?(\d{2,5})x(\d{2,5})', r.stderr)
467
+ if not m:
468
+ sys.exit('no video stream found in ' + take)
469
+ rot = re.search(r'rotate\s*:\s*-?(90|270)|rotation of -?90', r.stderr)
470
+ w, h = int(m.group(1)), int(m.group(2))
471
+ return (h, w) if rot else (w, h)
472
+
473
+
474
+ def ass_time(t):
475
+ h, rem = divmod(max(0.0, t), 3600)
476
+ m, s = divmod(rem, 60)
477
+ return f'{int(h)}:{int(m):02d}:{s:05.2f}'
478
+
479
+
480
+ def captions(segs, W, H, path):
481
+ """Groups of 3 to 5 words, broken at a line end or a cut, one group on screen at a time,
482
+ placed inside the band the apps leave clear."""
483
+ groups, t = [], 0.0
484
+ for s in segs:
485
+ dur = s['b'] - s['a']
486
+ cur = []
487
+ for w in s['words']:
488
+ if not w['text']:
489
+ if cur:
490
+ cur[-1]['e'] = t + (w['end'] - s['a'])
491
+ continue
492
+ cur.append({'text': w['text'], 's': t + (w['start'] - s['a']), 'e': t + (w['end'] - s['a'])})
493
+ if len(cur) >= 5 or w['text'].rstrip('"\'').endswith(('.', '!', '?', ',')) and len(cur) >= 2:
494
+ groups.append(cur)
495
+ cur = []
496
+ if cur:
497
+ groups.append(cur)
498
+ t += dur
499
+ size = round(H * 0.045)
500
+ # low on the frame, under the face, where the creator's own posted videos put them
501
+ margin = round(H * 0.04) if H > W else round(H * 0.08)
502
+ lines = ['[Script Info]', 'ScriptType: v4.00+', f'PlayResX: {W}', f'PlayResY: {H}', '', '[V4+ Styles]',
503
+ 'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding',
504
+ f'Style: Cap,Arial,{size},&H00FFFFFF,&H00FFFFFF,&H00000000,&H64000000,-1,0,0,0,100,100,0,0,1,{max(3, size // 12)},0,2,{round(W * 0.15)},{round(W * 0.15)},{margin},1',
505
+ '', '[Events]', 'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text']
506
+ for gi, g in enumerate(groups):
507
+ start = max(0.1, g[0]['s'] - 0.05) if gi == 0 else g[0]['s'] - 0.05
508
+ end = groups[gi + 1][0]['s'] - 0.05 if gi + 1 < len(groups) else g[-1]['e'] + 0.4
509
+ end = max(end, g[-1]['e'])
510
+ text = ' '.join(w['text'] for w in g).replace('{', '(').replace('}', ')')
511
+ lines.append(f'Dialogue: 0,{ass_time(start)},{ass_time(end)},Cap,,0,0,0,,{text}')
512
+ open(path, 'w', encoding='utf-8').write('\n'.join(lines) + '\n')
513
+
514
+
515
+ def render(take, work, out, shape, with_captions=True, zoom=False):
516
+ p = json.load(open(os.path.join(work, 'plan.json'), encoding='utf-8'))
517
+ words = json.load(open(os.path.join(work, 'words.json'), encoding='utf-8'))['words']
518
+ segs = stretches([l for l in p['lines'] if not l.get('missing')], loudness(take), words)
519
+ if not segs:
520
+ sys.exit('nothing kept, check plan.json')
521
+ iw, ih = probe_size(take)
522
+ W, H = {'16:9': (1920, 1080), '9:16': (1080, 1920)}[shape]
523
+ if iw * H > ih * W: # source wider than target: crop the sides
524
+ crop = f'crop=ih*{W}/{H}:ih'
525
+ else: # source taller: crop top and bottom, keeping the upper part where faces sit
526
+ crop = f'crop=iw:iw*{H}/{W}:0:(ih-iw*{H}/{W})/3'
527
+ ff = ffmpeg()
528
+ tmp = tempfile.mkdtemp(prefix='cut-', dir=work)
529
+ parts = []
530
+ for k, s in enumerate(segs):
531
+ v = f'{crop},scale={W}:{H},setsar=1'
532
+ if zoom and s['peak']:
533
+ v += f',scale=iw*{PUNCH}:ih*{PUNCH},crop={W}:{H}'
534
+ part = os.path.join(tmp, f'{k:04d}.mp4')
535
+ subprocess.run([ff, '-v', 'error', '-y', '-ss', f"{s['a']:.3f}", '-to', f"{s['b']:.3f}", '-i', take,
536
+ '-vf', v + ',fps=30', '-af', 'aresample=48000,afade=t=in:d=0.01,areverse,afade=t=in:d=0.01,areverse',
537
+ '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-pix_fmt', 'yuv420p',
538
+ '-c:a', 'aac', '-b:a', '192k', '-ac', '2', part], check=True)
539
+ parts.append(part)
540
+ # the part's real length drives caption timing
541
+ s['b'] = s['a'] + duration(part)
542
+ lst = os.path.join(tmp, 'list.txt')
543
+ open(lst, 'w').write(''.join(f"file '{x.replace(os.sep, '/')}'\n" for x in parts))
544
+ joined = os.path.join(tmp, 'joined.mp4')
545
+ subprocess.run([ff, '-v', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', lst, '-c', 'copy', joined], check=True)
546
+ if with_captions:
547
+ ass = os.path.join(tmp, 'captions.ass')
548
+ captions(segs, W, H, ass)
549
+ esc = ass.replace('\\', '/').replace(':', '\\:')
550
+ subprocess.run([ff, '-v', 'error', '-y', '-i', joined, '-vf', f"subtitles='{esc}'",
551
+ '-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p', '-c:a', 'copy',
552
+ '-movflags', '+faststart', out], check=True)
553
+ else:
554
+ shutil.copy(joined, out)
555
+ shutil.rmtree(tmp, ignore_errors=True)
556
+ total = sum(s['b'] - s['a'] for s in segs)
557
+ print(f'{out}: {len(segs)} cuts joined, {total:.1f}s, {W}x{H}')
558
+
559
+
560
+ def duration(path):
561
+ r = subprocess.run([ffmpeg(), '-hide_banner', '-i', path], capture_output=True, text=True, encoding='utf-8', errors='replace')
562
+ m = re.search(r'Duration: (\d+):(\d+):([\d.]+)', r.stderr)
563
+ return int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3))
564
+
565
+
566
+ def main():
567
+ a = sys.argv[1:]
568
+ if not a:
569
+ sys.exit(__doc__)
570
+ if a[0] == 'transcribe' and len(a) in (3, 4):
571
+ transcribe(a[1], a[2], careful='--captions' in a)
572
+ elif a[0] == 'plan' and len(a) == 3:
573
+ plan(a[1], a[2])
574
+ elif a[0] == 'render' and len(a) >= 4:
575
+ shape = a[a.index('--shape') + 1] if '--shape' in a and a.index('--shape') + 1 < len(a) else None
576
+ if shape not in ('16:9', '9:16'):
577
+ sys.exit('render needs --shape 16:9 (YouTube) or --shape 9:16 (Shorts, TikTok, Reels)')
578
+ render(a[1], a[2], a[3], shape, with_captions='--captions' in a, zoom='--zoom' in a)
579
+ else:
580
+ sys.exit(__doc__)
581
+
582
+
583
+ if __name__ == '__main__':
584
+ main()
@@ -0,0 +1,39 @@
1
+ Metadata-Version: 2.4
2
+ Name: jump-cut
3
+ Version: 1.0.0
4
+ Summary: Cut a raw talking-head take into a finished video: keeps the clean take of each line, cuts retakes, false starts and dead air, optional captions. Used by the Jump Cut Editor skill.
5
+ Author: Fuad Laguda
6
+ License: Copyright 2026 Fuad Laguda
7
+
8
+ This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
9
+ Full licence text: https://creativecommons.org/licenses/by/4.0/legalcode
10
+
11
+ You are free to share and adapt this work for any purpose, including commercially, as long as you give appropriate credit, provide a link to the licence, and indicate if changes were made.
12
+
13
+ Credit must read:
14
+
15
+ > Jump Cut Editor by Fuad Laguda and Postbarrel (https://postbarrel.com), licensed under CC BY 4.0.
16
+
17
+ Project-URL: Homepage, https://github.com/lagudafuadtosin/jump-cut
18
+ Keywords: video editing,jump cut,captions,whisper,ffmpeg,talking head
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: faster-whisper
23
+ Requires-Dist: numpy
24
+ Requires-Dist: imageio-ffmpeg
25
+ Dynamic: license-file
26
+
27
+ # jump-cut
28
+
29
+ The command-line tool behind the Jump Cut Editor skill for Claude: https://github.com/lagudafuadtosin/jump-cut
30
+
31
+ ```
32
+ pip install jump-cut
33
+
34
+ jump-cut transcribe TAKE.mp4 WORK_DIR [--captions]
35
+ jump-cut plan WORK_DIR SCRIPT.txt
36
+ jump-cut render TAKE.mp4 WORK_DIR OUT.mp4 --shape 16:9|9:16 [--captions] [--zoom]
37
+ ```
38
+
39
+ Needs Python 3.10 or newer. ffmpeg is used from your path, or from imageio-ffmpeg, which installs with this package.
@@ -0,0 +1,9 @@
1
+ jump_cut/__init__.py,sha256=9IapsE_6APrTjaqAksRp4BSifDnQxCwEmjYD_0ABdXk,96
2
+ jump_cut/__main__.py,sha256=qqlyQ3HaI4C6mwTPs420ug9YhdDwpDyib07GJm-_nhQ,30
3
+ jump_cut/cut.py,sha256=6V9AWJS_8-ZYVSH7H0CQn9WoYCEv4JYhxoHOg_UF0Hk,27900
4
+ jump_cut-1.0.0.dist-info/licenses/LICENSE,sha256=FjVI9bxIj_y8-JGKqib0J8IZ99-rQfoIsz-sr3Y1rXk,511
5
+ jump_cut-1.0.0.dist-info/METADATA,sha256=EsZVdJ-k4xFXJB61c0MxrsxqLoyF_XeZ_vY6chGuRHI,1668
6
+ jump_cut-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
7
+ jump_cut-1.0.0.dist-info/entry_points.txt,sha256=9Y2wL8pHYiqwKgiQGPT42dvyabAuFBHGDPyiLKf1Jns,47
8
+ jump_cut-1.0.0.dist-info/top_level.txt,sha256=hytpzMX1R0xZ-Yn2YZpufYObGI8Tiyr-FH0vww1cEsA,9
9
+ jump_cut-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ jump-cut = jump_cut.cut:main
@@ -0,0 +1,10 @@
1
+ Copyright 2026 Fuad Laguda
2
+
3
+ This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
4
+ Full licence text: https://creativecommons.org/licenses/by/4.0/legalcode
5
+
6
+ You are free to share and adapt this work for any purpose, including commercially, as long as you give appropriate credit, provide a link to the licence, and indicate if changes were made.
7
+
8
+ Credit must read:
9
+
10
+ > Jump Cut Editor by Fuad Laguda and Postbarrel (https://postbarrel.com), licensed under CC BY 4.0.
@@ -0,0 +1 @@
1
+ jump_cut