amagi-clipper 0.1.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.
@@ -0,0 +1,3 @@
1
+ """amagi-clipper: cut a long recording into vertical captioned clips, locally."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,126 @@
1
+ """Caption files for a clip: an .ass file to burn in (word-by-word highlight) and a plain .srt."""
2
+ from __future__ import annotations
3
+
4
+ import re
5
+
6
+ STRIP_PUNCT = re.compile(r"^[\"'(\[]+|[\"')\],;:]+$")
7
+
8
+
9
+ def chunk_words(words: list[dict], max_words: int = 3, max_chars: int = 14) -> list[list[dict]]:
10
+ """Split words into short on-screen chunks. A chunk also ends after sentence punctuation."""
11
+ chunks: list[list[dict]] = []
12
+ cur: list[dict] = []
13
+ for w in words:
14
+ text_len = len(" ".join(x["word"] for x in cur + [w]))
15
+ if cur and (len(cur) >= max_words or text_len > max_chars):
16
+ chunks.append(cur)
17
+ cur = []
18
+ cur.append(w)
19
+ if re.search(r"[.!?]$", w["word"]):
20
+ chunks.append(cur)
21
+ cur = []
22
+ if cur:
23
+ chunks.append(cur)
24
+ return chunks
25
+
26
+
27
+ def shift(words: list[dict], offset: float) -> list[dict]:
28
+ return [{**w, "start": max(0.0, w["start"] - offset), "end": max(0.0, w["end"] - offset)} for w in words]
29
+
30
+
31
+ def ass_time(t: float) -> str:
32
+ cs = int(round(max(0.0, t) * 100))
33
+ h, cs = divmod(cs, 360000)
34
+ m, cs = divmod(cs, 6000)
35
+ s, cs = divmod(cs, 100)
36
+ return f"{h:d}:{m:02d}:{s:02d}.{cs:02d}"
37
+
38
+
39
+ def srt_time(t: float) -> str:
40
+ ms = int(round(max(0.0, t) * 1000))
41
+ h, ms = divmod(ms, 3600000)
42
+ m, ms = divmod(ms, 60000)
43
+ s, ms = divmod(ms, 1000)
44
+ return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
45
+
46
+
47
+ def ass_escape(text: str) -> str:
48
+ return text.replace("\\", "\\\\").replace("{", "(").replace("}", ")").replace("\n", " ")
49
+
50
+
51
+ def display(word: str, upper: bool) -> str:
52
+ word = STRIP_PUNCT.sub("", word) or word
53
+ return word.upper() if upper else word
54
+
55
+
56
+ def hex_to_ass(color: str) -> str:
57
+ """'#FFD400' -> '&H00D4FF' (ASS override colors are BBGGRR)."""
58
+ c = color.lstrip("#")
59
+ if not re.fullmatch(r"[0-9A-Fa-f]{6}", c):
60
+ raise ValueError(f"color must look like #RRGGBB, got {color!r}")
61
+ r, g, b = c[0:2], c[2:4], c[4:6]
62
+ return f"&H{b}{g}{r}".upper()
63
+
64
+
65
+ def build_ass(words: list[dict], width: int, height: int, font: str = "Arial", font_size: int | None = None,
66
+ highlight: str = "#FFD400", upper: bool = True, clip_end: float | None = None,
67
+ headline: str | None = None) -> str:
68
+ """ASS subtitles with times relative to the clip start. Each chunk shows whole; the spoken word is highlighted.
69
+
70
+ `headline`, if given, sits at the top of the frame for the whole clip (used for audiogram clips).
71
+ """
72
+ size = font_size or max(24, round(height * 0.05))
73
+ margin_v = round(height * 0.22)
74
+ outline = max(2, round(size * 0.08))
75
+ hl = hex_to_ass(highlight)
76
+ lines = [
77
+ "[Script Info]",
78
+ "ScriptType: v4.00+",
79
+ f"PlayResX: {width}",
80
+ f"PlayResY: {height}",
81
+ "WrapStyle: 0",
82
+ "ScaledBorderAndShadow: yes",
83
+ "",
84
+ "[V4+ Styles]",
85
+ "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, "
86
+ "Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, "
87
+ "MarginR, MarginV, Encoding",
88
+ f"Style: Caption,{font},{size},&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,1,"
89
+ f"{outline},0,2,60,60,{margin_v},1",
90
+ f"Style: Headline,{font},{round(size * 0.8)},&H00FFFFFF,&H00FFFFFF,&H00000000,&H00000000,-1,0,0,0,100,100,0,0,1,"
91
+ f"{max(1, outline // 2)},0,8,90,90,{round(height * 0.12)},1",
92
+ "",
93
+ "[Events]",
94
+ "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
95
+ ]
96
+ if headline:
97
+ end = clip_end if clip_end is not None else (words[-1]["end"] + 0.3 if words else 0.0)
98
+ lines.append(f"Dialogue: 1,{ass_time(0)},{ass_time(end)},Headline,,0,0,0,,{ass_escape(headline)}")
99
+ chunks = chunk_words(words)
100
+ for ci, chunk in enumerate(chunks):
101
+ nxt = chunks[ci + 1][0]["start"] if ci + 1 < len(chunks) else None
102
+ chunk_end = chunk[-1]["end"] + 0.3
103
+ if nxt is not None:
104
+ # Hold the chunk through short pauses so captions don't blink off between phrases.
105
+ chunk_end = nxt if nxt - chunk[-1]["end"] < 1.0 else min(chunk_end, nxt)
106
+ if clip_end is not None:
107
+ chunk_end = min(chunk_end, clip_end)
108
+ for wi, w in enumerate(chunk):
109
+ start = w["start"]
110
+ end = chunk[wi + 1]["start"] if wi + 1 < len(chunk) else chunk_end
111
+ if end <= start:
112
+ continue
113
+ parts = []
114
+ for k, x in enumerate(chunk):
115
+ t = ass_escape(display(x["word"], upper))
116
+ parts.append(f"{{\\c{hl}&}}{t}{{\\c&HFFFFFF&}}" if k == wi else t)
117
+ lines.append(f"Dialogue: 0,{ass_time(start)},{ass_time(end)},Caption,,0,0,0,,{' '.join(parts)}")
118
+ return "\n".join(lines) + "\n"
119
+
120
+
121
+ def build_srt(words: list[dict]) -> str:
122
+ out = []
123
+ for i, chunk in enumerate(chunk_words(words, max_words=7, max_chars=42), 1):
124
+ text = " ".join(w["word"] for w in chunk)
125
+ out.append(f"{i}\n{srt_time(chunk[0]['start'])} --> {srt_time(chunk[-1]['end'])}\n{text}\n")
126
+ return "\n".join(out)
amagi_clipper/cli.py ADDED
@@ -0,0 +1,187 @@
1
+ """amagi-clipper - cut a long recording into vertical 9:16 clips with burned-in captions.
2
+
3
+ Transcribes locally with faster-whisper, scores every 20-75 s run of whole sentences
4
+ for how well it stands alone, and renders the top N with ffmpeg. No API key.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import argparse
9
+ import json
10
+ import re
11
+ import sys
12
+ import tempfile
13
+ from pathlib import Path
14
+
15
+ from . import __version__
16
+ from .captions import build_ass, build_srt, shift
17
+ from .media import ToolMissing, extract_audio, fmt_ts, log, probe, transcribe
18
+ from .render import LAYOUTS, render_clip
19
+ from .score import Clip, cut_points, rank
20
+
21
+
22
+ def parse_size(text: str) -> tuple[int, int]:
23
+ m = re.fullmatch(r"(\d{2,5})x(\d{2,5})", text.strip().lower())
24
+ if not m:
25
+ raise argparse.ArgumentTypeError("size must look like 1080x1920")
26
+ w, h = int(m.group(1)), int(m.group(2))
27
+ if w % 2 or h % 2:
28
+ raise argparse.ArgumentTypeError("width and height must be even numbers (H.264 needs that)")
29
+ return w, h
30
+
31
+
32
+ def build_parser() -> argparse.ArgumentParser:
33
+ p = argparse.ArgumentParser(
34
+ prog="amagi-clipper",
35
+ description="Cut a long podcast, webinar or stream VOD into vertical 9:16 clips with burned-in "
36
+ "captions. Local faster-whisper + ffmpeg, no API key.",
37
+ )
38
+ p.add_argument("input", help="audio or video file (anything ffmpeg can read)")
39
+ p.add_argument("-o", "--outdir", default="amagi_clipper_out", help="where run folders go (default: amagi_clipper_out)")
40
+ p.add_argument("-n", "--count", type=int, default=5, help="how many clips to cut (default: 5)")
41
+ p.add_argument("--min", dest="min_len", type=float, default=20.0, help="shortest clip in seconds (default: 20)")
42
+ p.add_argument("--max", dest="max_len", type=float, default=75.0, help="longest clip in seconds (default: 75)")
43
+ p.add_argument("--model", default="small", help="faster-whisper model: tiny, base, small (default), medium, large-v3")
44
+ p.add_argument("--device", default="auto", choices=["auto", "cpu", "cuda"], help="where whisper runs (default: auto, uses an NVIDIA GPU if present)")
45
+ p.add_argument("--language", default=None, help="spoken language code such as en; default: detect")
46
+ p.add_argument("--layout", default="auto", choices=("auto",) + LAYOUTS,
47
+ help="crop = fill the frame, blur = whole picture over a blurred copy, audiogram = waveform; "
48
+ "default: crop for video, audiogram for audio-only input")
49
+ p.add_argument("--size", type=parse_size, default=(1080, 1920), help="output WIDTHxHEIGHT (default: 1080x1920)")
50
+ p.add_argument("--font", default="Arial", help="caption font family (default: Arial)")
51
+ p.add_argument("--font-size", type=int, default=None, help="caption font size in pixels (default: 5%% of height)")
52
+ p.add_argument("--highlight", default="#FFD400", help="color of the word being spoken (default: #FFD400)")
53
+ p.add_argument("--no-upper", action="store_true", help="keep caption case as spoken instead of UPPERCASE")
54
+ p.add_argument("--no-headline", action="store_true", help="audiogram clips: leave out the hook headline at the top")
55
+ p.add_argument("--transcript", type=Path, default=None, help="reuse a transcript.json from an earlier run instead of transcribing")
56
+ p.add_argument("--dry-run", action="store_true", help="score and list clips, render nothing")
57
+ p.add_argument("--version", action="version", version=f"amagi-clipper {__version__}")
58
+ return p
59
+
60
+
61
+ def run_name(src: Path) -> str:
62
+ name = re.sub(r"[^\w\-.]+", "_", src.stem).strip("._")
63
+ return name[:80] or "recording"
64
+
65
+
66
+ def get_transcript(args, src: Path, run_dir: Path) -> dict:
67
+ cached = run_dir / "transcript.json"
68
+ if args.transcript:
69
+ log(f"using transcript {args.transcript}")
70
+ return json.loads(args.transcript.read_text(encoding="utf-8"))
71
+ if cached.exists():
72
+ data = json.loads(cached.read_text(encoding="utf-8"))
73
+ stat = src.stat()
74
+ if data.get("source_size") == stat.st_size and data.get("model") == args.model:
75
+ log(f"reusing {cached} (same file, same model)")
76
+ return data
77
+ with tempfile.TemporaryDirectory(prefix="amagi_clipper_") as tmp:
78
+ wav = extract_audio(src, Path(tmp) / "audio.wav")
79
+ data = transcribe(wav, args.model, args.device, args.language)
80
+ data["source"] = src.name
81
+ data["source_size"] = src.stat().st_size
82
+ cached.write_text(json.dumps(data, indent=1), encoding="utf-8")
83
+ return data
84
+
85
+
86
+ def clip_record(rank_no: int, clip: Clip, start: float, end: float, file: str | None) -> dict:
87
+ return {
88
+ "rank": rank_no,
89
+ "score": clip.score,
90
+ "parts": clip.parts,
91
+ "start": start,
92
+ "end": end,
93
+ "duration": round(end - start, 2),
94
+ "file": file,
95
+ "hook": clip.hook,
96
+ "text": clip.text,
97
+ "reasons": clip.reasons,
98
+ }
99
+
100
+
101
+ def write_report(run_dir: Path, src: Path, records: list[dict], args) -> None:
102
+ lines = [f"# Clips from {src.name}", "",
103
+ f"{len(records)} clips, {args.min_len:g}-{args.max_len:g} s, ranked by score (out of 100).", ""]
104
+ for r in records:
105
+ lines += [
106
+ f"## {r['rank']}. {r['score']:.1f} - [{fmt_ts(r['start'])} - {fmt_ts(r['end'])}] {r['duration']:.0f}s",
107
+ "",
108
+ f"- File: `{r['file']}`" if r["file"] else "- File: not rendered (--dry-run)",
109
+ f"- Hook: \"{r['hook']}\"",
110
+ "- Score parts: " + ", ".join(f"{k} {v:g}" for k, v in r["parts"].items()),
111
+ "- Why: " + "; ".join(r["reasons"]),
112
+ "",
113
+ f"> {r['text']}",
114
+ "",
115
+ ]
116
+ (run_dir / "clips.md").write_text("\n".join(lines), encoding="utf-8")
117
+ (run_dir / "clips.json").write_text(json.dumps({"source": src.name, "clips": records}, indent=1), encoding="utf-8")
118
+
119
+
120
+ def main(argv: list[str] | None = None) -> int:
121
+ for stream in (sys.stdout, sys.stderr):
122
+ if hasattr(stream, "reconfigure"):
123
+ stream.reconfigure(encoding="utf-8", errors="replace")
124
+ args = build_parser().parse_args(argv)
125
+ src = Path(args.input)
126
+ if not src.is_file():
127
+ print(f"amagi-clipper: no such file: {src}", file=sys.stderr)
128
+ return 2
129
+ if args.count < 1 or args.min_len <= 0 or args.max_len < args.min_len:
130
+ print("amagi-clipper: need --count >= 1 and 0 < --min <= --max", file=sys.stderr)
131
+ return 2
132
+
133
+ try:
134
+ info = probe(src)
135
+ if not info["has_audio"]:
136
+ print(f"amagi-clipper: {src} has no audio track", file=sys.stderr)
137
+ return 2
138
+ run_dir = Path(args.outdir) / run_name(src)
139
+ run_dir.mkdir(parents=True, exist_ok=True)
140
+ data = get_transcript(args, src, run_dir)
141
+ clips = rank(data["words"], args.count, args.min_len, args.max_len)
142
+ if not clips:
143
+ print(f"amagi-clipper: no {args.min_len:g}-{args.max_len:g} s stretch of whole sentences found "
144
+ f"({len(data['words'])} words transcribed). Try a lower --min.", file=sys.stderr)
145
+ return 1
146
+
147
+ layout = args.layout
148
+ if layout == "auto":
149
+ layout = "crop" if info["has_video"] else "audiogram"
150
+ if layout != "audiogram" and not info["has_video"]:
151
+ print(f"amagi-clipper: --layout {layout} needs a video track; {src.name} is audio-only", file=sys.stderr)
152
+ return 2
153
+ width, height = args.size
154
+
155
+ records = []
156
+ for i, clip in enumerate(clips, 1):
157
+ start, end = cut_points(clip, info["duration"])
158
+ stem = f"clip_{i:02d}"
159
+ file = None
160
+ if not args.dry_run:
161
+ words = shift(clip.words, start)
162
+ ass = build_ass(words, width, height, args.font, args.font_size, args.highlight,
163
+ upper=not args.no_upper, clip_end=end - start,
164
+ headline=clip.hook if layout == "audiogram" and not args.no_headline else None)
165
+ log(f"rendering {stem} [{fmt_ts(start)}-{fmt_ts(end)}] score {clip.score:.1f}")
166
+ render_clip(src, start, end - start, layout, width, height, run_dir, stem, ass)
167
+ (run_dir / f"{stem}.srt").write_text(build_srt(words), encoding="utf-8")
168
+ file = f"{stem}.mp4"
169
+ records.append(clip_record(i, clip, start, end, file))
170
+ write_report(run_dir, src, records, args)
171
+ except ToolMissing as e:
172
+ print(f"amagi-clipper: {e}", file=sys.stderr)
173
+ return 2
174
+ except (RuntimeError, ValueError, OSError) as e:
175
+ print(f"amagi-clipper: {e}", file=sys.stderr)
176
+ return 1
177
+
178
+ for r in records:
179
+ hook = r["hook"] if len(r["hook"]) <= 60 else r["hook"][:57] + "..."
180
+ print(f"#{r['rank']} {r['score']:5.1f} {fmt_ts(r['start'])}-{fmt_ts(r['end'])} {r['duration']:4.0f}s "
181
+ f"{r['file'] or '(dry run)'} \"{hook}\"")
182
+ print(run_dir)
183
+ return 0
184
+
185
+
186
+ if __name__ == "__main__":
187
+ sys.exit(main())
amagi_clipper/media.py ADDED
@@ -0,0 +1,137 @@
1
+ """ffmpeg/ffprobe helpers and local faster-whisper transcription."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import shutil
6
+ import subprocess
7
+ import sys
8
+ import wave
9
+ from pathlib import Path
10
+
11
+
12
+ class ToolMissing(RuntimeError):
13
+ pass
14
+
15
+
16
+ def require(tool: str) -> str:
17
+ path = shutil.which(tool)
18
+ if not path:
19
+ raise ToolMissing(f"{tool} not found on PATH. Install ffmpeg (it ships ffprobe too): https://ffmpeg.org/download.html")
20
+ return path
21
+
22
+
23
+ def log(msg: str) -> None:
24
+ print(f"[amagi-clipper] {msg}", file=sys.stderr, flush=True)
25
+
26
+
27
+ def probe(path: Path) -> dict:
28
+ """Return {'duration': float|None, 'has_video': bool, 'width': int|None, 'height': int|None}.
29
+
30
+ Cover art in an mp3/m4a is a video stream flagged attached_pic; that does not count as video.
31
+ """
32
+ require("ffprobe")
33
+ out = subprocess.run(
34
+ ["ffprobe", "-v", "error", "-print_format", "json", "-show_format", "-show_streams", str(path)],
35
+ capture_output=True, text=True, encoding="utf-8", errors="replace",
36
+ )
37
+ if out.returncode != 0:
38
+ raise RuntimeError(f"ffprobe could not read {path}: {out.stderr.strip()[:300]}")
39
+ return parse_probe(json.loads(out.stdout or "{}"))
40
+
41
+
42
+ def parse_probe(data: dict) -> dict:
43
+ info = {"duration": None, "has_video": False, "has_audio": False, "width": None, "height": None}
44
+ try:
45
+ info["duration"] = float(data.get("format", {}).get("duration"))
46
+ except (TypeError, ValueError):
47
+ pass
48
+ for s in data.get("streams", []):
49
+ kind = s.get("codec_type")
50
+ if kind == "audio":
51
+ info["has_audio"] = True
52
+ elif kind == "video" and not s.get("disposition", {}).get("attached_pic"):
53
+ if not info["has_video"]:
54
+ info["has_video"] = True
55
+ info["width"] = s.get("width")
56
+ info["height"] = s.get("height")
57
+ return info
58
+
59
+
60
+ def extract_audio(src: Path, dest: Path) -> Path:
61
+ """Decode any input to 16 kHz mono 16-bit WAV (what Whisper wants)."""
62
+ require("ffmpeg")
63
+ proc = subprocess.run(
64
+ ["ffmpeg", "-y", "-v", "error", "-i", str(src), "-vn", "-ac", "1", "-ar", "16000",
65
+ "-c:a", "pcm_s16le", str(dest)],
66
+ capture_output=True, text=True, encoding="utf-8", errors="replace",
67
+ )
68
+ if proc.returncode != 0:
69
+ raise RuntimeError(f"ffmpeg could not extract audio from {src}: {proc.stderr.strip()[:300]}")
70
+ return dest
71
+
72
+
73
+ def load_wav(path: Path):
74
+ """Read a 16 kHz mono s16 WAV into float32 samples.
75
+
76
+ Handing faster-whisper samples instead of a path means it never decodes with PyAV,
77
+ whose API changed in 19.x. ffmpeg already did the decoding.
78
+ """
79
+ import numpy as np
80
+
81
+ with wave.open(str(path), "rb") as w:
82
+ if w.getsampwidth() != 2 or w.getnchannels() != 1:
83
+ raise RuntimeError(f"unexpected WAV format in {path}")
84
+ raw = w.readframes(w.getnframes())
85
+ return np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
86
+
87
+
88
+ def pick_device(device: str) -> tuple[str, str]:
89
+ """Map --device to (device, compute_type) for faster-whisper."""
90
+ if device == "auto":
91
+ try:
92
+ import ctranslate2
93
+
94
+ device = "cuda" if ctranslate2.get_cuda_device_count() > 0 else "cpu"
95
+ except Exception:
96
+ device = "cpu"
97
+ return device, ("float16" if device == "cuda" else "int8")
98
+
99
+
100
+ def _run_whisper(wav: Path, model_size: str, dev: str, compute: str, language: str | None) -> dict:
101
+ from faster_whisper import WhisperModel
102
+
103
+ log(f"loading faster-whisper '{model_size}' on {dev} ({compute}); the first run downloads the model")
104
+ model = WhisperModel(model_size, device=dev, compute_type=compute)
105
+ segments, info = model.transcribe(load_wav(wav), language=language, vad_filter=True, word_timestamps=True)
106
+ words = []
107
+ for seg in segments:
108
+ for w in seg.words or []:
109
+ text = w.word.strip()
110
+ if text:
111
+ words.append({"start": round(float(w.start), 3), "end": round(float(w.end), 3), "word": text})
112
+ log(f"transcribed to {fmt_ts(seg.end)}")
113
+ return {"language": info.language, "duration": round(float(info.duration), 3), "model": model_size, "words": words}
114
+
115
+
116
+ def transcribe(wav: Path, model_size: str = "small", device: str = "auto", language: str | None = None,
117
+ run=_run_whisper) -> dict:
118
+ """Transcribe with word timestamps. Returns {'language', 'duration', 'model', 'words': [...]}.
119
+
120
+ With device 'auto', a GPU that is present but unusable (missing cuBLAS/cuDNN, out of memory)
121
+ falls back to the CPU instead of failing the run.
122
+ """
123
+ dev, compute = pick_device(device)
124
+ try:
125
+ return run(wav, model_size, dev, compute, language)
126
+ except RuntimeError as e:
127
+ if device != "auto" or dev != "cuda":
128
+ raise
129
+ log(f"GPU failed ({str(e).strip()[:120]}); falling back to CPU")
130
+ return run(wav, model_size, "cpu", "int8", language)
131
+
132
+
133
+ def fmt_ts(seconds: float) -> str:
134
+ seconds = max(0, int(seconds))
135
+ h, rem = divmod(seconds, 3600)
136
+ m, s = divmod(rem, 60)
137
+ return f"{h:d}:{m:02d}:{s:02d}" if h else f"{m:02d}:{s:02d}"
@@ -0,0 +1,56 @@
1
+ """Cut one clip with ffmpeg: vertical frame, burned-in captions, H.264/AAC mp4."""
2
+ from __future__ import annotations
3
+
4
+ import subprocess
5
+ from pathlib import Path
6
+
7
+ from .media import require
8
+
9
+ LAYOUTS = ("crop", "blur", "audiogram")
10
+
11
+
12
+ def filter_graph(layout: str, width: int, height: int, ass_name: str, bg: str = "0x111827") -> str:
13
+ """Build the -filter_complex string. ass_name must be a bare filename (ffmpeg runs in its folder)."""
14
+ subs = f"subtitles=filename='{ass_name}'"
15
+ w, h = width, height
16
+ if layout == "crop":
17
+ return (f"[0:v]scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h},setsar=1,"
18
+ f"format=yuv420p,{subs}[v]")
19
+ if layout == "blur":
20
+ return (f"[0:v]split[a][b];"
21
+ f"[a]scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h},boxblur=24:2[bg];"
22
+ f"[b]scale={w}:{h}:force_original_aspect_ratio=decrease[fg];"
23
+ f"[bg][fg]overlay=(W-w)/2:(H-h)/2,setsar=1,format=yuv420p,{subs}[v]")
24
+ if layout == "audiogram":
25
+ wave_h = round(h * 0.25)
26
+ return (f"[0:a]showwaves=s={w}x{wave_h}:mode=cline:scale=sqrt:rate=30:colors=0xF8FAFC[wv];"
27
+ f"color=c={bg}:s={w}x{h}:r=30[bg];"
28
+ f"[bg][wv]overlay=0:(H-h)/2:shortest=1,setsar=1,format=yuv420p,{subs}[v]")
29
+ raise ValueError(f"unknown layout {layout!r}; pick one of {', '.join(LAYOUTS)}")
30
+
31
+
32
+ def ffmpeg_cmd(src: Path, start: float, duration: float, graph: str, out_name: str, crf: int = 20) -> list[str]:
33
+ return [
34
+ "ffmpeg", "-y", "-v", "error", "-ss", f"{start:.3f}", "-t", f"{duration:.3f}", "-i", str(src),
35
+ "-filter_complex", graph, "-map", "[v]", "-map", "0:a:0",
36
+ "-c:v", "libx264", "-preset", "veryfast", "-crf", str(crf), "-r", "30",
37
+ "-c:a", "aac", "-b:a", "128k", "-ar", "48000",
38
+ "-movflags", "+faststart", "-shortest", out_name,
39
+ ]
40
+
41
+
42
+ def render_clip(src: Path, start: float, duration: float, layout: str, width: int, height: int,
43
+ out_dir: Path, stem: str, ass_text: str, crf: int = 20) -> Path:
44
+ """Write <stem>.ass and <stem>.mp4 into out_dir and return the mp4 path."""
45
+ require("ffmpeg")
46
+ out_dir.mkdir(parents=True, exist_ok=True)
47
+ ass_name, mp4_name = f"{stem}.ass", f"{stem}.mp4"
48
+ (out_dir / ass_name).write_text(ass_text, encoding="utf-8")
49
+ graph = filter_graph(layout, width, height, ass_name)
50
+ # Run inside out_dir so the subtitles filter gets a bare filename: Windows drive
51
+ # letters and backslashes need awkward escaping inside a filter graph.
52
+ cmd = ffmpeg_cmd(src.resolve(), start, duration, graph, mp4_name, crf)
53
+ proc = subprocess.run(cmd, cwd=out_dir, capture_output=True, text=True, encoding="utf-8", errors="replace")
54
+ if proc.returncode != 0:
55
+ raise RuntimeError(f"ffmpeg failed on {mp4_name}: {proc.stderr.strip()[-600:]}")
56
+ return out_dir / mp4_name
amagi_clipper/score.py ADDED
@@ -0,0 +1,289 @@
1
+ """Pick self-contained, quotable clips from a word-timestamped transcript.
2
+
3
+ No model is involved: every score is a sum of plain heuristics, and every point a
4
+ clip earns or loses is listed in its `reasons`, so you can see why it ranked where it did.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ from dataclasses import dataclass, field
10
+
11
+ SENTENCE_END = re.compile(r"[.!?]['\")\]]*$")
12
+ # A gap this long ends a sentence even when Whisper left out the punctuation.
13
+ PAUSE_BREAK = 1.2
14
+
15
+ # Openers that only make sense after something the viewer didn't hear.
16
+ DANGLING = {
17
+ "and", "but", "so", "because", "or", "which", "also", "then", "yeah", "yes", "no",
18
+ "um", "uh", "well", "like", "okay", "ok", "right", "anyway", "plus", "though", "although",
19
+ "cause", "'cause", "exactly", "mhm", "hmm",
20
+ }
21
+ # Pronouns pointing back at something said before the clip starts.
22
+ BACKREF = {"it", "that", "this", "they", "he", "she", "those", "these", "them", "him", "her", "there"}
23
+ FILLERS = {"um", "uh", "erm", "er", "hmm", "mhm", "ah"}
24
+ HOOK_PHRASES = [
25
+ "here's", "here is", "the truth", "the secret", "the problem", "the biggest", "the real",
26
+ "the one thing", "the number one", "most people", "nobody", "no one", "everyone", "never",
27
+ "stop", "don't", "if you", "you need", "you should", "the reason", "the mistake",
28
+ "i learned", "what i learned", "the best", "the worst", "the key", "the hardest",
29
+ "the moment", "imagine", "what if", "why", "how to", "how do", "the first", "let me tell you",
30
+ "i was wrong", "unpopular opinion", "the dirty secret", "nobody tells you",
31
+ ]
32
+ NUMBER_WORDS = {
33
+ "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten",
34
+ "hundred", "thousand", "million", "billion", "percent", "half", "double",
35
+ }
36
+ # Show furniture: fine in the episode, dead weight in a clip.
37
+ INTRO_PHRASES = ["welcome back", "welcome to", "today we're talking", "today we are talking", "in this episode"]
38
+ OUTRO_PHRASES = ["thanks for listening", "thanks for watching", "see you next time", "that's it for",
39
+ "that's all for", "subscribe", "until next time"]
40
+ WORD_RE = re.compile(r"[a-z0-9']+")
41
+
42
+
43
+ @dataclass
44
+ class Sentence:
45
+ start: float
46
+ end: float
47
+ words: list[dict]
48
+
49
+ @property
50
+ def text(self) -> str:
51
+ return " ".join(w["word"] for w in self.words).strip()
52
+
53
+ @property
54
+ def tokens(self) -> list[str]:
55
+ return WORD_RE.findall(self.text.lower())
56
+
57
+
58
+ @dataclass
59
+ class Clip:
60
+ start: float
61
+ end: float
62
+ sentences: list[Sentence]
63
+ score: float = 0.0
64
+ parts: dict = field(default_factory=dict)
65
+ reasons: list[str] = field(default_factory=list)
66
+ prev_end: float | None = None
67
+ next_start: float | None = None
68
+
69
+ @property
70
+ def duration(self) -> float:
71
+ return self.end - self.start
72
+
73
+ @property
74
+ def words(self) -> list[dict]:
75
+ return [w for s in self.sentences for w in s.words]
76
+
77
+ @property
78
+ def text(self) -> str:
79
+ return " ".join(s.text for s in self.sentences)
80
+
81
+ @property
82
+ def hook(self) -> str:
83
+ return self.sentences[0].text
84
+
85
+
86
+ def build_sentences(words: list[dict], pause_break: float = PAUSE_BREAK) -> list[Sentence]:
87
+ """Group words into sentences at terminal punctuation or at a long pause."""
88
+ sentences: list[Sentence] = []
89
+ cur: list[dict] = []
90
+ for i, w in enumerate(words):
91
+ cur.append(w)
92
+ nxt = words[i + 1] if i + 1 < len(words) else None
93
+ ends = bool(SENTENCE_END.search(w["word"]))
94
+ gap = (nxt["start"] - w["end"]) if nxt else 0.0
95
+ if nxt is None or ends or gap >= pause_break:
96
+ sentences.append(Sentence(cur[0]["start"], cur[-1]["end"], cur))
97
+ cur = []
98
+ return sentences
99
+
100
+
101
+ def candidates(sentences: list[Sentence], min_len: float, max_len: float) -> list[Clip]:
102
+ """Every run of whole consecutive sentences lasting between min_len and max_len seconds."""
103
+ out = []
104
+ for i in range(len(sentences)):
105
+ for j in range(i, len(sentences)):
106
+ dur = sentences[j].end - sentences[i].start
107
+ if dur > max_len:
108
+ break
109
+ if dur >= min_len:
110
+ out.append(Clip(sentences[i].start, sentences[j].end, sentences[i:j + 1]))
111
+ return out
112
+
113
+
114
+ def _first_token(s: Sentence) -> str:
115
+ toks = s.tokens
116
+ return toks[0] if toks else ""
117
+
118
+
119
+ def score_hook(first: Sentence) -> tuple[float, list[str]]:
120
+ text = first.text.lower()
121
+ toks = first.tokens
122
+ pts, why = 0.0, []
123
+ if not toks:
124
+ return 0.0, ["hook: empty first sentence"]
125
+ if toks[0] in DANGLING:
126
+ return 0.0, [f"hook: opens on '{toks[0]}', a weak first word"]
127
+ intro = next((p for p in INTRO_PHRASES if p in text), None)
128
+ if intro:
129
+ return 0.0, [f"hook: '{intro}' is show intro, not a hook"]
130
+ if first.text.rstrip().endswith("?"):
131
+ pts += 0.35
132
+ why.append("hook: opens with a question (+)")
133
+ phrase = next((p for p in HOOK_PHRASES if re.search(r"(^|\W)" + re.escape(p) + r"(\W|$)", text)), None)
134
+ if phrase:
135
+ pts += 0.35
136
+ why.append(f"hook: '{phrase}' framing (+)")
137
+ if any(t.isdigit() or t in NUMBER_WORDS for t in toks):
138
+ pts += 0.15
139
+ why.append("hook: has a number (+)")
140
+ if "you" in toks or "your" in toks:
141
+ pts += 0.15
142
+ why.append("hook: talks to 'you' (+)")
143
+ n = len(toks)
144
+ if 4 <= n <= 16:
145
+ pts += 0.2
146
+ why.append(f"hook: short first sentence, {n} words (+)")
147
+ elif n > 25:
148
+ pts -= 0.2
149
+ why.append(f"hook: long first sentence, {n} words (-)")
150
+ return max(0.0, min(1.0, pts)), why
151
+
152
+
153
+ def score_standalone(clip: Clip) -> tuple[float, list[str]]:
154
+ first, last = clip.sentences[0], clip.sentences[-1]
155
+ tok = _first_token(first)
156
+ pts, why = 0.0, []
157
+ if tok in DANGLING:
158
+ why.append(f"standalone: starts mid-thought ('{tok}') (-)")
159
+ else:
160
+ pts += 0.4
161
+ if tok in BACKREF:
162
+ why.append(f"standalone: opens on '{tok}', which points back to earlier talk (-)")
163
+ else:
164
+ pts += 0.3
165
+ if SENTENCE_END.search(last.words[-1]["word"]):
166
+ pts += 0.3
167
+ else:
168
+ why.append("standalone: last sentence has no closing punctuation (-)")
169
+ if pts >= 1.0:
170
+ why.append("standalone: clean start and finished last sentence (+)")
171
+ return pts, why
172
+
173
+
174
+ def score_ending(clip: Clip) -> tuple[float, list[str]]:
175
+ """A clip should end where the idea lands, not on a reply, an open question or the sign-off."""
176
+ last = clip.sentences[-1]
177
+ text = clip.text.lower()
178
+ pts, why = 1.0, []
179
+ if len(clip.sentences) > 1 and last.text.rstrip().endswith("?"):
180
+ pts -= 0.6
181
+ why.append("ending: stops on an open question (-)")
182
+ if len(clip.sentences) > 1 and len(last.tokens) <= 3:
183
+ pts -= 0.5
184
+ why.append(f"ending: trails off on a short reply, '{last.text}' (-)")
185
+ outro = next((p for p in OUTRO_PHRASES if p in text), None)
186
+ if outro:
187
+ pts -= 0.6
188
+ why.append(f"ending: runs into the sign-off ('{outro}') (-)")
189
+ if pts >= 1.0:
190
+ why.append("ending: lands on a full statement (+)")
191
+ return max(0.0, pts), why
192
+
193
+
194
+ def score_boundaries(clip: Clip, prev_end: float | None, next_start: float | None) -> tuple[float, list[str]]:
195
+ pts, why = 0.0, []
196
+ before = clip.start - prev_end if prev_end is not None else 99.0
197
+ after = next_start - clip.end if next_start is not None else 99.0
198
+ if before >= 0.5:
199
+ pts += 0.5
200
+ else:
201
+ why.append(f"cut: only {before:.1f}s of pause before the start (-)")
202
+ if after >= 0.5:
203
+ pts += 0.5
204
+ else:
205
+ why.append(f"cut: only {after:.1f}s of pause after the end (-)")
206
+ return pts, why
207
+
208
+
209
+ def score_length(dur: float, min_len: float, max_len: float) -> tuple[float, list[str]]:
210
+ span = max(max_len - min_len, 1e-6)
211
+ lo, hi = min_len + 0.1 * span, min_len + 0.6 * span
212
+ if lo <= dur <= hi:
213
+ return 1.0, [f"length: {dur:.0f}s sits in the {lo:.0f}-{hi:.0f}s sweet spot (+)"]
214
+ edge = (lo - dur) / (lo - min_len) if dur < lo else (dur - hi) / (max_len - hi)
215
+ return round(1.0 - 0.6 * max(0.0, min(1.0, edge)), 3), [f"length: {dur:.0f}s, outside the {lo:.0f}-{hi:.0f}s sweet spot"]
216
+
217
+
218
+ def score_delivery(clip: Clip) -> tuple[float, list[str]]:
219
+ words = clip.words
220
+ toks = [t for s in clip.sentences for t in s.tokens]
221
+ pts, why = 1.0, []
222
+ fillers = sum(1 for t in toks if t in FILLERS)
223
+ ratio = fillers / max(len(toks), 1)
224
+ if ratio > 0.02:
225
+ pts -= min(0.5, ratio * 10)
226
+ why.append(f"delivery: {fillers} filler words (-)")
227
+ wps = len(toks) / max(clip.duration, 1e-6)
228
+ if not 1.8 <= wps <= 4.0:
229
+ pts -= 0.25
230
+ why.append(f"delivery: {wps:.1f} words/s is {'slow' if wps < 1.8 else 'rushed'} (-)")
231
+ dead = max((b["start"] - a["end"] for a, b in zip(words, words[1:])), default=0.0)
232
+ if dead > 2.5:
233
+ pts -= 0.3
234
+ why.append(f"delivery: {dead:.1f}s of dead air inside the clip (-)")
235
+ return max(0.0, pts), why
236
+
237
+
238
+ WEIGHTS = {"hook": 30, "standalone": 20, "ending": 15, "length": 10, "boundaries": 10, "delivery": 15}
239
+
240
+
241
+ def score_clip(clip: Clip, prev_end: float | None, next_start: float | None, min_len: float, max_len: float) -> Clip:
242
+ results = {
243
+ "hook": score_hook(clip.sentences[0]),
244
+ "standalone": score_standalone(clip),
245
+ "ending": score_ending(clip),
246
+ "length": score_length(clip.duration, min_len, max_len),
247
+ "boundaries": score_boundaries(clip, prev_end, next_start),
248
+ "delivery": score_delivery(clip),
249
+ }
250
+ clip.prev_end, clip.next_start = prev_end, next_start
251
+ clip.parts = {k: round(v[0] * WEIGHTS[k], 1) for k, v in results.items()}
252
+ clip.score = round(sum(clip.parts.values()), 1)
253
+ clip.reasons = [r for _, (_, why) in results.items() for r in why]
254
+ return clip
255
+
256
+
257
+ def rank(words: list[dict], n: int = 5, min_len: float = 20.0, max_len: float = 75.0) -> list[Clip]:
258
+ """Score every candidate window and return the top n that don't overlap, best first."""
259
+ if min_len <= 0 or max_len < min_len:
260
+ raise ValueError("need 0 < min_len <= max_len")
261
+ sentences = build_sentences(words)
262
+ index = {id(s): i for i, s in enumerate(sentences)}
263
+ scored = []
264
+ for clip in candidates(sentences, min_len, max_len):
265
+ i, j = index[id(clip.sentences[0])], index[id(clip.sentences[-1])]
266
+ prev_end = sentences[i - 1].end if i > 0 else None
267
+ next_start = sentences[j + 1].start if j + 1 < len(sentences) else None
268
+ scored.append(score_clip(clip, prev_end, next_start, min_len, max_len))
269
+ scored.sort(key=lambda c: (-c.score, c.start, c.duration))
270
+ picked: list[Clip] = []
271
+ for c in scored:
272
+ if len(picked) >= n:
273
+ break
274
+ if all(c.end <= p.start or c.start >= p.end for p in picked):
275
+ picked.append(c)
276
+ return picked
277
+
278
+
279
+ def cut_points(clip: Clip, media_end: float | None = None, lead: float = 0.15, tail: float = 0.4) -> tuple[float, float]:
280
+ """Pad the clip a little so the first and last words aren't clipped, without reaching into neighbours."""
281
+ start = clip.start - lead
282
+ if clip.prev_end is not None:
283
+ start = max(start, (clip.prev_end + clip.start) / 2)
284
+ end = clip.end + tail
285
+ if clip.next_start is not None:
286
+ end = min(end, (clip.end + clip.next_start) / 2)
287
+ if media_end is not None:
288
+ end = min(end, media_end)
289
+ return round(max(0.0, start), 3), round(end, 3)
@@ -0,0 +1,165 @@
1
+ Metadata-Version: 2.4
2
+ Name: amagi-clipper
3
+ Version: 0.1.0
4
+ Summary: Turn a long podcast, webinar or stream VOD into vertical 9:16 clips with burned-in captions. Local faster-whisper + ffmpeg, no API key.
5
+ Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/amagilabs/amagi-clipper
8
+ Project-URL: Source, https://github.com/amagilabs/amagi-clipper
9
+ Project-URL: Issues, https://github.com/amagilabs/amagi-clipper/issues
10
+ Keywords: podcast,shorts,clips,whisper,ffmpeg,captions,reels,tiktok,cli,claude-code
11
+ Classifier: Environment :: Console
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Multimedia :: Video :: Conversion
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: faster-whisper>=1.0.0
20
+ Requires-Dist: av<19,>=15.1.0
21
+ Requires-Dist: numpy>=1.24
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=7.0; extra == "dev"
24
+ Dynamic: license-file
25
+
26
+ # amagi-clipper
27
+
28
+ Point it at a long podcast, webinar, or stream recording and get back vertical 9:16 clips with burned-in captions, ready for Shorts, Reels, and TikTok. It runs on your own computer with no API key and no subscription.
29
+
30
+ ![demo](assets/demo.gif)
31
+
32
+ amagi-clipper transcribes the recording locally with [faster-whisper](https://github.com/SYSTRAN/faster-whisper). It then scores every 20 to 75 second run of whole sentences on how well it stands alone, and uses ffmpeg to cut the top picks into 1080x1920 mp4s. Captions appear up to three words at a time, with the word being spoken in yellow.
33
+
34
+ It was built for solo podcasters and small agencies who record every week and never find the time to cut clips.
35
+
36
+ ![three clips from the demo episode](assets/clips.png)
37
+
38
+ *Frames from the three clips it cut from the demo episode (audio-only input, so it used the waveform layout).*
39
+
40
+ ## Install
41
+
42
+ ```
43
+ pipx install amagi-clipper
44
+ ```
45
+
46
+ Or from a clone of this repo: `pipx install .`
47
+
48
+ You also need [ffmpeg](https://ffmpeg.org/) on your PATH. Python 3.10 or newer. The first run downloads the Whisper model you pick. If you have an NVIDIA GPU, amagi-clipper uses it automatically. GPU transcription also needs NVIDIA's cuBLAS and cuDNN 9 libraries (see the [faster-whisper install notes](https://github.com/SYSTRAN/faster-whisper)). If they are missing, amagi-clipper says so and falls back to the CPU.
49
+
50
+ ## Usage
51
+
52
+ ```
53
+ amagi-clipper <file> [-o OUTDIR] [-n 5] [--min 20] [--max 75] [--layout auto|crop|blur|audiogram] [--model small] [--dry-run]
54
+ ```
55
+
56
+ | Option | What it does |
57
+ |---|---|
58
+ | `-o`, `--outdir` | Where run folders go (default `amagi_clipper_out`) |
59
+ | `-n`, `--count` | How many clips to cut (default 5) |
60
+ | `--min`, `--max` | Shortest and longest clip in seconds (default 20 and 75) |
61
+ | `--layout` | `crop` fills the frame from the center, `blur` puts the whole picture over a blurred copy, `audiogram` draws a waveform. Default: `crop` for video, `audiogram` for audio-only |
62
+ | `--model` | faster-whisper size: `tiny`, `base`, `small` (default), `medium`, `large-v3` |
63
+ | `--device` | `auto` (default), `cpu`, or `cuda` |
64
+ | `--language` | Spoken language code such as `en` (default: detect) |
65
+ | `--size` | Output size (default `1080x1920`) |
66
+ | `--font`, `--font-size`, `--highlight` | Caption font (default Arial), size in pixels (default 5% of frame height), and the color of the spoken word (default `#FFD400`) |
67
+ | `--no-upper` | Keep caption case as spoken instead of UPPERCASE |
68
+ | `--no-headline` | Audiogram clips: leave out the headline at the top |
69
+ | `--transcript` | Reuse a `transcript.json` from an earlier run instead of transcribing |
70
+ | `--dry-run` | Score and list the clips, render nothing |
71
+
72
+ Examples:
73
+
74
+ ```
75
+ # Five clips from a video podcast, center-cropped
76
+ amagi-clipper episode42.mp4
77
+
78
+ # A two-person or screen-share recording: keep the whole picture
79
+ amagi-clipper webinar.mp4 --layout blur -n 3
80
+
81
+ # See what it would cut before rendering anything
82
+ amagi-clipper episode42.mp4 --dry-run
83
+ ```
84
+
85
+ Transcription is the slow step, so the transcript is cached in the run folder. Run the same file again with a different `-n`, `--min`, `--max`, or `--layout` and Whisper is skipped.
86
+
87
+ ## Real output
88
+
89
+ The demo episode in `tests/fixtures/demo_episode.m4a` is 144 seconds of two synthesized voices. We wrote the script with three self-contained monologues buried among intro, outro, and back-and-forth chatter, to see whether amagi-clipper would find them. Here is the run on an RTX 3090 with the default `small` model:
90
+
91
+ ```
92
+ $ amagi-clipper tests/fixtures/demo_episode.m4a -o runs -n 3
93
+ #1 97.0 01:13-01:41 28s clip_01.mp4 "Why do most clips fail?"
94
+ #2 91.0 00:27-00:56 30s clip_02.mp4 "Here's the truth nobody tells you about growing a podcast."
95
+ #3 91.0 01:49-02:15 26s clip_03.mp4 "Stop paying $30 a month for clip software."
96
+ runs/demo_episode
97
+ ```
98
+
99
+ It picked the three monologues and skipped the intro. Transcription plus three 1080x1920 renders took 23.7 seconds of wall time.
100
+
101
+ Each run writes `<outdir>/<name>/`:
102
+
103
+ - `clip_01.mp4`, `clip_02.mp4`, ...: the vertical clips with captions burned in.
104
+ - `clip_01.srt`, ...: plain caption files, for platforms that take them.
105
+ - `clips.md`: every clip with its score, the reasons behind it, and the full text.
106
+ - `clips.json`: the same data for scripts.
107
+ - `transcript.json`: word-level timestamps, reused on the next run.
108
+
109
+ The entry for clip 1 in `clips.md` (full file in [examples/demo_episode](examples/demo_episode/clips.md)):
110
+
111
+ ```markdown
112
+ ## 1. 97.0 - [01:13 - 01:41] 28s
113
+
114
+ - File: `clip_01.mp4`
115
+ - Hook: "Why do most clips fail?"
116
+ - Score parts: hook 27, standalone 20, ending 15, length 10, boundaries 10, delivery 15
117
+ - Why: hook: opens with a question (+); hook: 'why' framing (+); hook: short first sentence, 5 words (+); standalone: clean start and finished last sentence (+); ending: lands on a full statement (+); length: 27s sits in the 26-53s sweet spot (+)
118
+ ```
119
+
120
+ ## How scoring works
121
+
122
+ amagi-clipper splits the transcript into sentences at end punctuation or at any pause of 1.2 seconds or more. Every run of whole sentences between `--min` and `--max` is a candidate. Each candidate gets up to 100 points:
123
+
124
+ | Part | Points | What earns them |
125
+ |---|---|---|
126
+ | Hook | 30 | The first sentence works as an opener: a question, a number, "here's", "why", "stop", talking to "you", short. An opener like "and", "so", or "but", or an intro line such as "welcome back", scores zero |
127
+ | Standalone | 20 | Starts clean, with no "it" or "that" pointing back at something the viewer never heard, and finishes its last sentence |
128
+ | Ending | 15 | Ends on a statement. Stopping on a question, on a short reply like "It was.", or running into the sign-off costs points |
129
+ | Length | 10 | Sits in the middle of your `--min`/`--max` range |
130
+ | Boundaries | 10 | Has a half-second pause before and after, so the cut does not clip a word |
131
+ | Delivery | 15 | Few filler words, 1.8 to 4.0 words per second, no dead air over 2.5 seconds |
132
+
133
+ The best clips are picked first and never overlap. Every point gained or lost is written to `clips.md` in plain words, so you can see why a clip ranked where it did.
134
+
135
+ ## Use it as a Claude Code skill
136
+
137
+ The repo includes a `SKILL.md`. Copy it into your skills folder:
138
+
139
+ ```
140
+ mkdir -p ~/.claude/skills/amagi-clipper
141
+ cp SKILL.md ~/.claude/skills/amagi-clipper/SKILL.md
142
+ ```
143
+
144
+ Then ask Claude to "cut five clips from episode42.mp4". It runs `amagi-clipper` and reads `clips.md` back to you.
145
+
146
+ ## Limitations
147
+
148
+ - Scoring is a heuristic, not an LLM. It finds clean, self-contained stretches with a strong first line. It cannot tell whether a joke lands. Watch the clips before you post them.
149
+ - `crop` is a fixed center crop with no face tracking. If the speaker sits off-center, use `--layout blur`.
150
+ - Whisper on a CPU is slow. On our busy test PC, `small` ran slower than real time. `--model base` or `tiny` is faster but less accurate, and an NVIDIA GPU is much faster.
151
+ - The demo episode is synthesized speech written for the test. Real conversations are messier, so expect to see more picks you would skip.
152
+
153
+ ## Related AmagiLabs projects
154
+
155
+ - [amagi-listen](https://github.com/amagilabs/amagi-listen): give Claude a podcast or meeting recording and get back a chaptered transcript.
156
+ - [amagi-watch](https://github.com/amagilabs/amagi-watch): give Claude a video URL and get back a transcript and key frames.
157
+ - More tools at [github.com/amagilabs](https://github.com/amagilabs).
158
+
159
+ If amagi-clipper saved you an afternoon of scrubbing through a timeline, a star helps other podcasters find it.
160
+
161
+ ## License
162
+
163
+ MIT. Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs). See [LICENSE](LICENSE).
164
+
165
+ Built by [AmagiLabs](https://amagilabs.ai).
@@ -0,0 +1,12 @@
1
+ amagi_clipper/__init__.py,sha256=PhWaKiFNVw6pqbdv-ficRJZRO8c8YMPoQKSgZLOEokU,108
2
+ amagi_clipper/captions.py,sha256=zGplGoexfwtAbdz-AYkIA7HdSolDIUmPhnuqhJoMR68,5314
3
+ amagi_clipper/cli.py,sha256=yRWWsAnJH8YpXs0l47cko-gMXMp34pZZLJY-4U7qWdY,9200
4
+ amagi_clipper/media.py,sha256=exYcOp9NVIMTcoXGnOO5mRcc7BXRSLNRsBqSAhg1vE0,5288
5
+ amagi_clipper/render.py,sha256=kokdiDg93mM6ueBRzeGU6L17PCxs5bu-0R7GvSu4XwI,2950
6
+ amagi_clipper/score.py,sha256=uGpneQPoY0dhYDIs5OAX1Bdh8Fj2H0MFZsXxNtW6xZg,11718
7
+ amagi_clipper-0.1.0.dist-info/licenses/LICENSE,sha256=E9pn1AIWzrWuEuaJE2YWjBuCSHHVGszC0IRq8u6hAQw,1115
8
+ amagi_clipper-0.1.0.dist-info/METADATA,sha256=HLuGY8UYsfoCXZuAEAVs3Hr1gq1rsNte6cJH7y42b4I,8975
9
+ amagi_clipper-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
10
+ amagi_clipper-0.1.0.dist-info/entry_points.txt,sha256=Okf2yZ0ooCi5ErIzEfEriGxZ9xpjI0BGGKgLaEId9Wk,57
11
+ amagi_clipper-0.1.0.dist-info/top_level.txt,sha256=3g5BIqvQ-dhS-bCwDA77g7RXEFgj-nbsdqM8B5sjk0s,14
12
+ amagi_clipper-0.1.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
+ amagi-clipper = amagi_clipper.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ amagi_clipper