Merge pull request #9 from mowshon/Refactoring

Code refactoring - Python 3.12

Author: mowshon

.gitignore

@@ -127,4 +127,15 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
-.idea/
+.idea/
+
+/*.mp3
+/*.mp4
+/*.wav
+/weights
+/*.png
+/cache
+/example.py
+/*.pth
+/test_*.py
+/source

MANIFEST.in

@@ -1,50 +1,87 @@
-# LipSync
-Lips Synchronization (Wav2Lip).
+# lipsync
 
-## Install
-```
-git clone git@github.com:mowshon/lipsync.git
-cd lipsync
-python setup.py install
-```
+lipsync is a Python library that moves lips in a video (or image) to match a given audio file. It is based on [Wav2Lip](https://github.com/Rudrabha/Wav2Lip), but many unneeded files and libraries have been removed, and the code has been updated to work with the latest versions of Python.
 
-Download the weights
-----------
-| Model  | Description |  Link to the model | 
-| :-------------: | :---------------: | :---------------: |
-| Wav2Lip  | Highly accurate lip-sync | [Link](https://iiitaphyd-my.sharepoint.com/:u:/g/personal/radrabha_m_research_iiit_ac_in/Eb3LEzbfuKlJiR600lQWRxgBIY27JZg80f7V9jtMfbNDaQ?e=TBFBVW)  |
-| Wav2Lip + GAN  | Slightly inferior lip-sync, but better visual quality | [Link](https://iiitaphyd-my.sharepoint.com/:u:/g/personal/radrabha_m_research_iiit_ac_in/EdjI7bZlgApMqsVoEUUXpLsBxqXbn5z8VTmoxp55YNDcIA?e=n9ljGW) |
+---
 
-### Project structure
-```
-└── project-folder
-   ├── cache/
-   ├── main.py
-   ├── wav2lip.pth
-   ├── face.mp4
-   └── audio.wav
+## Features
+
+- **Video lip synchronization**  
+  Synchronize lips in an existing video to match a new audio file.
+
+- **Image lip animation**  
+  Provide a single image and an audio file to generate a talking video.
+
+- **Runs on CPU and CUDA**  
+  You can choose whether to run on your CPU or a CUDA-enabled GPU for faster processing.
+
+- **Caching**  
+  If you use the same video multiple times with different audio files, lipsync can cache frames and reuse them. This makes future runs much faster.
+
+---
+
+## Pre-Trained Weights
+
+lipsync works with two different pre-trained models:
+
+1. **Wav2Lip ([Download wav2lip.pth](https://drive.google.com/file/d/1qKU8HG8dR4nW4LvCqpEYmSy6LLpVkZ21/view?usp=sharing))**  
+   - More accurate lip synchronization  
+   - Lips in the result may appear somewhat blurred
+
+2. **Wav2Lip + GAN ([Download wav2lip_gan.pth](https://drive.google.com/file/d/13Ktexq-nZOsAxqrTdMh3Q0ntPB3yiBtv/view?usp=sharing))**  
+   - Lips in the result are clearer  
+   - Synchronization may be slightly less accurate
+
+---
+
+## Installation
+
+```bash
+pip install lipsync
 ```
 
-## Example
+---
+
+## Usage Example
+
+Below is a simple example in Python. This assumes you have the model weights (either `wav2lip.pth` or `wav2lip_gan.pth`) in a `weights/` folder.
+
 ```python
 from lipsync import LipSync
 
-
 lip = LipSync(
-    checkpoint_path='wav2lip.pth',  # Downloaded weights
+    model='wav2lip',
+    checkpoint_path='weights/wav2lip.pth',
     nosmooth=True,
-    cache_dir='cache'  # Cache directory
+    device='cuda',
+    cache_dir='cache',
+    img_size=96,
+    save_cache=True,
 )
 
 lip.sync(
-    'face.mp4',
-    'audio.wav',
-    'output-file.mp4'
+    'source/person.mp4',
+    'source/audio.wav',
+    'result.mp4',
 )
 ```
 
-License and Citation
-----------
+### Important Parameters
+- **model**: `'wav2lip'` or `'wav2lip_gan'`
+- **checkpoint_path**: Path to the model weights (e.g., `wav2lip.pth`, `wav2lip_gan.pth`)
+- **nosmooth**: Set `True` to disable smoothing
+- **device**: `'cpu'` or `'cuda'`
+- **cache_dir**: Directory for saving frames
+- **save_cache**: Set `True` to save frames to `cache_dir` for faster re-runs
+
+---
+
+### Ethical Use
+
+Please be mindful when using **lipsync**. This library can generate videos that look convincing, so it could be used to spread disinformation or harm someone’s reputation. We encourage using it only for **entertainment** or **scientific** purposes, and always with **respect and consent** from any people involved.
+
+### License and Citation
+
 The software can only be used for personal/research/non-commercial purposes. Please cite the following paper if you have use this code:
 ```
 @inproceedings{10.1145/3394171.3413532,
@@ -64,8 +101,3 @@ The software can only be used for personal/research/non-commercial purposes. Ple
     series = {MM '20}
 }
 ```
-
-
-Acknowledgements
-----------
-Parts of the code structure is inspired by this [TTS repository](https://github.com/r9y9/deepvoice3_pytorch). We thank the author for this wonderful code. The code for Face Detection has been taken from the [face_alignment](https://github.com/1adrianb/face-alignment) repository. We thank the authors for releasing their code and models.