lipreader 0.1.0__tar.gz

lipreader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parham Fakhari
+
+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.

lipreader-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include requirements.txt

lipreader-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: lipreader
+Version: 0.1.0
+Summary: A CPU-only lip reading toolkit for command recognition from video
+Home-page: https://github.com/parhamfakhar1/lipreader
+Author: Parham Fakhari
+Author-email: parhamfakhari.nab2020@gmail.com
+License: MIT
+Project-URL: Bug Tracker, https://github.com/parhamfakhar1/lipreader/issues
+Project-URL: Source Code, https://github.com/parhamfakhar1/lipreader
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+
+# LipReader
+
+A lightweight, CPU-only lip reading toolkit for command recognition from video.  
+No GPU required — runs efficiently on Intel i5 and similar systems.
+
+## ✨ Features
+
+- **CPU-only**: No GPU or deep learning dependencies.
+- **CLI & API**: Use via command line or import as a Python library.
+- **Trainable**: Learn custom lip motion patterns from your own videos.
+- **JSON-based**: All data stored in human-readable JSON format.
+- **Real-time ready**: Optimized for low-latency inference.
+
+## 📦 Installation
+
+Install in development mode (recommended):
+
+```bash
+git clone https://github.com/Parhamfakhar1/lipreader.git
+cd lipreader
+pip install -e .
+```
+
+> Requires: Python 3.7+, OpenCV, NumPy
+
+## 🚀 Usage
+
+### Train a new command
+
+```bash
+lipreader train --video start.mp4 --word start
+```
+
+You can train the same word multiple times with different videos:
+
+```bash
+lipreader train -v start1.mp4 -w start
+lipreader train -v start2.mp4 -w start
+```
+
+### Predict from a video
+
+```bash
+lipreader predict --video test.mp4
+```
+
+**Sample output:**
+```
+🎯 Prediction: start
+
+📈 Probabilities:
+   start: 86.3%
+   stop: 13.7%
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `-v`, `--video` | Path to input video (MP4, AVI, etc.) |
+| `-w`, `--word` | Label for training (e.g., "start", "stop") |
+| `-d`, `--data` | Path to JSON data file (default: `lip_data.json`) |
+
+## 💻 Python API
+
+Use `LipReader` directly in your code:
+
+```python
+from lipreader import LipReader
+
+# Initialize
+reader = LipReader("commands.json")
+
+# Train
+reader.train("start.mp4", "start")
+
+# Predict
+predicted_word, probabilities = reader.predict("unknown.mp4")
+print(f"Detected: {predicted_word}")
+```
+
+## 🗃️ Data Format
+
+All trained patterns are saved in `lip_data.json`:
+
+```json
+{
+  "start": {
+    "samples": [
+      {
+        "avg_ratio": 1.28,
+        "ratio_std": 0.25,
+        "min_ratio": 0.78,
+        "max_ratio": 1.88,
+        "frame_count": 120,
+        "video": "start1.mp4"
+      }
+    ]
+  }
+}
+```
+
+## ⚠️ Limitations
+
+- Works best in **good lighting** with **front-facing video**.
+- Accuracy depends on **clear lip motion** (silent articulation works).
+- Not designed for full-sentence lip reading — optimized for **short commands**.
+
+## 📄 License
+
+MIT License
+```

lipreader-0.1.0/README.md

@@ -0,0 +1,113 @@
+
+# LipReader
+
+A lightweight, CPU-only lip reading toolkit for command recognition from video.  
+No GPU required — runs efficiently on Intel i5 and similar systems.
+
+## ✨ Features
+
+- **CPU-only**: No GPU or deep learning dependencies.
+- **CLI & API**: Use via command line or import as a Python library.
+- **Trainable**: Learn custom lip motion patterns from your own videos.
+- **JSON-based**: All data stored in human-readable JSON format.
+- **Real-time ready**: Optimized for low-latency inference.
+
+## 📦 Installation
+
+Install in development mode (recommended):
+
+```bash
+git clone https://github.com/Parhamfakhar1/lipreader.git
+cd lipreader
+pip install -e .
+```
+
+> Requires: Python 3.7+, OpenCV, NumPy
+
+## 🚀 Usage
+
+### Train a new command
+
+```bash
+lipreader train --video start.mp4 --word start
+```
+
+You can train the same word multiple times with different videos:
+
+```bash
+lipreader train -v start1.mp4 -w start
+lipreader train -v start2.mp4 -w start
+```
+
+### Predict from a video
+
+```bash
+lipreader predict --video test.mp4
+```
+
+**Sample output:**
+```
+🎯 Prediction: start
+
+📈 Probabilities:
+   start: 86.3%
+   stop: 13.7%
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `-v`, `--video` | Path to input video (MP4, AVI, etc.) |
+| `-w`, `--word` | Label for training (e.g., "start", "stop") |
+| `-d`, `--data` | Path to JSON data file (default: `lip_data.json`) |
+
+## 💻 Python API
+
+Use `LipReader` directly in your code:
+
+```python
+from lipreader import LipReader
+
+# Initialize
+reader = LipReader("commands.json")
+
+# Train
+reader.train("start.mp4", "start")
+
+# Predict
+predicted_word, probabilities = reader.predict("unknown.mp4")
+print(f"Detected: {predicted_word}")
+```
+
+## 🗃️ Data Format
+
+All trained patterns are saved in `lip_data.json`:
+
+```json
+{
+  "start": {
+    "samples": [
+      {
+        "avg_ratio": 1.28,
+        "ratio_std": 0.25,
+        "min_ratio": 0.78,
+        "max_ratio": 1.88,
+        "frame_count": 120,
+        "video": "start1.mp4"
+      }
+    ]
+  }
+}
+```
+
+## ⚠️ Limitations
+
+- Works best in **good lighting** with **front-facing video**.
+- Accuracy depends on **clear lip motion** (silent articulation works).
+- Not designed for full-sentence lip reading — optimized for **short commands**.
+
+## 📄 License
+
+MIT License
+```

lipreader-0.1.0/lipreader/__init__.py

@@ -0,0 +1,3 @@
+from .core import LipReader
+
+__version__ = "0.1.0"

lipreader-0.1.0/lipreader/cli.py

@@ -0,0 +1,45 @@
+import argparse
+import sys
+from .core import LipReader
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Lip Reading CLI — Train and predict lip motion patterns.",
+        prog="lipreader"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Train command
+    train_parser = subparsers.add_parser("train", help="Train a word from video")
+    train_parser.add_argument("--video", "-v", required=True, help="Input video path")
+    train_parser.add_argument("--word", "-w", required=True, help="Target word/label")
+    train_parser.add_argument("--data", "-d", default="lip_data.json", help="Data file")
+
+    # Predict command
+    pred_parser = subparsers.add_parser("predict", help="Predict word from video")
+    pred_parser.add_argument("--video", "-v", required=True, help="Test video path")
+    pred_parser.add_argument("--data", "-d", default="lip_data.json", help="Data file")
+
+    args = parser.parse_args()
+
+    try:
+        reader = LipReader(args.data)
+
+        if args.command == "train":
+            stats = reader.train(args.video, args.word)
+            print(f"✅ Trained word '{args.word}'")
+            print(f"   Avg Ratio: {stats['avg_ratio']:.2f} ± {stats['ratio_std']:.2f}")
+
+        elif args.command == "predict":
+            pred, probs = reader.predict(args.video)
+            if pred is None:
+                print("⚠️ No match found.")
+                sys.exit(1)
+            print(f"🎯 Prediction: {pred}")
+            print("\n📈 Probabilities:")
+            for w in sorted(probs, key=probs.get, reverse=True):
+                print(f"   {w}: {probs[w]:.1f}%")
+
+    except Exception as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        sys.exit(1)

lipreader-0.1.0/lipreader/core.py

@@ -0,0 +1,104 @@
+import cv2
+import numpy as np
+import json
+import os
+
+class LipReader:
+    def __init__(self, data_path="lip_data.json"):
+        self.data_path = data_path
+        self.face_cascade = cv2.CascadeClassifier(
+            cv2.data.haarcascades + 'haarcascade_frontalface_default.xml'
+        )
+        if self.face_cascade.empty():
+            raise RuntimeError("Failed to load Haar Cascade classifier.")
+
+    def extract_lip_ratio(self, frame, x, y, w, h):
+        face_roi = frame[y:y + h, x:x + w]
+        if face_roi.size == 0:
+            return None
+        gray = cv2.cvtColor(face_roi, cv2.COLOR_BGR2GRAY)
+        _, thresh = cv2.threshold(gray, 60, 255, cv2.THRESH_BINARY_INV)
+        kernel = np.ones((3, 3), np.uint8)
+        thresh = cv2.morphologyEx(thresh, cv2.MORPH_CLOSE, kernel)
+        thresh = cv2.morphologyEx(thresh, cv2.MORPH_OPEN, kernel)
+        contours, _ = cv2.findContours(thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        if contours:
+            largest = max(contours, key=cv2.contourArea)
+            if cv2.contourArea(largest) > 100:
+                x_l, y_l, w_l, h_l = cv2.boundingRect(largest)
+                return w_l / (h_l + 1e-6)
+        return None
+
+    def process_video(self, video_path):
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise FileNotFoundError(f"Cannot open video: {video_path}")
+        ratios = []
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+            gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+            faces = self.face_cascade.detectMultiScale(gray, 1.3, 5)
+            if len(faces) > 0:
+                x, y, w, h = max(faces, key=lambda r: r[2] * r[3])
+                ratio = self.extract_lip_ratio(frame, x, y, w, h)
+                if ratio is not None:
+                    ratios.append(ratio)
+        cap.release()
+        if not ratios:
+            raise ValueError("No lip region detected in video.")
+        return {
+            "avg_ratio": float(np.mean(ratios)),
+            "ratio_std": float(np.std(ratios)),
+            "min_ratio": float(np.min(ratios)),
+            "max_ratio": float(np.max(ratios)),
+            "frame_count": len(ratios)
+        }
+
+    def load_data(self):
+        if os.path.exists(self.data_path):
+            with open(self.data_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        return {}
+
+    def save_data(self, data):
+        with open(self.data_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    def train(self, video_path, word):
+        stats = self.process_video(video_path)
+        stats["video"] = os.path.basename(video_path)
+        data = self.load_data()
+        if word not in data:
+            data[word] = {"samples": [stats]}
+        else:
+            data[word]["samples"].append(stats)
+        self.save_data(data)
+        return stats
+
+    def predict(self, video_path):
+        test_stats = self.process_video(video_path)
+        data = self.load_data()
+        if not data:
+            raise ValueError("No trained words found. Train first with `.train()`.")
+
+        def similarity(test_avg, test_std, sample):
+            dist = abs(test_avg - sample["avg_ratio"])
+            std_diff = abs(test_std - sample["ratio_std"])
+            return max(0, 1.0 - (dist / 2.0) - (std_diff / 1.0))
+
+        scores = {}
+        for word, word_data in data.items():
+            score = np.mean([
+                similarity(test_stats["avg_ratio"], test_stats["ratio_std"], s)
+                for s in word_data["samples"]
+            ])
+            scores[word] = score
+
+        total = sum(scores.values())
+        if total == 0:
+            return None, {}
+        probabilities = {w: (s / total) * 100 for w, s in scores.items()}
+        prediction = max(probabilities, key=probabilities.get)
+        return prediction, probabilities

lipreader-0.1.0/lipreader.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: lipreader
+Version: 0.1.0
+Summary: A CPU-only lip reading toolkit for command recognition from video
+Home-page: https://github.com/parhamfakhar1/lipreader
+Author: Parham Fakhari
+Author-email: parhamfakhari.nab2020@gmail.com
+License: MIT
+Project-URL: Bug Tracker, https://github.com/parhamfakhar1/lipreader/issues
+Project-URL: Source Code, https://github.com/parhamfakhar1/lipreader
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+
+# LipReader
+
+A lightweight, CPU-only lip reading toolkit for command recognition from video.  
+No GPU required — runs efficiently on Intel i5 and similar systems.
+
+## ✨ Features
+
+- **CPU-only**: No GPU or deep learning dependencies.
+- **CLI & API**: Use via command line or import as a Python library.
+- **Trainable**: Learn custom lip motion patterns from your own videos.
+- **JSON-based**: All data stored in human-readable JSON format.
+- **Real-time ready**: Optimized for low-latency inference.
+
+## 📦 Installation
+
+Install in development mode (recommended):
+
+```bash
+git clone https://github.com/Parhamfakhar1/lipreader.git
+cd lipreader
+pip install -e .
+```
+
+> Requires: Python 3.7+, OpenCV, NumPy
+
+## 🚀 Usage
+
+### Train a new command
+
+```bash
+lipreader train --video start.mp4 --word start
+```
+
+You can train the same word multiple times with different videos:
+
+```bash
+lipreader train -v start1.mp4 -w start
+lipreader train -v start2.mp4 -w start
+```
+
+### Predict from a video
+
+```bash
+lipreader predict --video test.mp4
+```
+
+**Sample output:**
+```
+🎯 Prediction: start
+
+📈 Probabilities:
+   start: 86.3%
+   stop: 13.7%
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `-v`, `--video` | Path to input video (MP4, AVI, etc.) |
+| `-w`, `--word` | Label for training (e.g., "start", "stop") |
+| `-d`, `--data` | Path to JSON data file (default: `lip_data.json`) |
+
+## 💻 Python API
+
+Use `LipReader` directly in your code:
+
+```python
+from lipreader import LipReader
+
+# Initialize
+reader = LipReader("commands.json")
+
+# Train
+reader.train("start.mp4", "start")
+
+# Predict
+predicted_word, probabilities = reader.predict("unknown.mp4")
+print(f"Detected: {predicted_word}")
+```
+
+## 🗃️ Data Format
+
+All trained patterns are saved in `lip_data.json`:
+
+```json
+{
+  "start": {
+    "samples": [
+      {
+        "avg_ratio": 1.28,
+        "ratio_std": 0.25,
+        "min_ratio": 0.78,
+        "max_ratio": 1.88,
+        "frame_count": 120,
+        "video": "start1.mp4"
+      }
+    ]
+  }
+}
+```
+
+## ⚠️ Limitations
+
+- Works best in **good lighting** with **front-facing video**.
+- Accuracy depends on **clear lip motion** (silent articulation works).
+- Not designed for full-sentence lip reading — optimized for **short commands**.
+
+## 📄 License
+
+MIT License
+```

lipreader-0.1.0/lipreader.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+requirements.txt
+setup.py
+lipreader/__init__.py
+lipreader/cli.py
+lipreader/core.py
+lipreader/utils.py
+lipreader.egg-info/PKG-INFO
+lipreader.egg-info/SOURCES.txt
+lipreader.egg-info/dependency_links.txt
+lipreader.egg-info/entry_points.txt
+lipreader.egg-info/top_level.txt

lipreader-0.1.0/lipreader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lipreader-0.1.0/lipreader.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lipreader = lipreader.cli:main

lipreader-0.1.0/lipreader.egg-info/top_level.txt

@@ -0,0 +1 @@
+lipreader

lipreader-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lipreader-0.1.0/setup.py

@@ -0,0 +1,51 @@
+from setuptools import setup, find_packages
+import os
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+def read_requirements():
+    if os.path.exists("requirements.txt"):
+        with open("requirements.txt", "r", encoding="utf-8") as f:
+            return [line.strip() for line in f if line.strip() and not line.startswith("#")]
+    return ["opencv-python", "numpy"]
+
+setup(
+    name="lipreader",
+    version="0.1.0",
+    author="Parham Fakhari",
+    author_email="parhamfakhari.nab2020@gmail.com",
+    description="A CPU-only lip reading toolkit for command recognition from video",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/parhamfakhar1/lipreader",
+    project_urls={
+        "Bug Tracker": "https://github.com/parhamfakhar1/lipreader/issues",
+        "Source Code": "https://github.com/parhamfakhar1/lipreader",
+    },
+    license="MIT",
+    packages=find_packages(),
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Multimedia :: Video",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+    python_requires=">=3.7",
+    install_requires=read_requirements(),
+    entry_points={
+        "console_scripts": [
+            "lipreader=lipreader.cli:main",
+        ],
+    },
+    include_package_data=True,
+)