Do odtwarzania dźwięków używana jest własna biblioteka BasicSND, domyślnie załączana w BasicSDL, lub SDL_mixer. Obsługuje dowolną liczbę jednocześnie odtwarzanych kanałów 16-bitowego dźwięku stereo, domyślnie 16 dla BasicSND i 8 w SDL_mixer, + jeden kanał muzyczny. SDL_mixer wykorzystuje popularne biblioteki FLAC, MikMod MOD, Timidity MIDI, Ogg Vorbis i SMPEG MP3. BasicSND obsługuje formaty WAV, OGG, MOD i MIDI, posiada ponadto możliwość zmiany częstotliwości dźwięków, odtwarzania dźwięków MIDI, generator dźwięków syntezowanych i prosty sekwencer. Można też użyć BASSND - uproszczonej wersji BasicSND - pozbawionej obsługi muzyki, MIDI i akordów, jest za to mniejsza i troszkę szybsza, obsługuje WAV, OGG i MOD. Częstotliwość odtwarzania domyślnie wynosi 22050 Hz, do tej częstotliwości konwertowane są dźwięki podczas ładowania do pamięci. Można ją zmienić modyfikując w pliku BasicSDL.h zapis #define SOUNDFREQUENCY 22050 lub dodając go do programu przed #include "BasicSDL.h". Przy odtwarzaniu sekwencji dźwięków zaleca się, by ta częstotliwość była wielokrotnością SNDSpec.samples.
Dźwięk a muzyka Dźwięk jest w całości zapisany w pamięci w postaci nieskompresowanej. Na raz można odtworzyć tyle dźwięków - ile jest kanałów dźwiękowych. Muzyka może być zapamiętywana w określonym formacie lub odczytywana na bieżąco z pliku i podczas odtwarzania dekodowana "w locie" fragmentami. Jednocześnie obsługiwana jest tylko jedna muzyka.
BasicSND Jest podstawowym mikserem dźwięków BasicC zapisanym w krótkim pliku BasicSND.h, który jest załączany w BasicSDL.h. Po drobnych zmianach może być też używany bezpośrednio w C + SDL. Domyślnie obsługuje 16 wirtualnych kanałów dźwiękowych, ilość tę można zmienić, zmieniając wartość stałej: #define SNDCHANNELS 16 w pliku BasicSND.h lub własnym programie. "Kanał" jest strukturą typu struct SNDChan o polach: Uint8 play; stan odtwarzania: wartość 0 oznacza brak odtwarzania na kanale, 1 - odtwarzanie, 2 - dźwięk MIDI, 3 - przerwa pomiędzy dźwiękami, gdy odtwarzana jest sekwencja dźwięków SNDSample*spl; wskaźnik na dźwięk przypisany do kanału, 0 (NULL) gdy brak przypisania Uint8*data; wskaźnik na dane dźwięku do odtwarzania na kanale, 0 dla MIDI Uint32 dpos; aktualny nr bajtu danych odtwarzanego dźwięku, powinien być wielokrotnością 4, ponieważ pojedyncza próbka składa się z 4 bajtów (po 2 bajty na kanał lewy i prawy) Uint32 dlen; zawiera ilość bajtów danych dźwięku Uint8 loop; ilość odtworzeń dźwięku, 0 - powtarzanie w nieskończoność double(*waveform)(double); wskaźnik na funkcję generującą dźwięk, domyślnie sin float freq; częstotliwość generowanego dźwięku lub mnożnik częstotliwości dla SNDSample lub nr nuty MIDI float gainL; głośność kanału lewego, powinna mieścić się w przedziale 0-1 float gainR; głośność kanału prawego Uint32 duration; "długość" dźwięku w bajtach, wielokrotność 4 Uint32 attack; "czas" narastania dźwięku w bajtach do osiągnięcia danej głośności Uint32 release; "czas" zakończenia dźwięku, w którym głośność opada do 0 float*seq; wskaźnik na tablicę zawierającą sekwencję dźwięków Arr(-duration,freq,...) Uint16 spos; indeks tablicy seq wskazujący kolejny dźwięk Uint16 slen; ilość elementów w tablicy seq
Struktury te są przechowywane w tablicy SNDChan. Odtwarzane mogą być dźwięki próbkowane (np. typu .wav - odczytane z pliku), na które wskazuje SNDChan[c].spl (c - nr kanału), lub generowane przez funkcję wskazywaną przez SNDChan[c].waveform, jeśli spl wskazuje na NULL. Prócz .wav obsługiwany jest format .MOD, poprzez bibliotekę micromod.h, oraz .OGG, poprzez BasicOGG.h, która jest okrojoną biblioteką STB_vorbis. Jeśli nie korzystamy z tych formatów można wyłączyć te biblioteki poprzez usunięcie lub skomentowanie w pliku BasicSND.h zapisów #include "BasicOGG.h" i/lub #include "micromod.h". MOD może być ładowany również jako muzyka. Dźwięki przechowywane są w strukturach typu SNDSample o polach: Uint8*data; - dane próbek dźwiękowych, Uint32 len; - długość tych danych w bajtach, float vol; - głośność 0-1. Przy deklaracji zmiennych tego typu powinno się zainicjować ich pola zerami, np. SNDSample nazwa_zmiennej={0};
W zmiennej strukturalnej SNDSpec typu SDL_AudioSpec zawarta jest specyfikacja próbek dźwiękowych: SNDSpec.freq = SOUNDFREQUENCY; częstotliwość, domyślnie 22050 SNDSpec.format = AUDIO_S16SYS; format - 16 bitów ze znakiem (Sint16) SNDSpec.channels = 2; ilość kanałów wyjściowych: 2 (stereo) SNDSpec.samples = 500; ilość próbek przetwarzanych "na raz" przez funkcję SND_Mixe. Wg dokumentacji SDL powinna być potęgą 2, ale by dokładnie odtwarzać sekwencje - powinna być dzielnikiem SOUNDFREQUENCY SNDSpec.callback = SND_Mixe; funkcja miksująca dźwięki, wywoływana automatycznie, okresowo SNDSpec.userdata = NULL; wskaźnik na dane "użytkownika", aktualnie nieużywane.
Obsługiwana jest muzyka w formatach MOD oraz MID (pliki MI*, również pliki KAR - po zmianie końcówki na .MID). Do odtwarzania MIDI w systemach Windows wykorzystywana jest biblioteka windows.h + mmsystem.h (MCI) załączana w BasicSDL.h, w Linux fluidsynth.h załączana w BasicSND.h. libfluidsynth musi być zainstalowane wraz z libfluidsynth-dev i fontami dźwiękowymi sf2 w /usr/share/sounds/sf2/default-GM.sf2 (można to zmienić w pliku BasicSND.h w funkcji SND_FluidOpen). Jeśli nie wykorzystujemy funkcji danej biblioteki - najlepiej ją odłączyć. Dane muzyki zawiera zmienna SNDMusic typu struct SNDMusic o polach: Uint8 typ; wartość 0 - brak muzyki, 1 - MIDI MCI, 2. MIDI fluidsynth, 3 - wstrzymane odtwarzanie, 4 - MOD, 5 - MOD wstrzymane void*data; wskaźnik na dane wczytane z pliku MOD, nie wykorzystywane w MIDI.
Do odtwarzania dźwięków MIDI w Linuksie wymagana jest biblioteka fluidsynth.h, która jest domyślnie załączana w BasicSND.h.
Można korzystać bezpośrednio z funkcji danej biblioteki. W MCI wykorzystywana jest funkcja mciSendString, muzyka posiada alias m. W Fluidsynth wykorzystywane są zmienne fluid_player, fluid_synth, fluid_settings, fluid_audio.
System dźwiękowy jest inicjowany automatycznie komendą SDLOpen i zamykany przez SDLQuit. Jeśli nie chcemy otwierać innych elementów SDL - możemy inicjować komendą SND_init();, a zamknąć poprzez SND_quit();. Inicjacja, oprócz otwarcia urządzenia dźwiękowego SDL z odpowiednimi parametrami zapisanymi w SNDSpec, powoduje, dla wszystkich kanałów: wywołanie Wave(kanał,sin,0,0), ustawienie głośności na 1 i wyzerowanie pozostałych parametrów. Przed zamknięciem programu należy dodatkowo usunąć wszystkie używane zmienne typu SNDSample komendą DeleteSound. Odtwarzanie wstrzymujemy komendą SDL_PauseAudio(1);, przywrócenie odtwarzania: SDL_PauseAudio(0);. Nie dotyczy to muzyki MIDI MCI odtwarzanej przez system Windows.
Komendy Basic:
ChannelPanning(channel,left,right) Ustawia głośność (powinna mieścić się w zakresie 0-1) lewego (left) i prawego (right) kanału o nr channel. Nie działa dla MIDI.
DeleteMusic Zatrzymuje muzykę i usuwa dane.
DeleteSound(S) Usuwa dane dźwięku S i ustawia wskaźnik danych na NULL. S jest zmienną typu SNDSample.
FluidOpen Otwiera syntezator fluid_synth i przypisuje do niego sterownik fluid_audio (domyślnie ALSA). Jest to wymagane do odtwarzania dźwięków MIDI. Domyślnie fluidsynth jest też automatycznie otwierany w Linuksie komendą LoadMusic wywoływaną dla pliku MIDI, wtedy korzysta ze sterownika SDL, otwierany jest też fluid_player. Fluidsynth nie może być jednocześnie otwarty dla odtwarzania dźwięków MIDI i muzyki MIDI, fluidsynth jest zamykany komendą FluidClose lub DeleteMusic (jeśli załadowana jest muzyka MIDI).
FluidClose Zamyka fluidsynth. Wywołuje go też komenda DeleteMusic, jeśli muzyka korzysta z fluidsynth.
MidiChannelBallance(c,b) Ustawia balans głośników dla kanału MIDI. Kanały numerowane są od 0 do 15, więc np. kanał 10 MIDI ma nr c=9. b przyjmuje wartości 0-127.
MidiChannelExpire(c) Wygasza dźwięki MIDI (all notes off) na kanale c.
MidiChannelVol(c,v) Ustawia głośność MIDI kanału c, v: 0-127
MidiSeq(c,m,l) Uruchamia odtwarzanie sekwencji dźwięków MIDI na kanale c zapisaną w tablicy m (patrz komendy PlaySeq i Sound Seq) l-krotnie (dla 0 w nieskończoność). Wszystkie dźwięki akordów MIDI odtwarzane są na jednym kanale. Wywołuje procedurę SND_sequence(c,0,m,0,sizeof m/sizeof(m),l,1);
MidiSound(c,k,d,l) Odtwarza dźwięk MIDI k (2-127, np. 60 dla C4) na kanale c (0-15) o długości d (w sekundach) l razy (lub w nieskończoność dla 0). Kanał 9 przypisany jest do perkusji.
MidiVoice(c,v) Określa instrument v MIDI dla kanału c. v jest numerem MIDI od 1 do 128, pomimo, że w fluidsynth numeracja instrumentów, podobnie jak kanałów, zaczyna się od 0. W przypadku perkusji podajemy kanał 9 i instrument 1.
HaltChannel(c) Zatrzymuje odtwarzanie na kanale c i zwalnia pamięć danych dźwiękowych przypisanych do kanału c.
LoadMusic(FM) Ładuje plik muzyczny o nazwie FM i przypisuje go do zmiennej SNDMusic. Zmienna jest zadeklarowana w BasicSND. Dla MIDI MCI nazwa pliku nie może przekraczać 114 znaków.
LoadSound(S,FS) Ładuje dźwięk z pliku o nazwie FS i przypisuje do zmiennej S. Zmienna jest typu SNDSample i musi być wcześniej zadeklarowana. Wywołuje funkcję SND_LoadSound(FS,&S,1);, którą można wywołać bezpośrednio pamiętając o umieszczeniu średnika na końcu oraz znaku & przed zmienną S. Ostatnim parametrem funkcji jest mnożnik częstotliwości - 1 oznacza zachowanie oryginalnej wysokości dźwięku, a np. 2 - dźwięk będzie odtwarzany z 2x większą wysokością. Jeśli wskaźnik S.data był różny od NULL - pamięć danych S zostaje zwolniona (jeśli danych nie było - wystąpi błąd) przed załadowaniem nowych danych.
MusicVolume(volume) Ustawia głośność muzyki na volume 0-1. Wpływa też na głośność dźwięków MIDI fluidsynth. Nie działa dla MIDI MCI w Windows.
MulSoundFreq(S,SS,mul) Konwertuje dźwięk SS typu SNDSample mnożąc jego częstotliwość (wysokość) przez mul, skonwertowany dźwięk przypisuje do S. Zmienna S jest typu SNDSample i musi być wcześniej zadeklarowana, a jej wskaźnik danych powinien wynosić NULL. Gdy w miejsce S podamy SS - do SS zostaną przydzielone nowe dane dźwiękowe, a stare zostaną zwolnione. Komenda wywołuje funkcję SND_ConvertFrequency(Uint8*sdata,Uint32 slen,SDL_AudioSpec Spec,Uint8**ddata,float mul), parametry oznaczają: *sdata - wskaźnik na źródłowe dane dźwiękowe (do skonwertowania) slen - długość danych sdata w bajtach Spec - specyfikacja danych źródłowych **ddata - wskaźnik na wskaźnik danych wyjściowych dźwięku, czyli jeśli np. *data jest zmienną wskaźnikową na dane - w wywołaniu funkcji wpisujemy &data. mul - mnożnik częstotliwości danych źródłowych Po wykonaniu tej funkcji zwrócona zostanie wartość typu Uint32 zawierająca długość skonwertowanych danych, a zmienna odpowiadająca parametrowi ddata będzie zawierała wskaźnik na skonwertowane dane do formatu określonego w SNDSpec, przy czym częstotliwość źródłowa będzie przemnożona przez mul. UWAGA! Może się zdarzyć, np. jeśli przy deklaracji zmiennej nie zainicjujemy jej wartością NULL, że sdata i ddata będą wskazywały ten sam adres, co spowoduje zwolnienie wcześniejszych danych, a co nie musi być zgodne z oczekiwaniami programisty.
PauseChannel(channel) Wstrzymuje odtwarzanie na kanale o nr channel do momentu wywołania ResumeChannel lub innej komendy rozpoczynającej odtwarzanie.
PauseMusic Wstrzymuje odtwarzanie muzyki.
PlayMusic(loops) Odtwarza muzykę loops razy. Gdy loops=0 powtarza w nieskończoność. Dla MIDI MCI w Windows nie można odtwarzać w pętli, a po zakończeniu odtwarzania należy "przewinąć" na początek, jeśli chcemy odtworzyć ponownie. W starszych wersjach Fluidsynth w Linux po zakończeniu odtwarzania raczej nie można odtworzyć ponownie, należy znów załadować plik muzyczny komendą LoadMusic.
PlayingMusic Zwraca 1 jeśli gra muzyka, 0 jeśli nie.
PlayingChannel(channel) Status kanału channel: wartość 0 oznacza brak odtwarzania na kanale, 1 - odtwarzanie, 2 - dźwięk MIDI, 3 - przerwa pomiędzy dźwiękami, gdy odtwarzana jest sekwencja dźwięków.
PlaySound(channel,S,pitch,loops)