Skip to content

SETUP.md

Latest commit

 

History

History
94 lines (68 loc) · 3.27 KB

SETUP.md

File metadata and controls

94 lines (68 loc) · 3.27 KB
Raw

Setup

How to get the repository ready to train and evaluate models from a fresh clone.

Requirements

  • Python 3.12+
  • NVIDIA GPU with CUDA (verified on RTX 4090 Laptop, ~24 GB VRAM headroom is plenty)
  • ~60 GB free disk for the full MLAAD archive (much less for a subset)
  • uv for environment management (recommended)

1. Clone and install

git clone https://github.com/Woleek/supra-to-sub.git
cd supra-to-sub

# uv (recommended) — creates .venv and installs everything
uv sync

# Or with pip
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The project installs as an editable package named adar (see [tool.hatch.build.targets.wheel] in pyproject.toml). After install, import adar works from any cwd inside the project.

Verify CUDA is visible:

uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

2. Get the MLAAD dataset

The dataset can be fetched from https://deepfake-total.com/sourcetracing.

Expected layout after extraction (this is what the training/eval scripts assume):

data/MLAADv5_for_sourcetracing/
├── mlaad4sourcetracing/        # protocol CSVs
│   ├── train.csv               # path, model_name
│   ├── dev.csv
│   ├── eval.csv
│   ├── fine/                   # fine-grained splits (lang_seen/not_seen × model_seen/not_seen)
│   └── meta.txt
└── fake/<lang>/<tts_model>/    # audio files referenced by the CSVs
    └── *.wav

3. Generate pre-encoded features

The training scripts run on pre-encoded Wav2Vec2 features, not raw audio. Build them with:

make prepare

This is equivalent to:

uv run scripts/prepare_original_dataset.py \
  --mlaad_path data/MLAADv5_for_sourcetracing/ \
  --protocol_path data/MLAADv5_for_sourcetracing/mlaad4sourcetracing/ \
  --out_folder data/prepared_ds_seg_enc \
  --n_segments 4 \
  --encode \
  --batch_size 8 \
  --num_workers 2

It produces:

data/prepared_ds_seg_enc/
├── train/                       # 1 .pt file per (sample × segment × emphasis)
├── dev/
├── eval/
└── label_assignment.txt         # class_name | class_id | ID/OOD

label_assignment.txt is generated from the train.csv class set — anything in dev/eval that isn't in train is labeled OOD.

4. (Hierarchical only) Superclass label files

The canonical LUTs for the full 24-class MLAAD setup are committed at the repo root under data/:

  • data/superclass_mapping_known.csv — Class, Superclass, Class ID, Superclass ID for the ID classes. Class ID must match data/label_assignment.txt.
  • data/superclass_mapping_test.csv — same schema, but also includes OOD classes. Used by ood_detector.py as the "full" LUT.
  • data/label_assignment.txt and data/label_assignment_superclass.txt — class / superclass name → ID with ID/OOD flag.

These are the defaults wired into the makefile (make train_hier_shared, make train_hier_arch, make id_eval, make ood_eval). The path-resolution helper (adar.utils.resolve_label_path) accepts either an absolute / repo-relative path (e.g. data/superclass_mapping_known.csv) or a name relative to --path_to_dataset — see TRAINING.md for an example.