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.

```bash
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.

```bash
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.

```bash
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`