ecological-agent-skills 3.1.0

package/skills/acoustic-monitoring/scripts/compute_acoustic_indices.R

@@ -0,0 +1,235 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Usage: Rscript compute_acoustic_indices.R <audio_dir> <output_dir> [time_resolution_min] [freq_min] [freq_max]
+#
+# Computes acoustic indices (ACI, BI, NDSI, H, ADI, AEI) for all .wav/.flac
+# files in a directory, aggregates by time resolution, and produces summary
+# outputs and a soundscape heatmap.
+#
+# Outputs:
+#   acoustic_indices_timeseries.csv  — per-file index values with timestamps
+#   indices_summary.csv              — mean ± SD per index per hour-of-day
+#   soundscape_plot.png              — heatmap (hour × day × index)
+
+# ── Inline logger ─────────────────────────────────────────────────────────────
+SKILL_NAME <- "acoustic-monitoring"
+.log_ts  <- function() format(Sys.time(), "[%Y-%m-%d %H:%M:%S]")
+log_info <- function(...) message(.log_ts(), " [INFO]  ", sprintf(...))
+log_warn <- function(...) message(.log_ts(), " [WARN]  ", sprintf(...))
+log_error<- function(...) message(.log_ts(), " [ERROR] ", sprintf(...))
+log_step <- function(n, d) log_info("-- STEP %d: %s", n, d)
+log_decision <- function(v, val, why) log_info("DECISION | %s = %s | %s", v, val, why)
+dir.create("logs", recursive=TRUE, showWarnings=FALSE)
+
+suppressPackageStartupMessages(library(soundecology))
+suppressPackageStartupMessages(library(tuneR))
+suppressPackageStartupMessages(library(dplyr))
+suppressPackageStartupMessages(library(tidyr))
+suppressPackageStartupMessages(library(lubridate))
+suppressPackageStartupMessages(library(ggplot2))
+
+args <- commandArgs(trailingOnly = TRUE)
+if (length(args) < 2) {
+  log_error("Argumentos insuficientes. Uso: Rscript compute_acoustic_indices.R <audio_dir> <output_dir> [time_resolution_min] [freq_min_hz] [freq_max_hz]")
+  cat("Usage: Rscript compute_acoustic_indices.R <audio_dir> <output_dir>",
+      "[time_resolution_min] [freq_min_hz] [freq_max_hz]\n")
+  cat("Defaults: time_resolution_min=1  freq_min_hz=0  freq_max_hz=22050\n")
+  quit(status = 1)
+}
+
+audio_dir        <- args[1]
+output_dir       <- args[2]
+time_res_min     <- if (length(args) >= 3) as.integer(args[3]) else 1L
+freq_min_hz      <- if (length(args) >= 4) as.numeric(args[4]) else 0
+freq_max_hz      <- if (length(args) >= 5) as.numeric(args[5]) else 22050
+
+# ── Input precondition checks ────────────────────────────────────────────────
+if (!dir.exists(audio_dir)) {
+  log_error("Input nao encontrado: %s\nCausa provavel: caminho incorreto ou diretorio nao montado\nVerifique: se o diretorio de audio existe\nSkill anterior: [nenhuma — etapa inicial]", audio_dir)
+  stop("Missing audio_dir: ", audio_dir)
+}
+
+log_decision("time_res_min", time_res_min,
+             "resolucao temporal de agregacao em minutos; 1 min = resolucao completa por arquivo")
+log_decision("freq_min_hz", freq_min_hz,
+             "frequencia minima de analise em Hz; 0 = sem filtro inferior")
+log_decision("freq_max_hz", freq_max_hz,
+             "frequencia maxima de analise em Hz; limitado pela taxa de amostragem do arquivo")
+
+dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
+
+log_step(1, "Descobrindo arquivos de audio no diretorio")
+# ── Discover audio files ────────────────────────────────────────────────────
+wav_files  <- list.files(audio_dir, pattern = "\\.wav$",  full.names = TRUE,
+                         recursive = TRUE, ignore.case = TRUE)
+flac_files <- list.files(audio_dir, pattern = "\\.flac$", full.names = TRUE,
+                         recursive = TRUE, ignore.case = TRUE)
+audio_files <- c(wav_files, flac_files)
+
+if (length(audio_files) == 0) {
+  log_error("Nenhum arquivo .wav ou .flac encontrado em: %s\nCausa provavel: diretorio vazio ou extensoes em maiusculas nao reconhecidas\nVerifique: conteudo do diretorio de audio\nSkill anterior: [nenhuma]", audio_dir)
+  stop("No .wav or .flac files found in: ", audio_dir)
+}
+log_info("Encontrados %d arquivos de audio", length(audio_files))
+
+# ── Helper: extract timestamp from filename ─────────────────────────────────
+# Supports common recorder filename patterns:
+#   AUDIOMOTH_20240601_050000.wav
+#   SMM07207_0+1_20240601$050000.wav (Wildlife Acoustics)
+#   generic: any 8-digit date + 6-digit time
+parse_timestamp <- function(fname) {
+  base <- tools::file_path_sans_ext(basename(fname))
+  m <- regmatches(base,
+         regexpr("(\\d{8})[_$T](\\d{6})", base, perl = TRUE))
+  if (length(m) == 0 || nchar(m) == 0) return(NA_POSIXct_)
+  parts <- regmatches(m, regexpr("(\\d{8})[_$T](\\d{6})", m, perl = TRUE))
+  dt_str <- sub("([_$T])", " ", parts)
+  tryCatch(as.POSIXct(dt_str, format = "%Y%m%d %H%M%S", tz = "UTC"),
+           error = function(e) NA_POSIXct_)
+}
+
+log_step(2, "Computando indices acusticos por arquivo")
+# ── Compute indices per file ────────────────────────────────────────────────
+compute_file_indices <- function(fpath) {
+  tryCatch({
+    if (grepl("\\.flac$", fpath, ignore.case = TRUE)) {
+      # Convert FLAC to temp WAV for tuneR compatibility
+      tmp <- tempfile(fileext = ".wav")
+      system2("ffmpeg", args = c("-y", "-i", shQuote(fpath),
+                                 shQuote(tmp)), stdout = FALSE, stderr = FALSE)
+      wave <- readWave(tmp)
+      file.remove(tmp)
+    } else {
+      wave <- readWave(fpath)
+    }
+
+    sr <- wave@samp.rate
+    freq_max_use <- min(freq_max_hz, sr / 2)
+
+    # ACI — Acoustic Complexity Index
+    aci_res  <- acoustic_complexity(wave, min_freq = freq_min_hz,
+                                    max_freq = freq_max_use)
+    aci_val  <- aci_res$AciTotAll_left
+
+    # BI — Bioacoustic Index
+    bi_res   <- bioacoustic_index(wave, min_freq = max(freq_min_hz, 2000),
+                                  max_freq = min(freq_max_use, 8000))
+    bi_val   <- bi_res$left_area
+
+    # NDSI — Normalized Difference Soundscape Index
+    ndsi_res <- ndsi(wave, fft_w = 1024,
+                     anthro_min = max(freq_min_hz, 200),
+                     anthro_max = 2000,
+                     bio_min    = 2000,
+                     bio_max    = min(freq_max_use, 8000))
+    ndsi_val <- ndsi_res$ndsi_left
+
+    # H — Spectral and temporal entropy
+    h_res    <- acoustic_entropy(wave)
+    h_val    <- h_res$H
+
+    # ADI — Acoustic Diversity Index
+    adi_res  <- acoustic_diversity(wave, max_freq = freq_max_use, db_threshold = -50)
+    adi_val  <- adi_res$adi_left
+
+    # AEI — Acoustic Evenness Index
+    aei_res  <- acoustic_evenness(wave, max_freq = freq_max_use, db_threshold = -50)
+    aei_val  <- aei_res$aei_left
+
+    data.frame(
+      file      = basename(fpath),
+      datetime  = parse_timestamp(fpath),
+      ACI       = aci_val,
+      BI        = bi_val,
+      NDSI      = ndsi_val,
+      H         = h_val,
+      ADI       = adi_val,
+      AEI       = aei_val,
+      stringsAsFactors = FALSE
+    )
+  }, error = function(e) {
+    log_warn("Pulando %s: %s", basename(fpath), conditionMessage(e))
+    NULL
+  })
+}
+
+log_info("Computando indices — pode levar varios minutos para grandes conjuntos de dados...")
+results_list <- lapply(audio_files, compute_file_indices)
+results_list <- Filter(Negate(is.null), results_list)
+
+if (length(results_list) == 0) {
+  log_error("Nenhum arquivo processado com sucesso\nCausa provavel: formato de audio incompativel ou intervalo de frequencia invalido\nVerifique: formato WAV/FLAC e configuracoes de frequencia\nSkill anterior: [nenhuma]")
+  stop("No files could be processed. Check audio format and frequency range.")
+}
+log_info("%d de %d arquivos processados com sucesso", length(results_list), length(audio_files))
+
+log_step(3, "Agregando indices por resolucao temporal")
+indices_df <- dplyr::bind_rows(results_list)
+
+# ── Aggregate by time resolution ────────────────────────────────────────────
+if (!is.na(indices_df$datetime[1])) {
+  indices_df <- indices_df %>%
+    mutate(
+      time_block = floor_date(datetime, unit = paste(time_res_min, "mins")),
+      hour_of_day = hour(datetime),
+      date        = as.Date(datetime)
+    )
+} else {
+  # No timestamps extracted; use row order as proxy
+  indices_df <- indices_df %>%
+    mutate(time_block = seq_len(nrow(.)),
+           hour_of_day = NA_integer_,
+           date = NA)
+  log_warn("Nenhum timestamp extraido dos nomes de arquivo. Heatmap nao sera gerado.")
+}
+
+log_step(4, "Escrevendo CSV de serie temporal de indices")
+# ── Write timeseries CSV ────────────────────────────────────────────────────
+ts_path <- file.path(output_dir, "acoustic_indices_timeseries.csv")
+write.csv(indices_df, ts_path, row.names = FALSE)
+log_info("Serie temporal escrita: %s (%d linhas)", ts_path, nrow(indices_df))
+
+log_step(5, "Calculando e escrevendo resumo por hora do dia")
+# ── Write summary CSV ───────────────────────────────────────────────────────
+summary_df <- indices_df %>%
+  group_by(hour_of_day) %>%
+  summarise(
+    across(c(ACI, BI, NDSI, H, ADI, AEI),
+           list(mean = ~mean(.x, na.rm = TRUE),
+                sd   = ~sd(.x,   na.rm = TRUE))),
+    n_recordings = n(),
+    .groups = "drop"
+  )
+
+sum_path <- file.path(output_dir, "indices_summary.csv")
+write.csv(summary_df, sum_path, row.names = FALSE)
+log_info("Resumo escrito: %s", sum_path)
+
+log_step(6, "Gerando heatmap de paisagem sonora")
+# ── Soundscape heatmap ──────────────────────────────────────────────────────
+if (!all(is.na(indices_df$datetime))) {
+  plot_df <- indices_df %>%
+    select(date, hour_of_day, ACI, NDSI, H) %>%
+    pivot_longer(cols = c(ACI, NDSI, H), names_to = "index", values_to = "value") %>%
+    group_by(date, hour_of_day, index) %>%
+    summarise(value = mean(value, na.rm = TRUE), .groups = "drop")
+
+  p <- ggplot(plot_df, aes(x = hour_of_day, y = as.factor(date), fill = value)) +
+    geom_tile() +
+    scale_fill_viridis_c(option = "magma", na.value = "grey80") +
+    facet_wrap(~index, ncol = 1, scales = "free_x") +
+    labs(x = "Hour of day", y = "Date", fill = "Index value",
+         title = "Soundscape index heatmap (ACI, NDSI, H)") +
+    theme_minimal(base_size = 10) +
+    theme(axis.text.y = element_text(size = 7))
+
+  plot_path <- file.path(output_dir, "soundscape_plot.png")
+  ggsave(plot_path, p, width = 10, height = max(4, nrow(unique(plot_df[, "date"])) * 0.4 + 2),
+         dpi = 150)
+  log_info("Heatmap salvo: %s", plot_path)
+} else {
+  log_warn("Pulando heatmap: nenhum timestamp disponivel nos arquivos de audio")
+}
+
+log_info("Computacao de indices acusticos concluida")

package/skills/acoustic-monitoring/scripts/compute_acoustic_indices.py

@@ -0,0 +1,374 @@
+# ecological-agent-skills / Copyright (C) 2026 Francisco Diego Barros Barata
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Compute acoustic indices for passive acoustic monitoring using librosa and soundfile.
+
+Usage:
+    python compute_acoustic_indices.py <audio_dir> <output_dir>
+        [--resolution_min 1] [--freq_min 0] [--freq_max 22050]
+
+Implements:
+    ACI  — Acoustic Complexity Index (Pieretti et al. 2011)
+    BI   — Bioacoustic Index (Boelman et al. 2007), approximated
+    NDSI — Normalized Difference Soundscape Index (Kasten et al. 2012)
+    Ht   — Temporal entropy (Sueur et al. 2008)
+    Hf   — Spectral entropy (Sueur et al. 2008)
+    H    — Total entropy (Ht × Hf)
+
+Outputs:
+    acoustic_indices_timeseries.csv  — per-file indices with timestamps
+    indices_summary.csv              — mean ± SD by hour of day
+    soundscape_plot.png              — heatmap (date × hour, coloured by ACI)
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SKILL_NAME = "acoustic-monitoring"
+_LOG_DIR   = Path("logs")
+_LOG_DIR.mkdir(parents=True, exist_ok=True)
+_log_file  = _LOG_DIR / f"skill_{SKILL_NAME}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(asctime)s] [%(levelname)s] [" + SKILL_NAME + "] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+        logging.FileHandler(_log_file, encoding="utf-8"),
+    ],
+)
+logger = logging.getLogger(SKILL_NAME)
+
+def log_step(n: int, desc: str) -> None:
+    logger.info("-- STEP %d: %s", n, desc)
+
+def log_decision(var: str, val, why: str) -> None:
+    logger.info("DECISION | %s = %s | %s", var, val, why)
+
+import os
+import re
+import csv
+import math
+import argparse
+
+try:
+    import numpy as np
+    import librosa
+    import soundfile as sf
+except ImportError as e:
+    logger.error("Missing dependency: %s. Install with: pip install librosa soundfile numpy", e)
+    sys.exit(1)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Compute acoustic indices for PAM recordings"
+    )
+    parser.add_argument("audio_dir",  help="Directory containing .wav/.flac files")
+    parser.add_argument("output_dir", help="Directory for output files")
+    parser.add_argument("--resolution_min", type=int, default=1,
+                        help="Time aggregation resolution in minutes (default: 1)")
+    parser.add_argument("--freq_min", type=float, default=0,
+                        help="Minimum frequency in Hz (default: 0)")
+    parser.add_argument("--freq_max", type=float, default=22050,
+                        help="Maximum frequency in Hz (default: 22050)")
+    # Fallback positional for simple invocation
+    if len(sys.argv) >= 3 and not sys.argv[1].startswith("--"):
+        return parser.parse_args()
+    return parser.parse_args()
+
+
+def parse_timestamp(fname: str):
+    """Extract datetime from common logger filename patterns."""
+    patterns = [r"(\d{8})[_$T](\d{6})"]
+    for pat in patterns:
+        m = re.search(pat, fname)
+        if m:
+            try:
+                return datetime.strptime(m.group(1) + m.group(2), "%Y%m%d%H%M%S")
+            except ValueError:
+                pass
+    return None
+
+
+# ── Index computation functions ─────────────────────────────────────────────
+
+def compute_aci(y: np.ndarray, sr: int, n_fft: int = 1024, hop: int = 512,
+                freq_min: float = 0, freq_max: float = 22050) -> float:
+    """Acoustic Complexity Index (Pieretti et al. 2011).
+
+    ACI = sum(|D_k|) / sum(I_k)  per frequency bin, summed across bins.
+    D_k = absolute difference between adjacent time frames in bin k.
+    I_k = sum of intensities in bin k.
+    """
+    S = np.abs(librosa.stft(y, n_fft=n_fft, hop_length=hop))
+    freqs = librosa.fft_frequencies(sr=sr, n_fft=n_fft)
+    mask  = (freqs >= freq_min) & (freqs <= freq_max)
+    S = S[mask, :]
+    if S.shape[1] < 2:
+        return float("nan")
+    diffs  = np.abs(np.diff(S, axis=1))
+    totals = np.sum(S[:, :-1], axis=1)
+    totals[totals == 0] = np.finfo(float).eps
+    aci = float(np.sum(np.sum(diffs, axis=1) / totals))
+    return aci
+
+
+def compute_bi(y: np.ndarray, sr: int, n_fft: int = 1024, hop: int = 512,
+               bio_min: float = 2000, bio_max: float = 8000) -> float:
+    """Bioacoustic Index — area under mean spectrum in biophony band (2–8 kHz).
+    Approximation of Boelman et al. (2007).
+    """
+    S   = np.abs(librosa.stft(y, n_fft=n_fft, hop_length=hop))
+    freqs = librosa.fft_frequencies(sr=sr, n_fft=n_fft)
+    mask = (freqs >= bio_min) & (freqs <= min(bio_max, sr / 2))
+    S_bio = S[mask, :]
+    if S_bio.size == 0:
+        return float("nan")
+    mean_spec = np.mean(S_bio, axis=1)
+    mean_db   = 20 * np.log10(mean_spec + np.finfo(float).eps)
+    mean_db   = np.clip(mean_db - mean_db.min(), 0, None)
+    bi = float(np.trapz(mean_db))
+    return bi
+
+
+def compute_ndsi(y: np.ndarray, sr: int, n_fft: int = 1024, hop: int = 512,
+                 anthro_min: float = 200, anthro_max: float = 2000,
+                 bio_min: float = 2000, bio_max: float = 8000) -> float:
+    """Normalized Difference Soundscape Index (Kasten et al. 2012).
+    NDSI = (biophony - anthrophony) / (biophony + anthrophony)
+    """
+    S     = np.abs(librosa.stft(y, n_fft=n_fft, hop_length=hop)) ** 2
+    freqs = librosa.fft_frequencies(sr=sr, n_fft=n_fft)
+    anthro_mask = (freqs >= anthro_min) & (freqs < anthro_max)
+    bio_mask    = (freqs >= bio_min)    & (freqs <= min(bio_max, sr / 2))
+    anthro = float(np.sum(S[anthro_mask, :]))
+    bio    = float(np.sum(S[bio_mask, :]))
+    total  = anthro + bio
+    if total == 0:
+        return float("nan")
+    return (bio - anthro) / total
+
+
+def compute_entropy(y: np.ndarray, sr: int, n_fft: int = 1024,
+                    hop: int = 512) -> tuple[float, float, float]:
+    """Temporal entropy (Ht), spectral entropy (Hf), total entropy H = Ht × Hf.
+    After Sueur et al. (2008).
+    """
+    # Temporal entropy
+    env = np.abs(y)
+    env_sum = env.sum()
+    if env_sum == 0:
+        return float("nan"), float("nan"), float("nan")
+    env_norm = env / env_sum
+    env_norm[env_norm == 0] = np.finfo(float).eps
+    Ht = float(-np.sum(env_norm * np.log(env_norm)) / math.log(len(env_norm)))
+
+    # Spectral entropy
+    S   = np.abs(librosa.stft(y, n_fft=n_fft, hop_length=hop))
+    mean_spec = np.mean(S, axis=1)
+    sp_sum = mean_spec.sum()
+    if sp_sum == 0:
+        return Ht, float("nan"), float("nan")
+    sp_norm = mean_spec / sp_sum
+    sp_norm[sp_norm == 0] = np.finfo(float).eps
+    Hf = float(-np.sum(sp_norm * np.log(sp_norm)) / math.log(len(sp_norm)))
+
+    H = Ht * Hf
+    return Ht, Hf, H
+
+
+def process_file(fpath: Path, freq_min: float, freq_max: float) -> dict | None:
+    """Load audio and compute all indices. Returns dict or None on error."""
+    try:
+        y, sr = librosa.load(str(fpath), sr=None, mono=True)
+    except Exception as e:
+        logger.warning("Nao foi possivel carregar %s: %s", fpath.name, e)
+        return None
+
+    freq_max_use = min(freq_max, sr / 2)
+    n_fft = 1024
+    hop   = 512
+
+    aci  = compute_aci(y, sr, n_fft, hop, freq_min, freq_max_use)
+    bi   = compute_bi(y, sr, n_fft, hop,
+                      bio_min=max(freq_min, 2000),
+                      bio_max=min(freq_max_use, 8000))
+    ndsi = compute_ndsi(y, sr, n_fft, hop,
+                        anthro_min=max(freq_min, 200),
+                        anthro_max=2000,
+                        bio_min=2000,
+                        bio_max=min(freq_max_use, 8000))
+    Ht, Hf, H = compute_entropy(y, sr, n_fft, hop)
+
+    ts = parse_timestamp(fpath.name)
+    return {
+        "file":        fpath.name,
+        "datetime":    ts.strftime("%Y-%m-%d %H:%M:%S") if ts else "",
+        "date":        ts.strftime("%Y-%m-%d") if ts else "",
+        "hour":        ts.hour if ts else -1,
+        "ACI":         round(aci,  2),
+        "BI":          round(bi,   2),
+        "NDSI":        round(ndsi, 4),
+        "Ht":          round(Ht,   4),
+        "Hf":          round(Hf,   4),
+        "H":           round(H,    4),
+    }
+
+
+def write_summary(rows: list[dict], output_dir: Path) -> None:
+    """Write per-hour summary (mean ± SD) for each index."""
+    from collections import defaultdict
+    hour_data = defaultdict(lambda: {k: [] for k in ("ACI", "BI", "NDSI", "H")})
+    for r in rows:
+        if r["hour"] >= 0:
+            for idx in ("ACI", "BI", "NDSI", "H"):
+                v = r[idx]
+                if not math.isnan(v):
+                    hour_data[r["hour"]][idx].append(v)
+
+    path = output_dir / "indices_summary.csv"
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["hour", "ACI_mean", "ACI_sd", "BI_mean", "BI_sd",
+                         "NDSI_mean", "NDSI_sd", "H_mean", "H_sd", "n"])
+        for h in sorted(hour_data.keys()):
+            row = [h]
+            for idx in ("ACI", "BI", "NDSI", "H"):
+                vals = hour_data[h][idx]
+                if vals:
+                    row += [round(sum(vals) / len(vals), 3),
+                            round(math.sqrt(sum((v - sum(vals)/len(vals))**2
+                                               for v in vals) / max(len(vals)-1, 1)), 3)]
+                else:
+                    row += ["", ""]
+            row.append(sum(len(hour_data[h][k]) for k in ("ACI",)) // 1)  # n per hour
+            writer.writerow(row)
+    logger.info("Resumo escrito: %s", path)
+
+
+def write_heatmap(rows: list[dict], output_dir: Path) -> None:
+    """Produce a simple heatmap PNG of ACI by date × hour."""
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError:
+        logger.warning("matplotlib nao disponivel; pulando heatmap")
+        return
+
+    dated = [r for r in rows if r["date"] and r["hour"] >= 0]
+    if not dated:
+        logger.warning("Sem timestamps validos; heatmap nao gerado")
+        return
+
+    dates = sorted(set(r["date"] for r in dated))
+    hours = list(range(24))
+
+    from collections import defaultdict
+    grid = defaultdict(lambda: defaultdict(list))
+    for r in dated:
+        if not math.isnan(r["ACI"]):
+            grid[r["date"]][r["hour"]].append(r["ACI"])
+
+    matrix = np.full((len(dates), 24), np.nan)
+    for i, d in enumerate(dates):
+        for h in hours:
+            vals = grid[d][h]
+            if vals:
+                matrix[i, h] = sum(vals) / len(vals)
+
+    fig, ax = plt.subplots(figsize=(12, max(3, len(dates) * 0.35 + 2)))
+    im = ax.imshow(matrix, aspect="auto", cmap="magma",
+                   interpolation="nearest",
+                   extent=[-0.5, 23.5, len(dates) - 0.5, -0.5])
+    ax.set_xlabel("Hour of day")
+    ax.set_yticks(range(len(dates)))
+    ax.set_yticklabels(dates, fontsize=7)
+    ax.set_title("Acoustic Complexity Index (ACI) — date × hour heatmap")
+    plt.colorbar(im, ax=ax, label="ACI")
+    plt.tight_layout()
+    path = output_dir / "soundscape_plot.png"
+    fig.savefig(path, dpi=150)
+    plt.close(fig)
+    logger.info("Heatmap salvo: %s", path)
+
+
+def main():
+    args = parse_args()
+    audio_dir  = Path(args.audio_dir)
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # ── Input precondition checks ────────────────────────────────────────────
+    if not audio_dir.is_dir():
+        logger.error(
+            "Input nao encontrado: %s\n  Causa provavel: caminho incorreto ou diretorio nao montado\n  Skill anterior: [nenhuma — etapa inicial]",
+            audio_dir,
+        )
+        sys.exit(1)
+
+    log_decision("resolution_min", args.resolution_min,
+                 "resolucao de agregacao temporal em minutos")
+    log_decision("freq_min", args.freq_min,
+                 "frequencia minima de analise em Hz")
+    log_decision("freq_max", args.freq_max,
+                 "frequencia maxima de analise em Hz; limitado pela taxa de amostragem")
+
+    log_step(1, "Descobrindo arquivos de audio")
+    files = sorted(
+        p for ext in ("*.wav", "*.WAV", "*.flac", "*.FLAC")
+        for p in audio_dir.rglob(ext)
+    )
+    if not files:
+        logger.error(
+            "Nenhum arquivo de audio encontrado em %s\n  Causa provavel: diretorio vazio ou extensoes nao reconhecidas\n  Skill anterior: [nenhuma]",
+            audio_dir,
+        )
+        sys.exit(1)
+    logger.info("Encontrados %d arquivos de audio", len(files))
+
+    log_step(2, "Computando indices acusticos por arquivo")
+    rows = []
+    for i, fpath in enumerate(files, 1):
+        logger.info("  [%d/%d] %s", i, len(files), fpath.name)
+        try:
+            result = process_file(fpath, args.freq_min, args.freq_max)
+        except Exception as e:
+            logger.error("Unexpected error in process_file for %s: %s", fpath.name, e)
+            raise
+        if result:
+            rows.append(result)
+
+    if not rows:
+        logger.error(
+            "Nenhum arquivo processado com sucesso\n  Causa provavel: formato de audio incompativel ou intervalo de frequencia invalido\n  Skill anterior: [nenhuma]"
+        )
+        sys.exit(1)
+    logger.info("%d de %d arquivos processados com sucesso", len(rows), len(files))
+
+    log_step(3, "Escrevendo CSV de serie temporal")
+    # Write timeseries
+    ts_path = output_dir / "acoustic_indices_timeseries.csv"
+    fieldnames = ["file", "datetime", "date", "hour",
+                  "ACI", "BI", "NDSI", "Ht", "Hf", "H"]
+    with open(ts_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)
+    logger.info("Serie temporal escrita: %s (%d linhas)", ts_path, len(rows))
+
+    log_step(4, "Escrevendo resumo por hora do dia")
+    write_summary(rows, output_dir)
+
+    log_step(5, "Gerando heatmap de paisagem sonora")
+    write_heatmap(rows, output_dir)
+
+    logger.info("Computacao de indices acusticos concluida")
+
+
+if __name__ == "__main__":
+    main()