VoxDub / README.md
zyk21's picture
Improve README structure and DubBench documentation
373f052 verified
|
Raw History Blame Contribute Delete
6.63 kB
metadata
license: cc-by-nc-4.0
task_categories:
  - text-to-speech
language:
  - zh
  - en
tags:
  - audio-visual
  - video-dubbing
  - lip-sync

VoxDub

A bilingual lip-synchronized audio-visual dataset for automatic video dubbing.

Dataset Summary

VoxDub contains approximately 766K clips and 1.58K hours of Chinese and English audio-visual recordings collected from in-the-wild videos. It is designed for automatic video dubbing (AVD), with downstream evaluations on both text-to-speech (TTS) and AVD.

The curation pipeline combines speech-centered segmentation with dual-ASR transcription checking, speech quality filtering, face visibility checks, and lip-speech synchronization verification. The public data release contains annotations; source video and audio files are retrieved separately using the provided reconstruction tools.

Quick Start

After installation, download the annotations, extract them, and reconstruct a small subset:

hf download zyk21/VoxDub av_segments_v1.tar.zst \
  --repo-type dataset \
  --local-dir annotations

python scripts/pipeline.py extract
python scripts/pipeline.py run --from-annots --limit 10 --device cpu

For a configured CUDA environment, replace --device cpu with --device cuda.

--limit 10 selects up to 10 source videos, processing their annotated segments. It does not limit the output to 10 clips.

See the GitHub README for full usage details.

DubBench

1. Overview

DubBench contains English and Mandarin Chinese subsets. Each sample pairs a target utterance with a reference utterance.

In our experiments:

  • Inputs for all systems: reference audio, reference text, and target text
  • Additional input for AVD: target video
  • Output: generated target audio
  • Evaluation reference: ground-truth target audio

2. Data Sources

Please refer to the original datasets for their papers, licenses, and usage terms.

3. Dataset Structure

3.1 Repository Layout

dubbench/
├── english/
│   ├── metadata.tsv
│   ├── target.tar
│   └── reference.tar
└── chinese/
    ├── metadata.tsv
    ├── target.tar
    └── reference.tar

The four TAR archives are uncompressed.

3.2 Extracted Files

After extraction, each language subset has the following structure:

english/ or chinese/
├── metadata.tsv
├── target/
│   ├── <utterance_id>.mp4
│   ├── <utterance_id>.wav
│   └── <utterance_id>.txt
└── reference/
    ├── <utterance_id>.wav
    └── <utterance_id>.txt

Each target utterance includes .mp4, .wav, and .txt files. Each reference utterance includes .wav and .txt files.

4. Metadata Format

Each metadata.tsv file is UTF-8 encoded, has no header row, and contains four tab-separated columns:

Column Field Description
1 target_id Extensionless path of the target utterance
2 target_text Text to be generated
3 reference_id Extensionless path of the reference utterance
4 reference_text Text associated with the reference utterance

Example:

target/-4GNkXEUOwY_6_0_3<TAB>THERE'S NOTHING TO INSTALL...<TAB>reference/-4GNkXEUOwY_0_1_0<TAB>AND WHILE IT IS EASY...

Resolve an asset by joining the language subset directory with its utterance ID and file extension:

dubbench/english/target/-4GNkXEUOwY_6_0_3.wav

Reference utterances may be reused by multiple metadata rows. Samples should therefore be resolved through the IDs in metadata.tsv rather than by directory order.

5. Usage

5.1 Download

Download DubBench with the Hugging Face CLI:

hf download zyk21/VoxDub \
  --repo-type dataset \
  --include "dubbench/**" \
  --local-dir VoxDub

5.2 Extract

Extract the English subset:

tar -xf VoxDub/dubbench/english/target.tar \
  -C VoxDub/dubbench/english

tar -xf VoxDub/dubbench/english/reference.tar \
  -C VoxDub/dubbench/english

Replace english with chinese to extract the Chinese subset.

5.3 Python Example

import csv
import tarfile
from pathlib import Path

from huggingface_hub import snapshot_download


root = Path(
    snapshot_download(
        repo_id="zyk21/VoxDub",
        repo_type="dataset",
        allow_patterns="dubbench/**",
    )
)

subset = root / "dubbench" / "english"  # or "chinese"

for role in ("target", "reference"):
    with tarfile.open(subset / f"{role}.tar") as archive:
        archive.extractall(subset)

with (subset / "metadata.tsv").open(encoding="utf-8", newline="") as file:
    rows = csv.reader(file, delimiter="\t")

    for target_id, target_text, reference_id, reference_text in rows:
        target_audio = subset / f"{target_id}.wav"
        target_video = subset / f"{target_id}.mp4"
        reference_audio = subset / f"{reference_id}.wav"

        assert target_audio.is_file()
        assert target_video.is_file()
        assert reference_audio.is_file()

        # All systems use:
        #   reference_audio, reference_text, and target_text
        #
        # AVD additionally uses target_video.
        # The generated audio is evaluated against target_audio.

6. Attribution and Terms

The English and Chinese subsets are derived from CelebV-Dub and CMLR, respectively. Please cite the corresponding datasets and publications when using DubBench.

Users must follow the licenses and usage terms of the original datasets and source media. This repository does not grant additional rights to the original audio or video.

License

  • Repository code: MIT License.
  • Dataset annotations: CC BY-NC 4.0.
  • Source media: Rights remain with the original rights holders; the annotation release does not grant rights to the source videos or audio.