clipsmith-ai 0.2.0__tar.gz

clipsmith_ai-0.2.0/.dockerignore

@@ -0,0 +1,38 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+*.pyo
+.mypy_cache
+.ruff_cache
+.pytest_cache
+.coverage
+dist
+build
+site
+*.egg-info
+
+# Runtime artifacts — mounted as volumes, not baked in
+work/
+out/
+state.json
+*.mp4
+*.m4a
+*.ass
+*.srt
+
+# Secrets and local config — injected at runtime via env vars
+.env
+.env.example
+
+# Dev-only
+tests/
+docs/
+examples/
+scripts/
+mkdocs.yml
+AzureCLI.msi
+clipsmith.spec
+main.py

clipsmith_ai-0.2.0/.env.example

@@ -0,0 +1,29 @@
+# clipsmith secrets — copy this file to .env and fill in your key.
+# Run `clipsmith setup` to do this interactively.
+
+# LLM provider key (set the one you use)
+#ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# Twitch credentials — only needed for `watch` / `run-vod` (not for `process`)
+# TWITCH_CLIENT_ID=
+# TWITCH_CLIENT_SECRET=
+
+# Azure — only AZURE_SUBSCRIPTION_ID is required for cloud runs.
+# Storage accounts and file shares are provisioned automatically per run and torn down when done.
+# AZURE_SUBSCRIPTION_ID=
+
+# Azure Service Principal — recommended; avoids running as your personal admin account.
+# Run `clipsmith cloud setup-sp` (see docs/cloud.md) to create the SP and get these values.
+# Without these, DefaultAzureCredential falls back to `az login` (your personal account).
+# AZURE_CLIENT_ID=
+# AZURE_CLIENT_SECRET=
+# AZURE_TENANT_ID=
+
+# Docker Hub — optional; prevents image pull rate-limit errors on ACI
+# DOCKER_HUB_USERNAME=
+# DOCKER_HUB_PASSWORD=
+
+# Google Drive — optional; used to upload finished clips after a cloud run
+# GOOGLE_OAUTH_CLIENT_JSON=
+# GOOGLE_DRIVE_FOLDER_ID=

clipsmith_ai-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]" mypy
+      - run: ruff check src tests
+      - run: mypy src
+
+  tests:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get install -y ffmpeg
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/ -q
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: bandit -r src/ -ll -x tests/
+      - run: pip-audit --skip-editable

clipsmith_ai-0.2.0/.github/workflows/e2e-cloud.yml

@@ -0,0 +1,19 @@
+name: E2E Cloud
+on:
+  workflow_dispatch:
+
+jobs:
+  e2e-cloud:
+    runs-on: ubuntu-latest
+    env:
+      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      AZURE_CLIENT_ID:        ${{ secrets.AZURE_CLIENT_ID }}
+      AZURE_CLIENT_SECRET:    ${{ secrets.AZURE_CLIENT_SECRET }}
+      AZURE_TENANT_ID:        ${{ secrets.AZURE_TENANT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev,cloud]"
+      - run: python -m pytest tests/e2e/test_cloud.py --run-e2e -v

clipsmith_ai-0.2.0/.github/workflows/e2e.yml

@@ -0,0 +1,20 @@
+name: E2E
+on:
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    env:
+      TWITCH_CLIENT_ID: ${{ secrets.TWITCH_CLIENT_ID }}
+      TWITCH_CLIENT_SECRET: ${{ secrets.TWITCH_CLIENT_SECRET }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      E2E_VOD_ID: ${{ secrets.E2E_VOD_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: sudo apt-get install -y ffmpeg
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/e2e/ --run-e2e -q

clipsmith_ai-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

clipsmith_ai-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+name: Release Please
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json

clipsmith_ai-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+.env
+*-sa.json
+google_oauth_client.json
+~/.clipsmith_drive_token.json
+.pytest-tmp/
+.claude/
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+site/
+*.egg-info/
+
+# Pipeline artifacts
+out/
+work/
+state.json
+*.mp4
+*.m4a
+*.ass
+*.srt
+transcript.json
+chat.json
+picks.json
+candidates.json
+.coverage

clipsmith_ai-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: python -m mypy src
+        language: system
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: python -m pytest tests/ -q
+        language: system
+        pass_filenames: false

clipsmith_ai-0.2.0/.release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "packages": {
+    ".": {}
+  },
+  "changelog-types": [
+    {"type": "feat",  "section": "Features",     "hidden": false},
+    {"type": "fix",   "section": "Bug Fixes",    "hidden": false},
+    {"type": "perf",  "section": "Performance",  "hidden": false},
+    {"type": "chore", "section": "Misc",         "hidden": true},
+    {"type": "docs",  "section": "Misc",         "hidden": true},
+    {"type": "test",  "section": "Misc",         "hidden": true}
+  ]
+}

clipsmith_ai-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

clipsmith_ai-0.2.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.2.0](https://github.com/ricardogr07/clipsmith/compare/v0.1.0...v0.2.0) (2026-05-09)
+
+
+### Features
+
+* add --local flag to skip Twitch API calls for offline runs ([f7a2dd1](https://github.com/ricardogr07/clipsmith/commit/f7a2dd1c3662ca8dee8245c612284addb2a7b7cf))
+* add process and setup commands for non-technical users ([78a6b80](https://github.com/ricardogr07/clipsmith/commit/78a6b8087c0a0b34012be5e8375486d515849e6b))
+* add PyInstaller spec, Windows build script, and user README ([ec4ac9a](https://github.com/ricardogr07/clipsmith/commit/ec4ac9aa240beb8d248c526e8f04173e406ec6ac))
+* add reframe=none stream-copy and transcript-sample fallback ([5d2f84c](https://github.com/ricardogr07/clipsmith/commit/5d2f84cf5457d1817b2727f923c9a4bbbc1321e4))
+* PyPI distribution as clipsmith-ai with release-please and OIDC publish ([42673c4](https://github.com/ricardogr07/clipsmith/commit/42673c449d69bd38bb24fe74a13d101d5fcfa428))
+* replace chat_downloader with direct Twitch GQL pagination ([44933e7](https://github.com/ricardogr07/clipsmith/commit/44933e79b628ffead0307672bf26b89aeac8c670))
+* two-path .env discovery and bundled ffmpeg detection ([d10d6b6](https://github.com/ricardogr07/clipsmith/commit/d10d6b6482eeb9aeca4f619cf38a87b9cec9b72d))
+
+
+### Bug Fixes
+
+* install ffmpeg in tests job; upgrade pip and skip editable in pip-audit ([a570434](https://github.com/ricardogr07/clipsmith/commit/a570434e23aa14608f2e80f7169e97dccc7bf353))
+
+
+### Documentation
+
+* add ARCHITECTURE.md with pipeline diagram and module map ([ef554eb](https://github.com/ricardogr07/clipsmith/commit/ef554eb4999dc41e3f9c8032c3363e0ebb08f454))
+* add Artifacts section to architecture.md ([e0a0b37](https://github.com/ricardogr07/clipsmith/commit/e0a0b37d151a0323b631a7d985d464c40f1bc78d))
+* add MkDocs site with Material theme ([0765f6e](https://github.com/ricardogr07/clipsmith/commit/0765f6e9b9849a6b947d9a1e0a7d768476f8e0b3))
+* refresh all docs, add SP setup, replace Colab notebook ([41c9faf](https://github.com/ricardogr07/clipsmith/commit/41c9faf3c0ea76994a00dd83f38a9124e5d2f3d1))
+* refresh architecture, add cloud guide, update commands and configuration ([4b50d2d](https://github.com/ricardogr07/clipsmith/commit/4b50d2d1a7065f8e1484827c4a0580df027f48e2))

clipsmith_ai-0.2.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+# Install core pipeline only — cloud/Azure packages are local-CLI-only
+RUN pip install --no-cache-dir -e ".[vision]"
+
+# Bake the Whisper model so containers start immediately without downloading it.
+# Uses the "small" model matching the default in config.yaml (transcribe.model).
+# Rebuild the image if you switch to "medium" or "large-v3".
+RUN python -c "from faster_whisper import WhisperModel; WhisperModel('small', device='cpu', compute_type='int8')"
+
+VOLUME ["/app/work", "/app/out"]
+
+ENTRYPOINT ["clipsmith"]

clipsmith_ai-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo García Ramírez
+
+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.

clipsmith_ai-0.2.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: clipsmith-ai
+Version: 0.2.0
+Summary: Twitch VOD -> AI-selected vertical clips with burned-in Spanish captions.
+Project-URL: Homepage, https://github.com/ricardogr07/clipsmith
+Project-URL: Repository, https://github.com/ricardogr07/clipsmith
+Project-URL: Documentation, https://ricardogr07.github.io/clipsmith
+Author-email: Ricardo García Ramírez <rgr5882@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,clips,ffmpeg,llm,twitch,vertical-video,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: chat-downloader>=0.2
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.40
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: twitch-dl>=3.3
+Requires-Dist: typer>=0.12
+Provides-Extra: cloud
+Requires-Dist: azure-identity>=1.16; extra == 'cloud'
+Requires-Dist: azure-mgmt-containerinstance>=10; extra == 'cloud'
+Requires-Dist: azure-mgmt-resource>=23; extra == 'cloud'
+Requires-Dist: azure-mgmt-storage>=21; extra == 'cloud'
+Requires-Dist: azure-storage-file-share>=12; extra == 'cloud'
+Requires-Dist: google-api-python-client>=2; extra == 'cloud'
+Requires-Dist: google-auth-oauthlib>=1; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3; extra == 'ollama'
+Provides-Extra: vision
+Requires-Dist: opencv-python-headless>=4.9; extra == 'vision'
+Description-Content-Type: text/markdown
+
+# clipsmith
+
+Local Twitch → AI clip pipeline. Downloads a VOD, transcribes Spanish audio, ranks moments by chat activity, sends candidates to an LLM, and cuts 9:16 vertical MP4s — optionally with burned-in captions and a stacked webcam/gameplay layout for TikTok / YouTube Shorts.
+
+## Prerequisites
+
+| Tool | Install |
+|------|---------|
+| Python 3.11+ | python.org or `winget install Python.Python.3` |
+| ffmpeg | `winget install Gyan.FFmpeg` — must be on `PATH` |
+| twitch-dl | bundled via `pip install -e .` |
+| chat-downloader | bundled via `pip install -e .` |
+| faster-whisper | bundled via `pip install -e .` |
+
+Optional — webcam auto-detection:
+```sh
+pip install -e ".[vision]"   # installs opencv-python-headless
+```
+
+## Installation
+
+```sh
+git clone https://github.com/ricardogr07/clipsmith
+cd clipsmith
+pip install -e .
+```
+
+## Configuration
+
+### Secrets — `.env`
+
+Copy `.env.example` to `.env` and fill in your keys:
+
+```
+TWITCH_CLIENT_ID=...
+TWITCH_CLIENT_SECRET=...
+ANTHROPIC_API_KEY=...       # if using provider: anthropic
+OPENAI_API_KEY=...          # if using provider: openai
+```
+
+Get Twitch credentials at <https://dev.twitch.tv/console> → Register Your Application → OAuth Redirect: `http://localhost`.
+
+### Behaviour — `config.yaml`
+
+```yaml
+channels:
+  - chuyelwuero             # Twitch logins to watch
+
+llm:
+  provider: anthropic       # anthropic | openai | ollama
+  model_anthropic: claude-sonnet-4-6
+
+clip:
+  min_seconds: 15
+  max_seconds: 30
+
+caption:
+  enabled: false            # set true to burn subtitles into the video
+  font: Arial
+  font_size: 72             # ASS pts at 1080×1920 PlayRes
+  outline: 3
+  position: bottom          # bottom | middle | top
+
+reframe:
+  # center | webcam | stacked | none
+  mode: none
+  # Source-pixel crop for the webcam/face panel [x, y, w, h]
+  # Leave null to use center-crop fallback; set once per stream layout.
+  webcam_rect: null
+  # Source-pixel crop for the gameplay panel (stacked mode only)
+  # null = center-crop fallback
+  gameplay_rect: null
+  # Fraction of 1920px height given to the top (webcam) panel in stacked mode
+  # e.g. 0.4 → 768px webcam on top, 1152px gameplay on bottom
+  split_ratio: 0.4
+```
+
+## Usage
+
+### First-time setup
+
+```sh
+clipsmith setup
+```
+
+Saves your API key to `.env` and verifies ffmpeg is available.
+
+### Process a local MP4
+
+```sh
+clipsmith process path/to/recording.mp4
+```
+
+Runs the full pipeline — transcribe → score candidates → LLM selection → cut clips. Clips appear in `out/<video_id>/`.
+
+Useful flags:
+
+| Flag | Effect |
+|------|--------|
+| `--skip-transcribe` | Load cached `transcript.json` |
+| `--captions / --no-captions` | Override caption config |
+| `--reframe / --no-reframe` | Override reframe config |
+| `--provider anthropic\|openai` | Override LLM provider |
+
+### Daemon mode
+
+```sh
+clipsmith watch
+```
+
+Polls every `poll_interval_s` seconds (default 120). When a new archive VOD appears it runs the full pipeline automatically. State is persisted to `state.json` so already-processed VODs are skipped across restarts.
+
+### One-off Twitch VOD
+
+```sh
+clipsmith run-vod <video_id>
+```
+
+Useful flags:
+
+| Flag | Effect |
+|------|--------|
+| `--skip-download` | Use the existing `.mp4` in `work/<id>/` |
+| `--skip-transcribe` | Load cached `transcript.json` |
+| `--skip-chat` | Load cached `chat.json` |
+| `--skip-select` | Stop after candidates, skip LLM |
+| `--skip-clip` | Stop after picks, skip ffmpeg |
+| `--provider anthropic\|openai` | Override config LLM |
+| `--max-candidates N` | Cap candidates sent to LLM (default 20) |
+
+### Re-cut flat clips
+
+Re-run only the ffmpeg step from an existing `picks.json` (e.g. after adjusting caption style):
+
+```sh
+clipsmith clip <video_id>
+```
+
+### Stacked vertical layout (webcam + gameplay)
+
+After reviewing the flat clips, pick the best ones and reframe them into a stacked 9:16 layout — webcam on top, gameplay on bottom:
+
+```sh
+clipsmith reframe <video_id> clip_01 clip_04 clip_09
+```
+
+Output goes to `out/<video_id>/stacked/`. The reframe rects come from `config.yaml`; see the `reframe` section above.
+
+**Auto-detecting the webcam rect:**
+
+If `reframe.webcam_rect` is not set in `config.yaml`, clipsmith will try to detect the face rectangle automatically using OpenCV (requires `pip install -e ".[vision]"`). The result is cached to `work/<video_id>/webcam_rect.json` and reused on subsequent runs.
+
+To run detection manually and write the result directly into `config.yaml`:
+
+```sh
+clipsmith detect-webcam <video_id>
+```
+
+This samples frames, detects the webcam rectangle, and saves `reframe.webcam_rect` in `config.yaml` automatically — no manual copy-paste needed.
+
+### Sanity check
+
+```sh
+clipsmith whoami chuyelwuero
+```
+
+## Output
+
+```
+work/
+  <video_id>/
+    <video_id>.mp4          downloaded (or copied) source VOD
+    transcript.json         faster-whisper segments + word timestamps
+    chat.json               chat replay
+    candidates.json         ranked candidate moments
+    picks.json              LLM-accepted clips with titles and reasons
+    webcam_rect.json        auto-detected webcam rect (cached, vision only)
+
+out/
+  <video_id>/
+    clip_01_momento_gracioso.mp4    flat 9:16 clip
+    clip_01_momento_gracioso.ass    sidecar ASS subtitle file
+    clip_02_reaccion_epica.mp4
+    ...
+    stacked/
+      clip_01_momento_gracioso.mp4  stacked layout (webcam top, gameplay bottom)
+      clip_04_reaccion_epica.mp4
+      ...
+```
+
+All clips are 1080×1920 (9:16), 15–30 s, h264/aac, with optional burned-in Spanish karaoke captions.
+
+## Pipeline overview
+
+```
+watch / run-vod / process
+  ↓
+downloader      (twitch-dl)                → work/<id>/<id>.mp4
+  ↓
+detect-webcam   (opencv Haar cascade)      → work/<id>/webcam_rect.json  [optional]
+  ↓
+transcribe      (faster-whisper)           → transcript.json  (word timestamps, lang=es)
+  ↓
+chat            (chat-downloader)          → chat.json
+  ↓
+candidates      (density + clips + !clip)  → candidates.json
+  ↓
+selector        (LLM)                      → picks.json
+  ↓
+clipper         (ffmpeg + libass)          → out/<id>/clip_NN_<title>.mp4
+  ↓  [manual: clipsmith reframe]
+reframe         (ffmpeg filter_complex)    → out/<id>/stacked/clip_NN_<title>.mp4
+```
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+pip install -e ".[vision]"   # optional, for detect-webcam tests
+python -m pytest tests -q
+```