Audio, WAV e segnali — GX-TXT Documentation

Versione verificata

Framework	GX-TXT 0.9.8.10-dev-031
Import generico	`acq.audio` 1.0.1
Import PCM WAV	`acq.wav` 1.0.0
Decoder numerico	`analysis.audio_decode` 2.0.1

1. I due percorsi

Percorsi audio GX-TXT — La differenza è contrattuale: `audio.source` conserva una sorgente audio generica; `audio.waveform` rappresenta una sorgente PCM neutra adatta al decoder Analysis attuale.

2. acq.audio: sorgenti audio generiche

acq.audio importa sorgenti self-describing supportate da Audio Decode API / FFmpeg+FFprobe, ad esempio WAV, FLAC, MP3, AAC/M4A, OGG/Vorbis/Opus e altri formati riconosciuti dall'installazione corrente.

Può inoltre importare raw PCM headerless .pcm/.raw, ma soltanto se specifichi esplicitamente:

sample format (u8, s16le, s24le, f32le, ecc.);
sample rate;
numero di canali.

Non inferisce questi dati dal filename o dalla dimensione del file.

3. Il contract audio.source

L'output è un Dataset opaco audio.source. I byte originali restano autorevoli e vengono conservati byte-for-byte. L'importatore non:

decodifica campioni;
normalizza;
resampla;
mixa canali;
genera colonne tempo/ampiezza.

FFprobe technical metadata e tag vengono invece pubblicati attraverso Dataset Metadata API.

4. Metadata audio

Fra i campi possibili:

audio.container
audio.codec
audio.sample_rate_hz
audio.channels
audio.channel_layout
audio.sample_format
audio.bits_per_sample
audio.title
audio.artist
audio.album
tags.container.*
tags.stream.*

I metadata non cambiano l'identità o i byte della sorgente.

5. Raw PCM

I tre parametri raw PCM sono configuration fields del modulo e quindi valgono per l'intero batch corrente. Se file raw diversi hanno sample format, rate o channel count differenti, importali in passaggi incrementali separati.

6. acq.wav: WAV linear-PCM neutro

acq.wav ha un obiettivo più stretto: accetta soltanto WAV con linear PCM integer o IEEE float, verificando il contenuto del fmt chunk e non la sola estensione.

Un WAV contenente ADPCM, mu-law o MP3 viene rifiutato anche se termina in .wav.

L'output è un Dataset binario opaco audio.waveform. Anche qui l'import non effettua decoding.

7. Quale importatore scegliere?

Scopo	Scelta
Archiviare/preservare MP3, FLAC, AAC, OGG o audio generico	`acq.audio` → `audio.source`
Archiviare raw PCM headerless con parametri espliciti	`acq.audio` → `audio.source`
Importare WAV linear-PCM e poi usare il decoder Analysis corrente	`acq.wav` → `audio.waveform`

Contract corrente del decoder

Nella dev-031 analysis.audio_decode dichiara come input audio.waveform. Non assumere che un generico audio.source venga accettato automaticamente dal modulo solo perché CORE Audio Decode API può riconoscere più codec.

8. analysis.audio_decode

Il decoder Analysis usa CORE Audio Decode API v1 e Dataset Publication API v2. I campioni vengono elaborati a blocchi di 65.536 frames e pubblicati senza creare un PCM intermedio completo né un grande CSV decimale.

Storage Auto sceglie un provider con capability append/typed numeric/implicit axis appropriate.

9. Dataset numerico risultante

Schema timeseries audio decodificato — Il tempo è una coordinata uniforme implicita; i canali sono variabili numeriche associate alla stessa dimensione sample.

Identità logiche:

dimension_id = sample
coordinate variable_id = time
channel variable_ids = channel_1, channel_2, ...

Nomi canonici compatibili:

time_s
ch1
ch2
...

10. Tempo implicito

La coordinata tempo non deve essere materializzata una volta per campione:

origin = 0
step   = 1 / sample_rate
count  = decoded frame count

Canonical Dataset API e Table Stream ricostruiscono soltanto l'intervallo richiesto.

11. Ampiezza

La convenzione scientifica del decoder conserva normalized full-scale:

PCM integer normalizzato a FS;
floating PCM non clippato artificialmente a ±1;
amplitude_scale applica un moltiplicatore lineare;
amplitude_unit può restare FS oppure rappresentare una unità calibrata, per esempio V.

12. Multi-channel

L'importatore audio generico conserva il numero/layout canali come metadata. Il decoder crea invece variabili numeriche separate per i canali decodificati, tutte riferite alla stessa coordinata temporale.

13. Downstream

Un timeseries.table audio decodificato può essere letto da Canonical Dataset API, Table Stream e Plot Dataset e costituisce la base per analisi di segnale/spettro compatibili.