docs: Ajout de la documentation en Français de l'utilisation de Tadam.py

This commit is contained in:
Samuel Ortion 2022-08-23 16:49:17 +02:00
parent 175b3fdde3
commit e6dc23c8f7
5 changed files with 209 additions and 17 deletions

29
Snakefile Normal file
View File

@ -0,0 +1,29 @@
"""
Tadam!
Snakemake workflow for Vigie-Chiro audio preprocessing.
"""
import glob
import os
configfile: "config.yaml"
PREFIX = config["prefix"]
rule all:
input:
"output.zip.{archive_number}"
rule rename:
input:
"raw/{filename}.wav
output:
"raw/{prefix}{filename}.wav"
shell:
"if [[ {filename} = {PREFIX}* ]]; then echo 'Prefix already present'; else rename 's/^/{PREFIX}/' '{input}'; fi"
# rule time_expansion:
# input:
# "raw/*.wav"

9
config.yaml Normal file
View File

@ -0,0 +1,9 @@
---
source: raw
dest: exp
prefix: Car910130-2021-Pass1-Z1-AR
ratio: 0.1
length: 5
archive_size: 700
archive_name: output
...

102
docs/fr/TADAM.md Normal file
View File

@ -0,0 +1,102 @@
# 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.

View File

@ -0,0 +1,45 @@
#!/usr/bin/env bash
# Separate TADARIDA nights into corresponding folders
# Specify starting and ending hours for fixed point protocol
START_TIME="22:00"
END_TIME="06:01" # add 1 minute to include exceeding records
# Specify records source and destination directories
SOURCE_DIR="/run/media/ortion/Teensy"
DESTINATION_DIR="/run/media/ortion/55E981D167764F75/Documents/nature/media/protocoles/vigie-chiro/pt_fixe/490982/Pass0"
# Function that separates records of each nights using regex
function separate_nights() {
START_TIME=$(echo $1 | sed 's/:/ /g')
END_TIME=$(echo $2 | sed 's/:/ /g')
SOURCE_DIR=$3
DESTINATION_DIR=$4
# Get list of files in source directory
FILES=$(ls $SOURCE_DIR/*.wav)
current_date=""
current_dir=""
for FILE in $FILES; do
# Get date of record
DATE=$(echo $FILE | cut -d'_' -f2)
# Get hour of record
HOUR=$(echo $FILE | cut -d'_' -f3 | cut -d'.' -f1)
# Copy record in proper directory
# If time is in night range, copy record in destination directory into the current night directory
if [ "$TIME" -ge "$START_TIME" ] && [ "$TIME" -le "$END_TIME" ]; then
# If current dir is not yet specified create a directory according to the current date
if [ "$current_dir" == "" ]; then
current_dir=$(echo $DATE | cut -b 1-4,5-6,7-8 --output-delimiter="-")
mkdir -p "$current_dir/raw"
echo "New night !"
echo "Created directory $current_dir."
fi
cp "$FILE" "$DESTINATION_DIR/$current_dir/raw/"
else
current_dir=""
fi
done
}
separate_nights "$START_TIME" "$END_TIME" "$SOURCE_DIR" "$DESTINATION_DIR"

View File

@ -22,11 +22,9 @@ import os
import sys
import numpy as np
import getopt
import zipfile
verbose = False
def usage():
usage_str = """
@ -56,7 +54,7 @@ def usage():
-r (--ratio) - Specify samplerate convertion rate
Example:
tadam -v -i raw -o exp -l 5 -z -p "Car910130-2021-Pass1-Z1-AudioMoth_" -r 0.1
tadam.py -v -i raw -o exp -l 5 -z -p "Car910130-2021-Pass1-Z1-AudioMoth_" -r 0.1
"""
print(usage_str)
@ -64,8 +62,10 @@ def usage():
def rate(infile, outfile, rate_ratio):
data, samplerate = sf.read(infile)
new_samplerate = int(samplerate * rate_ratio)
try:
sf.write(outfile, data, new_samplerate)
except:
print(f"ERROR while converting sample rate {infile} to {outfile}")
def convert_folder(infolder, outfolder, rate_ratio, prefix):
try:
@ -94,7 +94,11 @@ def chunk(outfolder, length):
extension = infile.split(".")[-1]
if not extension in ["wav", "WAV"]:
continue
try:
data, samplerate = sf.read(infile)
except:
print("ERROR: cannot read file " + infile + " for chunking.")
else:
if verbose:
print(f"\t Splitting {infile} in {length}s-long chunks.")
sections = int(np.ceil(len(data) / samplerate / length))
@ -105,7 +109,10 @@ def chunk(outfolder, length):
filename = infile.replace('.wav', f'_{str(i).zfill(3)}.wav')
temp = data[i*samplerate*length: i *
samplerate*length+samplerate*length]
try:
sf.write(filename, temp, samplerate)
except:
print(f"ERROR: cannot write chunk file {filename}.")
os.remove(infile)
def zip_folder(outfolder):