# PyLipExtractor
PyLipExtractor is a powerful and easy-to-use Python package for extracting lip regions from videos. It leverages the high-precision MediaPipe Face Mesh to accurately detect and crop the lip area, providing a stable and reliable tool for researchers and developers working on lip-reading, facial analysis, and other related fields.
For detailed information about the package, its features, and how to use them, please refer to the [**Full Documentation**](DOCUMENTATION.md).
## Key Features
- **Accurate & Stable Lip Detection:** Utilizes MediaPipe Face Mesh for precise landmark detection.
- **Temporal Smoothing:** Applies an Exponential Moving Average (EMA) filter for smooth and consistent lip crops.
- **Illumination Normalization:** Includes an optional histogram matching filter to normalize video brightness.
- **Flexible Configuration:** Offers a wide range of customizable settings.
- **Customizable Hardware Acceleration:** Choose your preferred processing device (`auto`, `cuda`, or `cpu`) for video conversion. The package leverages NVIDIA GPU acceleration (if available) for faster processing and uses lossless compression to ensure no quality is lost.
## Demo
https://github.com/user-attachments/assets/a6841309-3e4d-4b7e-bd0f-b56a5cab28e4
*Original video by Tima Miroshnichenko*
## Installation
```bash
pip install pylipextractor
```
## Quick Start
Here is a basic example of how to use PyLipExtractor. For a more detailed and comprehensive example, please see `examples/example_usage.py`.
```python
from pylipextractor.lip_extractor import LipExtractor
# Create a LipExtractor instance
extractor = LipExtractor()
# Specify the path to your video
video_path = "path/to/your/video.mp4"
output_path = "output/lip_frames.npy"
# Extract the lip frames
extracted_frames, rtf_value = extractor.extract_lip_frames(video_path, output_path)
if extracted_frames is not None:
print(f"Successfully extracted {len(extracted_frames)} frames.")
if rtf_value is not None:
print(f"Real-Time Factor (RTF): {rtf_value:.4f}")
```
## Documentation
For a deep dive into all the features, configurations, and technical details, please read our [**Comprehensive Documentation**](DOCUMENTATION.md).
## Contributing
Contributions are welcome! Please see our [Contributing Guidelines](https://github.com/MehradYaghoubi/pylipextractor/blob/main/CONTRIBUTING.md) for more details.
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/MehradYaghoubi/pylipextractor/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pylipextractor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "lip-extraction, visual-speech-recognition, mediapipe, video-processing, lip-reading, ffmpeg, video-conversion, documentation, examples",
"author": null,
"author_email": "Mehrad Yaghoubi <mehradyaghoubi96@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/55/3e/866ad205afd7ad5547bb40f870571a98e9576266d5327fa3eb52f267ecee/pylipextractor-2.2.2.tar.gz",
"platform": null,
"description": "# PyLipExtractor\r\n\r\nPyLipExtractor is a powerful and easy-to-use Python package for extracting lip regions from videos. It leverages the high-precision MediaPipe Face Mesh to accurately detect and crop the lip area, providing a stable and reliable tool for researchers and developers working on lip-reading, facial analysis, and other related fields.\r\n\r\nFor detailed information about the package, its features, and how to use them, please refer to the [**Full Documentation**](DOCUMENTATION.md).\r\n\r\n## Key Features\r\n\r\n- **Accurate & Stable Lip Detection:** Utilizes MediaPipe Face Mesh for precise landmark detection.\r\n- **Temporal Smoothing:** Applies an Exponential Moving Average (EMA) filter for smooth and consistent lip crops.\r\n- **Illumination Normalization:** Includes an optional histogram matching filter to normalize video brightness.\r\n- **Flexible Configuration:** Offers a wide range of customizable settings.\r\n- **Customizable Hardware Acceleration:** Choose your preferred processing device (`auto`, `cuda`, or `cpu`) for video conversion. The package leverages NVIDIA GPU acceleration (if available) for faster processing and uses lossless compression to ensure no quality is lost.\r\n\r\n## Demo\r\n\r\nhttps://github.com/user-attachments/assets/a6841309-3e4d-4b7e-bd0f-b56a5cab28e4\r\n\r\n*Original video by Tima Miroshnichenko*\r\n\r\n## Installation\r\n\r\n```bash\r\npip install pylipextractor\r\n```\r\n\r\n## Quick Start\r\n\r\nHere is a basic example of how to use PyLipExtractor. For a more detailed and comprehensive example, please see `examples/example_usage.py`.\r\n\r\n```python\r\nfrom pylipextractor.lip_extractor import LipExtractor\r\n\r\n# Create a LipExtractor instance\r\nextractor = LipExtractor()\r\n\r\n# Specify the path to your video\r\nvideo_path = \"path/to/your/video.mp4\"\r\noutput_path = \"output/lip_frames.npy\"\r\n\r\n# Extract the lip frames\r\nextracted_frames, rtf_value = extractor.extract_lip_frames(video_path, output_path)\r\n\r\nif extracted_frames is not None:\r\n print(f\"Successfully extracted {len(extracted_frames)} frames.\")\r\n if rtf_value is not None:\r\n print(f\"Real-Time Factor (RTF): {rtf_value:.4f}\")\r\n```\r\n\r\n## Documentation\r\n\r\nFor a deep dive into all the features, configurations, and technical details, please read our [**Comprehensive Documentation**](DOCUMENTATION.md).\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please see our [Contributing Guidelines](https://github.com/MehradYaghoubi/pylipextractor/blob/main/CONTRIBUTING.md) for more details.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/MehradYaghoubi/pylipextractor/blob/main/LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for robust lip frame extraction from videos using MediaPipe, featuring enhanced stability, configurable options, and customizable GPU-accelerated lossless video format conversion for VSR tasks.",
"version": "2.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/MehradYaghoubi/pylipextractor/issues",
"Homepage": "https://github.com/MehradYaghoubi/pylipextractor"
},
"split_keywords": [
"lip-extraction",
" visual-speech-recognition",
" mediapipe",
" video-processing",
" lip-reading",
" ffmpeg",
" video-conversion",
" documentation",
" examples"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "078d3c57dee8637ae8fd64d947998c456460522e9b4f8893a41191e8769a093d",
"md5": "2f38079e6f2f42975c240e75b6c9da9a",
"sha256": "cd9a56d2adada7b2f929f862dcb9778c6f3d45a8f601c5c916a583fb39a4e3ba"
},
"downloads": -1,
"filename": "pylipextractor-2.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f38079e6f2f42975c240e75b6c9da9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15462,
"upload_time": "2025-07-26T19:08:10",
"upload_time_iso_8601": "2025-07-26T19:08:10.826591Z",
"url": "https://files.pythonhosted.org/packages/07/8d/3c57dee8637ae8fd64d947998c456460522e9b4f8893a41191e8769a093d/pylipextractor-2.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "553e866ad205afd7ad5547bb40f870571a98e9576266d5327fa3eb52f267ecee",
"md5": "40d9eaf6889e98d86e60e167504a1370",
"sha256": "55171bfd4d4605a4795f681adb227df3de1dce6804eccd1356737eaa5af32667"
},
"downloads": -1,
"filename": "pylipextractor-2.2.2.tar.gz",
"has_sig": false,
"md5_digest": "40d9eaf6889e98d86e60e167504a1370",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16198,
"upload_time": "2025-07-26T19:08:12",
"upload_time_iso_8601": "2025-07-26T19:08:12.459217Z",
"url": "https://files.pythonhosted.org/packages/55/3e/866ad205afd7ad5547bb40f870571a98e9576266d5327fa3eb52f267ecee/pylipextractor-2.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 19:08:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MehradYaghoubi",
"github_project": "pylipextractor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pylipextractor"
}
JSON
