livestream_clip_mining v1.0.0

name: "livestream_clip_mining" description: "Turn a live broadcast into shareable clips: hotkey marks and chat-triggered captures during the stream, then ranked clip candidates with ready cut commands after. Triggers on requests to capture stream highlights, mine a VOD for clips, or build a short-form cut pipeline for livestreams."

Livestream Clip Mining

Purpose

Capture the moments worth clipping while a stream is live, then turn the raw captures into a ranked shortlist with cut commands. Covers the full loop: before-stream planning, during-stream capture (hotkeys, chat commands, replay buffer), and post-stream ranking and cutting. Built for streamers and editors who want one stream to become a batch of short-form posts without scrubbing hours of VOD.

Workflow

1. Plan before going live. Write down 2-3 segments tonight that are likely to produce a moment: a ranked push, a first-time reaction, a promised payoff, a planned hot take. This shortlist turns review into a search instead of a browse. See references/clip-selection.md for what makes a moment clip-worthy.
2. Set up capture before the stream. Pick the capture mix from references/capture-setup.md: your own hotkey marker, a mod logging timestamps, a viewer !clip chat command, and the OBS replay buffer for instant social cuts. Record on a separate track or file where possible so cuts do not depend on platform VODs.
3. Capture during the stream. When something lands, hit the marker hotkey and note what happened (one phrase). A mod types timestamps into a shared doc. Viewers fire !clip for moments you missed. Save replay-buffer clips for moments you want posted while still live.
4. Gather inputs after the stream. Collect: the marker list (timestamp + note + source), the chat log with message-rate spikes, and the VOD file or platform markers. Normalize timestamps to seconds-from-stream-start.
5. Rank with bin/clipminer.py. It scores each candidate on source (hotkey and mod marks beat chat noise), chat-reaction intensity vs the rolling baseline, and whether the moment was explicitly requested (discounted). It outputs a ranked list plus ready ffmpeg cut commands.
6. Cut and finish only the shortlist. Open each clip 3-5s before the moment so the viewer sees the setup. Keep clips 15-45s for shorts feeds (Twitch allows 5-60s). Cut greetings and setup that add nothing. Each clip must pass the stranger test: someone with zero context must get it.

Output Contract

• A ranked candidate list: timestamp, score breakdown, note, suggested window.
• Cut commands that run as-is against the VOD or recording.
• A posted batch of clips: vertical reframe checked, hook-first, captioned, each with a title.
• Rejects: an explicit drop list with one-line reasons, so you do not re-litigate them.

Operating Rules

1. Plan the capture targets before the stream, not after.
2. Never rely on one capture source. Hotkeys miss things, chat floods, replay buffers fill up. Run at least two.
3. Timestamps are everything. Every marker needs seconds-from-start, not "a while ago".
4. Discount chat bursts the streamer requested ("everybody type W"). That is a reflex, not a moment.
5. Visible payoff beats off-screen reaction. If the clip never shows why anyone reacted, cut it.
6. Post while live only from replay-buffer files or pre-cut assets, never by editing the running VOD.
7. Do not invent quotes, numbers, or viewer reactions. If it is not in the log, the chat record, or the footage, it did not happen.