Wavegen – generator plików WAV z syntezą addytywną

Wavegen to lekki, samodzielny generator plików audio WAV napisany w czystym Pythonie (bez zewnętrznych bibliotek). Program działa z wiersza poleceń i umożliwia tworzenie próbek dźwiękowych z wykorzystaniem syntezy addytywnej – może sumować wiele oscylatorów jednocześnie, generować fale sinusoidalne, prostokątne i piłokształtne, a także obsługuje przetwarzanie wsadowe z plików CSV.

Wavegen to idealne narzędzie dla programistów, muzyków elektronicznych, studentów przetwarzania audio oraz każdego, kto potrzebuje szybko wygenerować proste pliki WAV bez instalowania ciężkiego oprogramowania.

GitHub: github.com/IgorBrzezek/wavegen

Do czego służy Wavegen?

Wavegen rozwiązuje problem generowania plików WAV z wiersza poleceń bez żadnych zależności. Przydaje się w wielu scenariuszach:

• Testowanie sprzętu audio – generowanie próbek o konkretnych częstotliwościach do testowania głośników, słuchawek lub układów elektronicznych.
• Edukacja – nauka działania syntezy dźwięku, dodawania fal, próbkowania i kwantyzacji.
• Produkcja muzyki – szybkie tworzenie próbek bazowych do dalszego przetwarzania w DAW.
• Praca badawcza – generowanie sygnałów testowych do analizy widmowej, badania aliasingu czy odpowiedzi częstotliwościowej.
• Automatyzacja – generowanie partii plików WAV z różnymi parametrami za pomocą plików wsadowych.

Jak to działa – mechanizm wewnętrzny

Wavegen generuje plik WAV krok po kroku:

1. Parser argumentów wiersza poleceń odczytuje parametry: typ fali, częstotliwości, czas trwania, głębię bitową i częstotliwość próbkowania.
2. Dla każdej próbki czasowej obliczana jest wartość fali dla każdego z zadanych oscylatorów z osobna.
3. Wartości wszystkich oscylatorów są sumowane (synteza addytywna).
4. Amplituda wynikowa jest normalizowana – dzielona przez liczbę sumowanych częstotliwości, aby uniknąć przesterowania (clippingu).
5. Wartość jest kwantowana do wybranej głębi bitowej (8 lub 16 bitów).
6. Dane są zapisywane do pliku WAV za pomocą standardowego modułu wave z biblioteki standardowej Pythona.
7. Program wyświetla podsumowanie: nazwę pliku, parametry, czas generowania i rozmiar pliku.

Dostępne typy fal:

• Sinusoidalna (sine) – sin(2π f t), czysta fala, podstawowy budulec dźwięku.
• Prostokątna (square) – sign(sin(2π f t)), wartości ±1, bogata w harmoniczne nieparzyste.
• Piłokształtna (sawtooth) – 2 * (t*f - floor(0.5 + t*f)), zawiera pełne spektrum harmonicznych.

Wymagania

• Python 3.7 lub nowszy
• Brak zewnętrznych bibliotek – program korzysta wyłącznie z modułów wbudowanych: wave, math, struct, argparse, os, sys, time.
• System operacyjny: dowolny z Pythonem 3 (Windows, Linux, macOS).

Instalacja i uruchomienie

Nie potrzeba instalacji. Wystarczy pobrać plik wavegen.py i uruchomić go bezpośrednio:

python wavegen.py --help

Na systemach Unix/Linux/macOS można też ustawić atrybut wykonywalności:

chmod +x wavegen.py
./wavegen.py --help

Opcje wiersza poleceń – szczegółowy opis

Opcja	Alias	Typ / Wartości	Domyślnie	Opis
-h	—	flaga	—	Krótka pomoc
--help	—	flaga	—	Pełna dokumentacja z metadanymi i przykładami
-o	--output	tekst	output.wav	Nazwa pliku wynikowego
--overwrite	—	flaga	wył.	Nadpisywanie bez pytania
--list	—	ścieżka	—	Tryb wsadowy – plik CSV z listą plików do wygenerowania
-t / --time / -len	—	sekundy	1,0	Czas trwania sygnału
--wave	—	sine, square, sawtooth	sine	Typ fali
-f	--frequency	tekst (lista po przecinku)	440	Lista częstotliwości w Hz, np. 440,880
--freq	—	liczba całkowita Hz	44100	Częstotliwość próbkowania
--bit	—	8 lub 16	16	Głębia bitowa

Format pliku wsadowego (batch mode)

Tryb wsadowy uruchamia się opcją --list <plik>. Plik powinien zawierać linie w formacie CSV:

nazwa_pliku, częstotliwość_próbkowania, głębia_bitowa, częstotliwości...

Linie zaczynające się od # oraz puste linie są ignorowane. Każda linia musi mieć co najmniej 4 pola oddzielone przecinkami.

Przykładowy plik wsadowy (batch.txt):

# nazwa_pliku, sample_rate, bit_depth, frequencies
out1.wav, 44100, 16, 100,200,300
out2.wav, 48000, 8, 220,440
out3.wav, 32000, 16, 440

Uruchomienie:

python wavegen.py --list batch.txt --wave sine --time 2 --overwrite

Typ fali i czas trwania są pobierane z opcji wiersza poleceń; częstotliwość próbkowania, głębia bitowa i częstotliwości pochodzą z każdej linii pliku.

Pełne przykłady użycia

1. Domyślna fala sinusoidalna (A4)

python wavegen.py -o sine440.wav -f 440

Generuje 1-sekundową falę sinusoidalną 440 Hz, 16-bit, 44,1 kHz, mono.

2. Fala prostokątna z wieloma częstotliwościami (3 sekundy)

python wavegen.py -f 100,200,300 -t 3 --wave square --overwrite -o square_mix.wav

Generuje 3-sekundową mieszaninę fal prostokątnych o częstotliwościach 100, 200 i 300 Hz.

3. Fala piłokształtna, 8-bit, niższe próbkowanie

python wavegen.py --wave sawtooth --bit 8 --freq 22050 -f 220,440 -o saw_8bit_22k.wav

4. Synteza addytywna – trójdźwięk

python wavegen.py -f 261.63,329.63,392.00 -t 2 -o triad_c_major.wav

Generuje 2-sekundowy trójdźwięk C-dur (C4, E4, G4) z falą sinusoidalną.

5. Generowanie wsadowe z pliku listy

python wavegen.py --list batch.txt --wave sine --time 1 --overwrite

Przetwarza wszystkie linie z pliku batch.txt, generując pliki WAV z parametrami określonymi w każdej linii.

6. Najwyższa jakość – 16-bit, 48 kHz

python wavegen.py -f 440 --freq 48000 --bit 16 -o high_quality.wav

7. Krótki sygnał testowy (0,1 sekundy)

python wavegen.py -f 1000 -t 0.1 -o click.wav

Przydatne do testowania opóźnień lub generowania sygnałów impulsowych.

Ograniczenia i uwagi

• Program generuje wyłącznie pliki mono (jeden kanał).
• Brak filtracji antyaliasingowej – bardzo wysokie częstotliwości bliskie lub powyżej granicy Nyquista (połowa częstotliwości próbkowania) będą aliasingować.
• Fale prostokątne i piłokształtne są generowane prostymi wzorami (bez band-limiting), co może wprowadzać harmoniczne powyżej Nyquista.
• W trybie pojedynczego pliku, jeśli plik już istnieje i nie podano --overwrite, program zapyta o zgodę na nadpisanie.
• Amplituda jest dzielona przez liczbę sumowanych częstotliwości – przy bardzo wielu częstotliwościach sygnał może być cichy.

Różnica między 8 a 16 bitami

Cecha	8-bit	16-bit
Zakres dynamiczny	~48 dB	~96 dB
Kodowanie	Unsigned byte (0-255, środek 128)	Signed short little-endian (-32768 do 32767)
Rozmiar pliku	2x mniejszy	2x większy
Jakość	Słabsza, szum kwantyzacji słyszalny	Dobra, standard CD

Podsumowanie

Wavegen to eleganckie, minimalistyczne narzędzie do generowania plików WAV w czystym Pythonie. Dzięki syntezie addytywnej pozwala tworzyć złożone struktury harmoniczne bez żadnych zewnętrznych bibliotek. Bogaty zestaw opcji (trzy typy fal, regulowana głębia bitowa, częstotliwość próbkowania, tryb wsadowy) sprawia, że sprawdzi się zarówno w edukacji, jak i w profesjonalnych zastosowaniach inżynierskich.

To doskonały przykład, jak napisać funkcjonalny, samodzielny generator audio przy użyciu wyłącznie standardowej biblioteki Pythona – bez Pillow, bez numpy, bez scipy.

Źródła: github.com/IgorBrzezek/wavegen