twitch-auto-clipper 0.1.7__tar.gz

twitch_auto_clipper-0.1.7/.coveragerc

@@ -0,0 +1,2 @@
+[run]
+omit = tests/*

twitch_auto_clipper-0.1.7/.github/workflows/test_runner.yml

@@ -0,0 +1,18 @@
+name: Unit Tests
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: pip install .
+
+      - name: Run tests
+        run: ./scripts/run_tests.sh

twitch_auto_clipper-0.1.7/.gitignore

@@ -0,0 +1,9 @@
+.env
+.coverage
+htmlcov
+links.txt
+myvenv
+log
+dist
+tests/main.py
+**/__pycache__

twitch_auto_clipper-0.1.7/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

twitch_auto_clipper-0.1.7/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: twitch_auto_clipper
+Version: 0.1.7
+Summary: Automatically create Twitch clips when chat activity spikes
+Project-URL: source, https://github.com/sqrtminustwo/twitch_auto_clipper
+Author-email: Maksym Ziborov <twitch_auto_clipper@blkflag.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: dacite>=1.9.2
+Requires-Dist: requests>=2.34.2
+Requires-Dist: sortedcollections>=2.1.0
+Provides-Extra: test
+Requires-Dist: coverage>=7.16.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+[![Unit Tests](https://github.com/sqrtminustwo/twitch_auto_clipper/actions/workflows/test_runner.yml/badge.svg?branch=main)](https://github.com/sqrtminustwo/twitch_auto_clipper/actions/workflows/test_runner.yml)
+
+# twitch_auto_clipper
+
+Automatically create Twitch clips when chat activity spikes.
+
+Twitch Auto Clipper monitors Twitch chat and detects moments where a large number of viewers send the same emote/message within a short period of time. When activity exceeds a configurable threshold, it automatically creates a Twitch clip.
+
+[demo]
+
+## Installation
+
+```bash
+pip install twitch_auto_clipper
+```
+
+## Requirements
+
+Minimum Python version supported by `twitch_auto_clipper` is 3.10.
+
+## Quick start
+
+```python
+from twitch_auto_clipper_sqrtminusone.TwitchAutoClipper import TwitchAutoClipper
+
+clipper = TwitchAutoClipper(
+    ["Marlon", "Lacy"],
+    "YOUR_CLIENT_ID",
+    "YOUR_CLIENT_SECRET",
+    on_clip=lambda clip: print(clip),
+    common_value=1,
+    emote_value=2,
+    clipable_message_ratio=0.5,
+)
+
+clipper.start()
+clipper.join()
+```
+
+> [!IMPORTANT]
+> `client_id` and `client_secret` are saved in [TwitchAuthTokens](twitch_auto_clipper_sqrtminusone/auth/TwitchAuthTokens.py) and only sent to the Twitch API.
+
+> [!IMPORTANT]
+> Upon initialization of [TwitchAutoClipper](twitch_auto_clipper_sqrtminusone/TwitchAutoClipper.py), your web browser should open to gain clipping permission for your Twitch account (as shown in the demo).
+
+## Features
+
+- Automatically handles Twitch OAuth token refresh
+- Automatically monitors multiple Twitch streams
+- Supports custom emotes/messages as clipping triggers
+- Optional 7TV emote support
+- Runs each streamer in separate thread
+
+## How it works
+
+```text
+Twitch chat
+     │
+     ▼
+Collect messages
+     │
+     ▼
+Count messages / emotes
+     │
+     ▼
+Detect activity spike
+     │
+     ▼
+Threshold exceeded?
+     │
+    YES
+     ▼
+Create Twitch clip
+     │
+     ▼
+Call on_clip callback
+```
+
+## Usage
+
+There are two classes that you will typically need:
+
+- `TwitchAutoClipper` — monitors Twitch chat and automatically creates clips when a message reaches the configured threshold.
+- `Clip` — contains information about a clip that was created.
+
+### `TwitchAutoClipper`
+
+```python
+TwitchAutoClipper(
+    streamers_names,
+    client_id,
+    client_secret,
+    on_clip,
+    counter_interval_seconds=...,
+    clipable_message_ratio=...,
+    clipable_wait=...,
+    common_value=...,
+    emote_value=...,
+    excluded_words=...,
+    logging_handlers=...,
+    logging_level=...
+)
+```
+
+| Argument                   | Description                                                                                                                                                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `streamers_names`          | List of Twitch usernames to monitor. Usernames are case-insensitive and are converted to lowercase.                                                                                                                                      |
+| `client_id`                | Your Twitch application client ID. Available from the [Twitch Developer Console](https://dev.twitch.tv/docs/authentication/register-app).                                                                                                |
+| `client_secret`            | Your Twitch application client secret. Available from the [Twitch Developer Console](https://dev.twitch.tv/docs/authentication/register-app).                                                                                            |
+| `on_clip`                  | Callback function invoked with a `Clip` instance when a clip is created.                                                                                                                                                                 |
+| `counter_interval_seconds` | Time interval over which chat message frequencies are counted. Once the interval ends, the counters are reset.                                                                                                                           |
+| `clipable_message_ratio`   | The weighted frequency of the most frequent message divided by the total number of messages received during the current interval. Because messages can have different values (`common_value` and `emote_value`), the ratio can exceed 1. |
+| `clipable_wait`            | Time to wait before creating a clip after a message reaches the clipping threshold. The waiting and clipping are performed in a separate thread, so this does not block the streamer thread.                                             |
+| `common_value`             | Value assigned to a regular chat message. A regular message is any message that is not a 7TV emote when the streamer has a 7TV profile.                                                                                                  |
+| `emote_value`              | Value assigned to a 7TV emote.                                                                                                                                                                                                           |
+| `excluded_words`           | Words that should be excluded from message frequency counting.                                                                                                                                                                           |
+| `logging_handlers`         | Logging handlers used by the package. See [`examples/logger.py`](examples/logger.py) for an example using multiple handlers.                                                                                                             |
+| `logging_level`            | Logging level used by the package. See the [Python logging documentation](https://docs.python.org/3/library/logging.html#logging-levels).                                                                                                |
+
+> [!NOTE]
+> If multiple streamers are configured, `on_clip` may be called concurrently from multiple threads. Make sure your callback is thread-safe and use the appropriate [Python threading APIs](https://docs.python.org/3/library/threading.html) when necessary.
+
+### `Clip`
+
+A `Clip` instance contains information about the clip that was created.
+
+| Attribute        | Description                                                                                                                                        |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message`        | The chat message that triggered the clip.                                                                                                          |
+| `message_count`  | Number of occurrences of the triggering message.                                                                                                   |
+| `ratio`          | Ratio of the triggering message to the total number of messages received during the counting interval.                                             |
+| `broadcaster_id` | Twitch broadcaster ID of the streamer for whom the clip was created. See the [Twitch API documentation](https://dev.twitch.tv/docs/api/reference). |
+| `url`            | URL of the created clip.                                                                                                                           |
+| `timestamp`      | Expected timestamp of the event highlighted by the clip.                                                                                           |
+| `duration`       | Clip duration in seconds.                                                                                                                          |
+
+## Motivation
+
+Manually watching an entire stream to find moments worth clipping is time-consuming.
+
+`twitch_auto_clipper` uses the audience's reaction as a signal: when chat suddenly becomes active around a particular message or emote, the bot can automatically capture the moment.
+
+## Roadmap
+
+- [x] Analyze Twitch chat through IRC
+- [x] Twitch OAuth authentication
+- [x] Automatically create clips
+- [x] Monitor multiple live streamers
+- [x] Save clips to a log
+- [x] Add automated tests
+- [ ] Pip package
+- [ ] Web page for constants editing

twitch_auto_clipper-0.1.7/README.md

@@ -0,0 +1,152 @@
+[![Unit Tests](https://github.com/sqrtminustwo/twitch_auto_clipper/actions/workflows/test_runner.yml/badge.svg?branch=main)](https://github.com/sqrtminustwo/twitch_auto_clipper/actions/workflows/test_runner.yml)
+
+# twitch_auto_clipper
+
+Automatically create Twitch clips when chat activity spikes.
+
+Twitch Auto Clipper monitors Twitch chat and detects moments where a large number of viewers send the same emote/message within a short period of time. When activity exceeds a configurable threshold, it automatically creates a Twitch clip.
+
+[demo]
+
+## Installation
+
+```bash
+pip install twitch_auto_clipper
+```
+
+## Requirements
+
+Minimum Python version supported by `twitch_auto_clipper` is 3.10.
+
+## Quick start
+
+```python
+from twitch_auto_clipper_sqrtminusone.TwitchAutoClipper import TwitchAutoClipper
+
+clipper = TwitchAutoClipper(
+    ["Marlon", "Lacy"],
+    "YOUR_CLIENT_ID",
+    "YOUR_CLIENT_SECRET",
+    on_clip=lambda clip: print(clip),
+    common_value=1,
+    emote_value=2,
+    clipable_message_ratio=0.5,
+)
+
+clipper.start()
+clipper.join()
+```
+
+> [!IMPORTANT]
+> `client_id` and `client_secret` are saved in [TwitchAuthTokens](twitch_auto_clipper_sqrtminusone/auth/TwitchAuthTokens.py) and only sent to the Twitch API.
+
+> [!IMPORTANT]
+> Upon initialization of [TwitchAutoClipper](twitch_auto_clipper_sqrtminusone/TwitchAutoClipper.py), your web browser should open to gain clipping permission for your Twitch account (as shown in the demo).
+
+## Features
+
+- Automatically handles Twitch OAuth token refresh
+- Automatically monitors multiple Twitch streams
+- Supports custom emotes/messages as clipping triggers
+- Optional 7TV emote support
+- Runs each streamer in separate thread
+
+## How it works
+
+```text
+Twitch chat
+     │
+     ▼
+Collect messages
+     │
+     ▼
+Count messages / emotes
+     │
+     ▼
+Detect activity spike
+     │
+     ▼
+Threshold exceeded?
+     │
+    YES
+     ▼
+Create Twitch clip
+     │
+     ▼
+Call on_clip callback
+```
+
+## Usage
+
+There are two classes that you will typically need:
+
+- `TwitchAutoClipper` — monitors Twitch chat and automatically creates clips when a message reaches the configured threshold.
+- `Clip` — contains information about a clip that was created.
+
+### `TwitchAutoClipper`
+
+```python
+TwitchAutoClipper(
+    streamers_names,
+    client_id,
+    client_secret,
+    on_clip,
+    counter_interval_seconds=...,
+    clipable_message_ratio=...,
+    clipable_wait=...,
+    common_value=...,
+    emote_value=...,
+    excluded_words=...,
+    logging_handlers=...,
+    logging_level=...
+)
+```
+
+| Argument                   | Description                                                                                                                                                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `streamers_names`          | List of Twitch usernames to monitor. Usernames are case-insensitive and are converted to lowercase.                                                                                                                                      |
+| `client_id`                | Your Twitch application client ID. Available from the [Twitch Developer Console](https://dev.twitch.tv/docs/authentication/register-app).                                                                                                |
+| `client_secret`            | Your Twitch application client secret. Available from the [Twitch Developer Console](https://dev.twitch.tv/docs/authentication/register-app).                                                                                            |
+| `on_clip`                  | Callback function invoked with a `Clip` instance when a clip is created.                                                                                                                                                                 |
+| `counter_interval_seconds` | Time interval over which chat message frequencies are counted. Once the interval ends, the counters are reset.                                                                                                                           |
+| `clipable_message_ratio`   | The weighted frequency of the most frequent message divided by the total number of messages received during the current interval. Because messages can have different values (`common_value` and `emote_value`), the ratio can exceed 1. |
+| `clipable_wait`            | Time to wait before creating a clip after a message reaches the clipping threshold. The waiting and clipping are performed in a separate thread, so this does not block the streamer thread.                                             |
+| `common_value`             | Value assigned to a regular chat message. A regular message is any message that is not a 7TV emote when the streamer has a 7TV profile.                                                                                                  |
+| `emote_value`              | Value assigned to a 7TV emote.                                                                                                                                                                                                           |
+| `excluded_words`           | Words that should be excluded from message frequency counting.                                                                                                                                                                           |
+| `logging_handlers`         | Logging handlers used by the package. See [`examples/logger.py`](examples/logger.py) for an example using multiple handlers.                                                                                                             |
+| `logging_level`            | Logging level used by the package. See the [Python logging documentation](https://docs.python.org/3/library/logging.html#logging-levels).                                                                                                |
+
+> [!NOTE]
+> If multiple streamers are configured, `on_clip` may be called concurrently from multiple threads. Make sure your callback is thread-safe and use the appropriate [Python threading APIs](https://docs.python.org/3/library/threading.html) when necessary.
+
+### `Clip`
+
+A `Clip` instance contains information about the clip that was created.
+
+| Attribute        | Description                                                                                                                                        |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message`        | The chat message that triggered the clip.                                                                                                          |
+| `message_count`  | Number of occurrences of the triggering message.                                                                                                   |
+| `ratio`          | Ratio of the triggering message to the total number of messages received during the counting interval.                                             |
+| `broadcaster_id` | Twitch broadcaster ID of the streamer for whom the clip was created. See the [Twitch API documentation](https://dev.twitch.tv/docs/api/reference). |
+| `url`            | URL of the created clip.                                                                                                                           |
+| `timestamp`      | Expected timestamp of the event highlighted by the clip.                                                                                           |
+| `duration`       | Clip duration in seconds.                                                                                                                          |
+
+## Motivation
+
+Manually watching an entire stream to find moments worth clipping is time-consuming.
+
+`twitch_auto_clipper` uses the audience's reaction as a signal: when chat suddenly becomes active around a particular message or emote, the bot can automatically capture the moment.
+
+## Roadmap
+
+- [x] Analyze Twitch chat through IRC
+- [x] Twitch OAuth authentication
+- [x] Automatically create clips
+- [x] Monitor multiple live streamers
+- [x] Save clips to a log
+- [x] Add automated tests
+- [ ] Pip package
+- [ ] Web page for constants editing

twitch_auto_clipper-0.1.7/examples/logger.py

@@ -0,0 +1,61 @@
+from twitch_auto_clipper_sqrtminusone.TwitchAutoClipper import TwitchAutoClipper
+from twitch_auto_clipper_sqrtminusone.utils.utils import now_formated
+from twitch_auto_clipper_sqrtminusone.clip.Clip import Clip
+
+import csv
+from dataclasses import asdict, fields, is_dataclass
+from pathlib import Path
+from threading import Lock
+from dotenv import load_dotenv
+import os
+
+
+class Logger:
+    def __open_writer(self, csvfile):
+        return csv.DictWriter(
+            csvfile, fieldnames=self.fieldnames, quoting=csv.QUOTE_NONNUMERIC
+        )
+
+    def __init__(self, type_to_log, dir=Path("log"), filename=f"{now_formated()}.csv"):
+        assert is_dataclass(type_to_log)
+
+        os.makedirs(dir, exist_ok=True)
+
+        self.type = type_to_log
+        self.path = Path(dir, filename)
+        self.fieldnames = [field.name for field in fields(type_to_log)]
+        self.file_lock = Lock()
+
+        with open(self.path, "w+") as csvfile:
+            writer = self.__open_writer(csvfile)
+            writer.writeheader()
+
+    def write(self, data):
+        assert type(data) is self.type
+        with self.file_lock:
+            with open(self.path, "a") as csvfile:
+                writer = self.__open_writer(csvfile)
+                writer.writerow(asdict(data))
+
+
+load_dotenv()
+
+CLIP_LOGGER = Logger(Clip)
+
+
+def on_clip(clip):
+    CLIP_LOGGER.write(clip)
+
+
+clipper = TwitchAutoClipper(
+    ["Marlon", "Lacy"],
+    os.getenv("client_id"),
+    os.getenv("client_secret"),
+    on_clip=on_clip,
+    common_value=1,
+    emote_value=2,
+    clipable_message_ratio=0.2,
+)
+
+clipper.start()
+clipper.join()

twitch_auto_clipper-0.1.7/examples/simple.py

@@ -0,0 +1,19 @@
+from twitch_auto_clipper_sqrtminusone.TwitchAutoClipper import TwitchAutoClipper
+
+from dotenv import load_dotenv
+from os import getenv
+
+load_dotenv()
+
+clipper = TwitchAutoClipper(
+    ["Marlon", "Lacy"],
+    getenv("client_id"),
+    getenv("client_secret"),
+    on_clip=lambda clip: print(clip),
+    common_value=1,
+    emote_value=2,
+    clipable_message_ratio=0.2,
+)
+
+clipper.start()
+clipper.join()

twitch_auto_clipper-0.1.7/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "twitch_auto_clipper"
+version = "0.1.7"
+authors = [
+  { name="Maksym Ziborov", email="twitch_auto_clipper@blkflag.org" },
+]
+description = "Automatically create Twitch clips when chat activity spikes"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.34.2",
+    "sortedcollections>=2.1.0",
+    "dacite>=1.9.2"
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+source = "https://github.com/sqrtminustwo/twitch_auto_clipper"
+
+
+[project.optional-dependencies]
+test = [
+    "coverage>=7.16.0",
+]

twitch_auto_clipper-0.1.7/pyrightconfig.json

@@ -0,0 +1,14 @@
+// https://www.datacamp.com/tutorial/pyright
+{
+    "include": [
+        "twitch_auto_clippter",
+    ],
+    "exclude": [
+        "**/__pycache__",
+        "**/myvenv"
+    ],
+    "pythonVersion": "3.12",
+    "typeCheckingMode": "off",
+    "venvPath": ".",
+    "venv": "myvenv"
+}

twitch_auto_clipper-0.1.7/scripts/coverage.sh

@@ -0,0 +1,3 @@
+coverage run -m unittest discover tests/
+coverage html
+open htmlcov/index.html

twitch_auto_clipper-0.1.7/scripts/install.sh

@@ -0,0 +1 @@
+pip install -i https://test.pypi.org/simple/ twitch-auto-clipper-sqrtminusone==0.1.4

twitch_auto_clipper-0.1.7/scripts/night_run.sh

@@ -0,0 +1,3 @@
+sudo echo "obtained sudo"
+python3 src/main.py
+sudo shutdown -h now

twitch_auto_clipper-0.1.7/scripts/rebuild.sh

@@ -0,0 +1,4 @@
+# update version in pyproject.toml first
+rm -rf dist
+python3 -m build
+python3 -m twine upload --repository testpypi dist/*

twitch_auto_clipper-0.1.7/scripts/run_test.sh

@@ -0,0 +1 @@
+python -m unittest "$1"

twitch_auto_clipper-0.1.7/scripts/run_tests.sh

@@ -0,0 +1 @@
+python -m unittest discover tests/