Skip to main content

Stream Clipping

A local Python tool that watches explicitly selected Twitch channels, detects chat activity spikes, records live video, and cuts candidate clips. It can also prepare completed clips as drafts in PostFling for human review.

Requirements

  • Python 3.10 or newer. The core pipeline uses only the Python standard library.
  • A Twitch application client ID and secret for live-stream polling.
  • yt-dlp and FFmpeg and ffprobe on PATH for recording and export. The chat-only checks do not require video tools.
  • Optional dependencies include Tesseract with English data for --fortnite-hud and faster-whisper with a cached Whisper Small model for speech-assisted options.

Installation

Install the CLI from PyPI in a Python virtual environment:

python -m pip install stream-clipper

Use stream-clipping to run the monitor and stream-clipping-postfling to preview or upload clips for draft review. These commands accept the same arguments as pipeline/live_monitor.py and pipeline/push_to_postfling.py in the source examples below. You can also run those scripts from a checkout without installing the package.

Twitch use and authorization

The monitor reads stream status from Twitch Helix and chat from Twitch IRC. Live recording uses yt-dlp. Use it only where you have authorization to record the broadcast and retain the footage and chat under Twitch's Terms of Service. Obtain the necessary rights before sharing clips, including rights for any third-party material in the clip. Twitch also documents its official clip creation and retrieval API.

The monitor requires an explicit --channels list; there is no implicit channel selection. Use channel login names separated by commas.

Configure and run

Create a local Twitch credential file (keep it outside source control):

TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret

Save it as secrets/twitch.env or another local path. Do not commit it. First run a short dry-run to check Twitch polling and chat connectivity. This mode does not record video:

python3 pipeline/live_monitor.py \
  --channels your_authorized_channel \
  --env secrets/twitch.env \
  --dry-run

After reviewing the dry-run output, start live recording and clipping:

python3 pipeline/live_monitor.py \
  --channels your_authorized_channel \
  --env secrets/twitch.env \
  --staging ./output/live

Stop with Ctrl-C. The staging directory defaults to ./output/live. The monitor keeps recordings and event logs there. Finished MP4s and their *_insights.json sidecars go in clips/ under staging. The default disk reserve pauses recording as free space falls. Recordings and exported clips can accumulate across sessions, so set a retention policy for staging.

By default, the chat log stores event metadata such as time and message rate. --save-chat-samples adds short raw chat excerpts. Restrict access to staging and retain recordings, chat logs, and clips only as long as necessary.

For a bounded connectivity check, use --smoke SECONDS with exactly one explicit channel and the credential file. That channel must be live. Smoke mode checks Twitch polling and chat but does not record. Use an active chat:

python3 pipeline/live_monitor.py \
  --channels your_authorized_channel \
  --env secrets/twitch.env \
  --smoke 30

Optional PostFling draft review

PostFling is optional. Its uploader defaults to review mode, which uploads the selected clips and saves editable workspace drafts for a person to review. It does not initiate publishing in that mode. Preview locally first with --dry-run:

python3 pipeline/push_to_postfling.py \
  --clips-dir ./output/live/clips \
  --channel YOUR_POSTFLING_CHANNEL \
  --platform YOUR_PLATFORM \
  --dry-run

To save drafts, load POSTFLING_EMAIL and POSTFLING_PASSWORD into the process environment from your secret store and omit --dry-run:

python3 pipeline/push_to_postfling.py \
  --clips-dir ./output/live/clips \
  --channel YOUR_POSTFLING_CHANNEL \
  --platform YOUR_PLATFORM

The default origin is http://127.0.0.1:8477 for local testing. For a remote instance, set POSTFLING_URL to the HTTPS origin, such as https://workspace.example, without an API path. The client rejects redirects.

Direct delivery is an explicit --mode direct action. Use it only when you have the required rights and authorization for the content and destination. Review each draft and destination before choosing direct delivery.

Optional MCP server

The stdio server lets an MCP client browse completed live clips while the monitor runs separately. Use an absolute path to a clips directory writable only by you and the monitor. Create it or wait for the monitor to save a clip before connecting the client.

With uvx, the client can launch the PyPI package with its MCP dependencies:

uvx --from 'stream-clipper[mcp]' stream-clipping-mcp \
  --clips-dir /absolute/path/to/output/live/clips
{
  "mcpServers": {
    "stream-clipping": {
      "command": "uvx",
      "args": [
        "--from", "stream-clipper[mcp]", "stream-clipping-mcp",
        "--clips-dir", "/absolute/path/to/output/live/clips"
      ]
    }
  }
}

If your client cannot find uvx on its PATH, use the absolute path to it. You can also run python -m pip install 'stream-clipper[mcp]' in a virtual environment and point the client at the installed stream-clipping-mcp executable with --clips-dir and the absolute directory path as arguments.

Launch from a source checkout

Install the MCP Python SDK in a virtual environment for the client to launch.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-mcp.txt

Use absolute paths in your client's MCP server configuration.

{
  "mcpServers": {
    "stream-clipping": {
      "command": "/absolute/path/to/stream-clipping/.venv/bin/python",
      "args": [
        "/absolute/path/to/stream-clipping/pipeline/clip_mcp.py",
        "--clips-dir", "/absolute/path/to/output/live/clips"
      ]
    }
  }
}

MCP tools

list_clips shows the newest completed MP4 and insights pairs first. It returns clip IDs, Twitch logins, Unix timestamps, and optional duration, score, and trigger fields. Use limit (1–100, default 25) and offset (default 0) to page through results.

To enable save_postfling_draft, append --postfling-config and the absolute path to a JSON file to args. Use the same workspace and Twitch-login mapping as the live monitor. Supply POSTFLING_EMAIL and POSTFLING_PASSWORD to the server process through your client's secret environment or launch wrapper.

{
  "origin": "https://workspace.example",
  "workspace_id": "YOUR_WORKSPACE_ID",
  "destinations": {
    "your_authorized_channel": "YOUR_DESTINATION_CHANNEL_ID"
  }
}

Call save_postfling_draft with a clip_id from list_clips. The tool uploads that MP4 to the configured PostFling workspace and saves an editable draft for the mapped destination. Review and publish through PostFling.

Tests

With FFmpeg and ffprobe installed, run the full suite from the repository root:

python3 -B -m unittest discover -s tests -v

License

Project code is under the MIT License. The external tools and model weights retain their own licenses.

Metadata

Release files for stream-clipper 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stream-clipper 0.1.0
File Size Uploaded Provenance Actions
stream_clipper-0.1.0.tar.gz 67.0 kB Without provenance Details for stream_clipper-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stream-clipper 0.1.0
File Interpreter ABI Platform Actions
stream_clipper-0.1.0-py3-none-any.whl Python 3 none any Details for stream_clipper-0.1.0-py3-none-any.whl

Total release size: 120.9 kB

Release files / stream_clipper-0.1.0.tar.gz

Download URL stream_clipper-0.1.0.tar.gz
Size 67.0 kB
Tags Source
SHA-256 checksum
How to use checksums
293cec7dc68e0bcb82bda75c0094700e220433f6049b03c1e4adaf88c4d4384f
BLAKE2b-256 checksum
How to use checksums
95b297c853cade21f97553d1e52642bd8295ee1fe2893368cbd711a869b01d83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / stream_clipper-0.1.0-py3-none-any.whl

Download URL stream_clipper-0.1.0-py3-none-any.whl
Size 53.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
196f32064a3ab4a0ded1f5700312738acf5c268c7f2905fd361fa64e7c69b7dd
BLAKE2b-256 checksum
How to use checksums
988d0b3e11bf3edb43fe17e8ea7ee8e7bc1b9b03c8a72af5a5add96adc7a7636
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for stream-clipper 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page