Главная » 2011»Июль»22 » Краткая справка на русском языке (русский help) по библиотеке BASS 2.4.
19:14
Краткая справка на русском языке (русский help) по библиотеке BASS 2.4.
Краткая справка на русском языке (русский help) по библиотеке BASS.dll версии 2.4.
Для любителей писать плееры на Delphi я выкладываю краткую справку по библиотеке bass.dll. Последнюю версию библиотеки можно скачать с официального сайта www.un4seen.com.
Библиотека BASS достаточно проста в использовании, имеет небольшой размер и поддерживает следующие возможности:
воспроизведение звуковых образцов (сэмплов) в формате WAV/AIFF/MP3/MP2/MP1/OGG; потоковое воспроизведение звуковых файлов в формате MP3/MP2/MP1/OGG/WAV/AIFF; потоковое воспроизведение звука из интернет (по протоколам http и ftp, с поддержкой серверов Shoutcast, Icecast & Icecast2); воспроизведение файлов музыкальных форматов (XM, IT, S3M, MOD, MTM, UMX), а также формата MO3 (mod музыка, сжатая MP3/OGG); запись звука; поддержка эффектов обработки звуков и эффектов DirectX 8 (только для Win32): Chorus / compressor / distortion / echo / flanger / gargle / parametric eq / reverb и т.д.; поддержка многоканального (а не только стерео) звука, в том числе и многоканальных OGG/WAV/AIFF файлов; поддержка многопотоковых звуковых карт; поддержка позиционируемого 3D звука и EAX; поддержка расширений (плагинов); и многое другое.
Основные понятия
Как и в большинстве библиотек для работы со звуковыми данными, в BASS представлены следующие звуковые объекты:
sample (сэмплы) - относительно небольшой оцифрованный звуковой фрагмент. "Небольшие" означает, что эти звуковые данные целиком загружаются в память. stream (потоки) - это звуковые данные, которые считываются порциями из звуковых файлов или из интернета и тут же передаются на воспроизводящее устройство. Потоковое воспроизведение позволяет проигрывать большие по размеру звуковые файлы и при этом не загружать их целиком в память. mod music (музыкальные модули) - это данные, представленные в музыкальных (так называемых "трекерных") форматах. В файлах с трекерной музыкой, как правило, содержатся команды для воспроизводящей программы (например, наподобие нотной записи) и образцы звучания инструментов, которые используются при воспроизведении (синтезе) этого музыкального модуля.
Непосредственное воспроизведение звука происходит через так называемые "каналы", поэтому все виды звуковых данных (sample, stream и mod music) связываются с каналами воспроизведения звука.
Основные функции библиотеки BASS:
Функции управления библиотекой (конфигурирование, инициализация, выгрузка, получение информации и т.д.);
function BASS_Pause(): BOOL; - Останавливает вывод, приостанавливая всю musics/samples/streams. Используйте BASS_Start(), чтобы возобновить вывод и приостановленные каналы. Пример использования: BASS_Pause();
function BASS_Stop(): BOOL; - Останавливает вывод, останавливая все musics/samples/streams. Эта функция может использоваться после BASS_Pause(), чтобы остановить приостановленные каналы, так, чтобы они не были продолжены функцией BASS_Start(); Пример использования: BASS_Stop();
function BASS_Start(): BOOL; - Начала (или продолжение) вывода звука. Пример использования: BASS_Start();
function BASS_GetCPU(): float; - Возвращает процент использования центрального процессора.
function BASS_SetVolume(volume: float ):BOOL; - установка громкости в Windovs. Параметр volume можно изменять в пределах от 0 до 1; Пример использования: BASS_SetVolume(TrackBar1.Position/10);
function BASS_GetVolume(): float; - Возвращает текущий уровень громкости звука в системе. Функция обратная предидущей.
function BASS_SetDevice(device: DWORD):BOOL; - Установка устройства вывода звукового потока. Параметр device = 0 - нет звука, 1 - вывод звука будет происходить на первое существующее устройство для вывода звука в системе.
function BASS_GetVersion(): DWORD; - Возвращает версию BASS, который загружен; Пример использования: // проверка корректности загруженной BASS.DLL if (HIWORD(BASS_GetVersion) <> BASSVERSION) then begin MessageBox(0,'Не корректная версия BASS.DLL',nil,MB_ICONERROR); Halt; end;
function BASS_Free():BOOL; - Освобождает все ресурсы, используемые устройством вывода. Пример использования: BASS_Free();
Функции с префиксом BASS_Stream..., предназначенные для работы с streams (загрузка, выгрузка, управление и т.д.);
function BASS_StreamCreateFile(mem: BOOL; f: Pointer; offset: QWORD; length: QWORD; flags: DWORD): HSTREAM; - Создаем звуковой поток из локального файла формата MP3, MP2, MP1, OGG, WAV, AIFF. В случае успешного завершения функция BASS_StreamCreateFileвозвращает дескриптор потока (тип HSTREAM ), который можно использовать в функциях управления каналом воспроизведения вместо дескриптора канала. Пример использования: Имя потока := Bass_streamCreateFile(false, PChar('C:\muzic.mp3'),0,0,0 {$IFDEF UNICODE} or BASS_UNICODE {$ENDIF});
function BASS_StreamFree(handle: HSTREAM): BOOL; - Освобождает звуковой поток, в скобках указываем имя потока. Функции с префиксом BASS_Music..., предназначенные для работы с mod music (загрузка, выгрузка, управление и т.д.);
function BASS_MusicLoad(mem: BOOL; f: Pointer; offset: QWORD; length: DWORD; flags: DWORD; freq: DWORD;): HMUSIC; - Загружает MOD музыкальный файл в форматах MO3 / IT / XM / S3M / MTM / MOD / UMX. В случае успешного выполнения функция BASS_MusicLoad возвращает дескриптор типа HMUSIC , который можно использовать в функциях управления каналом воспроизведения вместо дескриптора канала. Пример использования: Имя потока:= BASS_MusicLoad(False, PChar('C:\test.s3m'), 0, 0, BASS_MUSIC_RAMP {$IFDEF UNICODE} or BASS_UNICODE {$ENDIF}, 0);
function BASS_MusicFree(handle: HMUSIC): BOOL; - Освобождает ресурсы музыки, включая любой sync/DSP/FX. В скобках указываем имя потока. Функции с префиксом BASS_Sample..., предназначенные для работы с samples (загрузка, управление, выгрузка и т.д.);
function BASS_SampleLoad(mem: BOOL; f: Pointer; offset: QWORD; length: DWORD; max: DWORD; flags: DWORD): HSAMPLE; - Загружает WAV, AIFF, MP3, MP2, MP1, OGG или plugin поддерживает sample. В случае успешного выполнения функция BASS_SampleLoad возвращает дескриптор типа HSAMPLE , который можно использовать в функциях управления каналом воспроизведения вместо дескриптора канала. Пример использования: Имя потока:= BASS_SampleLoad(FALSE, PChar('C:\test.wav'), 0, 0, 3, BASS_SAMPLE_OVER_POS {$IFDEF UNICODE} or BASS_UNICODE {$ENDIF});
function BASS_SampleFree(handle: HSAMPLE): BOOL; - Освобождает ресурсы Sample. В скобках указываем имя потока.
Функции с префиксом BASS_Channel..., предназначенные для работы с каналами (воспроизведение, остановка, позиционирование, управление громкостью, балансировка каналов и т.д.);
function BASS_ChannelGetLength(handle, mode: DWORD): QWORD; - Узнать длинну звукового потока. Пример использования: BASS_ChannelGetLength(Имя потока,0);
function BASS_ChannelPlay(handle: DWORD; restart: BOOL): BOOL; - Начать проигрывать звук. Пример использования: Bass_channelPlay(Имя потока, false);
function BASS_ChannelPause(handle: DWORD): BOOL; - Сделать паузу. Пример использования: BASS_ChannelPause(Имя потока); function BASS_ChannelStop(handle: DWORD): BOOL; - Остановить проигрывание звука. Пример использования: BASS_ChannelStop(Имя потока);
function BASS_ChannelGetPosition(handle: DWORD; mode: DWORD):QWORD; - Возвращает позицию воспроизведения; Пример использования: scrollbar1.Position:=bass_channelGetPosition(Имя потока,0);
function BASS_ChannelSetPosition(handle: DWORD; pos: QWORD; mode: DWORD): BOOL; Установить новую позицию в потоке( необходимио для перемотки) Сдвигает позицию проигрывания на pos вперед. Пример использования BASS_ChannelSetPosition(Имя потока, ScrollBar1.Position, 0);
function BASS_ChannelBytes2Seconds(handle: DWORD; pos: QWORD): double; - Переводит текущуюю позицию воспроизведения во время (секунды); Пример использования: var TrackPos: Double; begin TrackPos:=BASS_ChannelBytes2Seconds(Имя потока,BASS_ChannelGetPosition(Имя потока,0)); end;
function BASS_ChannelGetAttribute(handle, attrib: DWORD; var value: FLOAT): BOOL; - Получает атрибуты канала.
function BASS_ChannelSetAttribute(handle, attrib: DWORD; var value: FLOAT): BOOL; - Устанавливает значение атрибута канала.Параметр value зависит от выбранного атрибута. Например для баланса атрибут (BASS_ATTRIB_PAN), -1 - левый канал, +1 - правый канал, 0 - центр, а для громкости звука атрибут (BASS_ATTRIB_VOL), 0 - нет звука, 1 - максимальная громкость. Пример использования: //установка громкости звука BASS_ChannelSetAttribute(Имя потока,BASS_ATTRIB_VOL,trackBar1.Position/10); //баланс BASS_ChannelSetAttribute(Имя потока,BASS_ATTRIB_PAN,Trackbar12.Position/5);
Функции с префиксом BASS_FXS..., предназначенные для создания различных звуковых эффектов;
function BASS_ChannelSetFX(handle: DWORD; type: DWORD; priority: int):HFX; - Устанавливает эффект на поток, MOD музыку, или канал записи.
function BASS_FXSetParameters(handle: HFX; params: Pointer): BOOL; - Устанавливает параметры эффекта.
function BASS_FXGetParameters(handle: HFX; params: Pointer): BOOL; - Возвращает параметры эффекта.
Пример использования: Создадим трех полосный эквалайзер. объявляем глобальные переменные: var p: BASS_DX8_PARAMEQ;//параметры эквалайзера fx: array[1..3] of integer;//количество регуляторов для эквалайзера channel: DWORD;
Далее в процедуре, перед выполнением команды BASS_ChannelPlay(channel, False); - проигрывание потока. пишем код настроек эквалайзера
fx[1] := BASS_ChannelSetFX(channel, BASS_FX_DX8_PARAMEQ, 1);//задаем эффект для первого регулятора fx[2] := BASS_ChannelSetFX(channel, BASS_FX_DX8_PARAMEQ, 1);//для второго fx[3] := BASS_ChannelSetFX(channel, BASS_FX_DX8_PARAMEQ, 1);//для третьего //задаем начальные значения параметров эквалайзера p.fGain := 0;//задаем усиление можно от -15 до 15. Поумолчанию 12. p.fBandwidth := 18;//задаем полосу пропускания можно от 1 до 36. Поумолчанию 12. p.fCenter := 125;//задаем центральную частоту регулирования в Гц BASS_FXSetParameters(fx[1], @p);//задаем сделанные настройки для первого регулятора p.fGain := 0; p.fBandwidth := 18; p.fCenter := 1000; BASS_FXSetParameters(fx[2], @p);//задаем сделанные настройки для второго регулятора p.fGain := 0; p.fBandwidth := 18; p.fCenter := 8000; BASS_FXSetParameters(fx[3], @p);//задаем сделанные настройки для третьего регулятора
//изменяем параметры усиления с помощью трех регуляторов в виде трекбаров procedure TForm1.TrackBar1Change(Sender: TObject); begin BASS_FXGetParameters(fx[1], @p); p.fgain := 15-TrackBar1.position; BASS_FXSetParameters(fx[1], @p); end;
Для любителей писать плееры на Delphi я выкладываю краткую справку по библиотеке bass.dll. Последнюю версию библиотеки можно скачать с официального сайта www.un4seen.com.