DTMF WAV Generator – generator sygnałów DTMF

DTMF WAV Generator (dtmfgen) to lekkie narzędzie konsolowe napisane w Pythonie, które służy do generowania plików WAV z tonami DTMF (Dual-Tone Multi-Frequency), znanymi powszechnie jako tony wybiercze używane w telefonii stacjonarnej. Program umożliwia tworzenie sekwencji tonów dla cyfr 0–9, znaków specjalnych * i #, a także rozszerzonych klawiszy A–D.

GitHub: github.com/IgorBrzezek/dtmfgen.

Do czego służy dtmfgen?

DTMF WAV Generator rozwiązuje problem potrzeby tworzenia próbek dźwiękowych tonów DTMF do testów, symulacji lub integracji z systemami telekomunikacyjnymi. Przydaje się w wielu scenariuszach:

• Testowanie systemów telefonicznych – generowanie sekwencji tonów do sprawdzania działania central PBX, systemów IVR (Interactive Voice Response) i automatycznych sekretarek.
• Symulacja wybierania numeru – tworzenie plików WAV imitujących wybieranie numeru telefonu, które można użyć w prezentacjach lub szkoleniach.
• Edukacja i badania – analiza widma częstotliwości DTMF, demonstracja działania standardu Bell 202/TIA-470.
• Automatyzacja – generowanie partii plików WAV z różnymi sekwencjami do dalszego przetwarzania w systemach embedded lub VoIP.

Jak to działa – mechanizm wewnętrzny

Każdy znak sekwencji jest mapowany na parę częstotliwości DTMF – jedną z grupy niskiej (697–941 Hz) i drugą z grupy wysokiej (1209–1633 Hz). Program sumuje dwie sinusoidy, normalizuje amplitudę do 16-bitowej wartości maksymalnej (32767) i zapisuje wynik jako próbki mono w formacie WAV.

Sekwencja znaków jest czyszczona z przecinków (które służą jedynie do grupowania) i konwertowana na wielkie litery. Dla każdego znaku generowana jest określona liczba próbek na podstawie czasu trwania tonu (-t) i częstotliwości próbkowania. Między kolejnymi znakami wstawiana jest cisza (-s), przy czym cisza nie jest dodawana po ostatnim znaku sekwencji.

Wymagania

• Python 3.8+ (zalecana wersja 3.10 lub nowsza).
• Standardowe biblioteki Pythona: argparse, wave, math, struct, os, sys, time – brak dodatkowych zależności.
• System operacyjny: Windows, macOS lub Linux.

Instalacja i uruchomienie

Wystarczy skopiować plik dtmfgen.py z repozytorium do dowolnego katalogu i uruchomić z linii poleceń:

python dtmfgen.py -DIAL 123


Plik dialed.wav pojawi się w bieżącym katalogu.

Na systemach Unix warto wcześniej nadać plikowi prawa wykonywania:

chmod +x dtmfgen.py


Opcje wiersza poleceń – szczegółowy opis

Opcja	Opis	Domyślnie
-DIAL SEKWENCJA	Sekwencja znaków do wygenerowania. Dozwolone: cyfry 0–9, *, #, A–D. Przecinki służą do grupowania i są ignorowane.	–
-o, --output PLIK	Nazwa pliku wyjściowego WAV.	dialed.wav
-t, --tone SEK	Czas trwania pojedynczego tonu w sekundach.	0.2
-s, --silence SEK	Długość ciszy pomiędzy kolejnymi znakami w sekundach.	0.1
--freq HZ	Częstotliwość próbkowania.	44100
--overwrite	Nadpisywanie istniejących plików bez pytania.	pyta
--list PLIK_CSV	Ścieżka do pliku CSV dla przetwarzania wsadowego.	–
-h	Skrócona pomoc (zwięzłe użycie).	–
--help	Pełna dokumentacja w konsoli z przykładami.	–

Tryby pracy

Tryb pojedynczego pliku

W tym trybie podajesz sekwencję do wybicia (dialingu) za pomocą parametru -DIAL. Możesz dostosować nazwę pliku wyjściowego, czas trwania tonu, długość ciszy i częstotliwość próbkowania.

Tryb wsadowy (CSV)

Umożliwia przetworzenie wielu wpisów z przygotowanego pliku tekstowego w formacie CSV. Każdy wiersz opisuje jeden docelowy plik WAV i parametry generacji w formacie:

<plik_wyjściowy>, <sekwencja>, <czas_tonu>, <czas_ciszy>


Przykładowy plik CSV (lista.csv):

dial1.wav, 12345, 0.2, 0.1
moj_numer.wav, 060123456, 0.5, 0.2


Linie puste oraz linie zaczynające się od znaku # są ignorowane.

Przykłady użycia

1. Domyślne czasy i nazwa pliku

python dtmfgen.py -DIAL 1,2,3


Generuje plik dialed.wav z tonami dla cyfr 1, 2, 3.

2. Własna nazwa i nadpisywanie

python dtmfgen.py -DIAL 060123456 -o dialed.wav --overwrite


Generuje ton dla sekwencji 060123456 z nadpisywaniem istniejącego pliku.

3. Dłuższe tony i przerwy

python dtmfgen.py -DIAL *#90A -t 0.5 -s 0.2


Tony trwają 0,5 s, przerwy między nimi 0,2 s.

4. Tryb wsadowy z plikiem CSV

python dtmfgen.py --list lista.csv


Program odczytuje wszystkie wpisy z pliku lista.csv i generuje odpowiadające im pliki WAV.

5. Niestandardowa częstotliwość próbkowania

python dtmfgen.py -DIAL 9876 --freq 8000 -o probka.wav


Generuje plik z częstotliwością próbkowania 8 kHz (typowa dla telekomunikacji).

Format pliku CSV

W trybie wsadowym każdy wiersz ma cztery pola oddzielone przecinkami:

• plik_wyjściowy – nazwa pliku WAV do utworzenia,
• sekwencja – znaki do wygenerowania,
• czas_tonu – czas trwania pojedynczego tonu w sekundach,
• czas_ciszy – długość ciszy w sekundach.

Dobre praktyki i wskazówki

• Unikaj przesterowania: pozostaw standardową amplitudę – pliki będą kompatybilne z większością odtwarzaczy.
• Spójne czasy: dla symulacji wybierania numerów telefonicznych typowe wartości to 0,2 s dla tonu i 0,1 s dla przerwy.
• Grupowanie przecinkami: możesz używać przecinków do grupowania cyfr (np. 48,60,123,456) – program je usunie.
• Nazewnictwo plików: dla wsadów używaj jednoznacznych nazw, np. klient01.wav, klient02.wav.

Rozwiązywanie problemów

• „Plik już istnieje”: użyj parametru --overwrite lub podaj inną nazwę przez -o.
• „You must provide -DIAL sequence or a –list file”: uruchom program z parametrem -DIAL albo --list.
• „List file not found”: sprawdź ścieżkę do pliku CSV.
• „Skipping invalid line”: upewnij się, że wiersz CSV ma 4 pola i poprawne wartości liczbowe dla czasu tonu i ciszy.
• Plik wynikowy jest pusty lub za krótki: sprawdź wartości parametrów -t, -s i --freq.

Podsumowanie

DTMF WAV Generator to proste, ale funkcjonalne narzędzie do generowania tonów wybierczych DTMF. Dzięki czystemu Pythonowi i brakowi zewnętrznych zależności działa natychmiast po ściągnięciu, bez żadnej konfiguracji. Obsługa dwóch trybów pracy (pojedynczego pliku i wsadowego) oraz regulacja wszystkich kluczowych parametrów (częstotliwość próbkowania, czas tonu, czas ciszy) czynią go uniwersalnym rozwiązaniem zarówno do testów, jak i do zastosowań produkcyjnych.

Program jest rozwijany przez autora Igora Brzeżka i dystrybuowany do pobrania na GitHubie: github.com/IgorBrzezek/dtmfgen.