Pypi Packaging

.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - releases/*
+    tags:
+      - "v*.*.*"
+  pull_request:
+    branches:
+      - main
+      - releases/*
+
+  workflow_dispatch:
+
+env:
+  PYTORCH_VERSION: "2.7"
+
+jobs:
+  build_and_test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('**/requirements.txt', '**/requirements-dev.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg libsm6 libxext6 libfontconfig1 libxrender1
+          # Install audio libraries for pydub
+          sudo apt-get install -y libavcodec-extra
+          pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew update 
+          brew install ffmpeg
+          pip3 install torch torchvision torchaudio
+
+      - name: Install dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # Install ffmpeg using chocolatey 
+          choco install -y ffmpeg
+          # Add ffmpeg to PATH 
+          echo "C:\ProgramData\chocolatey\lib\ffmpeg\tools\ffmpeg\bin" >> $GITHUB_PATH
+          # Install wget
+          choco install -y wget
+          pip3 install torch torchvision torchaudio
+
+      - name: Upgrade pip and dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel        
+          pip install -e .[dev]
+
+      - name: Lint with flake8
+        run: |
+          flake8 src/ tests/
+
+      - name: Format code with black
+        run: |
+          black --check src/ tests/
+
+      # Will implement type checking later
+      # - name: Run type checks with mypy
+      #   run: |
+      #     mypy --install-types --non-interactive --ignore-missing-imports
+      #     mypy src/
+      - name: Run tests
+        run: |
+          pytest --cov=captionalchemy -v
+
+  publish:
+    needs: build_and_test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/captionalchemy
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,10 +1,17 @@
 venv
 .venv
 __pycache__
+.mypy_cache
+captionalchemy.egg-info
+.pytest_cache
 
 *.env
-
+.env
 
 # Whisper 
 whisper.cpp
 /whisper.cpp
+
+# Coverage
+.coverage
+.coverage.*

CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CaptionAlchemy is a Python package for creating closed captions with face detection and recognition. It combines audio transcription, speaker diarization, and facial recognition to generate accurate subtitles with speaker identification.
+
+## Architecture
+
+The package follows a modular structure under `src/captionalchemy/`:
+
+- **Main Pipeline**: `caption.py` - Core orchestration of the caption generation process
+- **Audio Analysis**: `tools/audio_analysis/` - Voice activity detection, speaker diarization, and non-speech detection
+- **Captioning**: `tools/captioning/` - Whisper transcription, timing analysis, and output writers (SRT, VTT, SAMI)
+- **Computer Vision**: `tools/cv/` - Face embedding and recognition for speaker identification
+- **Media Utils**: `tools/media_utils/` - Video download and audio extraction utilities
+
+## Key Components
+
+### Core Pipeline Flow
+
+1. Embed known faces from JSON configuration
+2. Download/extract audio from video
+3. Run Voice Activity Detection (VAD) and speaker diarization
+4. Transcribe audio segments with Whisper
+5. Identify speakers using facial recognition
+6. Generate timestamped captions in chosen format
+
+### Dependencies
+
+- **Audio Processing**: pyannote.audio, pydub, librosa, openai-whisper
+- **Computer Vision**: opencv-python, insightface, onnxruntime
+- **Deep Learning**: Uses CUDA when available, falls back to CPU
+
+## Development Commands
+
+### Installation
+
+```bash
+pip install -e .
+```
+
+### Testing
+
+```bash
+pytest
+```
+
+### Linting
+
+```bash
+flake8
+mypy src/
+```
+
+### Running the Package
+
+```bash
+captionalchemy <video_path_or_url> -f srt -o output_captions
+```
+
+## Configuration
+
+- **Environment**: Uses `.env` file for configuration (HF_AUTH_TOKEN for Hugging Face models)
+- **Face Recognition**: Requires `known_faces.json`. `embed_faces.json` is an artifact generated.
+- **Whisper**: Integrates with whisper.cpp for transcription (requires models in `whisper.cpp/models/`)
+
+## External Dependencies
+
+- Whisper.cpp integration for transcription
+- Hugging Face models for audio analysis
+- ONNX runtime for face recognition models
+
+## Code Style
+
+- Line length: 110 characters (flake8 configured)
+- Python 3.10+ compatible
+- Type hints encouraged