stream-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 @@
1
+ """Twitch stream clipping and draft review tools."""
@@ -0,0 +1,4 @@
1
+ """Retired entry point for the transcript editing pilot."""
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit("The transcript editor has been retired.")
@@ -0,0 +1,103 @@
1
+ """Save a bounded sample of live source segments while the benchmark runs."""
2
+
3
+ import argparse
4
+ import json
5
+ import os
6
+ import shutil
7
+ import time
8
+ from pathlib import Path
9
+
10
+
11
+ MAX_REVIEW_BYTES = 384 * 1024**2
12
+
13
+
14
+ def sample_type(row):
15
+ decision = row["decision"]
16
+ if decision in {"exported", "boundaries need review", "footage rejected"}:
17
+ return decision
18
+ ranking = row["ranking"]
19
+ if ranking["chat_qualified"] or ranking["viewer_creators"] >= 3:
20
+ return "strong single signal"
21
+ return None
22
+
23
+
24
+ def save_source(staging, output, row, start, end, remaining_bytes):
25
+ channel = row["channel"]
26
+ sources = []
27
+ for recording in staging.glob(f"{channel}-*"):
28
+ matches = []
29
+ for path in recording.glob("*.ts"):
30
+ pdt = int(path.stem.rsplit("-", 1)[1]) / 1_000_000
31
+ if start - 4 <= pdt <= end:
32
+ matches.append((path, pdt))
33
+ if len(matches) > len(sources):
34
+ sources = matches
35
+ if not sources:
36
+ return 0
37
+ size = sum(path.stat().st_size for path, _ in sources)
38
+ if size > remaining_bytes:
39
+ return 0
40
+ sources.sort(key=lambda item: item[1])
41
+ output.mkdir(parents=True, exist_ok=True)
42
+ segment_times = []
43
+ for path, pdt in sources:
44
+ target = output / path.name
45
+ if not target.exists():
46
+ os.link(path, target)
47
+ segment_times.append(pdt)
48
+ review = {**row, "review_source": {"requested": [start, end], "segment_starts": segment_times}}
49
+ (output / "decision.json").write_text(json.dumps(review, indent=2) + "\n")
50
+ return size
51
+
52
+
53
+ def main():
54
+ parser = argparse.ArgumentParser(description=__doc__)
55
+ parser.add_argument("staging", type=Path)
56
+ parser.add_argument("monitor_pid", type=int)
57
+ args = parser.parse_args()
58
+ audit = args.staging / "quality.jsonl"
59
+ offset = 0
60
+ saved = set()
61
+ retained_bytes = 0
62
+ origin = time.time()
63
+ while True:
64
+ running = True
65
+ try:
66
+ os.kill(args.monitor_pid, 0)
67
+ except ProcessLookupError:
68
+ running = False
69
+ if audit.exists():
70
+ with audit.open() as decisions:
71
+ decisions.seek(offset)
72
+ while line := decisions.readline():
73
+ if not line.endswith("\n"):
74
+ break
75
+ offset = decisions.tell()
76
+ row = json.loads(line)
77
+ kind = sample_type(row)
78
+ if kind is None or shutil.disk_usage(args.staging).free <= 7 * 1024**3:
79
+ continue
80
+ ranking = row["ranking"]
81
+ anchor = ranking["chat_anchor"] or row["timestamp"]
82
+ bucket = (int((anchor - origin) // 1800), kind)
83
+ if bucket in saved:
84
+ continue
85
+ start = min(row.get("source_start", anchor), anchor - 35)
86
+ end = max(row.get("source_end", anchor), anchor + 20)
87
+ output = args.staging / "review-source" / f"{row['channel']}-{row['timestamp']:.6f}"
88
+ try:
89
+ size = save_source(args.staging, output, row, start, end,
90
+ MAX_REVIEW_BYTES - retained_bytes)
91
+ if size:
92
+ retained_bytes += size
93
+ saved.add(bucket)
94
+ except OSError as exc:
95
+ print(f"Could not retain review context for {output.name}: {exc}", flush=True)
96
+ if not running:
97
+ break
98
+ time.sleep(10)
99
+ print(f"Retained {len(saved)} live source samples, {retained_bytes} bytes", flush=True)
100
+
101
+
102
+ if __name__ == "__main__":
103
+ main()
@@ -0,0 +1,171 @@
1
+ #!/usr/bin/env python3
2
+ """Chat spike detection over a TwitchDownloader chat JSON.
3
+
4
+ Input: chat JSON from `TwitchDownloaderCLI chatdownload --id <vod> -o chat.json`
5
+ Output: candidate highlight windows (start/end/score) as JSON, written to
6
+ stdout or --out. Uses the Python standard library.
7
+
8
+ Usage:
9
+ python3 -B chat_spikes.py chat.json --top 10 --z 3.0 --window 75 --pad 15 \
10
+ [--out windows.json]
11
+
12
+ Method: per-second message and emote counts -> short moving average ->
13
+ z-score against a rolling baseline -> local maxima above the threshold,
14
+ merged when closer than --min-gap seconds, ranked by combined score.
15
+ """
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import gzip
20
+ import json
21
+ import math
22
+ import sys
23
+
24
+
25
+ def load_comments(path: str) -> list[dict]:
26
+ opener = gzip.open if path.endswith(".gz") else open
27
+ with opener(path, "rt", encoding="utf-8") as fh:
28
+ data = json.load(fh)
29
+ comments = data.get("comments") or []
30
+ # Defensive: keep only well-formed entries.
31
+ out = []
32
+ for c in comments:
33
+ try:
34
+ offset = float(c["content_offset_seconds"])
35
+ except (KeyError, TypeError, ValueError):
36
+ continue
37
+ msg = c.get("message") or {}
38
+ body = msg.get("body") or ""
39
+ emotes = msg.get("emoticons") or []
40
+ out.append({"t": offset, "body": body, "emotes": len(emotes)})
41
+ out.sort(key=lambda c: c["t"])
42
+ return out
43
+
44
+
45
+ def per_second_series(comments: list[dict]) -> tuple[list[int], list[int]]:
46
+ if not comments:
47
+ return [], []
48
+ duration = int(comments[-1]["t"]) + 1
49
+ msgs = [0] * duration
50
+ emotes = [0] * duration
51
+ for c in comments:
52
+ s = int(c["t"])
53
+ msgs[s] += 1
54
+ emotes[s] += c["emotes"]
55
+ return msgs, emotes
56
+
57
+
58
+ def moving_average(series: list[float], span: int) -> list[float]:
59
+ if span <= 1 or not series:
60
+ return list(series)
61
+ half = span // 2
62
+ prefix = [0.0]
63
+ for v in series:
64
+ prefix.append(prefix[-1] + v)
65
+ out = []
66
+ for i in range(len(series)):
67
+ lo, hi = max(0, i - half), min(len(series), i + half + 1)
68
+ out.append((prefix[hi] - prefix[lo]) / (hi - lo))
69
+ return out
70
+
71
+
72
+ def z_scores(series: list[float], baseline_span: int) -> list[float]:
73
+ """Z-score of each point against a rolling baseline ending just before it."""
74
+ n = len(series)
75
+ zs = [0.0] * n
76
+ prefix = [0.0]
77
+ prefix_sq = [0.0]
78
+ for v in series:
79
+ prefix.append(prefix[-1] + v)
80
+ prefix_sq.append(prefix_sq[-1] + v * v)
81
+ for i in range(n):
82
+ lo = max(0, i - baseline_span)
83
+ cnt = i - lo
84
+ if cnt < 10: # need a real baseline before scoring
85
+ continue
86
+ mean = (prefix[i] - prefix[lo]) / cnt
87
+ var = max(0.0, (prefix_sq[i] - prefix_sq[lo]) / cnt - mean * mean)
88
+ std = math.sqrt(var)
89
+ zs[i] = (series[i] - mean) / std if std > 1e-9 else 0.0
90
+ return zs
91
+
92
+
93
+ def pick_windows(z_msg: list[float], z_emote: list[float], smooth_msg: list[float],
94
+ smooth_emote: list[float], threshold: float, top: int,
95
+ window: int, pad: int, min_gap: int) -> list[dict]:
96
+ combined = [zm + 0.5 * ze for zm, ze in zip(z_msg, z_emote)]
97
+ candidates = []
98
+ for t, score in enumerate(combined):
99
+ if score < threshold:
100
+ continue
101
+ left = combined[t - 1] if t > 0 else -1.0
102
+ right = combined[t + 1] if t + 1 < len(combined) else -1.0
103
+ if score >= left and score >= right: # local maximum
104
+ candidates.append((t, score))
105
+ # Merge peaks closer than min_gap, keeping the higher-scoring one.
106
+ merged: list[tuple[int, float]] = []
107
+ for t, score in candidates:
108
+ if merged and t - merged[-1][0] < min_gap:
109
+ if score > merged[-1][1]:
110
+ merged[-1] = (t, score)
111
+ else:
112
+ merged.append((t, score))
113
+ merged.sort(key=lambda p: p[1], reverse=True)
114
+ windows = []
115
+ for t, score in merged[:top]:
116
+ start = max(0, t - window // 2 - pad)
117
+ end = t + window // 2 + pad
118
+ windows.append({
119
+ "start": start,
120
+ "end": end,
121
+ "peak": t,
122
+ "score": round(score, 2),
123
+ "msg_rate_per_s": round(smooth_msg[t], 2),
124
+ "emote_rate_per_s": round(smooth_emote[t], 2),
125
+ })
126
+ windows.sort(key=lambda w: w["start"])
127
+ return windows
128
+
129
+
130
+ def main() -> int:
131
+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
132
+ ap.add_argument("chat_json")
133
+ ap.add_argument("--top", type=int, default=10)
134
+ ap.add_argument("--z", type=float, default=3.0, help="z-score threshold")
135
+ ap.add_argument("--window", type=int, default=75, help="clip length seconds")
136
+ ap.add_argument("--pad", type=int, default=15, help="padding seconds each side")
137
+ ap.add_argument("--min-gap", type=int, default=60, help="merge peaks closer than this")
138
+ ap.add_argument("--smooth", type=int, default=10, help="moving average span (s)")
139
+ ap.add_argument("--baseline", type=int, default=300, help="rolling baseline span (s)")
140
+ ap.add_argument("--out", help="write JSON here instead of stdout")
141
+ args = ap.parse_args()
142
+
143
+ comments = load_comments(args.chat_json)
144
+ if not comments:
145
+ print("no usable comments found", file=sys.stderr)
146
+ return 1
147
+ msgs, emotes = per_second_series(comments)
148
+ smooth_msg = moving_average([float(m) for m in msgs], args.smooth)
149
+ smooth_emote = moving_average([float(e) for e in emotes], args.smooth)
150
+ z_msg = z_scores(smooth_msg, args.baseline)
151
+ z_emote = z_scores(smooth_emote, args.baseline)
152
+ windows = pick_windows(z_msg, z_emote, smooth_msg, smooth_emote,
153
+ args.z, args.top, args.window, args.pad, args.min_gap)
154
+ report = {
155
+ "source": args.chat_json,
156
+ "comments": len(comments),
157
+ "duration_s": len(msgs),
158
+ "windows": windows,
159
+ }
160
+ text = json.dumps(report, indent=2)
161
+ if args.out:
162
+ with open(args.out, "w", encoding="utf-8") as fh:
163
+ fh.write(text + "\n")
164
+ print(f"wrote {args.out} ({len(windows)} windows)", file=sys.stderr)
165
+ else:
166
+ print(text)
167
+ return 0
168
+
169
+
170
+ if __name__ == "__main__":
171
+ raise SystemExit(main())
@@ -0,0 +1,149 @@
1
+ """Browse completed live clips and optionally save a selected PostFling draft."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import asyncio
7
+ import json
8
+ import os
9
+ import stat
10
+ import sys
11
+ from itertools import islice
12
+ from pathlib import Path
13
+ from urllib.error import HTTPError
14
+
15
+ if __package__:
16
+ from .live_drafts import PostFlingDrafts
17
+ from .push_to_postfling import INSIGHTS_SUFFIX, LIVE_CLIP_NAME, call_json, media_index, save_clip_draft
18
+ else:
19
+ from live_drafts import PostFlingDrafts
20
+ from push_to_postfling import INSIGHTS_SUFFIX, LIVE_CLIP_NAME, call_json, media_index, save_clip_draft
21
+
22
+
23
+ MAX_INSIGHTS_BYTES = 128 * 1024
24
+ TRIGGERS = ("chat", "chat_reaction", "viewer_clip", "elimination", "knock", "win")
25
+
26
+
27
+ def completed_clip(clips_dir: Path, clip_id: str) -> tuple[Path, dict[str, str | float]]:
28
+ if not LIVE_CLIP_NAME.fullmatch(clip_id):
29
+ raise ValueError("Use a clip ID returned by list_clips")
30
+ channel, timestamp = clip_id.split("-", 1)
31
+ mp4 = clips_dir / f"{clip_id}.mp4"
32
+ sidecar = clips_dir / f"{clip_id}{INSIGHTS_SUFFIX}"
33
+ try:
34
+ video = mp4.lstat()
35
+ insights_file = sidecar.lstat()
36
+ if (not stat.S_ISREG(video.st_mode) or video.st_size == 0
37
+ or not stat.S_ISREG(insights_file.st_mode)
38
+ or insights_file.st_size > MAX_INSIGHTS_BYTES):
39
+ raise ValueError("Invalid clip or sidecar")
40
+ with sidecar.open("rb") as source:
41
+ raw_insights = source.read(MAX_INSIGHTS_BYTES + 1)
42
+ if len(raw_insights) > MAX_INSIGHTS_BYTES:
43
+ raise ValueError("Clip sidecar exceeds size limit")
44
+ insights = json.loads(raw_insights)
45
+ if not isinstance(insights, dict) or insights.get("channel") != channel:
46
+ raise ValueError("Clip sidecar does not match the channel")
47
+ except (OSError, ValueError, RecursionError):
48
+ raise ValueError("Completed clip unavailable") from None
49
+
50
+ metadata = {"clip_id": clip_id, "channel": channel, "timestamp": float(timestamp)}
51
+ for field in ("duration", "score"):
52
+ value = insights.get(field)
53
+ if type(value) in (int, float) and -sys.float_info.max <= value <= sys.float_info.max:
54
+ metadata[field] = float(value)
55
+ if insights.get("trigger") in TRIGGERS:
56
+ metadata["trigger"] = insights["trigger"]
57
+ return mp4, metadata
58
+
59
+
60
+ def list_completed_clips(clips_dir: Path, limit: int, offset: int) -> list[dict[str, str | float]]:
61
+ if not 1 <= limit <= 100 or not 0 <= offset <= sys.maxsize - limit:
62
+ raise ValueError("Use a limit from 1 to 100 and a nonnegative offset")
63
+ try:
64
+ candidates = (entry.name.removesuffix(INSIGHTS_SUFFIX) for entry in clips_dir.iterdir()
65
+ if entry.name.endswith(INSIGHTS_SUFFIX))
66
+ clip_ids = [clip_id for clip_id in candidates if LIVE_CLIP_NAME.fullmatch(clip_id)]
67
+ except OSError:
68
+ raise ValueError("Configured clips directory unavailable") from None
69
+ clip_ids.sort(key=lambda clip_id: (float(clip_id.split("-", 1)[1]), clip_id), reverse=True)
70
+
71
+ def completed_metadata():
72
+ for clip_id in clip_ids:
73
+ try:
74
+ _, metadata = completed_clip(clips_dir, clip_id)
75
+ except ValueError:
76
+ continue
77
+ yield metadata
78
+
79
+ return list(islice(completed_metadata(), offset, offset + limit))
80
+
81
+
82
+ def save_selected_draft(clips_dir: Path, postfling: PostFlingDrafts, clip_id: str) -> dict[str, str | bool]:
83
+ mp4, metadata = completed_clip(clips_dir, clip_id)
84
+ channel = metadata["channel"]
85
+ destination = postfling.destinations.get(channel)
86
+ if destination is None:
87
+ raise ValueError("No PostFling destination is configured for this Twitch channel")
88
+ try:
89
+ opener = postfling.connect()
90
+ channels, _ = call_json(opener, postfling.origin, "/api/channels")
91
+ if not any(item["id"] == destination for item in channels["channels"]):
92
+ raise ValueError("PostFling destination is unavailable in the configured workspace")
93
+ draft_id, saved = save_clip_draft(
94
+ opener, postfling.origin, destination, clip_id, mp4, "",
95
+ f"https://www.twitch.tv/{channel}", media_index(opener, postfling.origin),
96
+ )
97
+ except HTTPError as exc:
98
+ raise ValueError(f"PostFling draft request failed (HTTP {exc.code})") from None
99
+ except (OSError, TypeError, KeyError, json.JSONDecodeError):
100
+ raise ValueError("Could not save the PostFling draft") from None
101
+ return {"draft_id": draft_id, "saved": saved}
102
+
103
+
104
+ def make_server(clips_dir: Path, postfling: PostFlingDrafts | None):
105
+ from mcp.server.fastmcp import FastMCP
106
+ from mcp.types import ToolAnnotations
107
+
108
+ server = FastMCP("Stream Clipping")
109
+
110
+ @server.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False))
111
+ async def list_clips(limit: int = 25, offset: int = 0) -> dict[str, list[dict[str, str | float]]]:
112
+ """List completed live clips newest first, with no video or chat content."""
113
+ return {"clips": await asyncio.to_thread(list_completed_clips, clips_dir, limit, offset)}
114
+
115
+ if postfling is not None:
116
+ @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
117
+ async def save_postfling_draft(clip_id: str) -> dict[str, str | bool]:
118
+ """Upload a listed clip and save it as a draft at its configured PostFling destination."""
119
+ return await asyncio.to_thread(save_selected_draft, clips_dir, postfling, clip_id)
120
+
121
+ return server
122
+
123
+
124
+ def main():
125
+ parser = argparse.ArgumentParser(description=__doc__)
126
+ parser.add_argument("--clips-dir", type=Path, required=True,
127
+ help="directory with completed clips and their insights sidecars")
128
+ parser.add_argument("--postfling-config", type=Path,
129
+ help="enable draft uploads using this PostFling configuration file")
130
+ args = parser.parse_args()
131
+
132
+ try:
133
+ clips_dir = args.clips_dir.resolve(strict=True)
134
+ if not clips_dir.is_dir():
135
+ parser.error("--clips-dir must be a directory")
136
+ postfling = PostFlingDrafts(args.postfling_config, os.environ) if args.postfling_config else None
137
+ except (KeyError, OSError, RuntimeError, ValueError) as exc:
138
+ parser.error(str(exc))
139
+ try:
140
+ server = make_server(clips_dir, postfling)
141
+ except ModuleNotFoundError as exc:
142
+ if exc.name != "mcp":
143
+ raise
144
+ parser.error("install 'stream-clipper[mcp]' or the source checkout's requirements-mcp.txt")
145
+ server.run(transport="stdio")
146
+
147
+
148
+ if __name__ == "__main__":
149
+ main()
@@ -0,0 +1,150 @@
1
+ """Model-free source-window checks and conservative pause boundary hints.
2
+
3
+ These checks can identify a few mechanical capture failures. They do not judge
4
+ whether a moment is funny, coherent, or worth clipping.
5
+ """
6
+
7
+ import math
8
+ import re
9
+ import subprocess
10
+
11
+ if __package__:
12
+ from .twitch_slate import SLATE, is_slate
13
+ else:
14
+ from twitch_slate import SLATE, is_slate
15
+
16
+
17
+ FRAME_SIZE = len(SLATE)
18
+ _SILENCE_START = re.compile(r"silence_start:\s*(-?\d+(?:\.\d+)?)")
19
+ _SILENCE_END = re.compile(r"silence_end:\s*(-?\d+(?:\.\d+)?)")
20
+
21
+
22
+ def _sampled_frames(ffmpeg, path, start=0.0, duration=None):
23
+ seek = ["-ss", str(max(0.0, start))] if start > 0 else []
24
+ length = ["-t", str(duration)] if duration is not None else []
25
+ result = subprocess.run(
26
+ [ffmpeg, "-nostdin", "-loglevel", "error", "-threads", "2",
27
+ "-i", str(path), *seek, *length,
28
+ "-an", "-vf", "fps=1,scale=16:9,format=rgb24", "-pix_fmt", "rgb24",
29
+ "-f", "rawvideo", "-"],
30
+ check=True, timeout=60, stdout=subprocess.PIPE, start_new_session=True,
31
+ )
32
+ raw = result.stdout
33
+ return [raw[i:i + FRAME_SIZE] for i in range(0, len(raw) - FRAME_SIZE + 1, FRAME_SIZE)]
34
+
35
+
36
+ def _matches_template(frame, template):
37
+ return len(frame) == len(template) and sum(
38
+ abs(pixel - sample) for pixel, sample in zip(frame, template)
39
+ ) <= 10 * len(template)
40
+
41
+
42
+ def _load_template(ffmpeg, path):
43
+ result = subprocess.run(
44
+ [ffmpeg, "-nostdin", "-loglevel", "error", "-threads", "2", "-i", str(path),
45
+ "-frames:v", "1", "-vf", "scale=16:9,format=rgb24", "-pix_fmt", "rgb24",
46
+ "-f", "rawvideo", "-"],
47
+ check=True, timeout=15, stdout=subprocess.PIPE, start_new_session=True,
48
+ )
49
+ return result.stdout[:FRAME_SIZE] if len(result.stdout) >= FRAME_SIZE else b""
50
+
51
+
52
+ def inspect_source_window(ffmpeg, path, *, start=0.0, duration=None, brb_template=None):
53
+ """Inspect a bounded source interval and return rejection evidence.
54
+
55
+ Twitch ads require 80% of five or more one-second samples. An opt-in BRB
56
+ reference image requires a close match in five consecutive one-second
57
+ samples or 60% of at least five samples. Static
58
+ camera shots are not treated as BRB. Returns ``{"reject": bool,
59
+ "reasons": [...]}``; when duration is supplied, footage below 80% of its
60
+ requested sample count is also rejected.
61
+ """
62
+ frames = _sampled_frames(ffmpeg, path, start, duration)
63
+ reasons = []
64
+ if duration is not None and duration > 0:
65
+ required_samples = max(5, math.ceil(duration * 0.8))
66
+ if len(frames) < required_samples:
67
+ reasons.append("insufficient_video_footage")
68
+ if len(frames) >= 5 and sum(is_slate(frame) for frame in frames) / len(frames) >= 0.8:
69
+ reasons.append("sustained_twitch_slate")
70
+ if brb_template is not None and len(frames) >= 5:
71
+ reference = _load_template(ffmpeg, brb_template)
72
+ if reference:
73
+ matches = [_matches_template(frame, reference) for frame in frames]
74
+ if sum(matches) / len(matches) >= 0.60 or any(
75
+ all(matches[index:index + 5]) for index in range(len(matches) - 4)
76
+ ):
77
+ reasons.append("sustained_broadcaster_brb_template")
78
+ return {"reject": bool(reasons), "reasons": reasons}
79
+
80
+
81
+ def _silence_intervals(log):
82
+ """Parse FFmpeg silencedetect output into (start, end) second pairs."""
83
+ intervals = []
84
+ pending = None
85
+ for line in log.splitlines():
86
+ start = _SILENCE_START.search(line)
87
+ end = _SILENCE_END.search(line)
88
+ if start:
89
+ pending = float(start.group(1))
90
+ if end and pending is not None:
91
+ finish = float(end.group(1))
92
+ if finish > pending:
93
+ intervals.append((pending, finish))
94
+ pending = None
95
+ return intervals
96
+
97
+
98
+ def suggest_pause_bounds(ffmpeg, path, *, start, end, search_seconds=8.0):
99
+ """Suggest nearby boundaries at clear silence, allowing context recovery.
100
+
101
+ ``start`` and ``end`` are desired edges relative to the caller-provided
102
+ bounded footage. The search may extend or shorten either edge by at most
103
+ ``search_seconds``. A hint requires separate >=0.4s silence intervals at
104
+ both edges and leaves at least 8s of footage. Silence is a mechanical cue,
105
+ not proof of a sentence or joke boundary. Missing audio returns ``None``.
106
+ """
107
+ if start < 0 or end - start < 8 or search_seconds <= 0:
108
+ return None
109
+ search_seconds = min(float(search_seconds), 8.0)
110
+ window_start = max(0.0, start - search_seconds)
111
+ try:
112
+ result = subprocess.run(
113
+ [ffmpeg, "-nostdin", "-hide_banner", "-threads", "2", "-i", str(path),
114
+ "-ss", str(window_start),
115
+ "-t", str(end + search_seconds - window_start),
116
+ "-map", "0:a:0?", "-vn", "-af", "silencedetect=noise=-38dB:d=0.4", "-f", "null", "-"],
117
+ check=True, timeout=60, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
118
+ text=True, start_new_session=True,
119
+ )
120
+ except subprocess.CalledProcessError as exc:
121
+ detail = exc.stderr or ""
122
+ if isinstance(detail, bytes):
123
+ detail = detail.decode("utf-8", errors="replace")
124
+ if ("does not contain any stream" in detail or "matches no streams" in detail
125
+ or "Output file is empty" in detail):
126
+ return None
127
+ raise
128
+ intervals = _silence_intervals(result.stderr)
129
+ # Include the nearest edge of each gap. Before an edge this can extend the
130
+ # cut to preserve setup/payoff; after it, this can trim dead air.
131
+ start_candidates = []
132
+ end_candidates = []
133
+ for index, (quiet_start, quiet_end) in enumerate(intervals):
134
+ absolute_start = window_start + quiet_start
135
+ absolute_end = window_start + quiet_end
136
+ start_candidates.extend((index, edge) for edge in (absolute_start, absolute_end)
137
+ if start - search_seconds <= edge <= start + search_seconds)
138
+ end_candidates.extend((index, edge) for edge in (absolute_start, absolute_end)
139
+ if end - search_seconds <= edge <= end + search_seconds)
140
+ best = None
141
+ for start_index, suggested_start in start_candidates:
142
+ for end_index, suggested_end in end_candidates:
143
+ if start_index == end_index:
144
+ continue
145
+ if suggested_end - suggested_start < 8:
146
+ continue
147
+ score = abs(suggested_start - start) + abs(suggested_end - end)
148
+ if best is None or score < best[0]:
149
+ best = (score, suggested_start, suggested_end)
150
+ return (best[1], best[2]) if best else None