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):
git clone https://github.com/Parhamfakhar1/lipreader.git
cd lipreader
pip install -e .
Requires: Python 3.7+, OpenCV, NumPy
🚀 Usage
Train a new command
lipreader train --video start.mp4 --word start
You can train the same word multiple times with different videos:
lipreader train -v start1.mp4 -w start
lipreader train -v start2.mp4 -w start
Predict from a video
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:
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:
{
"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
Metadata
Release files for lipreader 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lipreader-0.1.0.tar.gz | 5.9 kB | Without provenance | Details for lipreader-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lipreader-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for lipreader-0.1.0-py3-none-any.whl |
Total release size: 12.4 kB
Release files / lipreader-0.1.0.tar.gz
| Download URL | lipreader-0.1.0.tar.gz |
|---|---|
| Size | 5.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
617c3b9220310eee692794afb1066c0d3d4718db20f8c857e1853b7c11fb3987
|
|
BLAKE2b-256 checksum How to use checksums |
cee30ca26e45e6390683153eb6a08cd0bec7cef42d810d82afb93ff7aaea5f3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.0
|
Release files / lipreader-0.1.0-py3-none-any.whl
| Download URL | lipreader-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e9a5059ab9ddd180f5839ce10a5126114935d02117339771673829286706144
|
|
BLAKE2b-256 checksum How to use checksums |
654e8784b0fc07c63132c257e280bd8da9ee2926955edabba4b6789f49864cb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.0
|
Security for lipreader 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.