# Comment utiliser Tadam

Tadam: un script qui réalise le traitement de l'audio, de la carte SD de votre enregistreur jusqu'au portail de Vigie-Chiro...

## Introduction

Tadam est un script python utilisé pour préprocesser un dossier d'enregistrements audio afin de le préparer pour l'envoie sur le portail [Vigie-Chiro](https://www.vigiechiro.herokuapp.com/), en vue d'une analyze  des ultrasons par Tadarida.

## Prérequis

- Python3 (avec pip)
- Wget ou Git (pour récupérér le script)
- 7z (pour la compression en zip -- installer p7zip)

## Installation

### Récupérer le script

Il y a deux manières d'installer Tadam, soit en utilisant Git et en clonant [le dépôt](https://forge.chapril.org/Chiro-Canto/TadaridaTools), soit en récupérant juste le fichier .py, en le téléchargeant depuis le dépôt (méthode recommandée, si vous ne souhaitez pas modifier le code de Tadam).

Méthode Git:

```bash
git clone https://forge.chapril.org/Chiro-Canto/TadaridaTools
cd TadaridaTools
sudo cp ./src/tadam.py /usr/local/bin/tadam.py
```

Méthode Wget:

```bash
wget https://forge.chapril.org/Chiro-Canto/TadaridaTools/raw/branch/master/src/tadam.py
sudo cp tadam.py /usr/local/bin/tadam.py
```

Dans les deux cas, il faut autoriser l'execution du script:

```bash
sudo chmod +x /usr/local/bin/tadam.py
```

### Récupérer les dépendences Python

```bash
pip3 install soundfile
```


## Usage

Maintenant que le script est installé, et est dans le PATH, il est utilisable dans n'importe quel dossier dans le terminal.

### Avant d'utiliser le script

Le plus simple est de commencer par créer un dossier concernant votre participation (par example avec un nom de dossier en YYYY-MM-DD, correspondant à la date de la participation, associé au point prospecté). 

Ensuite, il faut crééer deux sous dossier, l'un pour les fichiers wav bruts, l'autre pour les fichiers wav en temps expansé. 

Le nom de ces dossiers n'a pas d'importance, à conditions que vous adaptez correctement la ligne de commande Tadam après.

```bash
mkdir {raw,exp}
```

Il faut dès lors copier les fichiers concernant la participation depuis la carte SD vers le dossier raw.

Sous Linux, cela peut être fait en interface graphique, ou par exemple avec rsync:

```bash
rsync -avz --progress /chemin/dossier/carte/sd/ /chemin/dossier/raw/
```

Notez les `/` à la fin des chemins, pour copier le contenu du dossier, et non le dossier lui-même, quand vous utilisez rsync.

### Utilisation du script

Ouvrir, si ce n'est pas déjà fait, le terminal, dans le dossier contenant les dossiers raw et exp.

Tadam vient avec une aide succinte intégrée, qui détaille un peu les options disponibles; pour la voir, tapez:

```bash
tadam.py --help
```

Dans une utilisation standard, il faut taper:

```bash
tadam.py -v -i raw -o exp -l 5 -z -p "Car910130-2021-Pass1-Z1-AudioMoth_" -r 0.1
```

Détaillons un peu ce que fait cette commande.

- `-v` : active le mode verbeux, qui affiche des informations sur la progression du traitement.
- `-i` : indique le dossier contenant les fichiers wav bruts.
- `-o` : indique le dossier où seront stockés les fichiers wav en temps expansé.
- `-l` : indique la durée maximale des wav en sorties (les fichiers qui ferait plus que le nombre de secondes spécifié sont découpés en plusieurs fichiers)
- `-z`: indique au script de compresser les fichiers wav en sorties, en utilisant 7z une taille de 700Mo comme préconisé par Vigie-Chiro, si l'on souhaite accélérer l'upload.
- `-p` : indique le préfixe des fichiers wav en sorties. Il doivent être conforment à ce qui est prévu par Vigie-Chiro, se référer au tuto renommage.
 
 Enfin et surtout:
- `-r`: indique le ratio de conversion de la fréquence d'échantillonage (*sample rate*) des fichiers wav en sorties. 0.1 correspond a une expansion x10. Il faut faire attention au type d'enregistreur utilisé, et se référer aux tutos Vigie-Chiro pour choisir la bonne valeur.

Avec la ligne de commande présentée ci dessus, le script génère les fichiers sons expansés dans exp, et compresse exp, dans l'archive .zip output.zip, en fichier output.zip.1, output.zip.2, etc.