laughing-man 1.2.0__tar.gz

laughing_man-1.2.0/.envrc

@@ -0,0 +1,6 @@
+# Create virtual environment and install deps (uv.lock) on first use
+if [ ! -d .venv ]; then
+  uv venv && uv sync
+fi
+
+source .venv/bin/activate

laughing_man-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Python version
+        run: uv python install 3.12
+
+      - name: Sync dependencies
+        run: uv sync --group dev --python 3.12
+
+      - name: Commitizen changelog (dry-run)
+        run: uv run cz changelog --dry-run
+
+      - name: Commitizen commit messages (pull requests)
+        if: github.event_name == 'pull_request'
+        run: |
+          uv run cz check --rev-range "${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
+
+      - name: Ruff check
+        run: uv run ruff check src tests scripts
+
+      - name: Ruff format
+        run: uv run ruff format --check src tests scripts
+
+      - name: ty
+        run: uv run ty check
+
+      - name: Pytest
+        run: uv run pytest

laughing_man-1.2.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish package
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/laughing-man
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

laughing_man-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,142 @@
+name: Release
+
+on:
+  push:
+    branches: [master, main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    outputs:
+      bumped: ${{ steps.bump.outputs.bumped }}
+      version: ${{ steps.release_meta.outputs.version }}
+    if: |
+      github.event_name == 'push'
+      && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main')
+      && github.event.head_commit != null
+      && !contains(github.event.head_commit.message, '[skip ci]')
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Private half of the repo Deploy key (Settings → Deploy keys). Must allow write access.
+      # Add repository secret RELEASE_DEPLOY_KEY with the full PEM (BEGIN/END lines included).
+      - name: SSH agent (deploy key)
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.RELEASE_DEPLOY_KEY }}
+
+      - name: Trust GitHub SSH host key
+        run: mkdir -p ~/.ssh && ssh-keyscan -t ed25519,rsa,ecdsa github.com >> ~/.ssh/known_hosts
+
+      - name: Use SSH for git push
+        run: git remote set-url origin "git@github.com:${GITHUB_REPOSITORY}.git"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Sync dependencies (incl. commitizen)
+        run: uv sync --group dev --python 3.12
+
+      - name: Bump version, changelog, and tag
+        id: bump
+        run: |
+          set +e
+          uv run cz bump --yes --changelog --no-verify
+          code=$?
+          set -e
+          if [ "$code" -eq 0 ]; then
+            echo "bumped=true" >> "$GITHUB_OUTPUT"
+          elif [ "$code" -eq 3 ] || [ "$code" -eq 21 ]; then
+            echo "bumped=false" >> "$GITHUB_OUTPUT"
+            echo "No release: no new commits (exit 3), or commits are not bump-eligible types like feat/fix (exit 21, e.g. docs/ci/chore only). Skipping build and push."
+          else
+            exit "$code"
+          fi
+
+      - name: Prepare release notes
+        id: release_meta
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          set -euo pipefail
+          VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          # Commitizen range PREV..NEW = commits between tags (matches tag_format v$version).
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || true)
+          if [ -n "$PREV_TAG" ]; then
+            PREV_VER="${PREV_TAG#v}"
+            uv run cz changelog "${PREV_VER}..${VERSION}" --dry-run > release_notes.md
+          else
+            uv run cz changelog "${VERSION}" --dry-run > release_notes.md
+          fi
+
+      - name: Build sdist and wheel
+        if: steps.bump.outputs.bumped == 'true'
+        run: uv build
+
+      # Only when cz bump exited 0: a release commit and vX.Y.Z tag exist locally.
+      # Exit 3/21 never create a tag, so this step is skipped — no tags pushed.
+      - name: Push release commit and tag
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          git push origin "HEAD:${{ github.ref_name }}"
+          git push origin --tags
+
+      - name: Create GitHub release
+        if: steps.bump.outputs.bumped == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.release_meta.outputs.version }}
+          body_path: release_notes.md
+          files: |
+            dist/*
+
+      - name: Upload build artifacts
+        if: steps.bump.outputs.bumped == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # Releases created with GITHUB_TOKEN do not trigger other workflows' `on: release`
+  # handlers, so PyPI publish must run in this workflow after the GitHub Release exists.
+  publish-pypi:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.bumped == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/laughing-man
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+        with:
+          ref: v${{ needs.release.outputs.version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

laughing_man-1.2.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+*.egg-info/
+dist/
+build/
+
+# Local scratch / fixture captures at repo root (avoid accidental commits)
+/*.png
+/*.jpg
+/*.jpeg
+/*.gif
+/*.webp
+/*.bmp

laughing_man-1.2.0/.python-version

@@ -0,0 +1 @@
+3.13

laughing_man-1.2.0/AGENTS.md

@@ -0,0 +1,78 @@
+# Agent and contributor notes
+
+## Cursor cloud and headless environments
+
+This is a **Python CLI** app (webcam face overlay) managed with **uv** — no Docker, databases, or external services required for development.
+
+### Quick reference
+
+| Action | Command |
+| --- | --- |
+| Install / sync deps | `uv sync --group dev` |
+| Lint (Ruff) | `uv run ruff check src tests scripts` |
+| Typecheck (ty) | `uv run ty check` |
+| Run tests | `uv run pytest` (add `-v` for verbose) |
+| CLI help | `uv run laughing-man --help` |
+| Run the app | `uv run laughing-man` (needs a webcam) |
+
+### Environment caveats
+
+- **Webcam at runtime.** The main command opens a camera (often `/dev/video0` on Linux). In a **headless cloud VM** without a camera device, run **unit tests** and **import checks** only; the live overlay loop fails when opening the camera.
+- **Model download.** BlazeFace (`.tflite`) and YuNet (`.onnx`) may be fetched to `~/.cache/laughing-man/` on first use — **network access** may be required once.
+- **`tool.uv.link-mode = "copy"`** in `pyproject.toml` avoids broken OpenCV wheels when the uv cache and `.venv` sit on different filesystems. Do not change this without a good reason.
+- **Python version.** `.python-version` pins **3.13** for local/CI convenience; `requires-python` in `pyproject.toml` remains **>=3.10** for compatibility.
+
+## Conventional commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages so history stays readable and tooling (changelog generators, semantic versioning) can work if adopted later.
+
+**Format:** `type(scope): short description`
+
+Common **types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`.
+
+**Guidelines:**
+
+- Keep the subject line in imperative mood (e.g. “add ruff config”, not “added”).
+- One logical change per commit when practical (config vs. code fixes vs. CI).
+- Use a body for non-obvious rationale or breaking changes.
+
+**Examples:**
+
+- `feat(cli): add virtual camera option`
+- `fix(overlay): correct alpha compositing on custom images`
+- `chore(dev): add ruff and ty for lint and type checking`
+
+## Planning work and commits
+
+When planning a change set, **sketch the commits in advance**: what each commit will contain and its conventional message. That reduces the risk of **partial-file staging** (`git add -p` or staging only some hunks) mixing unrelated edits in the same file, which is easy to get wrong and produces confusing history.
+
+**Practical habits:**
+
+- **Order work** so one logical concern is finished before another touches the same files, when you can.
+- If one file must hold multiple concerns, **finish and commit the first concern entirely** (or split into a separate file in a first commit), then apply the second change set.
+- Use **interactive staging** only when you are deliberately splitting a file; double-check `git diff --staged` before committing.
+
+## Linting and type checking
+
+This project uses **Ruff** for linting/formatting and **ty** (Astral) for static type checking. **ty** is chosen for speed, alignment with Ruff/uv in the Astral ecosystem, and solid diagnostics; it is configured in `pyproject.toml` under `[tool.ty]`.
+
+From the repo root (with dev dependencies installed, e.g. `uv sync --group dev`):
+
+```bash
+uv run ruff check src tests scripts
+uv run ruff format --check src tests scripts
+uv run ty check
+```
+
+Auto-fix import/order issues and apply formatting:
+
+```bash
+uv run ruff check --fix src tests scripts
+uv run ruff format src tests scripts
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```

laughing_man-1.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v1.2.0 (2026-04-12)
+
+### Feat
+
+- **cli**: add --version and centralize __version__
+
+### Fix
+
+- **test**: avoid tomllib for Python 3.10 ty compatibility
+
+## v1.1.0 (2026-04-12)
+
+### Feat
+
+- **release**: set version 1.0.0 and run commitizen in CI
+- **cli**: add postprocess command for offline image/video overlay
+- custom overlay image, scale, and chroma-key helper
+- **overlay**: terminal lambda tuning, roi horizontal smoothing, defaults
+
+### Fix
+
+- **ci**: skip release when commits are not bump-eligible (e.g. docs/ci)
+- satisfy ruff and ty checks across source and scripts

laughing_man-1.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: laughing-man
+Version: 1.2.0
+Summary: Webcam Laughing Man face overlay (MediaPipe + OpenCV + Pillow)
+Requires-Python: >=3.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mediapipe>=0.10.33
+Requires-Dist: opencv-python>=4.13.0.92
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: pyvirtualcam>=0.15.0
+Requires-Dist: typer>=0.24.1

laughing_man-1.2.0/README.md

@@ -0,0 +1,49 @@
+# laughing-man
+
+Webcam **Laughing Man** face overlay (Ghost in the Shell style) using MediaPipe BlazeFace, OpenCV, and Pillow.
+
+## Setup
+
+Install dependencies (e.g. with [uv](https://github.com/astral-sh/uv)):
+
+```bash
+uv sync
+```
+
+Run the CLI:
+
+```bash
+uv run laughing-man
+```
+
+## Virtual webcam (Discord, OBS, browsers)
+
+Use `--virtual-cam` to expose the composited video as a camera other apps can select.
+
+### Linux: v4l2loopback
+
+The virtual device is provided by the **v4l2loopback** kernel module. Load it before starting the app (often required once per boot):
+
+```bash
+sudo modprobe v4l2loopback
+```
+
+You can create a named device on a fixed number (example):
+
+```bash
+sudo modprobe v4l2loopback devices=1 video_nr=10 card_label="LaughingMan"
+```
+
+Then point the CLI at that device if needed:
+
+```bash
+laughing-man --virtual-cam --v4l2-device /dev/video10
+```
+
+Use `--no-preview` to stream only to the virtual camera (no OpenCV window); stop with Ctrl+C.
+
+Package names vary by distro (e.g. `v4l2loopback-dkms` on Debian/Ubuntu).
+
+### Other platforms
+
+On Windows and macOS, [pyvirtualcam](https://github.com/letmaik/pyvirtualcam) may use OBS Virtual Camera or other backends when available.

laughing_man-1.2.0/docs/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Laughing Man — software architecture
+
+This document describes the high-level structure of the **laughing-man** project: a Python CLI that reads a webcam, detects a face, composites a “Laughing Man” style overlay, optionally blurs the frame when no face is visible, and can mirror the result to a **virtual camera** (e.g. v4l2loopback on Linux) or an OpenCV preview window.
+
+## Technology stack
+
+| Layer | Role |
+|--------|------|
+| **Typer** | CLI (`main` command, options, validation). |
+| **OpenCV** | Webcam capture, BGR frames, optional YuNet detector, preview window, compositing helpers. |
+| **MediaPipe Tasks** | BlazeFace short/full-range TFLite models in **VIDEO** mode. |
+| **Pillow (PIL)** | Overlay artwork, alpha compositing, pre-rotated overlay cache. |
+| **pyvirtualcam** | Virtual webcam output (BGR), including Linux v4l2loopback. |
+| **loguru** | Logging; configured from the CLI `--debug` flag. |
+
+Bundled default artwork lives under `src/laughing_man/assets/` (`limg.png`, `ltext.png`). BlazeFace and YuNet model files are resolved and optionally downloaded under the XDG cache directory (see `model.py`).
+
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `src/laughing_man/` | Application package — all runtime code. |
+| `src/laughing_man/assets/` | Default PNG overlay layers shipped with the wheel. |
+| `docs/` | Design notes and proposals (e.g. `proposals/`). |
+| `scripts/` | Standalone utilities (e.g. image prep), not part of the installed CLI. |
+| `pyproject.toml` | Project metadata, dependencies, console script `laughing-man`. |
+
+## Control flow (runtime)
+
+1. **Entry** — `laughing_man:app` (see `[project.scripts]` in `pyproject.toml`) loads `laughing_man/__init__.py`, which calls `bootstrap.apply_runtime_env()` once (TensorFlow/OpenCV/Qt log noise, Linux Qt hints), then exposes the Typer `app` from `cli.py`.
+2. **CLI** — `cli.main()` configures logging (`logging_setup.configure_logging`) and calls `run.run_overlay(...)` with parsed options.
+3. **Orchestration** — `run.run_overlay()` opens the webcam (`camera.open_webcam`), loads overlay images (`overlay.load_overlay_images`), ensures detector models exist (`model.ensure_*`), builds a **FaceBoxSource** (BlazeFace or YuNet, optionally wrapped for cascade), starts a **background thread** to prefill the rotated overlay cache, then runs the **capture loop**: read frame → `face_source.face_box(...)` → `roi.smooth_and_draw(...)` → optional `pyvirtualcam` send and/or OpenCV preview.
+
+```mermaid
+flowchart LR
+  subgraph entry [Entry]
+    Init["__init__.py\nbootstrap + app"]
+    CLI["cli.py\nTyper"]
+  end
+  subgraph core [Pipeline]
+    Run["run.py\nrun_overlay"]
+    Cam["camera.py"]
+    Det["FaceBoxSource\ndetection / cascade"]
+    ROI["roi.py\nsmooth_and_draw"]
+    VC["pyvirtualcam\noptional"]
+    Prev["OpenCV preview\noptional"]
+  end
+  Init --> CLI
+  CLI --> Run
+  Run --> Cam
+  Run --> Det
+  Run --> ROI
+  ROI --> VC
+  ROI --> Prev
+```
+
+## Module map (`src/laughing_man/`)
+
+Use this table to find responsibilities and jump to the right file.
+
+| Module | Responsibility |
+|--------|----------------|
+| **`__init__.py`** | Applies `bootstrap` before other imports; exports Typer `app`. |
+| **`bootstrap.py`** | Process environment defaults (`TF_CPP_MIN_LOG_LEVEL`, Qt on Linux, etc.). |
+| **`cli.py`** | Typer application: flags for detector, ROI tuning, virtual camera, overlay image, `--debug`. |
+| **`run.py`** | Main orchestration: webcam, model setup, overlay cache prefill thread, capture loop, virtual camera lifecycle. |
+| **`constants.py`** | Tunables: camera index, detection thresholds, ROI/overlay factors, key codes for tuning, default lambdas. |
+| **`protocols.py`** | Structural typing: `FaceBoxSource` (raw `(x,y,w,h)` per frame), `PrivacyEffect` (full-frame effect when privacy engages). |
+| **`deps.py`** | `PipelineDeps` — injectable implementations (e.g. privacy backend) for a run. |
+| **`camera.py`** | `open_webcam` and user-facing error messages when capture fails. |
+| **`model.py`** | BlazeFace / YuNet path resolution, cache dir, optional HTTP download. |
+| **`detection.py`** | BlazeFace: `FaceDetectorOptions`, `mediapipe_detect_face`, `BlazeFaceFaceBoxSource`. |
+| **`yunet_face.py`** | OpenCV `FaceDetectorYN` (YuNet): `create_yunet_detector`, `YuNetFaceBoxSource`. |
+| **`cascade.py`** | `CascadedFaceBoxSource` — expands the previous smoothed ROI and runs the inner detector on a crop first (YuNet-oriented); crop/box math helpers. |
+| **`roi.py`** | `RoiState`, temporal smoothing (**EMA**, **Kalman**, **Kalman + optical flow**), compositing the square overlay onto the face ROI, privacy debounce and `PrivacyEffect` application. |
+| **`box_tracking.py`** | `BoxKalman` (OpenCV Kalman on center/size) and optical-flow helper used by Kalman-flow ROI mode. |
+| **`overlay.py`** | Load bundled or custom overlay images; `build_rotated_overlay_frame`; square resize for the cache. |
+| **`privacy.py`** | `GaussianBlurPrivacy` — full-frame blur blended by strength. |
+| **`tuning.py`** | Interactive adjustment of `roi_lambda` / `size_lambda` via OpenCV keys or stdin (when TTY available). |
+| **`logging_setup.py`** | Single stderr sink for loguru; level from `--debug`. |
+
+**Face detection is intentionally pluggable:** anything implementing `FaceBoxSource` can supply `(x, y, w, h)` or `None`. BlazeFace uses MediaPipe VIDEO timestamps; YuNet ignores timestamps; cascade wraps another `FaceBoxSource` and uses shared `RoiState` from `smooth_and_draw`.
+
+## Data flow (one frame)
+
+1. **Input** — BGR `numpy` array from `VideoCapture.read()`.
+2. **Detection** — Selected backend returns the largest face box above minimum size (see `constants.MIN_FACE_SIZE`), or `None`.
+3. **Stabilization** — `roi.smooth_and_draw` updates `RoiState` using the chosen motion model, applies optional EMA on center/size, and composites the **pre-sized** RGB overlay and mask onto the face region.
+4. **Privacy** — After a streak of no-face frames, the pipeline increases blur via `PipelineDeps.privacy` (`GaussianBlurPrivacy` by default).
+5. **Output** — The same BGR frame is sent to the virtual camera (if enabled) and/or shown in a named OpenCV window; the rotating overlay angle advances each frame for the stock two-layer artwork.
+
+## External dependencies (conceptual)
+
+- **Webcam** — System video device (index from `constants.CAMERA_INDEX`, typically `0`).
+- **Virtual camera** — OS-specific: on Linux, **v4l2loopback** provides a `/dev/video*` sink that `pyvirtualcam` writes to; see `README.md` for `modprobe` examples.
+- **Models** — BlazeFace TFLite (short vs full range) and YuNet ONNX URLs/paths are centralized in `constants.py` / `model.py`; overrides via environment variables where documented in code.
+
+## Related documentation
+
+- **`README.md`** — Install, run, virtual webcam setup.
+- **`docs/proposals/`** — Exploratory design write-ups (not necessarily implemented).
+
+## Extension points (for contributors)
+
+- **New detector** — Implement `FaceBoxSource` in a new module and wire it in `run.py` similarly to `BlazeFaceFaceBoxSource` / `YuNetFaceBoxSource`.
+- **New privacy effect** — Implement `PrivacyEffect` and pass it in `PipelineDeps` (today `run.py` constructs `GaussianBlurPrivacy()` directly; wiring could be generalized if needed).
+- **ROI behavior** — `roi.smooth_and_draw` and `RoiState` encapsulate motion models; `box_tracking.py` holds Kalman/optical-flow primitives.