batdetect2/docs/source/how_to/choose-an-inference-input-mode.md

How to choose an inference input mode

Use this guide to decide whether predict directory, predict file_list, or predict dataset is the right entry point for your run.

Use predict directory when the recordings already live together

This is the simplest choice.

Use it when:

• your recordings are already organized in one directory tree,
• you want BatDetect2 to discover audio files for you,
• you are doing a first pass over a folder of recordings.

batdetect2 predict directory \
  path/to/model.ckpt \
  path/to/audio_dir \
  path/to/outputs

Use predict file_list when you need explicit control over the file set

Use it when:

• you want to run only a selected subset,
• your files are spread across directories,
• another tool has already produced the exact list of recordings to process.

The list file should contain one path per line.

batdetect2 predict file_list \
  path/to/model.ckpt \
  path/to/audio_files.txt \
  path/to/outputs

Use predict dataset when your workflow is already annotation-set driven

Use it when:

• your project already has a soundevent annotation set,
• you want prediction runs aligned with that annotation metadata,
• you want BatDetect2 to resolve recording paths from the annotation set.

batdetect2 predict dataset \
  path/to/model.ckpt \
  path/to/annotation_set.json \
  path/to/outputs

The dataset command reads a soundevent annotation set and extracts unique recording paths before inference.

Rule of thumb

• Start with directory for the easiest first run.
• Use file_list when selection matters.
• Use dataset when the rest of your workflow is already dataset-based.

Related pages

• Run batch predictions: {doc}run-batch-predictions
• Tune inference clipping: {doc}tune-inference-clipping
• Predict command reference: {doc}../reference/cli/predict