libpo32

Una piccola libreria C99 per i trasferimenti di dati acustici e la sintesi di batteria del Teenage Engineering PO-32.

libpo32 reimplementa lo stack di trasferimento del PO-32 Tonic e un modello di voce di batteria compatibile. Non è un firmware PO-32 completo né un emulatore di interfaccia; copre il formato dei pacchetti, il modem acustico, il decodificatore di frame e la sintesi di batteria locale necessari per costruire, inviare, ricevere e visualizzare in anteprima i trasferimenti PO-32.

Panoramica

Area	Cosa fornisce `libpo32`
Protocollo di trasferimento	Costruisce e analizza pacchetti di patch, pattern e stato PO-32
Modem acustico	Renderizza frame di trasferimento in audio DPSK per la riproduzione nel dispositivo
Decodificatore	Recupera frame e pacchetti normalizzati dall'audio di trasferimento
Sintesi di batteria	Renderizza localmente la voce di batteria a 21 parametri del PO-32 per anteprima e test

Il nucleo è C99 freestanding: nessun runtime libc, nessuna libreria DSP esterna, nessuna API audio di piattaforma, nessuna I/O su file. Vengono utilizzati solo gli header freestanding <stddef.h> e <stdint.h>. Adatto per target embedded e ambienti bare-metal.

Utilizzo con un PO-32

Il PO-32 non riceve audio di batteria finito quando si trasferisce un suono o un pattern. Riceve dati strutturati:

Dati	Significato
Pacchetti di patch	I due endpoint di patch per strumento (`Left` e `Right`), con lo slot dello strumento di destinazione codificato nel pacchetto
Pacchetti di pattern	Quali strumenti si attivano su quali step, con lo slot di pattern di destinazione codificato come `pattern_number`
Pacchetto di stato	Tempo, swing, default di morph e l'elenco dei pattern trasferiti

Il dispositivo utilizza quindi il proprio motore di sintesi interno per trasformare quei parametri in suono.

A livello generale, il flusso di lavoro con hardware reale è:

Passo	Cosa si fa
1	Costruire un trasferimento nel software a partire da dati di patch, pattern e stato
2	Renderizzare quel trasferimento in un WAV o in un flusso audio live
3	Mettere il PO-32 nel suo normale flusso di ricezione/importazione
4	Riprodurre l'audio di trasferimento renderizzato nel dispositivo
5	Il PO-32 decodifica i pacchetti e li scrive negli slot di suono o pattern nominati all'interno di quei pacchetti

Per Iniziare

Dalla radice del repository, configurare, compilare, eseguire i test e poi la demo:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j4
ctest --test-dir build --output-on-failure
./build/po32_demo

Opzionale, ma consigliato per lo sviluppo locale:

./scripts/install-git-hooks.sh

Questo abilita l'hook pre-commit gestito dal repository, che esegue clang-format sui file .c e .h in stage prima di ogni commit e valida i soggetti dei commit rispetto a Conventional Commits. L'hook pre-push gestito dal repository esegue lo script di analisi statica prima del push.

L'hook pre-commit richiede clang-format 18 e fallisce con qualsiasi altra versione principale; vedere CONTRIBUTING.md per le opzioni di installazione.

La demo costruisce un frame di trasferimento, lo renderizza in audio, lo decodifica nuovamente (verificando un roundtrip senza perdite), sintetizza un colpo di batteria e scrive due file WAV: demo_modem.wav e demo_kick.wav.

Installazione e Utilizzo

cmake --install distribuisce la libreria statica, gli header, un pacchetto CMake e un file pkg-config, quindi entrambi i percorsi di utilizzo funzionano immediatamente:

find_package(LibPO32 0.2 REQUIRED)
target_link_libraries(app PRIVATE LibPO32::po32)

cc app.c $(pkg-config --cflags --libs po32) -lm

Esempi

Comando	Scopo
`./build/po32_example`	Roundtrip minimo: codifica, renderizza, decodifica e verifica
`./build/po32_demo`	Demo end-to-end: costruzione/renderizzazione/decodifica del frame di trasferimento più sintesi di batteria locale
`./build/po32_pattern_editor`	Modifica interattiva dei pattern PO-32 ed esportazione WAV
`./build/po32_decode_capture <input.wav> <out-dir>`	Dump di pacchetti e pattern da un WAV di trasferimento

Progetti Realizzati con libpo32

Progetto	Cosa fa
Libpo32 for Schwung	Un modulo sintetizzatore di batteria a 16 voci per Schwung su Ableton Move, alimentato da `libpo32`

API Pubblica

Header	Responsabilità
`core/include/po32.h`	Costruttore di trasferimenti, helper per pacchetti, renderizzatore e decodificatore
`core/include/po32_synth.h`	Sintetizzatore di batteria

Documentazione

Documento	Scopo
Architettura	Come funziona il codec
Protocollo	Dettagli del formato wire
API C	Riferimento delle funzioni C
Sintesi	Percorso del segnale del sintetizzatore
Parametri di Patch	I 21 parametri
Binding	Come scrivere un nuovo binding linguistico
Esempi	Programmi di esempio supportati
Fuzzing	Harness di fuzzing e proprietà differenziali
Contribuire	Configurazione locale, controlli e convenzioni di commit

Struttura del Progetto

Percorso	Scopo
`core/src`	Implementazione C principale
`core/include`	Header C pubblici
`core/examples`	Esempi C supportati
`core/tests`	Copertura dei test principali
`core/fuzz`	Harness libFuzzer per ogni superficie di input non attendibile
`core/docs`	Note su architettura, protocollo e API
`bindings/go`	Binding Go (cgo, avvolge l'intera API pubblica)

Contribuire

Vedere CONTRIBUTING.md per la configurazione locale, i comandi di verifica e la policy Conventional Commits utilizzata per una cronologia compatibile con SemVer.

Licenza

libpo32 v0.3.0

Categorie