hf_space/README.md

Deploying GestureLSM to Hugging Face Spaces

This directory contains a minimal scaffold for running the demo.py Gradio UI inside a Hugging Face Space. Copy the files into a new Space repository (or push this folder as-is) and provide the model checkpoints via the Hugging Face Hub so the app can download them at startup.

1. Create the Space

1. In your Hugging Face account, click New Space.
2. Choose a Space name, set SDK to Gradio, and select CPU Basic hardware.
3. Leave the default visibility or mark it Private while testing.

2. Populate the Space repository

Upload the following from this folder to the Space:

• app.py – boots the Gradio interface, downloads weights if available, and ensures output folders exist.
• requirements.txt – Python dependencies.
• packages.txt – system packages (ffmpeg + openfst).
• prepare_assets.py (optional helper described below).
• Any configs, sample audio, and auxiliary data your demo needs (e.g. configs/, demo/examples/, mean_std/).

Tip: keep the repository lightweight. Large checkpoints should live in a separate dataset repo and be fetched at runtime.

3. Host the checkpoints

1. Create a private dataset repo on Hugging Face (e.g. username/gesturelsm-assets).
2. Upload the required files:
   • ckpt/net_300000_upper.pth
   • ckpt/net_300000_lower.pth
   • ckpt/net_300000_hands.pth
   • ckpt/net_300000_lower_trans.pth
   • ckpt/net_300000_upper.pth
   • ckpt/new_540_shortcut.bin
   • mean_std/*.npy
3. In your Space’s Settings → Variables and secrets, add a variable named HF_GESTURELSM_WEIGHTS_REPO with the value of the dataset repo (for example username/gesturelsm-assets).

When the Space boots, app.py will call snapshot_download to pull everything into ckpt/, preserving the original directory layout expected by demo.py.

4. Optional asset preparation script

If you need to perform additional setup (e.g. copying assets after download), you can push the provided prepare_assets.py and call it from app.py or __init__.py before launching the interface. Modify it to match your workflow.

5. Verify locally

Before pushing, test with the same layout on your machine:

conda activate gesturelsm
pip install -r hf_space/requirements.txt
python hf_space/app.py

Ensure the UI launches and generates outputs using locally stored checkpoints.

6. Push & run

Commit and push the Space repository. After the build completes, the public URL will auto-refresh and display the Gradio interface. Upload audio, wait for inference to finish, then download the generated video/NPZ results just like the local demo.

---

Add or adjust dependencies as new features require. Heavy rendering tasks can be slow on free CPU hardware; consider upgrading the Space or trimming the pipeline (e.g. precomputing alignments) if latency becomes an issue.