README.md

---
title: LipSync - LatentSync 1.6
emoji: 👄
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 5.24.0
python_version: "3.10"
app_file: app.py
pinned: false
short_description: Lipsync video (English only) - LatentSync 1.6
---

# OutofLipSync - LatentSync 1.6

Lipsync video with custom audio (English only) using **LatentSync 1.6** from ByteDance.

## Features

- **Resolution**: 512x512 (LatentSync 1.6)
- **Auto-download**: Checkpoints from `ByteDance/LatentSync-1.6`
- **Face detection**: Automatic face detection and cropping
- **Audio processing**: Audio separation, upsampling
- **Multiple outputs**: Step-by-step processing visualization

## HuggingFace Spaces Deployment

### 1. Tạo Space mới trên HuggingFace

- Vào <https://huggingface.co/new-space>
- Chọn:
  - **Owner**: Username của bạn
  - **Space name**: Tên bạn muốn (ví dụ: `lipsync-demo`)
  - **SDK**: Gradio
  - **Hardware**: GPU (cần ít nhất 18GB VRAM cho LatentSync 1.6)
  - **Visibility**: Public hoặc Private

### 2. Đẩy code lên Space

**Cách 1: Dùng Git**

```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
git remote add origin https://github.com/naicoi/OutofLipSync
git pull origin main
git push origin main
```

**Cách 2: Dùng HuggingFace CLI**

```bash
# Install huggingface-cli nếu chưa có
pip install huggingface_hub

# Login
huggingface-cli login

# Push code lên Space
git push https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME main
```

### 3. Đợi build và deploy

- HuggingFace sẽ tự động build và deploy
- Check status ở tab "Settings" → "Build"
- Khi build xong, app sẽ chạy tại: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

### 4. Yêu cầu

- **GPU**: Space cần có GPU (tối thiểu 18GB VRAM cho LatentSync 1.6)
- **Runtime**: Python 3.10
- **Disk space**: ~5GB cho checkpoints

### 5. Lưu ý

- Checkpoint được tải tự động từ `ByteDance/LatentSync-1.6` khi khởi động
- Quá trình tải checkpoint có thể mất vài phút
- Audio target chỉ hỗ trợ tiếng Anh

---

## 🚀 Deployment

### HuggingFace Spaces

1. Create a Space on HuggingFace
2. Push this repository to your Space
3. Done! HuggingFace will automatically:
   - Create Python environment
   - Install dependencies from requirements.txt
   - Start the application

**Requirements:**

- Hardware: A10G GPU (recommended, 24GB VRAM)
- Python: 3.10

## 💻 Local Development

### Option 1: Using uv (Fast - Recommended)

```bash
# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or: brew install uv

# Setup and install
./setup_local.sh

# Run application
uv run python app.py
```

**Why uv?** 10-100x faster than pip for dependency management!

### Option 2: Using pip (Standard)

```bash
# Create venv
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run application
python app.py
```

## 📦 Dependencies

- **requirements.txt**: All dependencies for application
- Packages are installed in `.venv/` (ignored by git)
- Git dependencies: LatentSync, FastAudioSR, tigersound, descript-audiotools

## ⚠️ Important Notes

### Flash-attn-3 for Local Testing

The `flash-attn-3` package only provides wheels for Linux x86_64:

- **HuggingFace (Linux)**: ✅ Works automatically
- **Local (macOS)**: ❌ Will fail during installation

**Workaround for local testing:**

```bash
# Comment out flash-attn-3 in requirements.txt for local testing
# Uncomment before pushing to HuggingFace
```

### Checkpoints

Checkpoints are automatically downloaded from `ByteDance/LatentSync-1.6` on startup.

### Audio Language

Target audio supports **English only**.

Check out the configuration reference at <https://huggingface.co/docs/hub/spaces-config-reference>