BASS 2.4
Copyright (c) 1999-2020 Un4seen Developments Ltd. All rights reserved.

Files that you should have found in the BASS package
====================================================
Win32 version
-------------
BASS.TXT        This file
BASS.DLL        BASS module
BASS.CHM        BASS documentation
MP3-FREE\
  BASS.DLL        BASS module using the OS's MP3 decoder
X64\
  BASS.DLL        64-bit BASS module
  MP3-FREE
    BASS.DLL        64-bit BASS module using the OS's MP3 decoder
C\              C/C++ API and examples...
  BASS.H          BASS C/C++ header file
  BASS.LIB        BASS import library
  BASS.SLN        Visual Studio solution for examples
  MAKEFILE        Makefile for examples
  MAKEFILE.IN     Makefile helper macros
  X64\
    BASS.LIB        64-bit BASS import library
  3DTEST\         3D/EAX example
    ...
  BASSTEST\       Simple playback example
    ...
  CONTEST\        Console example
    ...
  CUSTLOOP\       Custom looping example
    ...
  DEVLIST\        Device list example
    ...
  DSPTEST\        DSP example
    ...
  FXTEST\         DX8 effect example
    ...
  LIVEFX\         Full-duplex example
    ...
  LIVESPEC\       "Live" version of spectrum analyser example
    ...
  MODTEST\         MOD music example
    ...
  MULTI\          Multiple device example
    ...
  NETRADIO\       Internet streaming example
    ...
  PLUGINS\        Plugins example
    ...
  RECTEST\        Recording example
    ...
  SPEAKERS\       Multi-speaker example
    ...
  SPECTRUM\       Spectrum analyser example
    ...
  SYNTH\          Low latency custom streaming example
    ...
  WRITEWAV\       WAVE writer example
    ...
  BIN\            Precompiled examples
    3DTEST.EXE
    BASSTEST.EXE
    CONTEST.EXE
    CUSTLOOP.EXE
    DEVLIST.EXE
    DSPTEST.EXE
    FXTEST.EXE
    LIVEFX.EXE
    LIVESPEC.EXE
    MODTEST.EXE
    MULTI.EXE
    NETRADIO.EXE
    RECTEST.EXE
    SPEAKERS.EXE
    SPECTRUM.EXE
    SYNTH.EXE
    WRITEWAV.EXE
DELPHI\         Delphi API and examples...
  BASS.PAS        BASS Delphi unit
  3DTEST\         3D/EAX example
    ...
  BASSTEST\       Simple playback example
    ...
  CONTEST\        Console example
    ...
  CUSTLOOP\       Custom looping example
    ...
  DSPTEST\        DSP example
    ...
  FXTEST\         DX8 effect example
    ...
  LIVEFX\         Full-duplex example
    ...
  LIVESPEC\       "Live" version of spectrum analyser example
    ...
  MULTI\          Multiple device example
    ...
  NETRADIO\       Internet streaming example
    ...
  PLUGINS\        Plugins example
    ...
  RECORDTEST\     Recording example
    ...
  SAMPLEVIS\      Visualisation example
    ...
  SPEAKERS\       Multi-speaker example
    ...
  SPECTRUM\       Spectrum analyser example
    ...
  STREAMTEST\     User stream example
    ...
  WRITEWAV\       WAVE writer example
    ...
VB\             Visual Basic API and examples...
  BASS.BAS        BASS Visual Basic module
  3DTEST\         3D/EAX example
    ...
  BASSTEST\       Simple playback example
    ...
  CUSTLOOP\       Custom looping example
    ...
  DSPTEST\        DSP example
    ...
  FXTEST\         DX8 effect example
    ...
  LIVEFX\         Full-duplex example
    ...
  LIVESPEC\       "Live" version of spectrum analyser example
    ...
  MULTI\          Multiple device example
    ...
  NETRADIO\       Internet streaming example
    ...
  PLUGINS\        Plugins example
    ...
  RECTEST\        Recording example
    ...
  SPEAKERS\       Multi-speaker example
    ...
  SPECTRUM\       Spectrum analyser example
    ...
  SYNTH\          Low latency custom streaming example
    ...
  WRITEWAV\       WAVE writer example
    ...
  MEMORY\         Playing from memory example by Jobnik
    ...

NOTE: You may need to "Unblock" the BASS.CHM file in its "Properties" to view
      it on Windows 7. The documentation can also be viewed online at the BASS
      website.

NOTE: The Delphi and VB examples may not always be up to date with the C
      examples, so the latter should be preferred as references if possible.

NOTE: To run the example EXEs, first you will need to copy BASS.DLL into the
      same directory as them.

macOS version
-------------
BASS.TXT        This file
LIBBASS.DYLIB   BASS module
BASS.CHM        BASS documentation
CHMOX.APP       CHM file viewer
BASS.H          BASS C/C++ header file
BASS.XCODEPROJ  Xcode project for examples
MAKEFILE        Makefile for specific architectures
MP3-FREE\
  LIBBASS.DYLIB   BASS module using the OS's MP3 decoder
3DTEST\         3D example
  ...
BASSTEST\       Simple playback example
  ...
CONTEST\        Console example
  ...
CUSTLOOP\       Custom looping example
  ...
DEVLIST\        Device list example
  ...
DSPTEST\        DSP example
  ...
FXTEST\         DX8 effect example
  ...
LIVESPEC\       "Live" version of spectrum analyser example
  ...
MODTEST\        MOD music example
  ...
MULTI\          Multiple device example
  ...
NETRADIO\       Internet streaming example
  ...
PLUGINS\        Plugins example
  ...
RECTEST\        Recording example
  ...
SPEAKERS\       Multi-speaker example
  ...
SPECTRUM\       Spectrum analyser example
  ...
SYNTH\          Low latency custom streaming example
  ...
WRITEWAV\       WAVE writer example
  ...

NOTE: To view the documentation, you will need a CHM viewer, such as the
      included CHMOX. The documentation can also be viewed online at the BASS
      website.

NOTE: The GUI-based examples (not CONTEST/DEVLIST/WRITEWAV) use the old Carbon
      APIs that are not supported by 64-bit macOS. They will be replaced in
      future but are currently still included for reference (the BASS parts are
      still relevant).

Linux version
-------------
BASS.TXT        This file
LIBBASS.SO      BASS module
BASS.CHM        BASS documentation
BASS.H          BASS C/C++ header file
MAKEFILE        Makefile for examples
MAKEFILE.IN     Makefile helper macros
MP3-FREE\
  LIBBASS.SO      BASS module using the OS's MP3 decoder
X64\
  LIBBASS.SO      64-bit BASS module
  MP3-FREE
    LIBBASS.SO      64-bit BASS module using the OS's MP3 decoder
PASCAL\
  BASS.PAS        BASS Delphi/Pascal unit
3DTEST\         3D example
  ...
BASSTEST\       Simple playback example
  ...
CONTEST\        Console example
  ...
CUSTLOOP\       Custom looping example
  ...
DEVLIST\        Device list example
  ...
DSPTEST\        DSP example
  ...
FXTEST\         DX8 effect example
  ...
LIVESPEC\       "Live" version of spectrum analyser example
  ...
MODTEST\        MOD music example
  ...
MULTI\          Multiple device example
  ...
NETRADIO\       Internet streaming example
  ...
PLUGINS\        Plugins example
  ...
RECTEST\        Recording example
  ...
SPEAKERS\       Multi-speaker example
  ...
SPECTRUM\       Spectrum analyser example
  ...
SYNTH\          Low latency custom streaming example
  ...
WRITEWAV\       WAVE writer example
  ...

NOTE: To view the documentation, you will need a CHM viewer. The documentation
      can also be viewed online at the BASS website.

What's the point?
=================
BASS is an audio library for use in software on several platforms. Its
purpose is to provide the powerful and efficient sample, stream, MOD
music, and recording functions. All in a compact DLL that won't overly
bloat your software.

See the documentation for descriptions of all the BASS functions. Also
check the included example source-codes for some examples of how to use
BASS in your own programs.

Requirements
============
Win32 version
-------------
BASS requires WASAPI or DirectSound for playback and recording, but decoding
and silent playback on the "No sound" device is still possible without them.
DirectSound has been included with all Windows versions since Windows 98. On
Windows Vista and above, the default is to use WASAPI instead of DirectSound
for playback. 32-bit and 64-bit Windows are supported.

macOS version
-------------
macOS 10.5 or above is required. BASS uses CoreAudio for playback and recording,
so there are no special library/driver requirements. x86_64 / arm64 / i386
architectures are supported in a single universal library.

Linux version
-------------
BASS requires ALSA for playback and recording, but decoding and silent playback
on the "No sound" device is still possible without it. 32-bit (i386) and 64-bit
(x86-64) architectures are supported. ARM support is also available as a
separate download from the website.

Main Features
=============
* Samples
  supports WAV/AIFF/MP3/MP2/MP1/OGG and custom generated samples

* Sample streams
  stream any sample data in 8/16/32 bit, with both "push" and "pull" systems

* File streams
  MP3/MP2/MP1/OGG/WAV/AIFF file streaming

* Internet file streaming
  stream files from the internet, including Shout/Icecast

* User file streaming
  stream files from anywhere using any delivery method

* OS codecs
  ACM, Media Foundation and CoreAudio codec support for additional audio formats

* Multi-channel streaming
  support for more than plain stereo, including multi-channel OGG/WAV/AIFF files

* MOD music
  uses the same engine as XMPlay = best accuracy, speed, and quality

* MO3 music
  MP3/OGG compressed MOD music

* Add-on system
  support for more formats is available via add-ons (aka plugins)

* Multiple outputs
  simultaneously use multiple soundcards, and move channels between them

* Recording
  flexible recording system, with support for multiple devices

* Decode without playback
  streams and MOD musics can be outputted in any way you want

* Speaker assignment
  assign streams and MOD musics to specific speakers

* High precision synchronization
  synchronize events in your software to the streams and MOD musics

* Effects
  chorus/compressor/distortion/echo/flanger/gargle/parameq/reverb

* User defined DSP functions
  custom effects may be applied to individual streams or the final output mix

* 32 bit floating-point decoding and processing
  floating-point stream/music decoding, DSP/FX, and recording

* 3D sound
  play samples/streams/musics in any 3D position

Using BASS
==========
There is no guarantee that all future BASS versions will be compatible
with all previous versions, so your program should use BASS_GetVersion
to check the version that is loaded. This also means that you should
put the BASS module in the same directory as your executable (not just
somewhere in the path), to avoid the possibility of a wrong version being
loaded.

If you are updating your software from a previous BASS version, then
you should check the "History" section (below), to see if any of the
functions that you are using have been affected by a change.

Win32 version
-------------
C/C++, Delphi, and Visual Basic APIs and example projects are provided. To
use BASS with another language you will first have to convert the header
file. Or, as a last resort, you could use LoadLibrary and GetProcAddress.

The downside is that you have to manually import each function that you
use, with the GetProcAddress function. But it has been made a lot simpler
to import BASS this way by the use of the BASSDEF #define. Here's a small
example:

#define BASSDEF(f) (WINAPI *f) // define the functions as pointers
#include "bass.h"
...
HINSTANCE bass=LoadLibrary("BASS.DLL"); // load BASS
BASS_Init=GetProcAddress(bass,"BASS_Init"); // get BASS_Init
BASS_Init(-1,44100,0,hWnd,NULL); // call BASS_Init

To use BASS with Borland C++ Builder, you will first have to create a
Borland C++ Builder import library for it. This is done by using the
IMPLIB tool that comes with Borland C++ Builder. Simply execute this:

    IMPLIB BASSBCB.LIB BASS.DLL

... and then use BASSBCB.LIB in your projects to import BASS.

To use BASS with LCC-Win32, you will first have to create a compatible
import library for it. This is done by using the PEDUMP and BUILDLIB
tools that come with LCC-Win32. Run these 2 commands:

    PEDUMP /EXP BASS.LIB > BASSLCC.EXP
    BUILDLIB BASSLCC.EXP BASSLCC.LIB

... and then use BASSLCC.LIB in your projects to import BASS.

For the BASS functions that return strings (char*), VB users should use
the VBStrFromAnsiPtr function to convert the returned pointer into a VB
string.

macOS version
-------------
See the example Xcode project.

NOTE: The LIBBASS.DYLIB file must be put in the same directory as the
      executable, it can't just be somewhere in the path.

LIBBASS.DYLIB is a universal binary with support for the x86_64 / arm64 / i386
architectures. If not all of those architectures are needed, the included
makefile can be used to extract the wanted one(s). Type "make x86_64" or
"make arm64" or "make i386" to extract a particular architecture. "make 64bit"
can be used to extract the x86_64 and arm64 architectures (exclude i386), and
"make intel" to extract the x86_64 and i386 architectures (exclude arm64). Any
BASS add-ons placed in the same directory will also be processed.

Linux version
-------------
The LIBBASS.SO file needs to be in the OS's library search path for it to
be found; simply placing it in the same directory as the executable won't
necessarily work as it does on other platforms. The BASS libraries should
also not be placed in the standard library directories to avoid version
conflicts. To meet those competing requirements, a wrapper script could be
used to set the "LD_LIBRARY_PATH" environment variable before loading the
executable. Another option is to set the "rpath" in the executable, to tell
it where to look for libraries. That is what the example makefiles do.

When building both 32-bit and 64-bit executables, it is possible to simply
try linking with both LIBBASS.SO versions, and the linker will use the
appropriate version and ignore the other.

Latest Version
==============
The latest version of BASS can always be found at the BASS website:

    www.un4seen.com

Licence
=======
BASS is free for non-commercial use. If you are a non-commercial entity
(eg. an individual) and you are not making any money from your product
(through sales/advertising/etc), then you can use BASS in it for free.
If you wish to use BASS in commercial products, then please also see the
next section.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, BASS IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND/OR FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS SHALL NOT BE HELD
LIABLE FOR ANY DAMAGE THAT MAY RESULT FROM THE USE OF BASS. YOU USE
BASS ENTIRELY AT YOUR OWN RISK.

Usage of BASS indicates that you agree to the above conditions.

All trademarks and other registered names contained in the BASS
package are the property of their respective owners.

Commercial licensing
--------------------
BASS is available for use in your commercial products. The licence
types available are as follows:

SHAREWARE: Allows the usage of BASS in an unlimited number of your
shareware ("try before you buy") products, which must sell for no more
than 40 Euros each. Non-shareware products are also permitted, but the
product price limit is 10 Euros in that case. The price limit can be
raised by purchasing duplicate licences, eg. 2 licences doubles it. If
you are an individual (not a corporation) making and selling your own
software, this is the licence for you.

SINGLE COMMERCIAL: Allows the usage of BASS in one commercial product.

UNLIMITED COMMERCIAL: Allows the usage of BASS in an unlimited number
of your commercial products. This licence is on a per-site basis, eg.
if you are creating products with BASS at 2 sites/locations, then 2
licences are required.

Please note the products must be end-user products, eg. not components
used by other products.

These licences only cover your own software, not the publishing of
other's software. If you publish other's software, its developers (or
the software itself) will need to be licensed to use BASS.

These licences are on a per-platform basis, with reductions available
when licensing for multiple platforms. In all cases there are no royalties
to pay, and you can use future BASS updates without further cost.

These licences do not allow reselling/sublicensing of BASS. For example,
if a product is a development system, the users of said product are not
licensed to use BASS in their productions; they will need their own
licences.

If the standard licences do not meet your requirements, or if you have
any questions, please get in touch (email: bass@un4seen.com).

Visit the BASS website for the latest pricing:

    www.un4seen.com

MP3
---
MP3 technology is patented, and Thomson license the use of their and
Fraunhofer's patents. The inclusion of an MP3 decoder (eg. BASS) in a
commercial product requires an MP3 patent licence. Contact Thomson for
details:

    www.mp3licensing.com

Alternatively, the "MP3-FREE" BASS version does not include its own MP3
decoder but instead makes use of the operating system's already licensed
decoder. If an MP3 decoder is not available, then MP3 playback will not
be possible, but everything else will function as normal.

NOTE: When using the OS's MP3 decoder, BASS still does the file handling
      so all the usual features are still supported, including streaming,
      tag reading, pre-scanning, gapless playback, etc.

NOTE: Linux does not include an MP3 decoder as standard. The "MP3-FREE"
      BASS version will make use of the libmpg123 decoder, if installed.

Credits
=======
Ogg Vorbis decoding is based on libogg/vorbis,
Copyright (c) 2002-2020 Xiph.org Foundation

CHMOX is (c) 2004 Stéphane Boisson, http://chmox.sourceforge.net/

API/Sample contributors
-----------------------
Delphi: Titus Miloi, Rogier Timmermans, Alessandro Cappellozza,
        Jesse Naranjo, Chris Troesken, Evgeny Melnikov
Visual Basic: Adam Hoult, Hendrik Knaepen, Arthur Aminov,
              Peter Hebels

History
=======
These are the major (and not so major) changes at each version stage.
There are of course bug fixes and other little improvements made along
the way too! To make upgrading simpler, all functions affected by a
change to the BASS interface are listed.

2.4.15 - 17/12/2019
-------------------
* Channel processing granularity option
    BASS_ATTRIB_GRANULE (BASS_ChannelSetAttribute option)
* Asynchronous mixtime sync callbacks
    BASS_SYNC_THREAD (BASS_ChannelSetSync flag)
* Output device update period can be set in samples
    BASS_CONFIG_DEV_PERIOD (BASS_SetConfig option)
* Continuous output when nothing is playing is now optional on macOS/iOS too
    BASS_CONFIG_DEV_NONSTOP (BASS_SetConfig option)
* AAudio output support on Android
    BASS_Init
    BASS_CONFIG_ANDROID_AAUDIO (BASS_SetConfig option)
* Support for audio session IDs on Android
    BASS_CONFIG_ANDROID_SESSIONID (BASS_SetConfig option)
* ParcelFileDescriptor support on Android
    BASS_StreamCreateFile
    BASS_SampleLoad
    BASS_MusicLoad
* FloatValue Java class added to receive floating-point values on Android 10
    BASS_Get3DFactors
    BASS_RecordGetInput
    BASS_ChannelGetAttribute
    BASS_ChannelGet3DAttributes
* Audio session configuration option on iOS
    BASS_CONFIG_IOS_SESSION (BASS_SetConfig option)
* OGG channel type constant renamed/duplicated to VORBIS
    BASS_CTYPE_STREAM_VORBIS
* Error code for recognised file formats without audio
    BASS_ERROR_NOTAUDIO (BASS_StreamCreateFile/User/URL error code)
* Error code for unstreamable MP4 files due to atom order
    BASS_ERROR_UNSTREAMABLE (BASS_StreamCreateFileUser/URL error code)
* Fix for AAC streaming with BASS_STREAM_BLOCK on macOS 10.15 and iOS 13
    BASS_StreamCreateURL/FileUser
* Fix for playback rate changing bug when using DirectSound
    BASS_ATTRIB_FREQ (BASS_ChannelSetAttribute option)
* armv6 architecture support dropped on iOS

2.4.14 - 16/1/2019
------------------
* Support for playback on the "No sound" device
    BASS_Init
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad/Create
    BASS_ChannelPlay
* Improved sample rate conversion quality, including 64 point option
    BASS_ATTRIB_SRC (BASS_ChannelSetAttribute option)
    BASS_CONFIG_SRC/_SAMPLE (BASS_SetConfig options)
* Loopback (output device) recording on Windows Vista and above
    BASS_RecordInit
    BASS_RecordGetDeviceInfo
    BASS_DEVICE_LOOPBACK (BASS_DEVICEINFO flag)
    DEVLIST and RECTEST examples updated
* Native format recording option
    BASS_RecordStart
* Access to the 3D output mix for applying DSP/FX
    STREAMPROC_DEVICE_3D (BASS_StreamCreate option)
* Retrieval of a device's started/stopped status
    BASS_IsStarted
* Sync for when a device stops unexpectedly
    BASS_SYNC_DEV_FAIL (BASS_ChannelSetSync type)
* New channel playback state for a paused device
    BASS_ACTIVE_PAUSED_DEVICE (BASS_ChannelIsActive)
* Sync for when a device's sample format changes
    BASS_SYNC_DEV_FORMAT (BASS_ChannelSetSync type)
* Adjustable output device update period
    BASS_CONFIG_DEV_PERIOD (BASS_SetConfig option)
* Nyquist FFT option
    BASS_DATA_FFT_NYQUIST (BASS_ChannelGetData flag)
* Plugin-specific flags are ignored in standard stream creation functions
    BASS_StreamCreateFile/User/URL
* Pre-buffering during stream creation is now disabled by default
    BASS_CONFIG_NET_PREBUF_WAIT (BASS_SetConfig option)
    BASS_StreamCreateURL/FileUser
* Existing internet streams are unaffected by read timeout config changes
    BASS_CONFIG_NET_READTIMEOUT (BASS_SetConfig option)
* Retrieval of the number of existing handles
    BASS_CONFIG_HANDLES (BASS_GetConfig option)
* Windows mixer settings are retained by default and optionally not
    BASS_CONFIG_WASAPI_PERSIST (BASS_SetConfig option)
* Configurable OpenSSL library filename on Linux/Android
    BASS_CONFIG_LIBSSL (BASS_SetConfigPtr option)
* Files can be deleted/renamed while streaming on Windows (already true on other platforms)
    BASS_StreamCreateFile
* Fix for bug in playback buffering disabling option
    BASS_ATTRIB_NOBUFFER (BASS_ChannelSetAttribute option)
* Fix to support long logarithmic curves in volume effects
    BASS_FX_VOLUME (BASS_ChannelSetFX type)

2.4.13.8 - 6/2/2018
-------------------
* Indication of a file's original sample format being floating-point
    BASS_ORIGRES_FLOAT (BASS_CHANNELINFO/SAMPLE flag)
* Some extra sample data is retained to account for device latency in data retrieval
    BASS_ChannelGetData
* FFT window is shortened to match amount of available data when less than FFT size
    BASS_ChannelGetData
* FFT level adjusted to be approx the same regardless of amount of available data
    BASS_ChannelGetData
* Fix for crash when decoding channels are dissociated from a device
    BASS_NODEVICE (BASS_ChannelSetDevice option)

2.4.13 - 19/12/2017
-------------------
* WASAPI output on Windows (DirectSound is fallback/optional)
    BASS_DEVICE_DSOUND (BASS_Init flag)
    BASS_CONFIG_DEV_BUFFER/NONSTOP (BASS_SetConfig options)
    BASS_CONFIG_SRC/_SAMPLE (BASS_SetConfig options)
    BASS_ATTRIB_SRC/NORAMP (BASS_ChannelSetAttribute options)
* Default output device following support extended to Windows Vista and macOS
    BASS_CONFIG_DEV_DEFAULT (BASS_SetConfig option)
* Seamless playback buffer length changing
    BASS_ATTRIB_BUFFER (BASS_ChannelSetAttribute option)
    SYNTH example updated
* Access to the final output mix for applying DSP/FX
    STREAMPROC_DEVICE (BASS_StreamCreate option)
    BASS_CTYPE_STREAM_DEVICE
    FXTEST example updated
* Dissociating of decoding channels from a device
    BASS_NODEVICE (BASS_ChannelSetDevice option)
* Volume attribute levels above 1.0 for amplification
    BASS_ATTRIB_VOL (BASS_ChannelSetAttribute option)
* Logarithmic attribute slides
    BASS_SLIDE_LOG (BASS_ChannelSlideAttribute flag)
* Volume & panning attribute affected level retrieval
    BASS_LEVEL_VOLPAN (BASS_ChannelGetLevelEx flag)
* Volume level adjustment effect
    BASS_FX_VOLUME (BASS_ChannelSetFX type)
    BASS_FX_VOLUME_PARAM structure
* Asynchronous pre-buffering
    BASS_CONFIG_NET_PREBUF_WAIT (BASS_SetConfig option)
    BASS_StreamCreateURL/FileUser
    CONTEST and NETRADIO examples updated
* Decoding channels can be dissociated from a device
    BASS_ChannelSetDevice
* Resetting of user file streams/decoders
    BASS_POS_RESET (BASS_ChannelSetPosition flag)
* Relative seeking
    BASS_POS_RELATIVE (BASS_ChannelSetPosition flag)
* RIFF cue points chunk retrieval
    BASS_TAG_RIFF_CUE (BASS_ChannelGetTags type)
    TAG_CUE structure
* RIFF sample chunk retrieval
    BASS_TAG_RIFF_SMPL (BASS_ChannelGetTags type)
    TAG_SMPL structure
* Support for Category/Description/Grouping/Keywords/Lyrics MP4 tags
    BASS_TAG_MP4 (BASS_ChannelGetTags type)
* Separate channel type for dummy streams
    BASS_CTYPE_STREAM_DUMMY
* Stalled internet stream buffering progress retrieval
    BASS_FILEPOS_BUFFERING (BASS_StreamGetFilePosition mode)
    CONTEST and NETRADIO examples updated
* Playlist recursion depth config option
    BASS_CONFIG_NET_PLAYLIST_DEPTH (BASS_SetConfig options)
* Push file system read functions can now return 0 without ending the file
    STREAMFILE_BUFFERPUSH (BASS_StreamCreateFileUser system)
    FILEREADPROC
* 16 point SRC is used by default when SSE is available
    BASS_CONFIG_SRC (BASS_SetConfig option)
* Mono downmixing for all file formats in sample loading
    BASS_SAMPLE_MONO (BASS_SampleLoad flag)
* Mono OGG stream downmixing
    BASS_SAMPLE_MONO (BASS_StreamCreateFile/User/URL flag)
* Media Foundation availability detection
    BASS_CONFIG_MF_DISABLE (BASS_GetConfig option)
    PLUGINS example updated
* AudioTrack output on Android
    BASS_DEVICE_AUDIOTRACK (BASS_Init flag)
* Support for Android Media codecs
    BASS_StreamCreateFile/User/URL
    BASS_TAG_AM_MIME/NAME (BASS_ChannelGetTags type)
    BASS_CONFIG_AM_DISABLE (BASS_SetConfig option)
* Panning fix for MOD files created with ScreamTracker 3
    BASS_MusicLoad
* Fix for compressor and distotion DX8 effects with floating-point data on Windows
    BASS_FX_DX8_COMPRESSOR/DISTORTION (BASS_ChannelSetFX types)
* Fix for plugin freeing issue on 64-bit platforms (HPLUGIN is not library address any more)
    BASS_PluginLoad
    BASS_PluginFree

2.4.12 - 10/3/2016
------------------
* DSP/FX chain order modification
    BASS_FXSetPriority
* Average bitrate retrieval
    BASS_ATTRIB_BITRATE
* Ramping-out when stopping/pausing playback
    BASS_ChannelStop
    BASS_ChannelPause
* Disabling of playback ramping
    BASS_ATTRIB_NORAMP (BASS_ChannelSetAttribute option)
* Pre-buffering when playback buffering is disabled
    BASS_ChannelUpdate
    BASS_ATTRIB_NOBUFFER (BASS_ChannelSetAttribute option)
* Net agent and proxy config options now make a copy of the provided string
    BASS_CONFIG_NET_AGENT/PROXY (BASS_SetConfigPtr options)
    NETRADIO example updated
* Unicode net agent and proxy config options on Windows
    BASS_CONFIG_NET_AGENT/PROXY (BASS_SetConfigPtr options)
* 32768 sample FFT
    BASS_DATA_FFT32768 (BASS_ChannelGetData flag)
* Support for iTunes gapless info in MP3 files
    BASS_StreamCreateFile/User
* 529 sample delay removed from start of MP3 files without delay info
    BASS_StreamCreateFile/User/URL
* Support for numerical MP4 genre (gnre) tags
    BASS_TAG_MP4 (BASS_ChannelGetTags type)
* Support for BASSWMA's tag option when using Media Foundation WMA codec
    BASS_TAG_WMA (BASS_ChannelGetTags type)
* OpenMPT author tag retrieval
    BASS_TAG_MUSIC_AUTH (BASS_ChannelGetTags type)
* FastTracker2 panning for XM files
    BASS_MUSIC_FT2PAN (BASS_MusicLoad flag)
* Support for longer device names on Windows
    BASS_DEVICEINFO (name member)
* Checking for floating-point support on platforms that might not have it
    BASS_CONFIG_FLOAT (BASS_GetConfig option)
* Attribute size retrieval fix
    BASS_ChannelGetAttributeEx
* Fix for missing LC_VERSION_MIN issue with Xcode 7 on OSX, ppc architecture (PowerPC) support dropped
* LIST example renamed to DEVLIST

2.4.11 - 22/12/2014
-------------------
* Support for custom HTTP request headers
    BASS_StreamCreateURL
* HTTPS support on Linux/Android
    BASS_StreamCreateURL
* Redirection HTTP headers provided during connection
    BASS_STREAM_STATUS (BASS_StreamCreateURL flag)
    DOWNLOADPROC
* Adjustable stalled internet stream resumption buffer level
    BASS_ATTRIB_NET_RESUME (BASS_ChannelSetAttribute option)
* Extended level retrieval inc. multi-channel and RMS options
    BASS_ChannelGetLevelEx
* Inexact/faster seeking
    BASS_POS_INEXACT (BASS_ChannelSetPosition flag)
* Post-stream creation scanning (seek table building)
    BASS_POS_SCAN (BASS_ChannelSetPosition flag)
* Extended attribute support
    BASS_ChannelGet/SetAttributeEx
* Scanned info retrieval and setting
    BASS_ATTRIB_SCANINFO (BASS_ChannelGet/SetAttributeEx option)
* Built-in ADPCM WAVE file support on Linux/Android/WinCE
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
* Active MOD channel count retrieval
    BASS_ATTRIB_MUSIC_ACTIVE (BASS_ChannelGetAttribute option)
* Fractional sample rates
    BASS_ATTRIB_FREQ (BASS_ChannelSetAttribute option)
* Device type information
    BASS_DEVICE_TYPE_xxx (BASS_DEVICEINFO flags)
* Unicode support for recording input names
    BASS_CONFIG_UNICODE (BASS_SetConfig option)
    BASS_RecordGetInputName
* File size retrieval
    BASS_FILEPOS_SIZE (BASS_StreamGetFilePosition mode)
* Asynchronous file reading buffer level retrieval
    BASS_FILEPOS_ASYNCBUF (BASS_StreamGetFilePosition mode)
* MPEG data search limit raised to 1MB
    BASS_CONFIG_VERIFY (BASS_SetConfig option)
* Separate MPEG data search limit for internet/buffered streams
    BASS_CONFIG_VERIFY_NET (BASS_SetConfig option)
* Support for iTunes gapless info with Media Foundation and CoreAudio codecs
    BASS_StreamCreateFile/User
* Airplay receiver enumeration and selection on OSX
    BASS_DEVICES_AIRPLAY (BASS_GetDeviceInfo flag)
    BASS_CONFIG_AIRPLAY (BASS_SetConfig option)
* Media Foundation playback of audio from videos is now optional
    BASS_CONFIG_MF_VIDEO (BASS_SetConfig option)
* Optional floating-point or fixed-point data retrieval on Android/WinCE
    BASS_DATA_FLOAT/FIXED (BASS_ChannelGetData flags)
* Continuous output when nothing is playing on Linux/Android/WinCE
    BASS_CONFIG_DEV_NONSTOP (BASS_SetConfig option)
* Fix for decoding channels being ended when stopping the output device
    BASS_Stop
* Fix for Media Foundation internet/buffered streaming on Windows 8
    BASS_StreamCreateURL
    BASS_StreamCreateFileUser
* Improved compatibility with recent PulseAudio versions on Linux
* LIST and MODTEST examples added
* MASM API and examples removed (available as separate download)

2.4.10 - 16/2/2013
------------------
* Asynchronous file reading/buffering
    BASS_ASYNCFILE (BASS_StreamCreateFile/User flag)
    BASS_CONFIG_ASYNCFILE_BUFFER (BASS_SetConfig option)
* Support for chained OGG files (multiple logical bitstreams)
    BASS_StreamCreateFile/User
    BASS_CONFIG_OGG_PRESCAN (BASS_SetConfig option)
    BASS_POS_OGG (BASS_ChannelSetPosition/ChannelGetLength mode)
* OGG logical bitstream syncs are no longer automatically "mixtime"
    BASS_SYNC_OGG_CHANGE (BASS_ChannelSetSync type)
* Support for Soundtracker MOD files
    BASS_MusicLoad
* Complex FFT data
    BASS_DATA_FFT_COMPLEX (BASS_ChannelGetData flag)
* Volume levels above 1.0 for decoding channels
    BASS_ATTRIB_VOL (BASS_ChannelSetAttribute option)
* Recording device channel count retrieval on Windows/OSX/iOS
    BASS_RECORDINFO (formats member)
* Minimum recording period reduced to 5ms
    BASS_RecordStart
* Recording device period adjustment on OSX
    BASS_RecordStart
* Device UID retrieval on OSX
    BASS_DEVICEINFO (driver member)
* The desktop window handle is used when none is provided
    BASS_Init

2.4.9 - 3/5/2012
----------------
* Improved and adjustable sample rate conversion quality
    BASS_ATTRIB_SRC (BASS_ChannelSetAttribute option)
    BASS_CONFIG_SRC/_SAMPLE (BASS_SetConfig options)
* Support for buffered file & internet streams with CoreAudio codecs on OSX/iOS
    BASS_StreamCreateURL
    BASS_StreamCreateUser
* Data and level retrieval from sample channels
    BASS_ChannelGetData
    BASS_ChannelGetLevel
* Oldest sample channel will be overridden when there are multiple candidates
    BASS_SampleGetChannel
* Use of the device's output rate with MODs
    BASS_MusicLoad
* Optional device output rate setting on OSX/iOS
    BASS_DEVICE_FREQ (BASS_Init flag)
* UTF-8 device information on Windows
    BASS_CONFIG_UNICODE (BASS_SetConfig option)
* Speaker assignment with panning/balance control on Windows Vista/7
    BASS_CONFIG_VISTA_SPEAKERS (BASS_SetConfig option)
    BASS_ATTRIB_PAN (BASS_ChannelGet/Set/SlideAttribute option)
* Push stream queue level can be checked after using BASS_STREAMPROC_END
    BASS_StreamPutData
* Support for ALSA subdevices on Linux
    BASS_Init
    BASS_GetDeviceInfo
    BASS_RecordInit
    BASS_RecordGetDeviceInfo
* Device list fix on 64-bit OSX
    BASS_GetDeviceInfo
    BASS_RecordGetDeviceInfo
* BASS_UNICODE support fix on Linux
    BASS_PluginLoad
* Internet streaming tweaks/fixes on Windows
* SYNTH example updated to use device output rate
* RECTEST example updated (C version) for better Windows Vista/7 support
* Documentation updated with platform-specific info for Android

2.4.8 - 29/8/2011
-----------------
* Support for Media Foundation codecs on Windows 7 and updated Vista
    BASS_StreamCreateFile/User/URL
    BASS_TAG_MF (BASS_ChannelGetTags type)
    PLUGINS example updated
* Built-in support for MP4 tags on Win32/OSX/iOS (for Media Foundation & CoreAudio AAC/ALAC codecs)
    BASS_TAG_MP4 (BASS_ChannelGetTags type)
* WAVE format chunk retrieval
    BASS_TAG_WAVEFORMAT (BASS_ChannelGetTags type)
* Adjustable sample channel limit
    BASS_SampleSetInfo
* Per-channel CPU usage monitoring
    BASS_ATTRIB_CPU (BASS_ChannelGetAttribute option)
* Pre-allocation of push stream queue space
    BASS_StreamPutData
* Support for AIFF files with the data chunk before the format info chunk
    BASS_StreamCreateFile/User/URL
* Ramping-in disabled for all but the XM format (and MODs in FT2 mode) in "normal" ramping mode
    BASS_MUSIC_RAMP (BASS_MusicLoad flag)
* RIFF "INFO" tag reading fix
    BASS_TAG_RIFF_INFO (BASS_ChannelGetTags type)
* OSX 10.7 compatibility fix
* x86_64 architecture support on OSX
* Delphi dynamic loading unit removed (now available as separate download)

2.4.7 - 30/11/2010
------------------
* Decode-to-position seeking
    BASS_POS_DECODETO (BASS_ChannelSetPosition flag)
* Support for RIFF "DISP" text tags
    BASS_TAG_RIFF_DISP (BASS_ChannelGetTags type)
* Support for APEv1 tags
    BASS_TAG_APE (BASS_ChannelGetTags type)
    BASS_TAG_APE_BINARY (BASS_ChannelGetTags type)
* 16384 sample FFT
    BASS_DATA_FFT16384 (BASS_ChannelGetData flag)
* Support for AIFF files larger than 4GB
    BASS_StreamCreateFile/User/URL
* Acceptance of self-signed and invalid certificates
    BASS_StreamCreateURL
* Internet stream reading timeout
    BASS_CONFIG_NET_READTIMEOUT (BASS_SetConfig option)
* Support for removing a DSP within its DSPPROC
    BASS_ChannelRemoveDSP
* Buffer bypassing for lower latency output (not available on Windows)
    BASS_ATTRIB_NOBUFFER (BASS_ChannelSetAttribute option)
    SYNTH example added (OSX)
* A "Default" device that follows default device changes on Windows 7
    BASS_CONFIG_DEV_DEFAULT (BASS_SetConfig option)
* Xcode examples project added for OSX
* Documentation updated with platform-specific info for iOS/Linux/WinCE

2.4.6 - 17/6/2010
-----------------
* Support for APEv2 tags, including binary
    BASS_TAG_APE (BASS_ChannelGetTags type)
    BASS_TAG_APE_BINARY (BASS_ChannelGetTags type)
* Unicode/IDN URL support
    BASS_StreamCreateURL
* Decoding position retrieval
    BASS_POS_DECODE (BASS_ChannelGetPosition flag)
* Support for OGG 6/7.1 channel configs
    BASS_StreamCreateFile/User/URL
* Support for setting syncs within mixtime SYNCPROCs
    BASS_ChannelSetSync
* Support for setting additional DSP/FX within DSPPROCs
    BASS_ChannelSetDSP/FX
* DC bias removal in FFT processing
    BASS_DATA_FFT_REMOVEDC (BASS_ChannelGetData flag)
* Fix for incorrect (2x) return value when getting FFT data from a 16-bit channel
    BASS_ChannelGetData
* Fix for incorrect (STOPPED instead of PAUSED) channel status following BASS_Pause
    BASS_ChannelIsActive

2.4.5 - 18/12/2009
------------------
* Support for little-endian AIFF files
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
* Support for 64-bit floating-point WAVE/AIFF files
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
* Input volume retrieval failure results in a reading of -1 instead of 1
    BASS_RecordGetInput
    RECTEST example updated
* Input volume support on OSX
    BASS_RecordSetInput
    BASS_RecordGetInput
    RECTEST example updated
* Fix for deferred input settings on Vista
    BASS_RecordSetInput
* Windows MP3 codec given preference over other installed MP3 codecs (MP3-FREE version)
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad

2.4.4 - 13/10/2009
------------------
* RIFF/BWF "radio traffic" tag retrieval
    BASS_TAG_RIFF_CART (BASS_ChannelGetTags type)
    TAG_CART structure
* Support for ID3v2 tags in RIFF/WAVE/AIFF files ("ID3 " chunk)
    BASS_TAG_ID3V2 (BASS_ChannelGetTags type)
* Pushed fractional samples are refused rather than discarded
    BASS_StreamPutData
* DX8 effect emulation on OSX
    BASS_FX_DX8_CHORUS/DISTORTION/ECHO/FLANGER/PARAMEQ/REVERB (BASS_ChannelSetFX types)
    FXTEST example added
* UTF-16 support on OSX
    BASS_UNICODE (BASS_StreamCreateFile/SampleLoad/MusicLoad/PluginLoad flag)

2.4.3 - 8/5/2009
----------------
* MOD order list retrieval
    BASS_TAG_MUSIC_ORDERS (BASS_ChannelGetTags type)
* Support for ID3v2 tags in RIFF/WAVE files ("id3 " chunk)
    BASS_TAG_ID3V2 (BASS_ChannelGetTags type)
* Improved position reporting precision on Vista
    BASS_ChannelGetPosition
* Length retrieval when streaming in blocks (BASS_STREAM_BLOCK)
    BASS_ChannelGetLength
* Support for CoreAudio codecs on OSX
    BASS_StreamCreateFile/User
    BASS_SampleLoad
    BASS_TAG_CA_CODEC (BASS_ChannelGetTags type)
    TAG_CA_CODEC structure
* 3D algorithm option support on OSX
    BASS_CONFIG_3DALGORITHM (BASS_SetConfig option)

2.4.2 - 18/9/2008
-----------------
* RF64 support
    BASS_StreamCreateFile/User
* RIFF/BWF "Broadcast Audio Extension" tag retrieval
    BASS_TAG_RIFF_BEXT (BASS_ChannelGetTags type)
    TAG_BEXT structure
* ID3v1 tag structure
    TAG_ID3 structure
* Multiple simultaneous recordings per device on Vista & OSX (as on XP)
    BASS_RecordStart
* DX8 effect parameter defaults updated/corrected in documentation

2.4 - 2/4/2008
--------------
* "Push" streaming
    STREAMPROC_PUSH (BASS_StreamCreate option)
    BASS_StreamPutData
    LIVEFX and MULTI examples updated
* "Push" buffered file streaming
    STREAMFILE_BUFFERPUSH (BASS_StreamCreateFileUser system)
    BASS_StreamPutFileData
* STREAMFILEPROC replaced by table of callbacks for each file operation
    BASS_FILEPROCS (FILECLOSEPROC/FILELENPROC/FILEREADPROC/FILESEEKPROC)
    STREAMFILEPROC *removed*
* 64-bit file positioning
    BASS_SampleLoad
    BASS_MusicLoad
    BASS_StreamCreateFile
    BASS_StreamGetFilePosition
* File buffer level retrieval
    BASS_FILEPOS_BUFFER (BASS_StreamGetFilePosition mode)
* Sinc interpolated MOD music mixing
    BASS_MUSIC_SINCINTER (BASS_MusicLoad flag)
* MO3 2.4 support
    BASS_MusicLoad
* MOD orders positioning incorporated into channel functions
    BASS_ChannelGetLength
    BASS_ChannelSetPosition
    BASS_ChannelGetPosition
    BASS_MusicGetOrderPosition *removed*
    BASS_MusicGetOrders *removed*
* Channel attribute functions consolidated
    BASS_ChannelSetAttribute
    BASS_ChannelGetAttribute
    BASS_ChannelSlideAttribute
    BASS_ChannelIsSliding
    BASS_ChannelSetAttributes *removed*
    BASS_ChannelGetAttributes *removed*
    BASS_ChannelSlideAttributes *removed*
    BASS_ChannelSetEAXMix *removed*
    BASS_ChannelGetEAXMix *removed*
    BASS_MusicSetAttribute *removed*
    BASS_MusicGetAttribute *removed*
* Floating-point volume and panning
    BASS_SetVolume
    BASS_GetVolume
    BASS_RecordSetInput
    BASS_RecordGetInput
    BASS_ATTRIB_PAN/VOL (BASS_ChannelGet/Set/SlideAttribute options)
    BASS_ATTRIB_MUSIC_VOL_CHAN/INST (BASS_ChannelGet/Set/SlideAttribute options)
    BASS_SAMPLE (volume/pan/outvol members)
    BASS_CONFIG_MAXVOL *removed*
    BASSTEST and RECTEST examples updated
* Output device volume control on Vista (as on other OS)
    BASS_SetVolume
    BASS_GetVolume
* Multiple update threads
    BASS_CONFIG_UPDATETHREADS (BASS_SetConfig option)
    BASSTEST example updated
* Global volume range increased to 10000
    BASS_CONFIG_GVOL_SAMPLE/STREAM/MUSIC (BASS_SetConfig options)
    BASSTEST example updated
* Setting and retrieving of a sample's data
    BASS_SampleSetData
    BASS_SampleGetData
    BASS_SampleCreate
    BASS_SampleCreateDone *removed*
* Channel flag setting mask
    BASS_ChannelFlags
    BASS_ChannelSetFlags *removed*
    SPEAKERS example updated
* 256 sample FFT
    BASS_DATA_FFT256 (BASS_ChannelGetData flag)
* Channel locking to prevent access by other threads
    BASS_ChannelLock
* Manual channel buffer updating
    BASS_ChannelUpdate
    BASS_ChannelPreBuf *removed*
* Configurable manual update length
    BASS_Update
* Extended device information retrieval and detection of new/removed devices
    BASS_GetDeviceInfo
    BASS_RecordGetDeviceInfo
    BASS_DEVICEINFO structure
    BASS_GetDeviceDescription *removed*
    BASS_RecordGetDeviceDescription *removed*
    BASS_INFO (driver member) *removed*
    BASS_RECORDINFO (driver member) *removed*
    MULTI example updated
* Default device change tracking on Windows (as on OSX)
    BASS_Init
    BASS_RecordInit
* Speaker detection from Windows control panel
    BASS_DEVICE_CPSPEAKERS (BASS_Init flag)
* Channel automatically stopped & resumed for DX8 effects
    BASS_ChannelSetFX
    BASS_ChannelRemoveFX
* "double" precision position conversion
    BASS_ChannelBytes2Seconds
    BASS_ChannelSeconds2Bytes
* Separate config functions for pointers
    BASS_SetConfigPtr
    BASS_GetConfigPtr
    BASS_CONFIG_NET_AGENT/PROXY (BASS_SetConfigPtr options)
* Configurable file format verification length
    BASS_CONFIG_VERIFY (BASS_SetConfig option)
* Stream filename retrieval
    BASS_CHANNELINFO (file member)
* Channel sample retrieval
    BASS_CHANNELINFO (sample member)
* META syncs no longer receive metadata in the "data" parameter
    BASS_SYNC_META (BASS_ChannelSetSync type)
* Separate sync for OGG logical bitstream changes (instead of BASS_SYNC_META)
    BASS_SYNC_OGG_CHANGE (BASS_ChannelSetSync type)
    NETRADIO example updated (C version)
* Message syncing removed (use PostMessage instead)
    BASS_SYNC_MESSAGE (BASS_ChannelSetSync flag) *removed*
* Data retrieval from stopped/paused channels
    BASS_ChannelGetData
* Callback "user" parameters changed to pointers
    BASS_StreamCreate / STREAMPROC
    BASS_StreamCreateFileUser
    BASS_StreamCreateURL / DOWNLOADPROC
    BASS_RecordStart / RECORDPROC
    BASS_ChannelSetDSP / DSPPROC
    BASS_ChannelSetSync / SYNCPROC

2.3.0.3 - 30/7/2007
-------------------
* FX state resetting
    BASS_FXReset
* PLS/M3U playlist URL processing
    BASS_CONFIG_NET_PLAYLIST (BASS_SetConfig option)
    NETRADIO example updated
* Internet stream connection status retrieval
    BASS_FILEPOS_CONNECTED (BASS_StreamGetFilePosition mode)
* Lyrics3v2 tags
    BASS_TAG_LYRICS3 (BASS_ChannelGetTags type)
* IT virtual channel configuration
    BASS_CONFIG_MUSIC_VIRTUAL (BASS_SetConfig option)
* Accurate speaker detection on Vista
    BASS_INFO (speakers member)
* Device output/input rate retrieval on Vista
    BASS_INFO (freq member)
    BASS_RECORDINFO (freq member)
* Syncing upon position changes
    BASS_SYNC_SETPOS (BASS_ChannelSetSync type)
* Improved stall handling
    BASS_SYNC_STALL
* Invalid decoding channel flags produce an error instead of being ignored
    BASS_StreamCreate/File/User/URL
    BASS_MusicLoad

2.3.0.2 - 22/1/2007
-------------------
* Retrieval of a sample's existing channel handles
    BASS_SampleGetChannels
* 8192 sample FFT
    BASS_DATA_FFT8192 (BASS_ChannelGetData flag)
* Adjustable recording buffer
    BASS_CONFIG_REC_BUFFER (BASS_SetConfig option)
* Stopping decoding channels before the end
    BASS_ChannelStop
* Sample channels created paused to prevent overriding before playback
    BASS_SampleGetChannel
* Separate "MP3-FREE" version using the OS's MP3 decoder
    BASS_CONFIG_MP3_CODEC *removed*

2.3.0.1 - 12/6/2006
-------------------
* Ability to move a channel to another device
    BASS_ChannelSetDevice
    MULTI example updated
* Support for ID3v2.4 tags at end of file
    BASS_TAG_ID3V2 (BASS_ChannelGetTags type)

2.3 - 21/5/2006
---------------
* MOD message/instrument/sample text retrieval, merged with stream tag retrieval function
    BASS_ChannelGetTags
    BASS_TAG_MUSIC_NAME/MESSAGE/INST/SAMPLE (BASS_ChannelGetTags types)
    BASS_MusicGetName *removed*
    BASS_StreamGetTags *removed*
* Plugin information retrieval
    BASS_PluginGetInfo
    BASS_PLUGININFO/FORM structures
    BASS_CHANNELINFO (plugin member)
    PLUGINS example updated
* RIFF/WAVE "INFO" tag retrieval
    BASS_TAG_RIFF_INFO (BASS_StreamGetTags type)
* More specific WAVE format information
    BASS_CTYPE_STREAM_WAV_PCM/FLOAT (channel types)
    BASS_CTYPE_STREAM_WAV (channel type flag)
* Proxy server configuration
    BASS_CONFIG_NET_PROXY (BASS_SetConfig option)
    BASS_CONFIG_NET_NOPROXY *removed*
    NETRADIO example updated
* Passive FTP mode
    BASS_CONFIG_NET_PASSIVE (BASS_SetConfig option)
* Agent changes take immediate effect
    BASS_CONFIG_NET_AGENT (BASS_SetConfig option)
* Minimum time gap between creating new sample channels
    BASS_SAMPLE (mingap member)
    BASS_SampleGetChannel
* Support for Unicode plugin filenames
    BASS_PluginLoad
* Device output/input rate retrieval (MacOSX only)
    BASS_INFO (freq member)
    BASS_RECORDINFO (freq member)
* Extended version info (minor revision)
    BASS_GetVersion
* Unsupported codec error code
    BASS_ERROR_CODEC
* Optional use of the Windows MP3 codec
    BASS_CONFIG_MP3_CODEC (BASS_SetConfig option)
* 3D support for MacOSX
    BASS_Set3DFactors
    BASS_Get3DFactors
    BASS_Set3DPosition
    BASS_Get3DPosition
    BASS_Apply3D
    BASS_ChannelSet3DAttributes
    BASS_ChannelGet3DAttributes
    BASS_ChannelSet3DPosition
    BASS_ChannelGet3DPosition
    3DTEST example added (Win32 example also updated)
* VB version of SYNTH example added

2.2 - 2/10/2005
---------------
* Add-on plugin system
    BASS_PluginLoad
    BASS_PluginFree
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
    PLUGINS example added
* MOD position & syncing in bytes
    BASS_ChannelSetPosition
    BASS_ChannelGetPosition
    BASS_MusicGetOrderPosition added for orders position
    BASS_SYNC_MUSICPOS added for orders syncing
    MAKEMUSICPOS macro/define
    CUSTLOOP example updated
* Stream/MOD "length" functions combined (also works with samples), new MOD orders length function
    BASS_ChannelGetLength
    BASS_MusicGetOrders
    BASS_StreamGetLength *removed*
    BASS_MusicGetLength *removed*
* Support for AIFF files
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
* Support for 24 and 32-bit (integer) WAV files
    BASS_StreamCreateFile/User/URL
    BASS_SampleLoad
* WAV files are no longer converted to the "device" resolution
    BASS_StreamCreateFile/User/URL
* Recording master control
    BASS_RecordGetInput
    BASS_RecordSetInput
* Adjustable pre-buffering
    BASS_ChannelPreBuf
* Floating-point data retrieval
    BASS_DATA_FLOAT (BASS_ChannelGetData flag)
* Support for floating-point samples
    BASS_SampleLoad
    BASS_SampleCreate
* Multi-channel samples
    BASS_SampleLoad/Create
    BASS_SAMPLE (chans member)
* Sample lengths given in bytes
    BASS_SampleCreate
    BASS_SAMPLE (length member)
* MOD music 8-bit resolution option
    BASS_MusicLoad
* OGG vendor tag retrieval
    BASS_TAG_VENDOR (BASS_StreamGetTags type)
* Configurable "User-Agent" header for internet streams
    BASS_CONFIG_NET_AGENT (BASS_SetConfig option)
* Shoutcast metadata is now requested automatically
    BASS_STREAM_META flag *removed*
* Download callbacks receive all data from start of file/stream (including any non-audio data)
    DOWNLOADPROC
* Length when streaming in blocks is unavailable (BASS_ERROR_NOTAVAIL, not just 0)
    BASS_ChannelGetLength
* Support for growing custom file streams
    BASS_FILE_LEN (STREAMFILEPROC action)
* Query file action removed
    BASS_FILE_QUERY *removed*
* Recording channel syncing
    BASS_ChannelSetSync
* Info structure "size" members removed
    BASS_INFO structure
    BASS_RECORDINFO structure
* Little bit of flag reshuffling
    BASS_MP3_SETPOS renamed to BASS_STREAM_PRESCAN
    BASS_MUSIC_CALCLEN value changed and renamed to BASS_MUSIC_PRESCAN
    BASS_MUSIC_POSRESET value changed
* Add-on API enhancements
* MacOSX port introduced

2.1 - 28/11/2004
----------------
* Improved "mixtime" sync system, allowing custom looping
    SYNCPROC
    CUSTLOOP example added
* FX can now be in the DSP chain, so can be prioritized and applied in floating-point
    BASS_ChannelSetFX
    BASS_CONFIG_FLOATDSP (BASS_SetConfig option)
* Ability to set channel flags (eg. looping) independent of playback
    BASS_ChannelSetFlags
    SPEAKERS example updated
* Stream/MOD "play" and channel "resume" functions combined
    BASS_ChannelPlay
    BASS_StreamPlay *removed*
    BASS_MusicPlay *removed*
    BASS_MusicPlayEx *removed*
    BASS_ChannelResume *removed*
* Stream/MOD pre-buffering functions combined
    BASS_ChannelPreBuf
    BASS_StreamPreBuf *removed*
    BASS_MusicPreBuf *removed*
* MOD attribute functions combined, with added BPM/speed/globalvolume options
    BASS_MusicSetAttribute
    BASS_MusicGetAttribute
    BASS_MUSIC_ATTRIB_AMPLIFY
    BASS_MUSIC_ATTRIB_PANSEP
    BASS_MUSIC_ATTRIB_PSCALER
    BASS_MUSIC_ATTRIB_BPM
    BASS_MUSIC_ATTRIB_SPEED
    BASS_MUSIC_ATTRIB_VOL_GLOBAL
    BASS_MUSIC_ATTRIB_VOL_CHAN
    BASS_MUSIC_ATTRIB_VOL_INST
    BASS_MusicSetAmplify *removed*
    BASS_MusicSetPanSep *removed*
    BASS_MusicSetPositionScaler *removed*
    BASS_MusicSetVolume *removed*
    BASS_MusicGetVolume *removed*
* Flag to reset bpm/etc as well as notes when seeking in MOD musics
    BASS_MUSIC_POSRESETEX (BASS_MusicLoad & BASS_ChannelSetFlags flag)
* More flexible and concise sample channel creation system
    BASS_SampleGetChannel
    BASS_SamplePlay *removed*
    BASS_SamplePlayEx *removed*
    BASS_SamplePlay3D *removed*
    BASS_SamplePlay3DEx *removed*
* Support for up to 30 speakers
    BASS_SPEAKER_N macro/define
* More precise level measurement
    BASS_ChannelGetLevel
* Level can now be retrieved from decoding channels
    BASS_ChannelGetLevel
* Retrieval of a sample/channel's original sample resolution
    BASS_SAMPLE (origres member)
    BASS_CHANNELINFO (origres member)
* Support for streaming WAV files in "blocks"
    BASS_StreamCreateURL
    BASS_StreamCreateFileUser
* Status info (HTTP/ICY tags) available during connection to server
    BASS_STREAM_STATUS (BASS_StreamCreateURL flag)
    DOWNLOADPROC
    NETRADIO example updated (Delphi version also added)
* Adjustable internet stream pre-buffering
    BASS_CONFIG_NET_PREBUF (BASS_SetConfig option)
* Option to bypass proxy server
    BASS_CONFIG_NET_NOPROXY (BASS_SetConfig option)
* Option whether to allow channels to be played after BASS_Pause
    BASS_CONFIG_PAUSE_NOPLAY (BASS_SetConfig option)
* Recording channel count now a separate parameter
    BASS_RecordStart (chans parameter)
* Synchronizer for when a channel is freed
    BASS_SYNC_FREE (BASS_ChannelSetSync type)
* Data start file position retrieval
    BASS_FILEPOS_START (BASS_StreamGetFilePosition mode)
* Performance improvements
    MP2 decoding ~20% faster
    MP3/MP1 decoding & FFT processing all up to 10% faster
    OGG decoding ~3% faster
* C/C++ examples reorganised, with makefiles & VC++ projects
* Add-on API enhancements
* More DLL shrinkage :)

2.0 - 31/10/2003
----------------
* Multiple output device support
    BASS_Init (device number changes)
    BASS_SetDevice
    BASS_GetDevice
    BASS_ChannelGetDevice
    MULTI example updated (VB version also added)
* Multiple recording device support
    BASS_RecordSetDevice
    BASS_RecordGetDevice
    BASS_RecordStart
    BASS_ChannelGetDevice
    HRECORD handle
    RECORDPROC (handle parameter)
* Recording with DSP/FX
    BASS_ChannelSetDSP
    BASS_ChannelSetFX
* Recording position retrieval
    BASS_ChannelGetPosition
* Start recording paused
    BASS_RECORD_PAUSE (BASS_RecordStart flag)
* Multi-channel streams, inc. support for multichannel OGG & WAV files
    BASS_StreamCreate
    BASS_StreamCreateFile/User/URL
* FFT for individual channels, inc. multi-channel streams
    BASS_DATA_FFT_INDIVIDUAL (BASS_ChannelGetData flag)
    BASS_DATA_FFT512S/1024S/2048S/4096S *removed*
* DSP prioritizing
    BASS_ChannelSetDSP
    DSPTEST example updated
* Seeking in internet streamed files
    BASS_ChannelSetPosition
* Enhanced custom file stream systems
    BASS_StreamCreateFileUser
    BASS_FILE_SEEK (STREAMFILEPROC action)
    BASS_STREAM_FILEPROC flag *removed*
* Enhanced custom stream system with automatic stalling/resuming
    STREAMPROC
    BASS_STREAMPROC_END (STREAMPROC flag)
* Synchronizer for stalled/resumed playback
    BASS_SYNC_STALL (BASS_ChannelSetSync type)
* Synchronizer for completed download
    BASS_SYNC_DOWNLOAD (BASS_ChannelSetSync type)
* End sync support for custom streams
    BASS_SYNC_END (BASS_ChannelSetSync type)
* Synchronizer support for decoding channels
    BASS_ChannelSetSync
* Unified configuration function
    BASS_SetConfig
    BASS_GetConfig
    BASS_SetBufferLength *removed*
    BASS_SetNetConfig *removed*
    BASS_SetGlobalVolumes *removed*
    BASS_GetGlobalVolumes *removed*
    BASS_SetLogCurves *removed*
    BASS_Set3DAlgorithm *removed*
    BASS_DEVICE_FLOATDSP flag *removed*
* Internet stream saving to disk replaced by more flexible callback
    BASS_StreamCreateURL
    DOWNLOADPROC
    VB NETRADIO example updated
* Buffer length retrieval when "streaming in blocks"
    BASS_FILEPOS_END (BASS_StreamGetFilePosition mode)
* Individual sample rate setting for MOD musics
    BASS_MusicLoad
* Channel type and default sample rate retrieval
    BASS_ChannelGetInfo (replaces BASS_ChannelGetFlags)
    BASS_CHANNELINFO
* MOD music flag retrieval
    BASS_CHANNELINFO (flags member)
* Adjustable instrument volumes in MOD musics
    BASS_MusicSetVolume (replaces BASS_MusicSetChannelVol)
    BASS_MusicGetVolume (replaces BASS_MusicGetChannelVol)
* Automatically free a MOD music when it stops or ends
    BASS_MUSIC_AUTOFREE (BASS_MusicLoad flag)
* Class GUID added to initialization parameters
    BASS_Init
    BASS_SetCLSID *removed*
* Update period adjustable at any time
    BASS_CONFIG_UPDATEPERIOD (BASS_SetConfig option)
    BASS_DEVICE_NOTHREAD flag *removed*
* Customizable maximum volume setting
    BASS_CONFIG_MAXVOL (BASS_SetConfig option)
    BASS_DEVICE_VOL1000 flag *removed*
* Device volume is now always left as it is during init/freeing
    BASS_DEVICE_LEAVEVOL flag *removed*
* Device driver name retrieval
    BASS_INFO (driver member)
    BASS_RECORDINFO (driver member)
* Error codes are local to the current thread
    BASS_ErrorGetCode
* Performance improvements
    MP2 decoding 15-20% faster
    MP3 decoding ~5% faster
* Built-in CD functions removed (replaced in BASSCD)
    BASS_CDDoor *removed*
    BASS_CDFree *removed*
    BASS_CDGetID *removed*
    BASS_CDGetTrackLength *removed*
    BASS_CDGetTracks *removed*
    BASS_CDInDrive *removed*
    BASS_CDInit *removed*
    BASS_CDPlay *removed*
* Force channels to use software mixing
    BASS_SAMPLE_SOFTWARE (BASS_StreamCreate/File/User/URL & BASS_MusicLoad flag)
* Support for high-pass filter and forward/reverse (S9E/F) IT/MPT effects
* BASS_MUSIC flags rearranged to mirror BASS_SAMPLE/STREAM counterparts
* Output automatically started during initialization
* BASS_ChannelGetData once again accepts any "length" param
* All function comments have been removed from the API headers to avoid
  outdated/incorrect information - the documentation should be used.
* TMT Pascal API removed from main distribution - now available on the website
* A few more 'K' knocked off the DLL size :)

1.8a - 18/6/2003
----------------
* Tweaks 'n' fixes, including...
    Fixed seeking bug on 32-bit OGG streams
    Fixed seeking on a decoding channel after it has reached the end
    Low FPU precision (eg. when using Direct3D) issue addressed
    Improved speakers (BASS_INFO) detection
    BASS_ChannelSeconds2Bytes return value is rounded down to nearest sample
    BASS_ChannelGetData "length" param must equal a whole number of samples
    Slide syncs are triggered by "-2" volume slides on "autofree" streams
* Support for Unicode filenames
    BASS_UNICODE (BASS_SampleLoad/BASS_StreamCreateFile/BASS_MusicLoad flag)
* 4096 sample FFT
    BASS_DATA_FFT4096/S (BASS_ChannelGetData flags)
* Another 'K' knocked off the DLL size

1.8 - 9/3/2003
--------------
* 32-bit floating-point channels
    BASS_SAMPLE_FLOAT (BASS_StreamCreate/File/URL flag)
    BASS_MUSIC_FLOAT (BASS_MusicLoad flag)
    BASS_SAMPLE_FLOAT (BASS_RecordStart flag)
    BASS_DEVICE_FLOATDSP (BASS_Init flag)
    DSPTEST example updated
* Support for 32-bit floating-point (type 3) WAV files
    BASS_StreamCreateFile/URL
    BASS_SampleLoad
* Channel speaker assignment
    BASS_SPEAKER_FRONT (BASS_MusicLoad/BASS_StreamCreate/File/URL flag)
    BASS_SPEAKER_REAR                       "
    BASS_SPEAKER_CENLFE                     "
    BASS_SPEAKER_REAR2                      "
    BASS_SPEAKER_FRONTLEFT                  "
    BASS_SPEAKER_FRONTRIGHT                 "
    BASS_SPEAKER_REARLEFT                   "
    BASS_SPEAKER_REARRIGHT                  "
    BASS_SPEAKER_CENTER                     "
    BASS_SPEAKER_LFE                        "
    BASS_SPEAKER_REAR2LEFT                  "
    BASS_SPEAKER_REAR2RIGHT                 "
    BASS_INFO (speakers member)
    BASS_DEVICE_SPEAKERS (BASS_Init flag)
    4SPEAKER example replaced by SPEAKERS example
* Recording input type retrieval
    BASS_INPUT_TYPE_xxx (BASS_RecordGetInput)
    RECTEST example updated
* Non-interpolated MOD mixing
    BASS_MUSIC_NONINTER (BASS_MusicLoad/PlayEx flag)
* Performance improvements
    FFT up to 100% faster!
    MP3(MPEG2/2.5) decoding up to 60% faster
    MMX mixers 5-10% faster
    MP3(MPEG1)/MP2/MP1/OGG decoding all ~5% faster
* Optional disabling of FFT windowing
    BASS_DATA_FFT_NOWINDOW (BASS_ChannelGetData flag)
* BASS_ERROR_FILEFORM - error code to distinguish between file and sample format
    BASS_MusicLoad
    BASS_SampleLoad
    BASS_StreamCreate/File/URL
* BASS_StreamGetFilePosition mode flags added
    BASS_FILEPOS_DECODE/DOWNLOAD/END
* DirectSound 9 detection
    BASS_INFO (dsver member)
* Initialization flags retrieval
    BASS_INFO (initflags member)
* Half-rate MP3 playback option removed
    BASS_MP3_HALFRATE flag *removed*
* New internal "plugin" system - BASSWMA is further integrated as a result
* Improved documentation - integrated with BASSWMA, search option added
* VB version of DSPTEST example added
* Delphi RECORDTEST example added
* Guess what... reduced DLL size again :)

1.7 - 27/10/2002
----------------
* New alternative DX8 (DMO) effects implementation
    BASS_StreamCreate/File/URL
    BASS_MusicLoad
    BASS_ChannelSetFX
    SYNTH example updated
* User file streaming
    BASS_STREAM_FILEPROC (BASS_StreamCreate flag)
    STREAMFILEPROC
* DSP & FX support for decoding channels
    BASS_ChannelSetDSP
    BASS_ChannelSetFX
* Support for DX8 (DMO) effects in IT/XM/MO3 files
    BASS_MusicLoad
* Support for chained OGG streaming (and syncing)
    BASS_StreamCreateURL
    BASS_SYNC_META (BASS_ChannelSetSync type)
* Attribute (volume/frequency/pan) sliding
    BASS_ChannelSlideAttributes
    BASS_ChannelIsSliding
    BASS_SYNC_SLIDE (BASS_ChannelSetSync type)
* Recording without a callback function
    BASS_RecordStart
    LIVEFX example added
* Query a channel's buffered data
    BASS_DATA_AVAILABLE (BASS_ChannelGetData flag)
* Discard data from the recording buffer
    BASS_ChannelGetData
* Adjustable internet stream config (timeout/buffer lengths)
    BASS_SetNetConfig
* Recommended minimum buffer length
    BASS_INFO (minbuf member)
* MOD music flags adjustment without changing playback position
    BASS_MusicPlayEx
    PLAYER (MASM) example updated
* More functions are now useable in MOD music "mixtime" syncs
    SYNCPROC
    BASS_ChannelSetPosition
    BASS_MusicPlayEx
    BASS_MusicSetAmplify
    BASS_MusicSetPanSep
* Maximum buffer length increased to 5 seconds
    BASS_SetBufferLength
* Support for extended filter range in IT files
    BASS_MusicLoad
* Speedier MOD music file verification
    BASS_MusicLoad
* Delphi 3DTEST example fixed
* Magically reduced DLL size again :)

1.6a - 25/8/2002
----------------
* OGG support updated to 1.0
* Stereo FFT
    BASS_DATA_FFT512S/1024S/2048S (BASS_ChannelGetData flags)
* Support for "Invert Loop" (EFx) MOD effect
* Reduced DLL size
* New Delphi examples
    WRITEWAV - WAVE writer example
    SAMPLEVIS - Visualisation example

1.6 - 13/6/2002
---------------
* 64-bit stream lengths and positions
    BASS_StreamGetLength
    BASS_ChannelBytes2Seconds
    BASS_ChannelSeconds2Bytes
    BASS_ChannelGetPosition
    BASS_ChannelSetPosition
    BASS_ChannelSetSync
* Recording input selection
    BASS_RECORDINFO (inputs & singlein members)
    BASS_RecordGetInputName
    BASS_RecordGetInput
    BASS_RecordSetInput
* Adjustable recording update period
    BASS_RecordStart
* Load OGG files as samples
    BASS_SampleLoad
* CD drive door opening & closing
    BASS_CDDoor
* CDDB2 ID retrieval
    BASS_CDID_CDDB2 (BASS_CDGetID flag)
* Streaming beyond initial file length
    BASS_StreamCreateFile
* Recording position bytes<->seconds translation
    BASS_ChannelBytes2Seconds
    BASS_ChannelSeconds2Bytes
* Improved multi-threaded support (play from any thread)
    BASS_MusicPlay/Ex
    BASS_SamplePlay/3D/Ex
    BASS_StreamPlay
    BASS_DEVICE_NOSYNC flag *removed*
* Paused channel status
    BASS_ACTIVE_PAUSED (BASS_ChannelIsActive)
* Integrated WMA stream freeing
    BASS_StreamFree
    BASS_Free
* Pin-point accurate OGG seeking without BASS_MP3_SETPOS flag
* Win2k DS buffer bug fix

1.5a - 14/4/2002
----------------
* NT4 fix (also enables "nosound" device without DX installed)
    BASS_ERROR_DX error code
* MOD music loading without the samples
    BASS_MUSIC_NOSAMPLE (BASS_MusicLoad flag)
* Custom decoding channels
    BASS_STREAM_DECODE (BASS_StreamCreate flag)
* 5 second HTTP connection timeout
    BASS_ERROR_TIMEOUT (BASS_StreamCreateURL error code)

1.5 - 31/3/2002
---------------
* Improved performance
    MMX mixers lot faster (over 50% faster in some cases!)
    OGG decoding 15-20% faster
    MP3 decoding 5-10% faster
* Recording
    BASS_RecordGetDeviceDescription
    BASS_RecordInit
    BASS_RecordFree
    BASS_RecordGetInfo
    BASS_RecordStart
* OGG support built-in (OGG/VORBIS DLLs not required)
    BASS_DEVICE_OGG flag *removed*
* MOD music seeking in seconds
    BASS_MusicPlayEx
    BASS_ChannelSetPosition
* Shoutcast metadata retrieval
    BASS_STREAM_META (BASS_StreamCreateURL flag)
    BASS_TAG_META (BASS_StreamGetTags type)
    BASS_SYNC_META (BASS_ChannelSetSync type)
* 1000 volume levels
    BASS_DEVICE_VOL1000 (BASS_Init/CDInit flag)
* CDDB ID retrieval
    BASS_CDID_CDDB (BASS_CDGetID flag)
* Leave the CD volume as it is during init/closing
    BASS_DEVICE_LEAVEVOL (BASS_CDInit flag)
* FFT enabled on decoding channels
    BASS_ChannelGetData
* Left level duplicated on right for mono channels
    BASS_ChannelGetLevel
* Improved MPEG length estimation without BASS_MP3_SETPOS flag
    BASS_StreamGetLength
* Support for Modplug/ADPCM compressed files
    BASS_MusicLoad
* Device description function parameter change
    BASS_GetDeviceDescription
* MASM API

1.4 - 30/1/2002
---------------
* Channel decoding without playback
    BASS_MUSIC_DECODE (BASS_MusicLoad flag)
    BASS_STREAM_DECODE (BASS_StreamCreateFile/URL flag)
    BASS_ChannelGetData
* Windows message sync callbacks
    BASS_SYNC_MESSAGE (BASS_ChannelSetSync flag)
* Adjustable channel volumes in MOD musics
    BASS_MusicSetChannelVol
    BASS_MusicGetChannelVol
* Customizable DirectSound initialization object
    BASS_SetCLSID
* Retrieve HMUSIC/HSTREAM/HCHANNEL IDirectSoundBuffer interfaces
    BASS_GetDSoundObject
* A3D functions removed (use BASS_SetCLSID/BASS_GetDSoundObject to access A3D)
    BASS_DEVICE_A3D (BASS_Init flag)
    BASS_SetA3DResManager
    BASS_GetA3DResManager
    BASS_SetA3DHFAbsorbtion
    BASS_GetA3DHFAbsorbtion
* Callback functions now work in VB6
    DSPPROC
    STREAMPROC
    SYNCPROC
* Improved PCM WAVE streaming performance
    BASS_StreamCreateFile
    BASS_StreamCreateURL
* OGG modules updated to RC3
* Stereo sample support in MO3 format
* MO3 encoder now distributed separately from BASS

1.3 - 17/11/2001
----------------
* Manual buffer updating
    BASS_DEVICE_NOTHREAD (BASS_Init flag)
    BASS_Update
* Adjustable buffer update period (allows small buffer sizes)
    BASS_Init
* Output device latency retrieval
    BASS_INFO (latency member)
* MPEG/OGG seeking without BASS_MP3_SETPOS flag
    BASS_ChannelSetPosition
* Internet file streaming from offsets
    BASS_StreamCreateURL
* File stream tag/comment retrieval (ID3/ID3v2/OGG/HTTP/ICY tags)
    BASS_StreamGetTags
* Byte<->time position translation
    BASS_ChannelBytes2Seconds
    BASS_ChannelSeconds2Bytes
* UMX (Unreal/Tournament music package) format support
    BASS_MusicLoad
* S3M/IT sync fx changed to S2x (S0x conflicted with S00)
    BASS_SYNC_MUSICFX
* Stereo sample support in IT/XM/S3M formats
* MO3: OGG compression supported

1.2 - 25/9/2001
---------------
* OGG (Ogg Vorbis) stream support
    BASS_DEVICE_OGG (BASS_Init flag)
    BASS_StreamCreateFile
    BASS_StreamCreateURL
* Channel linking (start/stop/pause/resume channels together)
    BASS_ChannelSetLink
    BASS_ChannelRemoveLink
* MOD music playback length calculation
    BASS_MUSIC_CALCLEN (BASS_MusicLoad flag)
    BASS_MusicGetLength
* Pre-buffering
    BASS_MusicPreBuf
    BASS_StreamPreBuf
* Samples with single simultaneous playbacks have same HSAMPLE/HCHANNEL handle
    BASS_SamplePlay/Ex
* Stopping a custom stream flushes its buffer contents
    BASS_ChannelStop

1.1a - 31/8/2001
----------------
* NT4 bug fixed
* XM Wxx effect syncing
    BASS_SYNC_MUSICFX
* MP3/2/1 rewinding without BASS_MP3_SETPOS
    BASS_ChannelSetPosition

1.1 - 11/8/2001
---------------
* DX8 (DMO) effects
    BASS_SAMPLE_FX (BASS_StreamCreate/File/URL flag)
    BASS_MUSIC_FX (BASS_MusicLoad flag)
    BASS_ChannelSetFX
    BASS_ChannelRemoveFX
    BASS_FXSetParameters
    BASS_FXGetParameters
    BASS_FXCHORUS structure
    BASS_FXCOMPRESSOR structure
    BASS_FXDISTORTION structure
    BASS_FXECHO structure
    BASS_FXFLANGER structure
    BASS_FXGARGLE structure
    BASS_FXI3DL2REVERB structure
    BASS_FXPARAMEQ structure
    BASS_FXREVERB structure
* Internet file streaming in blocks (inc. Shoutcast/Icecast stream support)
    BASS_STREAM_BLOCK (BASS_StreamCreateURL flag)
* 512/1024/2048 sample FFT
    BASS_DATA_FFT512/1024/2048 (BASS_ChannelGetData flags)
* CD identification
    BASS_CDGetID
* Improved DX version detection
    BASS_INFO (dsver member)

1.0 - 20/6/2001
---------------
* Load MP3/MP2/MP1 files as samples
    BASS_SampleLoad
* Internet file streaming from FTP servers
    BASS_StreamCreateURL
* Save a local copy of internet file streams
    BASS_StreamCreateURL
* Sample accurate file stream seeking
    BASS_ChannelSetPosition
    BASS_StreamGetBlockLength *removed*
* Stream position synchronizer
    BASS_SYNC_POS
* Increased synchronizer precision
* Improved MPEG file detection and error detection
* Stop MOD musics on a backwards jump effect
    BASS_MUSIC_STOPBACK (BASS_MusicLoad/PlayEx flag)
* Leave the volume as it is during closing (as well as initialization)
    BASS_DEVICE_LEAVEVOL (BASS_Init flag)
* Optional automatic use of foreground window handle during initialization
    BASS_Init
* Reduced DLL size
* VB API fixes

0.9 - 18/4/2001
---------------
* Internet file streaming
    BASS_StreamCreateURL
* MP1 & MP2 (MPEG layer 1 & 2) support
    BASS_StreamCreateFile/URL
* MPEG 2.5 support (12000/11025/8000hz sample rates)
    BASS_StreamCreateFile/URL
* Decoding/download/end file stream position retrieval
    BASS_StreamGetFilePosition
* XMPlay surround sound for MOD musics
    BASS_MUSIC_SURROUND (BASS_MusicLoad/PlayEx flag)
    BASS_MUSIC_SURROUND2 (BASS_MusicLoad/PlayEx flag)
* Restrict the download rate of internet file streams
    BASS_STREAM_RESTRATE (BASS_StreamCreateURL flag)
* Check if an internet file stream is stalled
    BASS_ChannelIsActive
* Automatically free a stream when it stops or ends
    BASS_STREAM_AUTOFREE (BASS_StreamCreate/File/URL flag)
* Leave the volume as it is during initialization
    BASS_DEVICE_LEAVEVOL (BASS_Init flag)
* Number of CD tracks retrieval
    BASS_CDGetTracks
* CD track length retrieval
    BASS_CDGetTrackLength
* Exact stream length set after whole file is streamed
    BASS_StreamGetLength
* TMT Pascal API and samples
* Dynamic-loading Delphi API

0.8a - 28/2/2000
----------------
* Updated Delphi API and samples

0.8 - 24/1/2000
---------------
* Improved MP3 performance on P2/K6 and above CPUs
* User DSP functions on streams and MOD musics
    BASS_ChannelSetDSP
    BASS_ChannelRemoveDSP
* DX7 voice allocation & management
    BASS_SAMPLE_VAM (BASS_SampleLoad/Create flag)
    BASS_VAM_xxx flags
    BASS_SAMPLE (vam & priority members)
* DX7 software 3D algorithm selection
    BASS_Set3DAlgorithm
* DirectSound interface retrieval
    BASS_GetDSoundObject
* Log/linear volume & panning curves
    BASS_SetLogCurves
* User data passed to callback functions
    STREAMPROC - BASS_StreamCreate
    SYNCPROC - BASS_ChannelSetSync
* New synchronizer
    BASS_SYNC_MUSICFX
* New synchronizer flag
    BASS_SYNC_MIXTIME
* Disable synchronizers option - saves a little CPU time
    BASS_DEVICE_NOSYNC (BASS_Init flag)
* Hi-res floating-point CPU usage monitoring
    BASS_GetCPU
* Wait for playback to start when playing a CD
    BASS_CDPlay
* DirectSound (dsound.dll) version retrieval
    BASS_INFO (dsver member)
* Removed volume sliding functions (they were fairly pointless)
    BASS_SlideVolume
    BASS_IsSliding
* MO3: read/write encoder settings
* MO3: remove inst/samp/message texts now optional
* MO3: LAME encoder settings

0.7 - 3/10/1999
---------------
* MO3 (MP3 compressed MODs)
* A3D functions
    BASS_DEVICE_A3D (BASS_Init flag)
    BASS_INFO (a3d member)
    BASS_SetA3DResManager
    BASS_GetA3DResManager
    BASS_SetA3DHFAbsorbtion
    BASS_GetA3DHFAbsorbtion
* Music/stream immediate sample data retrieval
    BASS_ChannelGetData
* File stream (WAV/MP3) length retrieval
    BASS_StreamGetLength
    BASS_StreamGetBlockLength
* File stream seeking
    BASS_ChannelSetPosition
* Mono MP3 option (lower CPU usage)
    BASS_StreamCreateFile
* Music length retrieval
    BASS_MusicGetLength
* Music name retrieval
    BASS_MusicGetName
* Stop notes when moving MOD music position
    BASS_MUSIC_POSRESET (BASS_MusicLoad/BASS_MusicPlayEx flag)
* BASS_ERROR_FREQ - invalid sample rate error code
    BASS_SampleCreate
    BASS_SamplePlayEx
    BASS_SamplePlay3DEx
    BASS_StreamCreate
    BASS_ChannelSetAttributes
* Delphi and VB APIs

0.6a - 26/7/1999
----------------
* Half rate MP3 option (lower CPU usage)
    BASS_MP3_HALFRATE
* Loading/streaming from file offsets
    BASS_MusicLoad
    BASS_SampleLoad
    BASS_StreamCreateFile
* Global music/sample/stream volume levels
    BASS_SetGlobalVolumes
    BASS_GetGlobalVolumes
* Other new function
    BASS_SampleStop
* New synchronizer
    BASS_SYNC_END
* New sample overrider
    BASS_SAMPLE_OVER_DIST
* LoadLibrary/GetProcAddress instructions and example

0.5 - 4/7/1999
--------------
* Documentation!
* File streaming (MP3 and WAV)
    BASS_StreamCreateFile
* Custom generated samples
    BASS_SampleCreate
    BASS_SampleCreateDone
* Other new function
    BASS_MusicSetPositionScaler
* Renamed function
    BASS_ChannelClearSync -> BASS_ChannelRemoveSync
* Alterations made to
    BASS_ChannelGetPosition
    BASS_SampleLoad
    BASS_StreamPlay

0.4 - 30/3/1999
---------------
* Compressed WAV samples support (using audio CODECs)
* Updated CD volume handling - now works with SB Live
* More linear channel volume/pan scales (were slightly off before)
* "No sound" device option
* 3D sound functions
    BASS_Set3DFactors
    BASS_Get3DFactors
    BASS_Set3DPosition
    BASS_Get3DPosition
    BASS_Apply3D
    BASS_SamplePlay3D
    BASS_SamplePlay3DEx
    BASS_ChannelSet3DAttributes
    BASS_ChannelGet3DAttributes
    BASS_ChannelSet3DPosition
    BASS_ChannelGet3DPosition
* EAX functions
    BASS_SetEAXParameters
    BASS_GetEAXParameters
    BASS_ChannelSetEAXMix
    BASS_ChannelGetEAXMix
* Other new functions
    BASS_GetDeviceDescription
    BASS_SetBufferLen
    BASS_ChannelGetFlags
    BASS_ChannelPause
    BASS_ChannelResume
    BASS_ChannelSetPosition
* Replaced function
    BASS_CDResume -> BASS_ChannelResume
* Alterations made to
    BASS_Init
    BASS_CDInit
    BASS_SampleLoad
    BASS_StreamPlay
    BASS_INFO structure
    BASS_SAMPLE structure
    BASS_DEVICE_xxx flags
    BASS_SAMPLE_xxx flags

0.3 - 8/3/1999
--------------
* Synchronization functions
    BASS_ChannelSetSync
    BASS_ChannelClearSync
* Other new functions
    BASS_GetVersion
    BASS_ChannelGetPosition
    BASS_ChannelGetLevel
    BASS_ChannelGetAttributes
    BASS_ChannelSetAttributes
* Replaced functions
    BASS_MusicStop -> BASS_ChannelStop
    BASS_MusicSetVolume -> BASS_ChannelSetAttributes
    BASS_CDStop -> BASS_ChannelStop
    BASS_CDSetVolume -> BASS_ChannelSetAttributes
    BASS_CDGetVolume -> BASS_ChannelGetAttributes
    BASS_ChannelUpdate -> BASS_ChannelSetAttributes
* Alterations made to
    BASS_MusicPlayEx
    BASS_StreamPlay
    BASS_INFO structure

0.2 - 28/2/1999
---------------
* First public release

Bug reports, Suggestions, Comments, Enquiries, etc
==================================================
If you have any of the aforementioned please visit the BASS forum at the
website. If you can't find an answer there, you can also email:

    bass@un4seen.com


Upgrading from 2.3

As with every release, all functions/etc affected by a change are listed in the "History" section of the BASS.TXT file. To make upgrading existing code simple, some brief guidelines are also listed below.

BASS_GetDeviceDescription, BASS_RecordGetDeviceDescription
These functions have been superseded by the new BASS_GetDeviceInfo and BASS_RecordGetDeviceInfo functions, respectively.

BASS_INFO, BASS_RECORDINFO
The "driver" member has been moved to the new BASS_DEVICEINFO structure.

BASS_Init, BASS_RecordInit
The default device (-1) is no longer hardcoded to the first device on Windows (already the case on OSX).

BASS_ChannelGetAttributes, BASS_ChannelSetAttributes, BASS_ChannelSlideAttributes
These functions have been replaced by BASS_ChannelGetAttribute, BASS_ChannelSetAttribute and BASS_ChannelSlideAttribute, respectively.

BASS_ChannelIsSliding
An "attrib" parameter has been added to check if a specific attribute is sliding.

BASS_MusicGetAttribute, BASS_MusicSetAttribute
These functions have been incorporated into BASS_ChannelGetAttribute and BASS_ChannelSetAttribute. The channel and instrument volume settings are also now floating-point, with a range of 0 to 1. The attribute names have also changed slightly: the "MUSIC" and "ATTRIB" parts are swapped around.

BASS_ChannelGetLength, BASS_ChannelGetPosition, BASS_ChannelSetPosition
A "mode" parameter has been added to these 3 functions. Set that to BASS_POS_BYTE (or 0) to maintain the previous functionality.

BASS_MusicGetOrders, BASS_MusicGetOrderPosition, MAKEMUSICPOS
These functions (and macro) have been incorporated into BASS_ChannelGetLength, BASS_ChannelGetPosition and BASS_ChannelSetPosition, via the BASS_POS_MUSIC_ORDER "mode".

BASS_MusicLoad
The "offset" parameter is now 64-bit (QWORD).

BASS_SampleLoad
The "offset" parameter is now 64-bit (QWORD).

BASS_SampleCreate
This function now returns a sample handle. The sample's data can be set using the new BASS_SampleSetData function.

BASS_SampleCreateDone
This function is no longer required following the change to BASS_SampleCreate.

BASS_StreamCreateFile
The "offset" and "length" parameters are now 64-bit (QWORD).

BASS_StreamGetFilePosition
The return value is now 64-bit (QWORD).

BASS_GetVolume, BASS_SetVolume
The volume is now a floating-point value, with a range of 0 to 1.

BASS_CONFIG_MAXVOL
This config option has been removed, as it is no longer needed following the advent of floating-point volume settings.

BASS_CONFIG_GVOL_MUSIC, BASS_CONFIG_GVOL_SAMPLE, BASS_CONFIG_GVOL_STREAM
The global volume settings now have a range of 0 to 10000.

BASS_RecordGetInput, BASS_RecordSetInput
The volume has been separated from the flags and made a floating-point value, with a range of 0 to 1.

BASS_Update
A "length" parameter has been added.

BASS_ChannelPreBuf
This function has been superseded by BASS_ChannelUpdate. No parameter changes are required.

BASS_ChannelSetFlags
This function has been superseded by BASS_ChannelFlags. For the same functionality, set the "mask" parameter to -1.

BASS_ChannelSetSync
BASS_SYNC_META sync callbacks no longer receive the metadata in the "data" parameter. It can be retrieved via BASS_ChannelGetTags (BASS_TAG_META) instead. The BASS_SYNC_META sync is also no longer triggered by a new logical bitstream in a chained OGG stream; a dedicated BASS_SYNC_OGG_CHANGE sync has been added for that purpose. The BASS_SYNC_MESSAGE flag has been removed, and can be reproduced by using the PostMessage Win32 API function in a SYNCPROC.

BASS_ChannelBytes2Seconds
The return value is now 64-bit floating-point (double).

BASS_ChannelSeconds2Bytes
The "pos" parameter is now 64-bit floating-point (double).

BASS_SetConfig
This function now returns a boolean value, instead of the config's new setting. If needed, BASS_GetConfig can be used to get that.

BASS_CONFIG_NET_AGENT, BASS_CONFIG_NET_PROXY
Config options that deal with pointers, like these 2, are now handled by the new BASS_SetConfigPtr and BASS_GetConfigPtr functions.

BASS_CHANNELINFO
"sample" and "filename" members have been added.

DSPPROC, DOWNLOADPROC, RECORDPROC, STREAMPROC, SYNCPROC
All callback function "user" parameters are now pointers.

Upgrading from 2.2

In case you're skipping a version, here are the previous upgrade guidelines.

BASS_GetVersion
The format of the return value has been changed, to include the minor revision.

BASS_StreamGetTags
This function is replaced by BASS_ChannelGetTags. No parameter changes are required.

BASS_MusicGetName
This function is replaced by BASS_ChannelGetTags and the BASS_TAG_MUSIC_NAME tag type.

BASS_PluginLoad
A "flags" parameter has been added.

BASS_CONFIG_NET_NOPROXY
This config option has been replaced by the more flexible BASS_CONFIG_NET_PROXY config option. The BASS_CONFIG_NET_NOPROXY behaviour can be reproduced by setting the new option to NULL.

BASS_CTYPE_STREAM_WAV
This "ctype" is now just a flag to indicate any type of WAVE file, and is no longer a channel type in itself. The LOWORD used with this flag indicates the specific codec (PCM, ADPCM, etc).

BASS_CHANNELINFO, BASS_INFO, BASS_RECORDINFO, BASS_SAMPLE
These four structures have new "plugin", "freq", "freq" and "mingap" members, respectively.

Upgrading from 2.1

In case you're skipping another version, here are the previous upgrade guidelines.

BASS_StreamGetLength, BASS_MusicGetLength
These functions have been merged into BASS_ChannelGetLength, which gives the byte length of a channel. To get the number of orders in a MOD music, BASS_MusicGetOrders has been added. Also note that requesting the length when streaming in blocks will now result in a BASS_ERROR_NOTAVAIL error, instead of just 0.

BASS_ChannelGetPosition
This function now returns the position in bytes with MOD musics, as it does with other channels. BASS_MusicGetOrderPosition has been added to get the order/row position.

BASS_ChannelSetPosition
This function now sets the position in bytes with MOD musics by default. A MAKEMUSICPOS macro has been added for setting the position in orders/rows.

BASS_ChannelSetSync
The BASS_SYNC_POS sync parameter is now in bytes for MOD musics too. Use the BASS_SYNC_MUSICPOS sync for order/row positions. BASS_ChannelPreBuf
A "length" parameter has been added, to specify how much data to pre-buffer.

BASS_SampleCreate
The number of channels is now specified in a separate parameter, rather than via the use of the BASS_SAMPLE_MONO flag. The sample length is also now specified in bytes rather than samples.

BASS_StreamCreateFile
WAV files are no longer automatically converted to the device initialization resolution (as specified in the BASS_Init call), eg. 8-bit WAV files will produce 8-bit streams.

BASS_StreamCreateURL
Shoutcast metadata is now requested automatically, so the BASS_STREAM_META flag has been removed.

BASS_INFO structure, BASS_RECORDINFO structure
The "size" member has been removed, so there's now no need to set that before calling BASS_GetInfo and BASS_RecordGetInfo.

BASS_SAMPLE structure
A "chans" member has been added.

STREAMFILEPROC callback
The BASS_FILE_QUERY action has been removed. The BASS_FILE_LEN action may be used more than once with unbuffered streams, not just at the start.

Upgrading from 2.0

In case you're skipping another version, here are the previous upgrade guidelines.

BASS_StreamPlay
This function is replaced by BASS_ChannelPlay. The "flags" parameter is not carried forward to the new function, instead the flags can be changed at any time using BASS_ChannelSetFlags.

BASS_MusicPlay, BASS_MusicPlayEx
These functions are also replaced by BASS_ChannelPlay. The BASS_MusicPlayEx "pos" and "flags" parameters are not carried forward to the new function, instead they can be implemented via the BASS_ChannelSetPosition and BASS_ChannelSetFlags functions. The "reset" parameter is also not carried forward, the BASS_MUSIC_POSRESETEX flag replaces that.

BASS_SamplePlay, BASS_SamplePlayEx, BASS_SamplePlay3D, BASS_SamplePlay3DEx
These functions are replaced by a combination of BASS_SampleGetChannel and BASS_ChannelPlay. The BASS_ChannelSetAttributes and BASS_ChannelSet3DAttributes functions can be used to replace the functionality of the "Ex" versions.

BASS_ChannelResume
Another function replaced by BASS_ChannelPlay.

BASS_MusicSetAmplify, BASS_MusicSetPanSep, BASS_MusicSetPositionScaler, BASS_MusicSetVolume, BASS_MusicGetVolume
These functions are all replaced by BASS_MusicSetAttribute and BASS_MusicGetAttribute.

BASS_StreamPreBuf, BASS_MusicPreBuf
These functions are replaced by BASS_ChannelPreBuf.

BASS_RecordStart
The number of channels (mono/stereo) is now specified in a separate parameter, rather than via the use of the BASS_SAMPLE_MONO flag.

BASS_ChannelGetLevel
The level reading is now more precise, having a range of 0 to 32768, instead of the old 0 to 128.

BASS_ChannelSetFX
There is a new "priority" parameter.

BASS_CONFIG_FLOATDSP
Note that this config option can now affect FX too.


BASS_GetConfig

Retrieves the value of a config option.

DWORD BASS_GetConfig(
    DWORD option
);

Parameters

optionThe option to get the value of... one of the following.
BASS_CONFIG_3DALGORITHM | The 3D algorithm for software mixed 3D channels.
BASS_CONFIG_AM_DISABLE | Disable the use of Android media codecs?
BASS_CONFIG_ANDROID_AAUDIO | Enable AAudio output on Android?
BASS_CONFIG_ANDROID_SESSIONID | Session ID to use for output on Android.
BASS_CONFIG_ASYNCFILE_BUFFER | Asynchronous file reading buffer length.
BASS_CONFIG_BUFFER | Playback buffer length.
BASS_CONFIG_CURVE_PAN | Panning translation curve.
BASS_CONFIG_CURVE_VOL | Volume translation curve.
BASS_CONFIG_DEV_BUFFER | Output device buffer length.
BASS_CONFIG_DEV_DEFAULT | Include a "Default" entry in the output device list?
BASS_CONFIG_DEV_NONSTOP | Do not stop an output device when nothing is playing?
BASS_CONFIG_DEV_PERIOD | Output device update period.
BASS_CONFIG_FLOAT | Floating-point sample data is supported?
BASS_CONFIG_FLOATDSP | Pass 32-bit floating-point sample data to all DSP functions?
BASS_CONFIG_GVOL_MUSIC | Global MOD music volume.
BASS_CONFIG_GVOL_SAMPLE | Global sample volume.
BASS_CONFIG_GVOL_STREAM | Global stream volume.
BASS_CONFIG_HANDLES | Number of existing HMUSIC / HRECORD / HSAMPLE / HSTREAM handles.
BASS_CONFIG_IOS_SESSION | Audio session configuration on iOS.
BASS_CONFIG_MF_DISABLE | Disable the use of Media Foundation?
BASS_CONFIG_MF_VIDEO | Play the audio from videos using Media Foundation?
BASS_CONFIG_MUSIC_VIRTUAL | IT virtual channels.
BASS_CONFIG_NET_BUFFER | Internet download buffer length.
BASS_CONFIG_NET_PASSIVE | Use passive mode in FTP connections?
BASS_CONFIG_NET_PLAYLIST | Process URLs in playlists?
BASS_CONFIG_NET_PLAYLIST_DEPTH | Maximum nested playlist processing depth.
BASS_CONFIG_NET_PREBUF | Amount to pre-buffer before playing internet streams.
BASS_CONFIG_NET_PREBUF_WAIT | Wait for pre-buffering when opening internet streams?
BASS_CONFIG_NET_READTIMEOUT | Time to wait for a server to deliver more data.
BASS_CONFIG_NET_TIMEOUT | Time to wait for a server to respond to a connection request.
BASS_CONFIG_OGG_PRESCAN | Pre-scan chained OGG files?
BASS_CONFIG_PAUSE_NOPLAY | Prevent channels being played when the output is paused?
BASS_CONFIG_REC_BUFFER | Recording buffer length.
BASS_CONFIG_SRC | Default sample rate conversion quality.
BASS_CONFIG_SRC_SAMPLE | Default sample rate conversion quality for samples.
BASS_CONFIG_UNICODE | Unicode device information?
BASS_CONFIG_UPDATEPERIOD | Update period of playback buffers.
BASS_CONFIG_UPDATETHREADS | Number of update threads.
BASS_CONFIG_VERIFY | File format verification length.
BASS_CONFIG_VERIFY_NET | File format verification length for internet streams.
BASS_CONFIG_VISTA_SPEAKERS | Enable speaker assignment with panning/balance control on Windows Vista and newer?
BASS_CONFIG_VISTA_TRUEPOS | Enable true play position mode on Windows Vista and newer?
BASS_CONFIG_WASAPI_PERSIST | Retain Windows mixer settings across sessions?
other config options may be supported by add-ons, see the documentation.

Return value

If successful, the value of the requested config option is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_ILLPARAM option is invalid.

See also

BASS_GetConfigPtr, BASS_SetConfig


BASS_GetConfigPtr

Retrieves the value of a pointer config option.

void *BASS_GetConfigPtr(
    DWORD option
);

Parameters

optionThe option to set the value of... one of the following.
BASS_CONFIG_LIBSSL | Library to use for handling HTTPS connections.
BASS_CONFIG_NET_AGENT | "User-Agent" header.
BASS_CONFIG_NET_PROXY | Proxy server settings.
other config options may be supported by add-ons, see the documentation.

Return value

If successful, the value of the requested config option is returned, else NULL is returned. NULL may also be a valid setting with some config options, in which case the error code should be used to confirm whether it's an error. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_ILLPARAM option is invalid.

See also

BASS_GetConfig, BASS_SetConfigPtr


BASS_SetConfig

Sets the value of a config option.

BOOL BASS_SetConfig(
    DWORD option,
    DWORD value
);

Parameters

optionThe option to set the value of... one of the following.
BASS_CONFIG_3DALGORITHM | The 3D algorithm for software mixed 3D channels.
BASS_CONFIG_AM_DISABLE | Disable the use of Android media codecs?
BASS_CONFIG_ANDROID_AAUDIO | Enable AAudio output on Android?
BASS_CONFIG_ANDROID_SESSIONID | Session ID to use for output on Android.
BASS_CONFIG_ASYNCFILE_BUFFER | Asynchronous file reading buffer length.
BASS_CONFIG_BUFFER | Playback buffer length.
BASS_CONFIG_CURVE_PAN | Panning translation curve.
BASS_CONFIG_CURVE_VOL | Volume translation curve.
BASS_CONFIG_DEV_BUFFER | Output device buffer length.
BASS_CONFIG_DEV_DEFAULT | Include a "Default" entry in the output device list?
BASS_CONFIG_DEV_NONSTOP | Do not stop an output device when nothing is playing?
BASS_CONFIG_DEV_PERIOD | Output device update period.
BASS_CONFIG_FLOATDSP | Pass 32-bit floating-point sample data to all DSP functions?
BASS_CONFIG_GVOL_MUSIC | Global MOD music volume.
BASS_CONFIG_GVOL_SAMPLE | Global sample volume.
BASS_CONFIG_GVOL_STREAM | Global stream volume.
BASS_CONFIG_IOS_SESSION | Audio session configuration on iOS.
BASS_CONFIG_MF_DISABLE | Disable the use of Media Foundation?
BASS_CONFIG_MF_VIDEO | Play the audio from videos using Media Foundation?
BASS_CONFIG_MUSIC_VIRTUAL | IT virtual channels.
BASS_CONFIG_NET_BUFFER | Internet download buffer length.
BASS_CONFIG_NET_PASSIVE | Use passive mode in FTP connections?
BASS_CONFIG_NET_PLAYLIST | Process URLs in playlists?
BASS_CONFIG_NET_PLAYLIST_DEPTH | Maximum nested playlist processing depth.
BASS_CONFIG_NET_PREBUF | Amount to pre-buffer before playing internet streams.
BASS_CONFIG_NET_PREBUF_WAIT | Wait for pre-buffering when opening internet streams?
BASS_CONFIG_NET_READTIMEOUT | Time to wait for a server to deliver more data.
BASS_CONFIG_NET_TIMEOUT | Time to wait for a server to respond to a connection request.
BASS_CONFIG_OGG_PRESCAN | Pre-scan chained OGG files?
BASS_CONFIG_PAUSE_NOPLAY | Prevent channels being played when the output is paused?
BASS_CONFIG_REC_BUFFER | Recording buffer length.
BASS_CONFIG_SRC | Default sample rate conversion quality.
BASS_CONFIG_SRC_SAMPLE | Default sample rate conversion quality for samples.
BASS_CONFIG_UNICODE | Unicode device information?
BASS_CONFIG_UPDATEPERIOD | Update period of playback buffers.
BASS_CONFIG_UPDATETHREADS | Number of update threads.
BASS_CONFIG_VERIFY | File format verification length.
BASS_CONFIG_VERIFY_NET | File format verification length for internet streams.
BASS_CONFIG_VISTA_SPEAKERS | Enable speaker assignment with panning/balance control on Windows Vista and newer?
BASS_CONFIG_VISTA_TRUEPOS | Enable true play position mode on Windows Vista and newer?
BASS_CONFIG_WASAPI_PERSIST | Retain Windows mixer settings across sessions?
other config options may be supported by add-ons, see the documentation.
value The new option setting. See the option's documentation for details on the possible values.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_ILLPARAM option is invalid.

Remarks

Some config options have a restricted range of values, so the config's actual value may not be the same as requested if it was out of range. BASS_GetConfig can be used to confirm what the value is.

Config options can be used at any time and are independent of initialization, ie. BASS_Init does not need to have been called beforehand.

Where a config option is shown to have a "BOOL" value, 0 (zero) is taken to be "FALSE" and anything else is taken to be "TRUE".

See also

BASS_GetConfig, BASS_SetConfigPtr


BASS_SetConfigPtr

Sets the value of a pointer config option.

BOOL BASS_SetConfigPtr(
    DWORD option,
    void *value
);

Parameters

optionThe option to set the value of... one of the following.
BASS_CONFIG_LIBSSL | Library to use for handling HTTPS connections.
BASS_CONFIG_NET_AGENT | "User-Agent" header.
BASS_CONFIG_NET_PROXY | Proxy server settings.
other config options may be supported by add-ons, see the documentation.
value The new option setting. See the option's documentation for details on the possible values.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_ILLPARAM option is invalid.

Remarks

Config options can be used at any time and are independent of initialization, ie. BASS_Init does not need to have been called beforehand.

See also

BASS_GetConfigPtr, BASS_SetConfig


BASS_CONFIG_3DALGORITHM config option

The 3D algorithm for software mixed 3D channels.

BASS_SetConfig(
    BASS_CONFIG_3DALGORITHM,
    DWORD algo
);

Parameters

algoOne of these algorithms.
BASS_3DALG_DEFAULT | The default algorithm. If the user has selected a surround sound speaker configuration (eg. 4 or 5.1) in the control panel, the sound is panned among the available directional speakers. Otherwise it equates to BASS_3DALG_OFF.
BASS_3DALG_OFF | Uses normal left and right panning. The vertical axis is ignored except for scaling of volume due to distance. Doppler shift and volume scaling are still applied, but the 3D filtering is not performed. This is the most CPU efficient algorithm, but provides no virtual 3D audio effect. Head Related Transfer Function processing will not be done. Since only normal stereo panning is used, a channel using this algorithm may be accelerated by a 2D hardware voice if no free 3D hardware voices are available.
BASS_3DALG_FULL | This algorithm gives the highest quality 3D audio effect, but uses more CPU. This algorithm requires WDM drivers, if it's not available then BASS_3DALG_OFF will automatically be used instead.
BASS_3DALG_LIGHT | This algorithm gives a good 3D audio effect, and uses less CPU than the FULL algorithm. This algorithm also requires WDM drivers, if it's not available then BASS_3DALG_OFF will automatically be used instead.

Remarks

These algorithms only affect 3D channels that are being mixed in software. BASS_ChannelGetInfo can be used to check whether a channel is being software mixed.

Changing the algorithm only affects subsequently created or loaded samples, musics, or streams; it does not affect any that already exist.

Platform-specific

When using DirectSound output on Windows, DirectX 7 or above is required for this option to have effect. Otherwise, including when using WASAPI output on Windows, only the BASS_3DALG_DEFAULT and BASS_3DALG_OFF options are available.

See also

BASS_GetConfig, BASS_SampleCreate, BASS_SampleLoad, BASS_SetConfig


BASS_CONFIG_AM_DISABLE config option

Disable the use of Android media codecs?

BASS_SetConfig(
    BASS_CONFIG_AM_DISABLE,
    BOOL disable
);

Parameters

disable Disable Android media codecs?

Remarks

This option determines whether Android media codecs can be used to decode files and streams. It is set to FALSE by default when Android media codecs are available, which is on Android 4.1 and above. It will otherwise be TRUE and read-only.

Platform-specific

This config option is only available on Android.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamCreateURL


BASS_CONFIG_ANDROID_AAUDIO config option

Enable AAudio output on Android?

BASS_SetConfig(
    BASS_CONFIG_ANDROID_AAUDIO,
    BOOL enable
);

Parameters

enable Enable AAudio output?

Remarks

Android has three audio APIs: AudioTrack, OpenSL ES, AAudio. AudioTrack is available in all Android versions. OpenSL ES was introduced in Android 2.3. AAudio was introduced in Android 8. BASS includes support for all three. AudioTrack is used if the BASS_DEVICE_AUDIOTRACK flag is specified with BASS_Init (or on pre-2.3 Android). Otherwise, this option determes whether OpenSL ES or AAudio is used.

The default setting is TRUE (AAudio enabled) on Android 8.1 and above, and FALSE on earlier Android versions. It can be set to TRUE on Android 8.0 devices too but AAudio is known to be buggy/crash on some of those devices. The setting will be ignored on older Android versions where AAudio is not available. Changes take effect from the next BASS_Init call.

Platform-specific

This config option is only available on Android.

See also

BASS_GetConfig, BASS_SetConfig, BASS_Init


BASS_CONFIG_ANDROID_SESSIONID config option

The audio session ID to use for output on Android.

BASS_SetConfig(
    BASS_CONFIG_ANDROID_SESSIONID,
    DWORD id
);

Parameters

id The session ID.

Remarks

This option allows a session ID to be specified for BASS to use with AAudio or AudioTrack output (OpenSL ES is not affected). The session ID can then be used to apply Android's AudioEffect-based effects on the BASS output (and anything else that uses the same session ID). The AudioManager generateAudioSessionId method can be used to generate a session ID for this.

Changes take effect from the next BASS_Init call.

Platform-specific

This config option is only available on Android.

See also

BASS_GetConfig, BASS_SetConfig, BASS_Init


BASS_CONFIG_ASYNCFILE_BUFFER config option

The buffer length for asynchronous file reading.

BASS_SetConfig(
    BASS_CONFIG_ASYNCFILE_BUFFER,
    DWORD length
);

Parameters

length The buffer length in bytes. This will be rounded up to the nearest 4096 byte (4KB) boundary.

Remarks

This determines the amount of file data that can be read ahead of time with asynchronous file reading. The default setting is 65536 bytes (64KB). Changes only affect streams that are created afterwards, not any that already exist. So it is possible to have streams with differing buffer lengths by using this config option before creating each of them.

When asynchronous file reading is enabled, the buffer level is available from BASS_StreamGetFilePosition.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile, BASS_StreamGetFilePosition


BASS_CONFIG_BUFFER config option

The playback buffer length for HSTREAM and HMUSIC channels.

BASS_SetConfig(
    BASS_CONFIG_BUFFER,
    DWORD length
);

Parameters

length The buffer length in milliseconds. The minimum length is 10ms, the maximum is 5000 milliseconds. If the length specified is outside this range, it is automatically capped.

Remarks

The default buffer length is 500 milliseconds. Increasing the length, decreases the chance of the sound possibly breaking-up on slower computers, but also increases the latency for DSP/FX. The buffer length should always be greater than the update period (BASS_CONFIG_UPDATEPERIOD), which determines how often the buffer is refilled.

Small buffer lengths are only required if the sound is going to be changing in real-time, for example, in a soft-synth. If you need to use a small buffer, then the minbuf member of BASS_INFO should be used to get the recommended minimum buffer length supported by the device and its drivers, and add that to the update period plus some margin for the stream's processing. Even then, it is still possible that the sound could break up on some systems, it is also possible that smaller buffers may be fine. So when using small buffers, you should have an option in your software for the user to finetune the length used, for optimal performance.

Using this config option only affects the HMUSIC/HSTREAM channels that are created afterwards, not any that have already been created. So you can have channels with differing buffer lengths by using this config option each time before creating them. A channel's buffer length can be also reduced (or bypassed entirely) at any time via the BASS_ATTRIB_BUFFER attribute.

If automatic updating is disabled, make sure you call BASS_Update frequently enough to keep the buffers updated.

See also

BASS_GetConfig, BASS_GetInfo, BASS_SetConfig, BASS_ATTRIB_BUFFER, BASS_CONFIG_UPDATEPERIOD


BASS_CONFIG_CURVE_VOL config option

The translation curve of volume values.

BASS_SetConfig(
    BASS_CONFIG_CURVE_VOL,
    BOOL logvol
);

Parameters

logvol Volume curve... FALSE = linear, TRUE = logarithmic.

Remarks

When using the linear curve, the volume range is from 0% (silent) to 100% (full). When using the logarithmic curve, the volume range is from -100 dB (effectively silent) to 0 dB (full). For example, a volume level of 0.5 is 50% linear or -50 dB logarithmic.

The linear curve is used by default.

See also

BASS_GetConfig, BASS_SetConfig, BASS_SetVolume, BASS_ATTRIB_VOL, BASS_CONFIG_CURVE_PAN


BASS_CONFIG_CURVE_PAN config option

The translation curve of panning values.

BASS_SetConfig(
    BASS_CONFIG_CURVE_PAN,
    BOOL logpan
);

Parameters

logpan Panning curve... FALSE = linear, TRUE = logarithmic.

Remarks

The panning curve affects panning in exactly the same way as the volume curve (BASS_CONFIG_CURVE_VOL) affects the volume.

The linear curve is used by default.

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_PAN, BASS_CONFIG_CURVE_VOL


BASS_CONFIG_DEV_BUFFER config option

The output device buffer length.

BASS_SetConfig(
    BASS_CONFIG_DEV_BUFFER,
    DWORD length
);

Parameters

length The buffer length in milliseconds.

Remarks

The device buffer is where the final mix of all playing channels is placed, ready for the device to play. Its length affects the latency of things like starting and stopping playback of a channel, so you will probably want to avoid setting it unnecessarily high, but setting it too short could result in breaks in the sound. When using a large device buffer, the BASS_ATTRIB_BUFFER attribute could be used to skip the channel buffering step, to avoid further increasing latency for real-time generated sound and/or DSP/FX changes.

The buffer length needs to be a multiple of, and at least double, the device's update period, which can be set via the BASS_CONFIG_DEV_PERIOD option. The buffer length will be rounded up automatically if necessary to achieve that. The system may also choose to use a different buffer length if the requested one is too short or long, or needs rounding for granularity.

Changes to this config setting only affect subsequently initialized devices, not any that are already initialized. The "No Sound" device does not have a buffer, so is unaffected by this option.

Platform-specific

The default setting is 30ms on Windows, 40ms on Linux and Android, 200ms on Windows CE. This option is not available on OSX or iOS; the device buffer length on those platforms is twice the device update period, which can be set via the BASS_CONFIG_DEV_PERIOD option.

On Windows, this config option only applies when WASAPI output is used.

On Linux, BASS will attempt to set the device buffer-feeding thread to real-time priority (as on other platforms) to reduce the chances of it getting starved of CPU, but if that is not possible (eg. the user account lacks permission) then it may be necessary to increase the buffer length to avoid breaks in the output when the CPU is busy.

When using AudioTrack output on Android, the buffer length will be automatically raised to the minimum given by the AudioTrack getMinBufferSize method if necessary.

See also

BASS_GetConfig, BASS_GetInfo, BASS_Init, BASS_SetConfig, BASS_ATTRIB_BUFFER, BASS_CONFIG_DEV_PERIOD


BASS_CONFIG_DEV_DEFAULT config option

Include a "Default" entry in the output device list?

BASS_SetConfig(
    BASS_CONFIG_DEV_DEFAULT,
    BOOL default
);

Parameters

default If TRUE, a "Default" device will be included in the device list.

Remarks

This option adds a "Default" entry to the output device list, which maps to the device that is currently the system's default. Its output will automatically switch over when the system's default device setting changes.

When enabled, the "Default" device will also become the default device to BASS_Init (with device = -1). Both it and the device that it currently maps to will have the BASS_DEVICE_DEFAULT flag set by BASS_GetDeviceInfo.

This option can only be set before BASS_GetDeviceInfo or BASS_Init has been called.

Platform-specific

This config option is only available on Windows and OSX. On Windows, the automatic device switching feature requires Windows Vista or above (Windows 7 when DirectSound is used).

When the "Default" device is used with DirectSound, the BASS_SetVolume and BASS_GetVolume functions work a bit differently to usual; they deal with the "session" volume, which only affects the current process's output on the device, rather than the device's volume.

See also

BASS_GetConfig, BASS_SetConfig, BASS_Init


BASS_CONFIG_DEV_NONSTOP config option

Do not stop the output device when nothing is playing on it?

BASS_SetConfig(
    BASS_CONFIG_DEV_NONSTOP,
    BOOL nonstop
);

Parameters

nonstop If TRUE, sample data will continue to be sent to the output device while nothing is playing.

Remarks

By default, BASS will stop sending data to the output device when nothing is playing, to save a little CPU. When that happens, the device buffer will become empty, and the next playback will begin more quickly as a result. Or it may be delayed if the device has gone to sleep in the meantime. If more consistent playback latency (around the value given by BASS_GetInfo) is wanted, this option can be enabled to keep the device buffer filled with silence when nothing is playing. The output will still be stopped by BASS_Stop then.

See also

BASS_GetConfig, BASS_SetConfig, BASS_CONFIG_DEV_BUFFER


BASS_CONFIG_DEV_PERIOD config option

The output device update period.

BASS_SetConfig(
    BASS_CONFIG_DEV_PERIOD,
    int period
);

Parameters

period The update period in milliseconds, or in samples if negative.

Remarks

The device update period determines how often data is generated and placed in an output device's buffer. A shorter period allows a smaller buffer and lower latency but may use more CPU than a longer period.

The system may choose to use a different period if the requested one is too short or long, or needs rounding for granularity. The period actually being used can be obtained with BASS_GetInfo (the minbuf value).

The default setting is 10ms. Changes only affect subsequently initialized devices, not any that are already initialized.

Platform-specific

On Windows, this config option only applies to the "No Sound" device; the period with real devices is set by Windows (usually 10ms). On iOS, except on the "No Sound" device, negative (samples) settings are ignored and changes take immediate effect rather than being delayed until the next device initialization. On Windows CE, the default setting is 50ms.

Example

Request an update period of 15ms.
BASS_SetConfig(stream, BASS_CONFIG_DEV_PERIOD, 15);

Request an update period of 512 samples.

BASS_SetConfig(stream, BASS_CONFIG_DEV_PERIOD, -512);

See also

BASS_GetConfig, BASS_GetInfo, BASS_Init, BASS_SetConfig, BASS_CONFIG_DEV_BUFFER


BASS_CONFIG_FLOAT config option

Floating-point sample data is supported?

BASS_GetConfig(
    BASS_CONFIG_FLOAT
);

Remarks

This is a read-only config option that indicates whether floating-point sample data is supported, eg. the BASS_SAMPLE_FLOAT flag. A value of 0 means it is not. Floating-point data is not supported on platforms/architectures that do not have an FPU, eg. older ARM platforms/architectures.

When floating-point data is not supported, the BASS_CONFIG_FLOATDSP option is still available, but it will result in DSPPROC functions receiving 8.24 fixed-point data instead of floating-point.

Platform-specific

This option is only available on Android, Linux, and Windows CE. Floating-point is always supported on other platforns.

Example

Check if floating-point sample data is supported.
int floatsupport = BASS_GetConfig(BASS_CONFIG_FLOAT);
if (floatsupport) {
    // floating-point is supported on this platform/architecture
}

See also

BASS_GetConfig


BASS_CONFIG_FLOATDSP config option

Pass 32-bit floating-point sample data to all DSP functions?

BASS_SetConfig(
    BASS_CONFIG_FLOATDSP,
    BOOL floatdsp
);

Parameters

floatdsp If TRUE, 32-bit floating-point sample data is passed to all DSPPROC callback functions.

Remarks

Normally DSP functions receive sample data in whatever format the channel is using, ie. it can be 8, 16 or 32-bit. But when this config option is enabled, BASS will convert 8/16-bit sample data to 32-bit floating-point before passing it to DSP functions, and then convert it back after all the DSP functions are done. As well as simplifying the DSP code (no need for 8/16-bit processing), this also means that there is no degradation of quality as sample data passes through a chain of DSP.

This config option also applies to effects set via BASS_ChannelSetFX, except for DX8 effects when using the "With FX flag" DX8 effect implementation.

Changing the setting while there are DSP or FX set could cause problems, so should be avoided.

Platform-specific

Floating-point data is not supported on some platforms/architectures, in which case this config option will enable 8.24 fixed-point data instead of floating-point. The BASS_CONFIG_FLOAT option can be used to check that.

See also

BASS_GetConfig, BASS_SetConfig, BASS_CONFIG_FLOAT, DSPPROC callback


BASS_CONFIG_GVOL_MUSIC config option

The global MOD music volume level.

BASS_SetConfig(
    BASS_CONFIG_GVOL_MUSIC,
    DWORD volume
);

Parameters

volume MOD music global volume level... 0 (silent) to 10000 (full).

Remarks

This config option allows you to have control over the volume levels of all the MOD musics, which may be useful for setup options, eg. separate music and effect volume controls.

A channel's final volume = channel volume x global volume / 10000. For example, if a stream's volume is 0.5 and the global stream volume is 8000, then effectively the stream's volume level is 0.4 (0.5 x 8000 / 10000 = 0.4).

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_VOL, BASS_CONFIG_GVOL_SAMPLE, BASS_CONFIG_GVOL_STREAM


BASS_CONFIG_GVOL_SAMPLE config option

The global sample volume level.

BASS_SetConfig(
    BASS_CONFIG_GVOL_SAMPLE,
    DWORD volume
);

Parameters

volume Sample global volume level... 0 (silent) to 10000 (full).

Remarks

This config option allows you to have control over the volume levels of all the samples, which may be useful for setup options, eg. separate music and effect volume controls.

A channel's final volume = channel volume x global volume / 10000. For example, if a stream's volume is 0.5 and the global stream volume is 8000, then effectively the stream's volume level is 0.4 (0.5 x 8000 / 10000 = 0.4).

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_VOL, BASS_CONFIG_GVOL_MUSIC, BASS_CONFIG_GVOL_STREAM


BASS_CONFIG_GVOL_STREAM config option

The global stream volume level.

BASS_SetConfig(
    BASS_CONFIG_GVOL_STREAM,
    DWORD volume
);

Parameters

volume Stream global volume level... 0 (silent) to 10000 (full).

Remarks

This config option allows you to have control over the volume levels of all the streams, which may be useful for setup options, eg. separate music and effect volume controls.

A channel's final volume = channel volume x global volume / 10000. For example, if a stream's volume is 0.5 and the global stream volume is 8000, then effectively the stream's volume level is 0.4 (0.5 x 8000 / 10000 = 0.4).

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_VOL, BASS_CONFIG_GVOL_MUSIC, BASS_CONFIG_GVOL_SAMPLE


BASS_CONFIG_HANDLES config option

Number of existing HMUSIC / HRECORD / HSAMPLE / HSTREAM handles.

BASS_GetConfig(
    BASS_CONFIG_HANDLES
);

Remarks

This is a read-only config option that gives the total number of HMUSIC / HRECORD / HSAMPLE / HSTREAM handles that currently exist, which can be useful for detecting leaks, ie. unfreed handles. Some add-ons may create their own handles for internal usage, so a single stream can increase (and decrease when freed) the total number of handles by more than one.

See also

BASS_GetConfig


BASS_CONFIG_IOS_SESSION config option

Audio session configuration on iOS.

BASS_SetConfig(
    BASS_CONFIG_IOS_SESSION,
    DWORD config
);

Parameters

configA combination of these flags.
BASS_IOS_SESSION_MIX | Allow other apps to be heard at the same time. Enables AVAudioSessionCategoryOptionMixWithOthers.
BASS_IOS_SESSION_DUCK | Allow other apps to be heard at the same time but reduce their volume level. Enables AVAudioSessionCategoryOptionDuckOthers.
BASS_IOS_SESSION_AMBIENT | Use the "ambient" category.
BASS_IOS_SESSION_SPEAKER | Route the output to the speaker instead of the receiver. Enables AVAudioSessionCategoryOptionDefaultToSpeaker.
BASS_IOS_SESSION_DISABLE | Disable BASS's audio session configuration management so that the app can handle that itself.

Remarks

By default, the audio session category is set to AVAudioSessionCategoryPlayback. If BASS_IOS_SESSION_AMBIENT is set then the category will be set to AVAudioSessionCategorySoloAmbient instead, or AVAudioSessionCategoryAmbient if BASS_IOS_SESSION_MIX or BASS_IOS_SESSION_DUCK is also set. If BASS_IOS_SESSION_SPEAKER is set or BASS_RecordInit has been called then the category will be set to AVAudioSessionCategoryPlayAndRecord (regardless of BASS_IOS_SESSION_AMBIENT). Descriptions of these categories and other options can be found in Apple's AVAudioSession documentation.

When BASS's audio session configuration management is disabled (BASS_IOS_SESSION_DISABLE is set), BASS will still activate the session during initialization and after an interruption but do nothing else. Except for the "No Sound" device, the BASS_CONFIG_DEV_PERIOD option is disabled by this; the AVAudioSession setPreferredIOBufferDuration method can be used instead.

The default setting is BASS_IOS_SESSION_MIX.

Platform-specific

This config option is only available on iOS.

See also

BASS_GetConfig, BASS_SetConfig, BASS_Init, BASS_RecordInit


BASS_CONFIG_LIBSSL config option

The OpenSSL (or compatible) library to use for handling HTTPS connections.

BASS_SetConfigPtr(
    BASS_CONFIG_LIBSSL,
    char *filename
);

Parameters

filename The filename of the OpenSSL library to use... NULL = use default. This should include the full path if it is not in the system library search path.

Remarks

By default, BASS will try to use the system's OpenSSL library to handle HTTPS connections. It will look for libssl.so, libssl.so.1.1, libssl.so.10, or libssl.so.1.0.0. If the target system uses a different filename for it, or you want to use a custom OpenSSL build, this option should be set to that. That should be done before the first HTTPS connection is opened. If the specified library cannot be loaded, BASS will fallback to trying the defaults.

BASS_SetConfigPtr makes a copy of the provided string, so it does not need to persist beyond the call.

Platform-specific

This option is only available on the Linux and Android platforms.

On Android, BASS will look for the library in the app's library directory if a full path is not provided. A BASS_SSL add-on is available, which will be used by default when present. If that is not present then the default is to use the system's libssl.so or libboringssl.so library, but note that is not possible when targetting Android 7 (API level 24) or above.

See also

BASS_GetConfigPtr, BASS_SetConfigPtr, BASS_StreamCreateURL


BASS_CONFIG_MF_DISABLE config option

Disable the use of Media Foundation?

BASS_SetConfig(
    BASS_CONFIG_MF_DISABLE,
    BOOL disable
);

Parameters

disable Disable Media Foundation?

Remarks

This option determines whether Media Foundation codecs can be used to decode files and streams. It is set to FALSE by default when Media Foundation codecs are available, which is on Windows 7 and above, and updated versions of Vista. It will otherwise be TRUE and read-only.

Platform-specific

This config option is only available on Windows.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamCreateURL, BASS_CONFIG_MF_VIDEO


BASS_CONFIG_MF_VIDEO config option

Play the audio from video files using Media Foundation?

BASS_SetConfig(
    BASS_CONFIG_MF_VIDEO,
    BOOL video
);

Parameters

video Accept video files?

Remarks

This option is enabled by default.

Platform-specific

This config option is only available on Windows.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamCreateURL


BASS_CONFIG_MUSIC_VIRTUAL config option

The maximum number of virtual channels to use in the rendering of IT files.

BASS_SetConfig(
    BASS_CONFIG_MUSIC_VIRTUAL,
    DWORD chans
);

Parameters

chans The number of virtual channels... 1 (min) to 512 (max). If the value specified is outside this range, it is automatically capped.

Remarks

This setting only affects IT files, as the other MOD music formats do not have virtual channels. The default setting is 64. Changes only apply to subsequently loaded files, not any that are already loaded.

See also

BASS_GetConfig, BASS_MusicLoad, BASS_SetConfig, BASS_ATTRIB_MUSIC_ACTIVE


BASS_CONFIG_NET_AGENT config option

The "User-Agent" request header sent to servers.

BASS_SetConfigPtr(
    BASS_CONFIG_NET_AGENT,
    char *agent
);

Parameters

agent The "User-Agent" header.

Remarks

BASS_SetConfigPtr makes a copy of the provided string, so it does not need to persist beyond the call. Changes take effect from the next internet stream creation call.

Platform-specific

On Windows and Windows CE, the BASS_UNICODE flag can be used with a UTF-16 string ("wchar_t" rather than "char").

See also

BASS_GetConfigPtr, BASS_SetConfigPtr, BASS_StreamCreateURL


BASS_CONFIG_NET_BUFFER config option

The internet download buffer length.

BASS_SetConfig(
    BASS_CONFIG_NET_BUFFER,
    DWORD length
);

Parameters

length The buffer length in milliseconds.

Remarks

Increasing the buffer length decreases the chance of the stream stalling, but also increases the time taken to create the stream as more data has to be pre-buffered (adjustable via the BASS_CONFIG_NET_PREBUF config option). Aside from the pre-buffering, this setting has no effect on streams without either the BASS_STREAM_BLOCK or BASS_STREAM_RESTRATE flags.

When streaming in blocks, this option determines the download buffer length. The effective buffer length can actually be a bit more than that specified, including data that has been read from the buffer by the decoder but not yet decoded.

This config option also determines the buffering used by "buffered" user file streams created with BASS_StreamCreateFileUser.

The default buffer length is 5 seconds (5000 milliseconds). The net buffer length should be larger than the length of the playback buffer (BASS_CONFIG_BUFFER), otherwise the stream is likely to stall soon after starting playback.

Using this config option only affects streams created afterwards, not any that have already been created.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFileUser, BASS_StreamCreateURL, BASS_CONFIG_BUFFER, BASS_CONFIG_NET_PREBUF, BASS_CONFIG_NET_TIMEOUT


BASS_CONFIG_NET_PASSIVE config option

Use passive mode in FTP connections?

BASS_SetConfig(
    BASS_CONFIG_NET_PASSIVE,
    BOOL passive
);

Parameters

passive If TRUE, passive mode is used, otherwise normal/active mode is used.

Remarks

Changes take effect from the next internet stream creation call. By default, passive mode is enabled.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL


BASS_CONFIG_NET_PLAYLIST config option

Process URLs in PLS and M3U playlists?

BASS_SetConfig(
    BASS_CONFIG_NET_PLAYLIST,
    DWORD netlists
);

Parameters

netlists When to process URLs in PLS and M3U playlists... 0 = never, 1 = in BASS_StreamCreateURL only, 2 = in BASS_StreamCreateFile and BASS_StreamCreateFileUser too.

Remarks

When enabled, BASS will process PLS and M3U playlists, trying each URL until it finds one that it can play. BASS_ChannelGetInfo can be used to find out the URL that was successfully opened.

Nested playlists are suported, that is a playlist can contain the URL of another playlist. The BASS_CONFIG_NET_PLAYLIST_DEPTH option limits the nested playlist depth.

By default, playlist processing is disabled.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_PLAYLIST_DEPTH


BASS_CONFIG_NET_PLAYLIST_DEPTH config option

Maximum nested playlist processing depth.

BASS_SetConfig(
    BASS_CONFIG_NET_PLAYLIST_DEPTH,
    DWORD depth
);

Parameters

depth Maximum nested playlist processing depth... 0 = do not process nested playlists.

Remarks

When playlist processing is enabled via the BASS_CONFIG_NET_PLAYLIST option, this option limits how deep into nested playlists BASS_StreamCreateURL will go. The default depth is 1, which means playlists within the root playlist will be processed, but not playlists within those playlists.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_PLAYLIST


BASS_CONFIG_NET_PREBUF config option

Amount to pre-buffer before playing internet streams.

BASS_SetConfig(
    BASS_CONFIG_NET_PREBUF,
    DWORD prebuf
);

Parameters

prebuf Amount (percentage) to pre-buffer.

Remarks

This setting determines what percentage of the buffer length (BASS_CONFIG_NET_BUFFER) should be filled before starting playback. The default is 75%. This setting is just a minimum; BASS will always pre-download a certain amount to detect the stream's format and initialize the decoder.

The pre-buffering can be done by BASS_StreamCreateURL or asynchronously, depending on the BASS_CONFIG_NET_PREBUF_WAIT setting.

As well as internet streams, this config setting also applies to "buffered" user file streams created with BASS_StreamCreateFileUser.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_PREBUF_WAIT


BASS_CONFIG_NET_PREBUF_WAIT config option

Wait for pre-buffering when opening internet streams?

BASS_SetConfig(
    BASS_CONFIG_NET_PREBUF_WAIT,
    BOOL wait
);

Parameters

wait Wait for pre-buffering... FALSE = no, TRUE = yes.

Remarks

This setting determines whether BASS_StreamCreateURL will wait for an amount of data to be downloaded before returning the new stream's handle. The amount is determined by the BASS_CONFIG_NET_BUFFER and BASS_CONFIG_NET_PREBUF settings. The default setting is disabled, which means pre-buffering will happen asynchronously and playback will begin in a stalled state while pre-buffering is in progress. The progress can be monitored with BASS_StreamGetFilePosition (BASS_FILEPOS_BUFFERING).

As well as internet streams, this config setting also applies to streams created with BASS_StreamCreateFileUser and the STREAMFILE_BUFFER file system. BASS_StreamCreateFileUser will never pre-buffer when using the STREAMFILE_BUFFERPUSH system.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_PREBUF


BASS_CONFIG_NET_PROXY config option

Proxy server settings.

BASS_SetConfigPtr(
    BASS_CONFIG_NET_PROXY,
    char *proxy
);

Parameters

proxy The proxy server settings, in the form of "user:pass@server:port"... NULL = don't use a proxy. "" (empty string) = use the OS's default proxy settings. If only the "user:pass@" part is specified, then those authorization credentials are used with the default proxy server. If only the "server:port" part is specified, then that proxy server is used without any authorization credentials.

Remarks

BASS_SetConfigPtr makes a copy of the provided string, so it does not need to persist beyond the call. Changes take effect from the next internet stream creation call.

Platform-specific

On Windows and Windows CE, the BASS_UNICODE flag can be used with a UTF-16 string ("wchar_t" rather than "char").

See also

BASS_GetConfigPtr, BASS_SetConfigPtr, BASS_StreamCreateURL


BASS_CONFIG_NET_READTIMEOUT config option

The time to wait for a server to deliver more data for an internet stream.

BASS_SetConfig(
    BASS_CONFIG_NET_READTIMEOUT,
    DWORD timeout
);

Parameters

timeout The time to wait, in milliseconds... 0 = no timeout.

Remarks

When the timeout is hit, the connection with the server will be closed.

The default setting is 0, no timeout. Changes only affect subsequently created streams, not any that already exist.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_TIMEOUT


BASS_CONFIG_NET_TIMEOUT config option

The time to wait for a server to respond to a connection request.

BASS_SetConfig(
    BASS_CONFIG_NET_TIMEOUT,
    DWORD timeout
);

Parameters

timeout The time to wait, in milliseconds.

Remarks

The default timeout is 5 seconds (5000 milliseconds).

When playlist processing is enabled via the BASS_CONFIG_NET_PLAYLIST option, the timeout applies to each playlist entry rather than the playlist as a whole.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateURL, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_READTIMEOUT


BASS_CONFIG_OGG_PRESCAN config option

Pre-scan chained OGG files?

BASS_SetConfig(
    BASS_CONFIG_OGG_PRESCAN,
    BOOL prescan
);

Parameters

prescan If TRUE, chained OGG files are pre-scanned.

Remarks

This option is enabled by default, and is equivalent to including the BASS_STREAM_PRESCAN flag in a BASS_StreamCreateFile call when opening an OGG file. It can be disabled if seeking and an accurate length reading are not required from chained OGG files, for faster stream creation.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile


BASS_CONFIG_PAUSE_NOPLAY config option

Prevent channels being played while the output is paused?

BASS_SetConfig(
    BASS_CONFIG_PAUSE_NOPLAY,
    BOOL noplay
);

Parameters

noplay If TRUE, channels cannot be played while the output is paused.

Remarks

When the output is paused using BASS_Pause, and this config option is enabled, channels cannot be played until the output is resumed using BASS_Start. Any attempts to play a channel will result in a BASS_ERROR_START error.

By default, this config option is enabled.

See also

BASS_GetConfig, BASS_SetConfig, BASS_Pause


BASS_CONFIG_REC_BUFFER config option

The buffer length for recording channels.

BASS_SetConfig(
    BASS_CONFIG_REC_BUFFER,
    DWORD length
);

Parameters

length The buffer length in milliseconds... 1000 (min) - 5000 (max). If the length specified is outside this range, it is automatically capped.

Remarks

Unlike a playback buffer, where the aim is to keep the buffer full, a recording buffer is kept as empty as possible and so this setting has no effect on latency. The default recording buffer length is 2000 milliseconds. Unless processing of the recorded data could cause significant delays, or you want to use a large recording period with BASS_RecordStart, there should be no need to increase this.

Using this config option only affects the recording channels that are created afterwards, not any that have already been created. So it is possible to have channels with differing buffer lengths by using this config option each time before creating them.

See also

BASS_GetConfig, BASS_RecordStart, BASS_SetConfig


BASS_CONFIG_SRC config option

The default sample rate conversion quality.

BASS_SetConfig(
    BASS_CONFIG_SRC,
    DWORD quality
);

Parameters

quality The sample rate conversion quality... 0 = linear interpolation, 1 = 8 point sinc interpolation, 2 = 16 point sinc interpolation, 3 = 32 point sinc interpolation, 4 = 64 point sinc interpolation. Other values are also accepted.

Remarks

This config option determines what sample rate conversion quality new channels will initially have, except for sample channels (HCHANNEL), which use the BASS_CONFIG_SRC_SAMPLE setting. A channel's sample rate conversion quality can subsequently be changed via the BASS_ATTRIB_SRC attribute.

When an SSE supporting CPU is present, the default setting is 2, otherwise it is 1.

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_SRC, BASS_CONFIG_SRC_SAMPLE


BASS_CONFIG_SRC_SAMPLE config option

The default sample rate conversion quality for sample channels.

BASS_SetConfig(
    BASS_CONFIG_SRC_SAMPLE,
    DWORD quality
);

Parameters

quality The sample rate conversion quality... 0 = linear interpolation, 1 = 8 point sinc interpolation, 2 = 16 point sinc interpolation, 3 = 32 point sinc interpolation, 4 = 64 point sinc interpolation. Other values are also accepted.

Remarks

This config option determines what sample rate conversion quality a new sample channel (HCHANNEL) will initially have, following a BASS_SampleGetChannel call. The channel's sample rate conversion quality can subsequently be changed via the BASS_ATTRIB_SRC attribute.

The default setting is 0 (linear interpolation).

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_SRC, BASS_CONFIG_SRC


BASS_CONFIG_UNICODE config option

Use the Unicode character set in device information?

BASS_SetConfig(
    BASS_CONFIG_UNICODE,
    BOOL unicode
);

Parameters

unicode If TRUE, device information will be in UTF-8 form. Otherwise it will be ANSI.

Remarks

This config option determines what character set is used in the BASS_DEVICEINFO structure and by the BASS_RecordGetInputName function. The default setting is ANSI, and it can only be changed before BASS_GetDeviceInfo or BASS_Init or BASS_RecordGetDeviceInfo or BASS_RecordInit has been called.

Platform-specific

This config option is only available on Windows.

See also

BASS_GetConfig, BASS_SetConfig, BASS_DEVICEINFO structure


BASS_CONFIG_UPDATEPERIOD config option

The update period of HSTREAM and HMUSIC channel playback buffers.

BASS_SetConfig(
    BASS_CONFIG_UPDATEPERIOD,
    DWORD period
);

Parameters

period The update period in milliseconds... 0 = disable automatic updating. The minimum period is 5ms, the maximum is 100ms. If the period specified is outside this range, it is automatically capped.

Remarks

The update period is the amount of time between updates of the playback buffers of HSTREAM/HMUSIC channels that are playing; no update cycles occur when nothing is playing. Shorter update periods allow smaller buffers to be set with the BASS_CONFIG_BUFFER config option, but as the rate of updates increases, so the overhead of setting up the updates becomes a greater part of the CPU usage. The update period only affects HSTREAM and HMUSIC channels; it does not affect samples. Nor does it have any effect on decoding channels, as they are not played.

BASS creates one or more threads (determined by BASS_CONFIG_UPDATETHREADS) specifically to perform the updating, except when automatic updating is disabled (period = 0), in which case BASS_Update or BASS_ChannelUpdate should be used instead. This allows BASS's CPU usage to be synchronized with your software's. For example, in a game loop you could call BASS_Update once per frame, to keep all the processing in sync so that the frame rate is as smooth as possible.

The update period can be altered at any time, including during playback. The default period is 100ms.

See also

BASS_ChannelUpdate, BASS_GetConfig, BASS_SetConfig, BASS_Update, BASS_CONFIG_BUFFER, BASS_CONFIG_UPDATETHREADS, BASS_ATTRIB_BUFFER


BASS_CONFIG_UPDATETHREADS config option

The number of threads to use for updating playback buffers.

BASS_SetConfig(
    BASS_CONFIG_UPDATETHREADS,
    DWORD threads
);

Parameters

threads The number of threads to use... 0 = disable automatic updating.

Remarks

The number of update threads determines how many HSTREAM/HMUSIC channel playback buffers can be updated in parallel; each thread can process one channel at a time. The default is to use a single thread, but additional threads can be used to take advantage of multiple CPU cores. There is generally nothing much to be gained by creating more threads than there are CPU cores, but one benefit of using multiple threads even with a single CPU core is that a slowly updating channel need not delay the updating of other channels.

When automatic updating is disabled (threads = 0), BASS_Update or BASS_ChannelUpdate should be used instead.

The number of update threads can be changed at any time, including during playback.

Platform-specific

The number of update threads is limited to 1 on the Windows CE platform.

See also

BASS_ChannelUpdate, BASS_GetConfig, BASS_SetConfig, BASS_Update, BASS_CONFIG_BUFFER, BASS_CONFIG_UPDATEPERIOD


BASS_CONFIG_VERIFY config option

The amount of data to check in order to verify/detect the file format.

BASS_SetConfig(
    BASS_CONFIG_VERIFY,
    DWORD length
);

Parameters

length The amount of data to check, in bytes... 1000 (min) to 1000000 (max). If the value specified is outside this range, it is automatically capped.

Remarks

Of the file formats supported as standard, this setting only affects the detection of MP3/MP2/MP1 formats, but it may also be used by add-ons (see the documentation). The verification length excludes any tags that may be found at the start of the file. The default length is 16000 bytes.

For internet (and "buffered" user file) streams, the BASS_CONFIG_VERIFY_NET setting determines how much data is checked.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_CONFIG_VERIFY_NET


BASS_CONFIG_VERIFY_NET config option

The amount of data to check in order to verify/detect the file format of internet streams.

BASS_SetConfig(
    BASS_CONFIG_VERIFY_NET,
    DWORD length
);

Parameters

length The amount of data to check, in bytes... 1000 (min) to 1000000 (max), or 0 = 25% of the BASS_CONFIG_VERIFY setting (with a minimum of 1000 bytes). If the value specified is outside this range, it is automatically capped.

Remarks

Of the file formats supported as standard, this setting only affects the detection of MP3/MP2/MP1 formats, but it may also be used by add-ons (see the documentation). The verification length excludes any tags that may be found at the start of the file. The default setting is 0, which means 25% of the BASS_CONFIG_VERIFY setting.

As well as internet streams, this config setting also applies to "buffered" user file streams created with BASS_StreamCreateFileUser.

See also

BASS_GetConfig, BASS_SetConfig, BASS_StreamCreateFileUser, BASS_StreamCreateURL, BASS_CONFIG_VERIFY


BASS_CONFIG_VISTA_SPEAKERS config option

Enable speaker assignment with panning/balance control on Windows Vista and newer?

BASS_SetConfig(
    BASS_CONFIG_VISTA_SPEAKERS,
    BOOL enable
);

Parameters

enable If TRUE, speaker assignment with panning/balance control is enabled on Windows Vista and newer.

Remarks

Panning/balance control via the BASS_ATTRIB_PAN attribute is not available when speaker assignment is used on Windows with DirectSound due to the way that the speaker assignment needs to be implemented there. The situation is improved with Windows Vista, and speaker assignment can generally be done in a way that does permit panning/balance control to be used at the same time, but there may still be some drivers that it does not work properly with, so it is disabled by default and can be enabled via this config option. Changes only affect channels that are created afterwards, not any that already exist.

Platform-specific

This config option is only available on Windows. It is available on all Windows versions (not including CE), but only has effect when using DirectSound output on Windows Vista and newer. Speaker assignment with panning/balance control is always possible when BASS is generating the final mix, including when using WASAPI output on Windows.

See also

BASS_GetConfig, BASS_SetConfig, BASS_ATTRIB_PAN


BASS_CONFIG_VISTA_TRUEPOS config option

Enable true play position mode on Windows Vista and newer?

BASS_SetConfig(
    BASS_CONFIG_VISTA_TRUEPOS,
    BOOL truepos
);

Parameters

truepos If TRUE, DirectSound's "true play position" mode is enabled on Windows Vista and newer.

Remarks

Unless this option is enabled, the reported playback position will advance in 10ms steps on Windows Vista and newer. As well as affecting the precision of BASS_ChannelGetPosition, this also affects the timing of non-mixtime syncs. When this option is enabled, it allows finer position reporting but it also increases latency.

The default setting is enabled. Changes only affect channels that are created afterwards, not any that already exist. The latency and minbuf values in the BASS_INFO structure reflect the setting at the time of the device's BASS_Init call.

Platform-specific

This config option is only available on Windows. It is available on all Windows versions (not including CE), but only has effect when using DirectSound output on Windows Vista and newer.

See also

BASS_ChannelGetPosition, BASS_GetConfig, BASS_GetInfo, BASS_SetConfig


BASS_CONFIG_WASAPI_PERSIST config option

Retain Windows mixer settings across sessions?

BASS_SetConfig(
    BASS_CONFIG_WASAPI_PERSIST,
    BOOL persist
);

Parameters

persist If TRUE, Windows mixer settings will persist across sessions.

Remarks

When using WASAPI output, this option determines whether the volume and mute settings in Windows mixer will persist across sessions, ie. the next time your application runs. Those settings always persist when using DirectSound output on Windows Vista and above.

The default setting is TRUE.

Platform-specific

This config option in only available on Windows.

See also

BASS_GetConfig, BASS_SetConfig


BASS_PluginFree

Unplugs an add-on.

BOOL BASS_PluginFree(
    HPLUGIN handle
);

Parameters

handle The plugin handle... 0 = all plugins.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.

Remarks

If there are streams created by a plugin in existence when it is being freed, the streams will automatically be freed too. Samples loaded by the plugin are unaffected as the plugin has nothing to do with them once they are loaded; the sample data is already fully decoded.

See also

BASS_PluginLoad


BASS_PluginGetInfo

Retrieves information on a plugin.

const BASS_PLUGININFO *BASS_PluginGetInfo(
    HPLUGIN handle
);

Parameters

handle The plugin handle.

Return value

If successful, a pointer to the plugin info is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Remarks

The plugin information does not change, so the returned pointer remains valid for as long as the plugin is loaded.

Error codes

BASS_ERROR_HANDLE handle is not valid.

Example

List the formats supported by a plugin.
const BASS_PLUGININFO *info = BASS_PluginGetInfo(plugin); // get the plugin info
int a;
for (a = 0; a < info->formatc; a++) { // display the array of formats...
    printf("ctype=%x name=%s exts=%s\n",
        info->formats[a].ctype, info->formats[a].name, info->formats[a].exts);
}

See also

BASS_PluginLoad, BASS_PLUGININFO structure


BASS_PluginLoad

Plugs an "add-on" into the standard stream and sample creation functions.

HPLUGIN BASS_PluginLoad(
    char *file,
    DWORD flags
);

Parameters

file Filename of the add-on/plugin.
flagsA combination of these flags.
BASS_UNICODE file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.

Return value

If successful, the loaded plugin's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_FILEOPEN | The file could not be opened.
BASS_ERROR_FILEFORM | The file is not a plugin.
BASS_ERROR_VERSION | The plugin requires a different BASS version. Due to the use of the "stdcall" calling-convention, and so risk of stack faults from unexpected API differences, an add-on won't load at all on Windows if the BASS version is unsupported, and a BASS_ERROR_FILEFORM error will be generated instead of this.
BASS_ERROR_ALREADY | The plugin is already loaded.

Remarks

There are two ways in which add-ons can provide support for additional formats. They can provide dedicated functions to create streams of the specific format(s) they support and/or they can plug into the standard stream creation functions: BASS_StreamCreateFile, BASS_StreamCreateURL, and BASS_StreamCreateFileUser. This function enables the latter method. Both methods can be used side by side. The obvious advantage of the plugin system is convenience, while the dedicated functions can provide extra options that are not possible via the shared function interfaces. See an add-on's documentation for more specific details on it.

As well as the stream creation functions, plugins also add their additional format support to BASS_SampleLoad.

Information on what file formats a plugin supports is available via the BASS_PluginGetInfo function.

When using multiple plugins, the stream/sample creation functions will try each of them in the order that they were loaded via this function, until one that accepts the file is found.

When an add-on is already loaded (eg. if you are using functions from it), the plugin system will use the same instance (the reference count will just be incremented); there will not be 2 copies of the add-on in memory.

Platform-specific

Dynamic libraries are not permitted on iOS, so add-ons are provided as static libraries instead, which means this function has to work a little differently. The add-on needs to be linked into the executable, and a "plugin" symbol declared and passed to this function (instead of a filename). See the example below.

Example

Plugin the FLAC add-on.
#ifdef _WIN32 // Windows/CE
    BASS_PluginLoad("bassflac.dll", 0);
#elif __linux__ // Linux
    BASS_PluginLoad("libbassflac.so", 0);
#elif TARGET_OS_IPHONE // iOS
    extern void BASSFLACplugin;
    BASS_PluginLoad(&BASSFLACplugin, 0);
#else // OSX
    BASS_PluginLoad("libbassflac.dylib", 0);
#endif

See also

BASS_PluginFree, BASS_PluginGetInfo


BASS_PLUGINFORM structure

Information on a plugin supported format.

typedef struct {
    DWORD ctype;
    char *name;
    char *exts;
} BASS_PLUGINFORM;

Members

ctype | The channel type, as would appear in the BASS_CHANNELINFO structure.
name | Format description.
exts | File extension filter, in the form of "*.ext1;*.ext2;...".

Remarks

The extension filter is for information only. A plugin will check the file contents rather than file extension, to verify that it is a supported format.

Platform-specific

On Windows CE, name and exts are in UTF-16 form ("WCHAR" rather than "char").

See also

BASS_PluginGetInfo, BASS_PLUGININFO structure


BASS_PLUGININFO structure

Used with BASS_PluginGetInfo to retrieve information on a plugin.

typedef struct {
    DWORD version;
    DWORD formatc;
    BASS_PLUGINFORM *formats;
} BASS_PLUGININFO;

Members

version | Plugin version, in the same form as given by BASS_GetVersion.
formatc | Number of supported formats.
formats | The array of supported formats. The array contains formatc elements.

See also

BASS_PluginGetInfo, BASS_PLUGINFORM structure


BASS_ErrorGetCode

Retrieves the error code for the most recent BASS function call in the current thread.

int BASS_ErrorGetCode();

Return value

If no error occurred during the last BASS function call then BASS_OK is returned, else one of the BASS_ERROR values is returned. See the function description for an explanation of what the error code means.

Error codes are stored for each thread. So if you happen to call 2 or more BASS functions at the same time, they will not interfere with each other's error codes.

Error codes list

0 | BASS_OK
1 | BASS_ERROR_MEM
2 | BASS_ERROR_FILEOPEN
3 | BASS_ERROR_DRIVER
4 | BASS_ERROR_BUFLOST
5 | BASS_ERROR_HANDLE
6 | BASS_ERROR_FORMAT
7 | BASS_ERROR_POSITION
8 | BASS_ERROR_INIT
9 | BASS_ERROR_START
10 | BASS_ERROR_SSL
14 | BASS_ERROR_ALREADY
17 | BASS_ERROR_NOTAUDIO
18 | BASS_ERROR_NOCHAN
19 | BASS_ERROR_ILLTYPE
20 | BASS_ERROR_ILLPARAM
21 | BASS_ERROR_NO3D
22 | BASS_ERROR_NOEAX
23 | BASS_ERROR_DEVICE
24 | BASS_ERROR_NOPLAY
25 | BASS_ERROR_FREQ
27 | BASS_ERROR_NOTFILE
29 | BASS_ERROR_NOHW
31 | BASS_ERROR_EMPTY
32 | BASS_ERROR_NONET
33 | BASS_ERROR_CREATE
34 | BASS_ERROR_NOFX
37 | BASS_ERROR_NOTAVAIL
38 | BASS_ERROR_DECODE
39 | BASS_ERROR_DX
40 | BASS_ERROR_TIMEOUT
41 | BASS_ERROR_FILEFORM
42 | BASS_ERROR_SPEAKER
43 | BASS_ERROR_VERSION
44 | BASS_ERROR_CODEC
45 | BASS_ERROR_ENDED
46 | BASS_ERROR_BUSY
47 | BASS_ERROR_UNSTREAMABLE
-1 | BASS_ERROR_UNKNOWN
Add-ons may introduce additional error codes.


BASS_Free

Frees all resources used by the output device, including all its samples, streams and MOD musics.

BOOL BASS_Free();

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks

This function should be called for all initialized devices before the program closes. It is not necessary to individually free the samples/streams/musics as these are all automatically freed by this function.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_Init


BASS_GetCPU

Retrieves the current CPU usage of BASS.

float BASS_GetCPU();

Return value

The BASS CPU usage as a percentage.

Remarks

This function includes the time taken to render stream (HSTREAM) and MOD music (HMUSIC) channels during playback, and any DSP functions set on those channels. It also includes any FX that are not using the "with FX flag" DX8 effect implementation. The processing of some add-on stream formats may not be entirely included, if they use additional decoding threads; see the add-on documentation for details.

This function does not strictly tell the CPU usage, but rather how timely the processing is. For example, if it takes 10ms to generate 100ms of data, that would be 10%. If the reported usage gets to 100%, that means the channel data is being played faster than it can be generated and buffer underruns are likely to occur.

If automatic updating is disabled, then the value returned by this function is only updated after each call to BASS_Update. BASS_ChannelUpdate usage is not included. The CPU usage of an individual channel is available via the BASS_ATTRIB_CPU attribute.

Platform-specific

When using DirectSound output on Windows, the CPU usage does not include sample channels (HCHANNEL), which are mixed by the output device/drivers (hardware mixing) or Windows (software mixing). On other platforms and when using WASAPI output on Windows, the CPU usage does include sample playback as well as the generation of the final output mix.

On Windows, the CPU usage value does not include the decoding of internet (or "buffered" user file) streams that use Media Foundation codecs.

See also

BASS_CONFIG_UPDATETHREADS, BASS_ATTRIB_CPU


BASS_GetDevice

Retrieves the device setting of the current thread.

DWORD BASS_GetDevice();

Return value

If successful, the device number is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_Init has not been successfully called; there are no initialized devices.

See also

BASS_ChannelGetDevice, BASS_Init, BASS_SetDevice


BASS_GetDeviceInfo

Retrieves information on an output device.

BOOL BASS_GetDeviceInfo(
    DWORD device,
    BASS_DEVICEINFO *info
);

Parameters

device | The device to get the information of... 0 = first.
info | Pointer to a structure to receive the information.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DEVICE device is invalid.

Remarks

This function can be used to enumerate the available devices for a setup dialog. Device 0 is always the "no sound" device, so you should start at device 1 if you only want to list real output devices.

Platform-specific

On Linux, a "Default" device is hardcoded to device number 1, which uses the default output set in the ALSA config, and the real devices start at number 2. That is also the case on Windows and OSX when the BASS_CONFIG_DEV_DEFAULT option is enabled.

Example

Get the total number of real devices currently present.
int a, count = 0;
BASS_DEVICEINFO info;
for (a = 1; BASS_GetDeviceInfo(a, &info); a++)
    if (info.flags & BASS_DEVICE_ENABLED) // device is enabled
        count++; // count it

See also

BASS_GetInfo, BASS_Init, BASS_DEVICEINFO structure


BASS_GetDSoundObject

Retrieves a pointer to a DirectSound object interface.

void *BASS_GetDSoundObject(
    DWORD object
);

Parameters

objectThe interface to retrieve. This can be a HCHANNEL, HMUSIC or HSTREAM handle, in which case an IDirectSoundBuffer interface is returned, or one of the following.
BASS_OBJECT_DS | Retrieve the IDirectSound interface.
BASS_OBJECT_DS3DL | Retrieve the IDirectSound3DListener interface.

Return value

If successful, then a pointer to the requested object is returned, otherwise NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_ILLPARAM | object is invalid.
BASS_ERROR_NOTAVAIL | The requested object is not available with the current device.

Remarks

This function allows those that are familiar with DirectSound to access the internal DirectSound object interfaces, so that extra external functionality can be "plugged" into BASS. If you create any objects through a retrieved interface, make sure you release the objects before calling BASS_Free.

See the DirectX SDK for information on the DirectSound interfaces.

When using multiple devices, and requesting either the BASS_OBJECT_DS or BASS_OBJECT_DS3DL object interfaces, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Platform-specific

DirectSound in a Windows thing, so this function is not available on other platforms.

Example

Set the speaker configuration to "headphones".
#include <dsound.h>
...
IDirectSound *ds = BASS_GetDSoundObject(BASS_OBJECT_DS); // get object
IDirectSound_SetSpeakerConfig(ds, DSSPEAKER_HEADPHONE); // headphones

See also

BASS_Init


BASS_GetInfo

Retrieves information on the device being used.

BOOL BASS_GetInfo(
    BASS_INFO *info
);

Parameters

info Pointer to a structure to receive the information.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Example

Display the device's output rate.
BASS_INFO info;
BASS_GetInfo(&info);
printf("sample rate = %d\n", info.freq);

See also

BASS_GetDeviceInfo, BASS_INFO structure


BASS_GetVersion

Retrieves the version of BASS that is loaded.

DWORD BASS_GetVersion();

Return value

The BASS version. For example, 0x02040103 (hex), would be version 2.4.1.3

Remarks

There is no guarantee that a previous or future version of BASS supports all the BASS functions that you are using, so you should always use this function to make sure the correct version is loaded. It is safe to assume that future revisions (indicated in the LOWORD) will be fully compatible.

The BASS API includes a BASSVERSION constant, which can be used to check that the loaded BASS.DLL matches the API version used, ignoring revisions.

Example

Check that the correct BASS version is loaded, ignoring the revision.
if (HIWORD(BASS_GetVersion()) != BASSVERSION) {
    // incorrect version loaded!
}

Check that revision 1.0 or above of the correct BASS version is loaded.

DWORD version = BASS_GetVersion(); // get the version number
if (HIWORD(version) != BASSVERSION // check the main version
    || LOWORD(version) < 0x100) { // check the revision
    // incorrect version loaded!
}


BASS_GetVolume

Retrieves the current master volume level.

float BASS_GetVolume();

Return value

If successful, the volume level is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | There is no volume control when using the "no sound" device.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_SetVolume


BASS_Init

Initializes an output device.

BOOL BASS_Init(
    int device,
    DWORD freq,
    DWORD flags,
    HWND win,
    GUID *clsid
);

Parameters

device | The device to use... -1 = default device, 0 = no sound, 1 = first real output device. BASS_GetDeviceInfo can be used to enumerate the available devices.
freq | Output sample rate.
flagsA combination of these flags.
BASS_DEVICE_8BITS | Use 8-bit resolution.
BASS_DEVICE_16BITS | Use 16-bit resolution.
BASS_DEVICE_MONO | Mono output.
BASS_DEVICE_STEREO | Limit the output to stereo, saving some CPU if the device has more speakers available.
BASS_DEVICE_3D | Enable 3D functionality.
BASS_DEVICE_LATENCY | Calculates the latency of the device, that is the delay between requesting a sound to play and it actually being heard. A recommended minimum buffer length is also calculated. Both values are retrievable in the BASS_INFO structure (latency & minbuf members). These calculations can increase the time taken by this function by 1-3 seconds when using DirectSound output.
BASS_DEVICE_CPSPEAKERS | Use the Windows control panel setting to detect the number of speakers. Soundcards generally have their own control panel to set the speaker config, so the Windows control panel setting may not be accurate unless it matches that. This flag has no effect on Vista, as the speakers are already accurately detected.
BASS_DEVICE_SPEAKERS | Force the enabling of speaker assignment. With some devices/drivers, the number of speakers BASS detects may be 2, when the device in fact supports more than 2 speakers. This flag forces the enabling of assignment to 8 possible speakers. This flag has no effect with non-WDM drivers.
BASS_DEVICE_NOSPEAKER | Ignore speaker arrangement. This flag tells BASS not to make any special consideration for speaker arrangements when using the SPEAKER flags, eg. swapping the CENLFE and REAR speaker channels in 5/7.1 speaker output. This flag should be used with plain multi-channel (rather than 5/7.1) devices.
BASS_DEVICE_FREQ | Set the device's output rate to freq, otherwise leave it as it is.
BASS_DEVICE_DSOUND | Initialize the device to use the old DirectSound output system instead of WASAPI. If WASAPI is not available (pre-Vista Windows), then this will be applied automatically.
BASS_DEVICE_AUDIOTRACK | Initialize the device to use AudioTrack output instead of OpenSL ES or AAudio. If OpenSL ES and AAudio are not available (pre-2.3 Android) then this will be applied automatically.
BASS_DEVICE_DMIX | Initialize the device using the ALSA "dmix" plugin, else initialize the device for exclusive access.
win | The application's main window... 0 = the desktop window (use this for console applications). This is only needed when using DirectSound output.
clsid | Class identifier of the object to create, that will be used to initialize DirectSound... NULL = use default.

Return value

If the device was successfully initialized, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DX | DirectX (or ALSA on Linux) is not installed.
BASS_ERROR_DEVICE | device is invalid.
BASS_ERROR_ALREADY | The device has already been initialized. BASS_Free must be called before it can be initialized again.
BASS_ERROR_DRIVER | There is no available device driver.
BASS_ERROR_BUSY | Something else has exclusive use of the device.
BASS_ERROR_FORMAT | The specified format is not supported by the device. Try changing the freq and flags parameters.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

This function must be successfully called before using any sample, stream or MOD music functions. The recording functions may be used without having called this function.

Simultaneously using multiple devices is supported in the BASS API via a context switching system; instead of there being an extra "device" parameter in the function calls, the device to be used is set prior to calling the functions. BASS_SetDevice is used to switch the current device. When successful, BASS_Init automatically sets the current thread's device to the one that was just initialized.

When using the default device (device = -1), BASS_GetDevice can be used to find out which device it was mapped to.

The BASS_CONFIG_DEV_BUFFER and BASS_CONFIG_DEV_PERIOD config options determine how much data is buffered for the device and how often it is updated.

Platform-specific

On Linux, a "Default" device is hardcoded to device number 1, which uses the default output set in the ALSA config; that could map directly to one of the other devices or it could use ALSA plugins. If the BASS_CONFIG_DEV_DEFAULT config option has been enabled, a "Default" device is also available on Windows and OSX. In both cases, the "Default" device will also be the default device (device = -1)

The sample format specified in the freq and flags parameters has no effect on the device output on iOS or OSX, and not on Windows unless VxD drivers are used (on Windows 98/95); with WDM drivers (on Windows XP/2000/Me/98SE), the output format is automatically set depending on the format of what is played and what the device supports, while on Vista and newer, the output format is determined by the user's choice in the Sound control panel. On Linux, the output device will use the specified format if possible, but will otherwise use a format as close to it as possible. On Android, the device's native sample rate (as reported by the AudioTrack getNativeOutputSampleRate method) will be used unless the BASS_DEVICE_FREQ flag is specified, in which case the freq parameter will be used (this only affects BASS's output format, not the device's output format). If the BASS_DEVICE_FREQ flag is specified on iOS or OSX, then the device's output rate will be set to the freq parameter if possible. The BASS_DEVICE_FREQ flag has no effect on other platforms. BASS_GetInfo can be used to check what the output format actually is.

When DirectSound output is used on Windows, BASS will not be generating the final output mix and so some BASS features will be unavailable, including sample rate conversion quality configuration, playback buffer bypassing, and access to the final mix.

On Android, when the BASS_DEVICE_AUDIOTRACK flag is not specified, AAudio or OpenSL ES output may be used depending on the BASS_CONFIG_ANDROID_AAUDIO config option setting. AAudio has a low latency mode, which will be enabled when BASS_CONFIG_DEV_BUFFER is set below 50.

On Windows, when specifying a class identifier (clsid), BASS_GetDSoundObject can be used to retrieve the DirectSound object after successful initialization, and through that access any special interfaces that the object may provide.

The win and clsid parameters are only used with DirectSound output on Windows and are ignored in all other cases. That applies to the BASS_DEVICE_LATENCY flag too, as latency information is otherwise available without it. The BASS_DEVICE_CPSPEAKERS and BASS_DEVICE_SPEAKERS flags only have effect on pre-Vista Windows; the number of available speakers is always accurately detected otherwise. The BASS_DEVICE_STEREO flag is ignored on Windows and OSX.

The BASS_DEVICE_DMIX flag is only available on Linux, and allows multiple applications to share the device (if they all use "dmix"). It may also be possible for multiple applications to use exclusive access if the device is capable of hardware mixing. If exclusive access initialization fails, the BASS_DEVICE_DMIX flag will automatically be tried; if that happens, it can be detected via BASS_GetInfo and the initflags.

Example

Initialize BASS to use the default output device, and a nominal format of 44100 Hz stereo 16-bit.
BASS_Init(-1, 44100, 0, hwnd, NULL);

See also

BASS_Free, BASS_GetCPU, BASS_GetDeviceInfo, BASS_GetDSoundObject, BASS_GetInfo, BASS_MusicLoad, BASS_SampleCreate, BASS_SampleLoad, BASS_SetConfig, BASS_SetDevice, BASS_StreamCreate, BASS_StreamCreateFile, BASS_StreamCreateURL, BASS_Update, BASS_CONFIG_BUFFER, BASS_CONFIG_DEV_BUFFER, BASS_CONFIG_DEV_DEFAULT, BASS_CONFIG_UPDATEPERIOD


BASS_IsStarted

Checks if the output has been started.

BOOL BASS_IsStarted();

Return value

If the device has been started, then TRUE is returned, else FALSE is returned.

Remarks

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_ChannelIsActive, BASS_Pause, BASS_Start, BASS_Stop


BASS_Pause

Stops the output, pausing all musics/samples/streams on it.

BOOL BASS_Pause();

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks

Use BASS_Start to resume the output and paused channels.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_ChannelPause, BASS_Start, BASS_Stop, BASS_CONFIG_PAUSE_NOPLAY


BASS_SetDevice

Sets the device to use for subsequent calls in the current thread.

BOOL BASS_SetDevice(
    DWORD device
);

Parameters

device The device to use... 0 = no sound, 1 = first real output device.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DEVICE | device is invalid.
BASS_ERROR_INIT | The device has not been initialized.

Remarks

Simultaneously using multiple devices is supported in the BASS API via a context switching system; instead of there being an extra "device" parameter in the function calls, the device to be used is set prior to calling the functions. The device setting is local to the current thread, so calling functions with different devices simultaneously in multiple threads is not a problem.

The functions that use the device selection are the following: BASS_Free, BASS_GetDSoundObject, BASS_GetInfo, BASS_Start, BASS_Stop, BASS_Pause, BASS_SetVolume, BASS_GetVolume, BASS_Set3DFactors, BASS_Get3DFactors, BASS_Set3DPosition, BASS_Get3DPosition, BASS_SetEAXParameters, BASS_GetEAXParameters. It also determines which device is used by a new sample/stream/music: BASS_MusicLoad, BASS_SampleLoad, BASS_StreamCreateFile, etc.

When one of the above functions (or BASS_GetDevice) is called, BASS will check the current thread's device setting, and if no device is selected (or the selected device is not initialized), BASS will automatically select the lowest device that is initialized. This means that when using a single device, there is no need to use this function; BASS will automatically use the device that is initialized. Even if you free the device, and initialize another, BASS will automatically switch to the one that is initialized.

Example

Create a stream of an MP3 file on device 2.
BASS_SetDevice(2); // select device 2
stream = BASS_StreamCreateFile(FALSE, "afile.mp3", 0, 0, 0); // create the stream

See also

BASS_ChannelGetDevice, BASS_ChannelSetDevice, BASS_GetDevice, BASS_Init


BASS_SetVolume

Sets the output master volume.

BOOL BASS_SetVolume(
    float volume
);

Parameters

volume The volume level... 0 (silent) to 1 (max).

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | There is no volume control when using the "no sound" device.
BASS_ERROR_ILLPARAM | volume is invalid.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The actual volume level may not be exactly the same as requested, due to underlying precision differences. BASS_GetVolume can be used to confirm what the volume is.

This function affects the volume level of all applications using the same output device. If you wish to only affect the level of your application's sounds, the BASS_ATTRIB_VOL attribute and/or the BASS_CONFIG_GVOL_MUSIC / BASS_CONFIG_GVOL_SAMPLE / BASS_CONFIG_GVOL_STREAM config options should be used instead.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_GetVolume, BASS_ATTRIB_VOL, BASS_CONFIG_CURVE_VOL, BASS_CONFIG_GVOL_MUSIC, BASS_CONFIG_GVOL_SAMPLE, BASS_CONFIG_GVOL_STREAM


BASS_Start

Starts (or resumes) the output.

BOOL BASS_Start();

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The output is automatically started by BASS_Init, so there is usually no need to use this function unless BASS_Stop or BASS_Pause has been used. But the output may also be paused automatically if the output device becomes unavailable (eg. disconnected). A BASS_SYNC_DEV_FAIL sync can be set via BASS_ChannelSetSync to be notified when that happens. BASS_IsStarted can be used to check if the output is currently running.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Platform-specific

When using DirectSound output on Windows, and the device becomes unavailable (eg. disconnected), this function will not be able to resume output once the device becomes available again; the device will need to be reinitialized via BASS_Init.

See also

BASS_IsStarted, BASS_Pause, BASS_Stop


BASS_Stop

Stops the output, stopping all musics/samples/streams on it.

BOOL BASS_Stop();

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_Init has not been successfully called.

Remarks

This function can be used after BASS_Pause to stop the paused channels, so that they will not be resumed the next time BASS_Start is called.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_ChannelStop, BASS_Pause, BASS_Start


BASS_Update

Updates the HSTREAM and HMUSIC channel playback buffers.

BOOL BASS_Update(
    DWORD length
);

Parameters

length The amount of data to render, in milliseconds.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_NOTAVAIL Updating is already in progress.

Remarks

When automatic updating is disabled, this function or BASS_ChannelUpdate needs to be used to keep the playback buffers updated. The length parameter should include some safety margin, in case the next update cycle gets delayed. For example, if calling this function every 100ms, 200 would be a reasonable length parameter.

See also

BASS_ChannelUpdate, BASS_CONFIG_BUFFER, BASS_CONFIG_UPDATETHREADS


BASS_DEVICEINFO structure

Used with BASS_GetDeviceInfo or BASS_RecordGetDeviceInfo to retrieve information on a device.

typedef struct {
    char *name;
    char *driver;
    DWORD flags;
} BASS_DEVICEINFO;

Members

name | Description of the device.
driver | The filename of the driver.
flagsThe device's current status... a combination of these flags.
BASS_DEVICE_ENABLED | The device is enabled. It will not be possible to initialize the device if this flag is not present.
BASS_DEVICE_DEFAULT | The device is the system default.
BASS_DEVICE_INIT | The device is initialized, ie. BASS_Init or BASS_RecordInit has been called.
BASS_DEVICE_LOOPBACK | The device is a loopback recording device; it captures the sound from an output device. The corresponding output device can be identified by having the same driver value.
The type of device may also be indicated in the high 8 bits (use BASS_DEVICE_TYPE_MASK to test), and can be one of the following.
BASS_DEVICE_TYPE_DIGITAL | An audio endpoint device that connects to an audio adapter through a connector for a digital interface of unknown type.
BASS_DEVICE_TYPE_DISPLAYPORT | An audio endpoint device that connects to an audio adapter through a DisplayPort connector.
BASS_DEVICE_TYPE_HANDSET | The part of a telephone that is held in the hand and that contains a speaker and a microphone for two-way communication.
BASS_DEVICE_TYPE_HDMI | An audio endpoint device that connects to an audio adapter through a High-Definition Multimedia Interface (HDMI) connector.
BASS_DEVICE_TYPE_HEADPHONES | A set of headphones.
BASS_DEVICE_TYPE_HEADSET | An earphone or a pair of earphones with an attached mouthpiece for two-way communication.
BASS_DEVICE_TYPE_LINE | An audio endpoint device that sends a line-level analog signal to a line-input jack on an audio adapter or that receives a line-level analog signal from a line-output jack on the adapter.
BASS_DEVICE_TYPE_MICROPHONE | A microphone.
BASS_DEVICE_TYPE_NETWORK | An audio endpoint device that the user accesses remotely through a network.
BASS_DEVICE_TYPE_SPDIF | An audio endpoint device that connects to an audio adapter through a Sony/Philips Digital Interface (S/PDIF) connector.
BASS_DEVICE_TYPE_SPEAKERS | A set of speakers.

Remarks

When a device is disabled/disconnected, it is still retained in the device list, but the BASS_DEVICE_ENABLED flag is removed from it. If the device is subsequently re-enabled, it may become available again with the same device number, or the system may add a new entry for it.

When a new device is connected, it can affect the other devices and result in the system moving them to new device entries. If an affected device is initialized, it will stop working and will need to be reinitialized using its new device number.

Platform-specific

On Windows, driver can reveal the type of driver being used on systems that support both VxD and WDM drivers (Windows Me/98SE). Further information can be obtained from the file via the GetFileVersionInfo function. On Vista and newer, the device's endpoint ID is given rather than its driver filename. On OSX, driver is the device's UID, and on Linux it is the ALSA device name. It is unused on other platforms. The device type is only available on Windows (Vista and newer) and OSX. On Windows, DisplayPort devices will have BASS_DEVICE_TYPE_HDMI rather than BASS_DEVICE_TYPE_DISPLAYPORT.

When the BASS_CONFIG_DEV_DEFAULT option is enabled, the BASS_DEVICE_DEFAULT flag will be set on both the "Default" device and the device that it currently maps to.

Depending on the BASS_CONFIG_UNICODE config setting, name and driver can be in ANSI or UTF-8 form on Windows. They are always in UTF-16 form ("WCHAR" rather than "char") on Windows CE, and UTF-8 on other platforms.

See also

BASS_GetDeviceInfo, BASS_RecordGetDeviceInfo, BASS_CONFIG_UNICODE


BASS_INFO structure

Used with BASS_GetInfo to retrieve information on the current device.

typedef struct {
    DWORD flags;
    DWORD hwsize;
    DWORD hwfree;
    DWORD freesam;
    DWORD free3d;
    DWORD minrate;
    DWORD maxrate;
    BOOL eax;
    DWORD minbuf;
    DWORD dsver;
    DWORD latency;
    DWORD initflags;
    DWORD speakers;
    DWORD freq;
} BASS_INFO;

Members

flagsThe device's capabilities... a combination of the following flags.
DSCAPS_CONTINUOUSRATE | The device supports all sample rates between minrate and maxrate.
DSCAPS_EMULDRIVER | The device's drivers do not have DirectSound support, so it is being emulated. Updated drivers should be installed.
DSCAPS_CERTIFIED | The device driver has been certified by Microsoft. This flag is always set on WDM drivers.
DSCAPS_SECONDARYMONO | Mono samples are supported by hardware mixing.
DSCAPS_SECONDARYSTEREO | Stereo samples are supported by hardware mixing.
DSCAPS_SECONDARY8BIT | 8-bit samples are supported by hardware mixing.
DSCAPS_SECONDARY16BIT | 16-bit samples are supported by hardware mixing.
hwsize | The device's total amount of hardware memory.
hwfree | The device's amount of free hardware memory.
freesam | The number of free sample slots in the hardware.
free3d | The number of free 3D sample slots in the hardware.
minrate | The minimum sample rate supported by the hardware.
maxrate | The maximum sample rate supported by the hardware.
eax | The device supports EAX and has it enabled? The device's "Hardware acceleration" needs to be set to "Full" in its "Advanced Properties" setup, else EAX is disabled. This is always FALSE if BASS_DEVICE_3D was not specified when BASS_Init was called.
minbuf | The minimum buffer length (rounded up to the nearest millisecond) recommended for use (with the BASS_CONFIG_BUFFER config option).
dsver | DirectSound version... 9 = DX9/8/7/5 features are available, 8 = DX8/7/5 features are available, 7 = DX7/5 features are available, 5 = DX5 features are available. 0 = none of the DX9/8/7/5 features are available.
latency | The average delay (rounded up to the nearest millisecond) for channel playback to start and be heard.
initflags | The flags parameter of the BASS_Init call.
speakers | The number of available speakers, which can be accessed via the speaker assignment flags.
freq | The device's current output sample rate.

Platform-specific

When using DirectSound output on pre-Vista Windows, it is possible for speakers to mistakenly be 2 with some devices/drivers when the device in fact supports more speakers. In that case, the BASS_DEVICE_CPSPEAKERS flag can be used (with BASS_Init) to use the Windows control panel setting, or the BASS_DEVICE_SPEAKERS flag can be used to force the enabling of speaker assignment to up to 8 speakers, even though the device may not really support that many speakers. The result of assigning channels to nonexistent speakers is undefined; they may be heard on other speakers or not heard at all.

The device's sample rate is only available on Windows/OSX/iOS. On other platforms, the freq member is BASS's output rate (set by BASS_Init) which may not necessarily be the same as the device's output rate due to resampling by the OS. The freq member is not available on Windows prior to Vista.

The flags, hwsize, hwfree, freesam, free3d, minrate, maxrate, eax, and dsver members are only used on Windows with DirectSound output.

When using DirectSound output on Windows, the availability of the latency and minbuf values depends on the BASS_DEVICE_LATENCY flag being used when BASS_Init was called.

See also

BASS_GetInfo


BASS_Apply3D

Applies changes made to the 3D system.

void BASS_Apply3D();

Remarks

This function must be called to apply any changes made with BASS_Set3DFactors, BASS_Set3DPosition, BASS_ChannelSet3DAttributes or BASS_ChannelSet3DPosition. This allows multiple changes to be synchronized, and also improves performance.

This function applies 3D changes on all the initialized devices. There is no need to re-call it for each individual device when using multiple devices.

See also

BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_Set3DFactors, BASS_Set3DPosition


BASS_Get3DFactors

Retrieves the factors that affect the calculations of 3D sound.

BOOL BASS_Get3DFactors(
    float *distf,
    float *rollf,
    float *doppf
);

Parameters

distf | The distance factor... NULL = don't retrieve it.
rollf | The rolloff factor... NULL = don't retrieve it.
doppf | The doppler factor... NULL = don't retrieve it.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NO3D | The device was not initialized with 3D support.

Remarks

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_Set3DFactors


BASS_Get3DPosition

Retrieves the position, velocity, and orientation of the listener.

BOOL BASS_Get3DPosition(
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *vel,
    BASS_3DVECTOR *front,
    BASS_3DVECTOR *top
);

Parameters

pos | The position of the listener... NULL = don't retrieve it.
vel | The listener's velocity... NULL = don't retrieve it.
front | The direction that the listener's front is pointing... NULL=don't retrieve it.
top | The direction that the listener's top is pointing... NULL = don't retrieve it.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NO3D | The device was not initialized with 3D support.

Remarks

The front and top parameters must both be retrieved in a single call, they cannot be retrieved individually.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_Set3DPosition, BASS_3DVECTOR structure


BASS_GetEAXParameters

Retrieves the current type of EAX environment and its parameters.

BOOL BASS_GetEAXParameters(
    DWORD *env,
    float *vol,
    float *decay
    float *damp
);

Parameters

env | The EAX environment... NULL = don't retrieve it. See BASS_SetEAXParameters for a list of the possible environments.
vol | The volume of the reverb... NULL = don't retrieve it.
decay | The decay duration... NULL = don't retrieve it.
damp | The damping... NULL = don't retrieve it.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOEAX | The current device does not support EAX.

Remarks

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Platform-specific

This function is only available on Windows, and EAX is only supported pre-Vista.

See also

BASS_SetEAXParameters


BASS_Set3DFactors

Sets the factors that affect the calculations of 3D sound.

BOOL BASS_Set3DFactors(
    float distf,
    float rollf,
    float doppf
);

Parameters

distf | The distance factor... 0 or less = leave current... examples: 1.0 = use meters, 0.9144 = use yards, 0.3048 = use feet. By default BASS measures distances in meters, you can change this setting if you are using a different unit of measurement.
rollf | The rolloff factor, how fast the sound quietens with distance... 0.0 (min) - 10.0 (max), less than 0.0 = leave current... examples: 0.0 = no rolloff, 1.0 = real world, 2.0 = 2x real.
doppf | The doppler factor... 0.0 (min) - 10.0 (max), less than 0.0 = leave current... examples: 0.0 = no doppler, 1.0 = real world, 2.0 = 2x real. The doppler effect is the way a sound appears to change pitch when it is moving towards or away from you. The listener and sound velocity settings are used to calculate this effect, this doppf value can be used to lessen or exaggerate the effect.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NO3D | The device was not initialized with 3D support.

Remarks

As with all 3D functions, use BASS_Apply3D to apply the changes.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Example

Use yards as the distance measurement unit, while leaving the current rolloff and doppler factors untouched.
BASS_Set3DFactors(0.9144, -1.0, -1.0);
BASS_Apply3D(); // apply the change

See also

BASS_Apply3D, BASS_Get3DFactors


BASS_Set3DPosition

Sets the position, velocity, and orientation of the listener (ie. the player).

BOOL BASS_Set3DPosition(
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *vel,
    BASS_3DVECTOR *front,
    BASS_3DVECTOR *top
);

Parameters

pos | The position of the listener... NULL = leave current.
vel | The listener's velocity in units (as set with BASS_Set3DFactors) per second... NULL = leave current. This is only used to calculate the doppler effects, and in no way affects the listener's position.
front | The direction that the listener's front is pointing... NULL = leave current. This is automatically normalized.
top | The direction that the listener's top is pointing... NULL = leave current. This is automatically normalized, and adjusted to be at a right-angle to the front vector if necessary.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NO3D | The device was not initialized with 3D support.

Remarks

The front and top parameters must both be set in a single call, they cannot be set individually. As with all 3D functions, use BASS_Apply3D to apply the changes.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

See also

BASS_Apply3D, BASS_Get3DPosition, BASS_Set3DFactors, BASS_3DVECTOR structure


BASS_SetEAXParameters

Sets the type of EAX environment and its parameters.

BOOL BASS_SetEAXParameters(
    int env,
    float vol,
    float decay,
    float damp
);

Parameters

env | The EAX environment... -1 = leave current, or one of the following. EAX_ENVIRONMENT_GENERIC, EAX_ENVIRONMENT_PADDEDCELL, EAX_ENVIRONMENT_ROOM, EAX_ENVIRONMENT_BATHROOM, EAX_ENVIRONMENT_LIVINGROOM, EAX_ENVIRONMENT_STONEROOM, EAX_ENVIRONMENT_AUDITORIUM, EAX_ENVIRONMENT_CONCERTHALL, EAX_ENVIRONMENT_CAVE, EAX_ENVIRONMENT_ARENA, EAX_ENVIRONMENT_HANGAR, EAX_ENVIRONMENT_CARPETEDHALLWAY, EAX_ENVIRONMENT_HALLWAY, EAX_ENVIRONMENT_STONECORRIDOR, EAX_ENVIRONMENT_ALLEY, EAX_ENVIRONMENT_FOREST, EAX_ENVIRONMENT_CITY, EAX_ENVIRONMENT_MOUNTAINS, EAX_ENVIRONMENT_QUARRY, EAX_ENVIRONMENT_PLAIN, EAX_ENVIRONMENT_PARKINGLOT, EAX_ENVIRONMENT_SEWERPIPE, EAX_ENVIRONMENT_UNDERWATER, EAX_ENVIRONMENT_DRUGGED, EAX_ENVIRONMENT_DIZZY, EAX_ENVIRONMENT_PSYCHOTIC.
vol | The volume of the reverb... 0 (off) to 1 (max), less than 0 = leave current.
decay | The time in seconds it takes the reverb to diminish by 60 dB... 0.1 (min) to 20 (max), less than 0 = leave current.
damp | The damping, high or low frequencies decay faster... 0 = high decays quickest, 1 = low/high decay equally, 2 = low decays quickest, less than 0 = leave current.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOEAX | The output device does not support EAX.

Remarks

The use of EAX functions requires that the output device supports EAX. BASS_GetInfo can be used to check that. EAX only affects 3D channels, but EAX functions do not require BASS_Apply3D to apply the changes.

Presets are provided for all the EAX environments. To use a preset, simply call BASS_SetEAXParameters(preset), where preset is one of the following.
EAX_PRESET_GENERIC, EAX_PRESET_PADDEDCELL, EAX_PRESET_ROOM, EAX_PRESET_BATHROOM, EAX_PRESET_LIVINGROOM, EAX_PRESET_STONEROOM, EAX_PRESET_AUDITORIUM, EAX_PRESET_CONCERTHALL, EAX_PRESET_CAVE, EAX_PRESET_ARENA, EAX_PRESET_HANGAR, EAX_PRESET_CARPETEDHALLWAY, EAX_PRESET_HALLWAY, EAX_PRESET_STONECORRIDOR, EAX_PRESET_ALLEY, EAX_PRESET_FOREST, EAX_PRESET_CITY, EAX_PRESET_MOUNTAINS, EAX_PRESET_QUARRY, EAX_PRESET_PLAIN, EAX_PRESET_PARKINGLOT, EAX_PRESET_SEWERPIPE, EAX_PRESET_UNDERWATER, EAX_PRESET_DRUGGED, EAX_PRESET_DIZZY, EAX_PRESET_PSYCHOTIC.

When using multiple devices, the current thread's device setting (as set with BASS_SetDevice) determines which device this function call applies to.

Platform-specific

This function is only available on Windows, and EAX is only supported pre-Vista.

Example

Use the EAX_PRESET_ARENA preset.
BASS_SetEAXParameters(EAX_PRESET_ARENA);

See also

BASS_GetEAXParameters, BASS_ATTRIB_EAXMIX


BASS_3DVECTOR structure

Structure used by the 3D functions to describe positions, velocities, and orientations.

typedef struct {
    float x;
    float y;
    float z;
} BASS_3DVECTOR;

Members

x | +ve = right, -ve = left.
y | +ve = up, -ve = down.
z | +ve = front, -ve = behind.

Remarks

As can be seen above, the left-handed coordinate system is used.


BASS_SampleCreate

Creates a new sample.

HSAMPLE BASS_SampleCreate(
    DWORD length,
    DWORD freq,
    DWORD chans,
    DWORD max,
    DWORD flags
);

Parameters

length | The sample's length, in bytes.
freq | The default sample rate.
chans | The number of channels... 1 = mono, 2 = stereo, etc.
max | Maximum number of simultaneous playbacks... 1 (min) - 65535 (max)... use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).
flagsA combination of these flags.
BASS_SAMPLE_8BITS | Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the sample is 16-bit.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. Not really recommended for samples as it (at least) doubles the memory usage.
BASS_SAMPLE_LOOP | Looped? Note that only complete sample loops are allowed; you cannot loop just a part of the sample. More fancy looping can be achieved via streaming.
BASS_SAMPLE_SOFTWARE | Force the sample to not use hardware DirecSound mixing.
BASS_SAMPLE_VAM | Enables the DX7 voice allocation and management features on the sample, which allows the sample to be played in software or hardware. This flag is ignored if the BASS_SAMPLE_SOFTWARE flag is also specified.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the sample must be mono (chans=1).
BASS_SAMPLE_MUTEMAX | Mute the sample when it is at (or beyond) its max distance (software-mixed 3D samples only).
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DIST | Override: the channel furthest away (from the listener) is overridden (3D samples only).

Return value

If successful, the new sample's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_ILLPARAM | max is invalid.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The sample's initial content is undefined. BASS_SampleSetData should be used to set the sample's data.

Unless the BASS_SAMPLE_SOFTWARE flag is used, the sample will use hardware mixing if hardware resources are available. Use BASS_GetInfo to see if there are hardware mixing resources available, and which sample formats are supported by the hardware. The BASS_SAMPLE_VAM flag allows a sample to be played by both hardware and software, with the decision made when the sample is played rather than when it is loaded. A sample's VAM options are set via BASS_SampleSetInfo.

To play a sample, first a channel must be obtained using BASS_SampleGetChannel, which can then be played using BASS_ChannelPlay.

If you want to play a large or one-off sample, then it would probably be better to stream it instead with BASS_StreamCreate.

Platform-specific

The BASS_SAMPLE_VAM flag is only available when using DirectSound output on Windows and requires DirectX 7 (or above).

Example

Create a 440 Hz sine wave sample.
HSAMPLE sample = BASS_SampleCreate(256, 440 * 64, 1, 1, BASS_SAMPLE_LOOP | BASS_SAMPLE_OVER_POS); // create sample
short data[128]; // data buffer
int a;
for (a = 0; a < 128; a++)
    data[a] = (short)(32767.0 * sin(a * 6.283185 / 64)); // sine wave
BASS_SampleSetData(sample, data); // set the sample's data

See also

BASS_SampleLoad, BASS_SampleSetData, BASS_StreamCreate


BASS_SampleFree

Frees a sample's resources.

BOOL BASS_SampleFree(
    HSAMPLE handle
);

Parameters

handle The sample handle.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.

See also

BASS_SampleCreate, BASS_SampleLoad


BASS_SampleGetChannel

Creates/initializes a playback channel for a sample.

HCHANNEL BASS_SampleGetChannel(
    HSAMPLE handle,
    BOOL onlynew
);

Parameters

handle | Handle of the sample to play.
onlynew | Do not recycle/override one of the sample's existing channels?

Return value

If successful, the handle of the new channel is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid sample handle.
BASS_ERROR_NOCHAN | The sample has no free channels... the maximum number of simultaneous playbacks has been reached, and no BASS_SAMPLE_OVER flag was specified for the sample or onlynew = TRUE.
BASS_ERROR_TIMEOUT | The sample's minimum time gap (BASS_SAMPLE) has not yet passed since the last channel was created.

Remarks

Use BASS_SampleGetInfo and BASS_SampleSetInfo to set a sample's default attributes, which are used when creating a channel. After creation, a channel's attributes can be changed via BASS_ChannelSetAttribute, BASS_ChannelSet3DAttributes and BASS_ChannelSet3DPosition. BASS_Apply3D should be called before starting playback of a 3D sample, even if you just want to use the default settings.

If a sample has a maximum number of simultaneous playbacks of 1 (the max parameter was 1 when calling BASS_SampleLoad or BASS_SampleCreate), then the HCHANNEL handle returned will be identical to the HSAMPLE handle. That means you can use the HSAMPLE handle with functions that usually require a HCHANNEL handle, but you must still call this function first to initialize the channel.

When channel overriding has been enabled via a BASS_SAMPLE_OVER flag and there are multiple candidates for overriding (eg. with identical volume), the oldest of them will be chosen to make way for the new channel.

A sample channel is automatically freed when it's overridden by a new channel, or when stopped by BASS_ChannelStop, BASS_SampleStop or BASS_Stop. If you wish to stop a channel and re-use it, BASS_ChannelPause should be used to pause it instead. Determining whether a channel still exists can be done by trying to use the handle in a function call. A list of all the sample's existing channels can also be retrieved via BASS_SampleGetChannels.

The new channel will have an initial state of being paused (BASS_ACTIVE_PAUSED). This prevents the channel being claimed by another call of this function before it has been played, unless it gets overridden due to a lack of free channels.

All of a sample's channels share the same sample data, and just have their own individual playback state information (volume/position/etc).

Example

Play a sample with its default settings.
HCHANNEL channel = BASS_SampleGetChannel(sample, FALSE); // get a sample channel
BASS_ChannelPlay(channel, FALSE); // play it

See also

BASS_ChannelPlay, BASS_ChannelSet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttribute, BASS_SampleCreate, BASS_SampleGetChannels, BASS_SampleLoad, BASS_SampleStop, BASS_CONFIG_SRC_SAMPLE


BASS_SampleGetChannels

Retrieves all a sample's existing channels.

DWORD BASS_SampleGetChannels(
    HSAMPLE handle,
    HCHANNEL *channels
);

Parameters

handle | The sample handle.
channels | An array to put the sample's channel handles in. The array should be the same size as the sample's max setting when the sample was created, which can be retrieved using BASS_SampleGetInfo. NULL can be used to just check how many channels exist.

Return value

If successful, the number of existing channels is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid sample handle.

Remarks

To determine whether a particular sample channel still exists, it is simplest to just try it in a function call.

Example

Set the sample rate of all a sample's channels to 10000 Hz.
BASS_SAMPLE info;
HCHANNEL *channels;
DWORD a, count;
BASS_SampleGetInfo(sample, &info); // get sample info for "max" value
channels = (HCHANNEL*)malloc(info.max * sizeof(HCHANNEL)); // allocate channels array
count = BASS_SampleGetChannels(sample, channels); // get the channels
for (a = 0; a < count; a++) // go through them all and...
    BASS_ChannelSetAttribute(channels[a], BASS_ATTRIB_FREQ, 10000); // set the sample rate to 10000
free(channels); // free the channels array

See also

BASS_SampleGetChannel, BASS_SampleGetInfo


BASS_SampleGetData

Retrieves a copy of a sample's data.

BOOL BASS_SampleGetData(
    HSAMPLE handle,
    void *buffer
);

Parameters

handle | The sample handle.
buffer | Pointer to a buffer to receive the data.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The buffer must be big enough to receive the sample's data, the size of which can be retrieved via BASS_SampleGetInfo.

See also

BASS_ChannelGetData, BASS_SampleSetData


BASS_SampleGetInfo

Retrieves a sample's default attributes and other information.

BOOL BASS_SampleGetInfo(
    HSAMPLE handle,
    BASS_SAMPLE *info
);

Parameters

handle | The sample handle.
info | Pointer to a structure to receive the sample information.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE The handle is invalid.

Remarks

Use this function and BASS_SampleSetInfo to edit a sample's default attributes.

See also

BASS_SampleSetInfo, BASS_SAMPLE structure


BASS_SampleLoad

Loads a WAV, AIFF, MP3, MP2, MP1, OGG or plugin supported sample.

HSAMPLE BASS_SampleLoad(
    BOOL mem,
    void *file,
    QWORD offset,
    DWORD length,
    DWORD max,
    DWORD flags
);

Parameters

mem | TRUE = load the sample from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to load the sample from (only used if mem = FALSE).
length | Data length... 0 = use all data up to the end of file (if mem = FALSE). If length over-runs the end of the file, it will automatically be lowered to the end of the file.
max | Maximum number of simultaneous playbacks... 1 (min) - 65535 (max). Use one of the BASS_SAMPLE_OVER flags to choose the override decider, in the case of there being no free channel available for playback (ie. the sample is already playing max times).
flagsA combination of these flags.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. Not really recommended for samples as it (at least) doubles the memory usage.
BASS_SAMPLE_LOOP | Looped? Note that only complete sample loops are allowed, you cannot loop just a part of the sample. More fancy looping can be achieved by streaming the file.
BASS_SAMPLE_MONO | Convert the sample to mono, if it is not already mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_SOFTWARE | Force the sample to not use hardware DirectSound mixing.
BASS_SAMPLE_VAM | Enables the DX7 voice allocation and management features on the sample, which allows the sample to be played in software or hardware. This flag is ignored if the BASS_SAMPLE_SOFTWARE flag is also specified.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the sample must be mono.
BASS_SAMPLE_MUTEMAX | Mute the sample when it is at (or beyond) its max distance (software-mixed 3D samples only).
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DIST | Override: the channel furthest away (from the listener) is overridden (3D samples only).
BASS_UNICODE | file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.

Return value

If successful, the loaded sample's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_ILLPARAM | max and/or length is invalid. The length must be specified when loading from memory.
BASS_ERROR_FILEOPEN | The file could not be opened.
BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
BASS_ERROR_CODEC | The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the sample is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

This function supports the same file formats as BASS_StreamCreateFile does, including those supported via the plugin system.

Unless the BASS_SAMPLE_SOFTWARE flag is used, the sample will use hardware mixing if hardware resources are available. Use BASS_GetInfo to see if there are hardware mixing resources available, and which sample formats are supported by the hardware. The BASS_SAMPLE_VAM flag allows a sample to be played by both hardware and software, with the decision made when the sample is played rather than when it is loaded. A sample's VAM options are set via BASS_SampleSetInfo.

To play a sample, first a channel must be obtained using BASS_SampleGetChannel, which can then be played using BASS_ChannelPlay.

After loading a sample from memory (mem = TRUE), the memory can safely be discarded, as a copy is made.

If you want to play a large or one-off sample, then it would probably be better to stream it instead with BASS_StreamCreateFile.

Platform-specific

The BASS_SAMPLE_VAM flag is only available when using DirectSound output on Windows and requires DirectX 7 (or above).

On Android, file may be a String, ByteBuffer, ParcelFileDescriptor, or asset (via the Asset class) when using Java. See the BASS.JAVA file for available overloads.

See also

BASS_SampleCreate, BASS_SampleFree, BASS_SampleGetChannel, BASS_SampleGetInfo, BASS_StreamCreateFile


BASS_SampleSetData

Sets a sample's data.

BOOL BASS_SampleSetData(
    HSAMPLE handle,
    void *buffer
);

Parameters

handle | The sample handle.
buffer | Pointer to the data.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The required length and format of the data can be retrieved via BASS_SampleGetInfo.

A sample's data can be set at any time, including during playback.

See also

BASS_SampleCreate, BASS_SampleGetData


BASS_SampleSetInfo

Sets a sample's default attributes.

BOOL BASS_SampleSetInfo(
    HSAMPLE handle,
    BASS_SAMPLE *info
);

Parameters

handle | The sample handle.
info | Pointer to the sample information structure.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | The handle is invalid.
BASS_ERROR_ILLPARAM | The BASS_SAMPLE max value is invalid.

Remarks

Use this function and BASS_SampleGetInfo to edit a sample's default attributes. Changing a sample's default attributes does not affect any existing channels, it only affects channels subsequently created via BASS_SampleGetChannel. The exception is the VAM settings, changes to that apply to all the sample's channels at their next playback (BASS_ChannelPlay). Use BASS_ChannelSetAttribute and BASS_ChannelSet3DAttributes to change the attributes of an existing sample channel.

The sample's maximum number of simultaneous playbacks can be changed via the max member of the BASS_SAMPLE structure. If the new maximum is lower than the existing number of channels, the channels will remain existing until they are stopped.

The length, origres and chans members of the BASS_SAMPLE structure cannot be modified; any changes are ignored. Only the BASS_SAMPLE_LOOP and BASS_SAMPLE_OVER flags can be changed.

Example

Set a sample's default volume to 0.5.
BASS_SAMPLE info;
BASS_SampleGetInfo(sample, &info); // get the sample's current info
info.volume = 0.5; // set the default volume to 0.5
BASS_SampleSetInfo(sample, &info); // set the updated info

See also

BASS_ChannelSet3DAttributes, BASS_ChannelSetAttribute, BASS_SampleGetInfo, BASS_SAMPLE structure


BASS_SampleStop

Stops all instances of a sample.

BOOL BASS_SampleStop(
    HSAMPLE handle
);

Parameters

handle The sample handle.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid sample.

Remarks

If a sample is playing simultaneously multiple times, calling this function will stop them all, which is obviously simpler than calling BASS_ChannelStop multiple times.

See also

BASS_ChannelStop


BASS_SAMPLE structure

Used with BASS_SampleGetInfo and BASS_SampleSetInfo to retrieve and set the default playback attributes of a sample.

typedef struct {
    DWORD freq;
    float volume;
    float pan;
    DWORD flags;
    DWORD length;
    DWORD max;
    DWORD origres;
    DWORD chans;
    DWORD mingap;
    DWORD mode3d;
    float mindist;
    float maxdist;
    DWORD iangle;
    DWORD oangle;
    float outvol;
    DWORD vam;
    DWORD priority;
} BASS_SAMPLE;

Members

freq | Default sample rate.
volume | Default volume... 0 (silent) to 1 (full).
pan | Default panning position... -1 (full left) to +1 (full right), 0 = centre.
flagsA combination of these flags.
BASS_SAMPLE_8BITS | 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are present, then the sample is 16-bit.
BASS_SAMPLE_FLOAT | 32-bit floating-point.
BASS_SAMPLE_LOOP | Looped?
BASS_SAMPLE_3D | The sample has 3D functionality enabled.
BASS_SAMPLE_MUTEMAX | Mute the sample when it is at (or beyond) its max distance (3D samples only).
BASS_SAMPLE_SOFTWARE | The sample is not using hardware mixing.
BASS_SAMPLE_VAM | DX7 voice allocation and management features are enabled (see below).
BASS_SAMPLE_OVER_VOL | Override: the channel with the lowest volume is overridden.
BASS_SAMPLE_OVER_POS | Override: the longest playing channel is overridden.
BASS_SAMPLE_OVER_DIST | Override: the channel furthest away (from the listener) is overridden (3D samples only).
length | The length in bytes.
max | Maximum number of simultaneous playbacks.
origres | The original resolution (bits per sample)... 0 = undefined. If the original sample format is floating-point, then the BASS_ORIGRES_FLOAT flag will be set and the number of bits will be in the LOWORD.
chans | Number of channels... 1 = mono, 2 = stereo, etc.
mingap | Minimum time gap in milliseconds between creating channels using BASS_SampleGetChannel. This can be used to prevent flanging effects caused by playing a sample multiple times very close to each other. The default setting, after loading/creating a sample, is 0 (disabled).
The following are the sample's default 3D attributes (if the sample is 3D).
mode3dThe 3D processing mode... one of these flags.
BASS_3DMODE_NORMAL | Normal 3D processing.
BASS_3DMODE_RELATIVE | The sample's 3D position (position/velocity/orientation) is relative to the listener. When the listener's position/velocity/orientation is changed with BASS_Set3DPosition, the sample's position relative to the listener does not change.
BASS_3DMODE_OFF | Turn off 3D processing on the sample, the sound will be played in the centre.
mindist | The minimum distance. The sample's volume is at maximum when the listener is within this distance.
maxdist | The maximum distance. The sample's volume stops decreasing when the listener is beyond this distance.
iangle | The angle of the inside projection cone in degrees... 0 (no cone) to 360 (sphere).
oangle | The angle of the outside projection cone in degrees... 0 (no cone) to 360 (sphere).
outvol | The delta-volume outside the outer projection cone... 0 (silent) to 1 (full).
The following are the sample's DX7 voice allocation/management settings (if VAM is enabled).
vamvoice allocation/management flags... a combination of these
BASS_VAM_HARDWARE | Play the sample in hardware. If no hardware voices are available then the play call will fail.
BASS_VAM_SOFTWARE | Play the sample in software (ie. non-accelerated). No other VAM flags may be used together with this flag.
The following flags enable hardware resource stealing... if the hardware has no available voices, a currently playing buffer will be stopped to make room for the new buffer. Only samples with VAM enabled are considered for termination.
BASS_VAM_TERM_TIME | If there are no free hardware voices, the buffer to be terminated will be the one with the least time left to play.
BASS_VAM_TERM_DIST | If there are no free hardware voices, the buffer to be terminated will be one that was loaded/created with the BASS_SAMPLE_MUTEMAX flag and is beyond its max distance (maxdist). If there are no buffers that match this criteria, then the play call will fail.
BASS_VAM_TERM_PRIO | If there are no free hardware voices, the buffer to be terminated will be the one with the lowest priority. This flag may be used with the TERM_TIME or TERM_DIST flag, if multiple voices have the same priority then the time or distance is used to decide which to terminate.
priority | Priority, used with the BASS_VAM_TERM_PRIO flag... 0 (min) to 0xFFFFFFFF (max).

Remarks

When a sample has 3D functionality, the iangle and oangle angles decide how wide the sound is projected around the orientation angle (as set via BASS_ChannelSet3DPosition). Within the inside angle the volume level is the level set in the volume member (or the BASS_ATTRIB_VOL attribute when the sample is playing). Outside the outer angle, the volume changes according to the outvol value. Between the inner and outer angles, the volume gradually changes between the inner and outer volume levels. If the inner and outer angles are 360 degrees, then the sound is transmitted equally in all directions.

When VAM is enabled, and neither the BASS_VAM_HARDWARE or BASS_VAM_SOFTWARE flags are specified, then the sample will be played in hardware if resources are available, and in software if no hardware resources are available.

See also

BASS_SampleCreate, BASS_SampleGetInfo, BASS_SampleLoad, BASS_SampleSetInfo


BASS_StreamCreate

Creates a user sample stream.

HSTREAM BASS_StreamCreate(
    DWORD freq,
    DWORD chans,
    DWORD flags,
    STREAMPROC *proc,
    void *user
);

Parameters

freq | The default sample rate. The sample rate can be changed using BASS_ChannelSetAttribute.
chans | The number of channels... 1 = mono, 2 = stereo, 4 = quadraphonic, 6 = 5.1, 8 = 7.1.
flagsA combination of these flags.
BASS_SAMPLE_8BITS | Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the stream is 16-bit.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_SOFTWARE | Force the stream to not use hardware DirectSound mixing.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono (chans=1). The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_FX | Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_DECODE | Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
procThe user defined stream writing function, or one of the following.
STREAMPROC_DEVICE | Create a "dummy" stream for the device's final output mix. This allows DSP/FX to be applied to all channels that are playing on the device, rather than individual channels. DSP/FX parameter change latency is also reduced because channel playback buffering is avoided. The stream is created with the device's current output sample format; the freq, chans, and flags parameters are ignored. It will always be floating-point except on platforms/architectures that do not support floating-point (see BASS_CONFIG_FLOAT), where it will be 16-bit instead.
STREAMPROC_DUMMY | Create a "dummy" stream. A dummy stream does not have any sample data of its own, but a decoding dummy stream (with BASS_STREAM_DECODE flag) can be used to apply DSP/FX processing to any sample data, by setting DSP/FX on the stream and feeding the data through BASS_ChannelGetData. The dummy stream should have the same sample format as the data being fed through it.
STREAMPROC_PUSH | Create a "push" stream. Instead of BASS pulling data from a STREAMPROC function, data is pushed to BASS via BASS_StreamPutData.
user | User instance data to pass to the callback function. Unused when creating a dummy or push stream.

Return value

If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Sample streams allow any sample data to be played through BASS, and are particularly useful for playing a large amount of sample data without requiring a large amount of memory. If you wish to play a sample format that BASS does not support, then you can create a stream and decode the sample data into it.

Each device has a single final output mix stream, which can be used to apply DSP/FX to the device output. Multiple requests for a final output mix stream (using STREAMPROC_DEVICE) on the same device will receive the same stream handle, which cannot be freed via BASS_StreamFree. It will automatically be freed if the device's output format (sample rate or channel count) changes. A BASS_SYNC_FREE sync can be set via BASS_ChannelSetSync to be notified when this happens, at which point a new stream with the device's new format could be created.

BASS can automatically stream MP3, MP2, MP1, OGG, WAV and AIFF files, using BASS_StreamCreateFile, and also from HTTP and FTP servers, using BASS_StreamCreateURL. BASS_StreamCreateFileUser allows streaming from other sources too.

Platform-specific

The STREAMPROC_DEVICE option is not available when using DirectSound output on Windows because BASS does not produce the final output mix then.

See also

BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamCreateURL, BASS_StreamFree, BASS_StreamPutData, STREAMPROC callback, BASS_CONFIG_BUFFER


BASS_StreamCreateFile

Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file.

HSTREAM BASS_StreamCreateFile(
    BOOL mem,
    void *file,
    QWORD offset,
    QWORD length,
    DWORD flags
);

Parameters

mem | TRUE = stream the file from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to begin streaming from (only used if mem = FALSE).
length | Data length... 0 = use all data up to the end of the file (if mem = FALSE).
flagsA combination of these flags.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONO | Decode/play the file (OGG/MP3/MP2/MP1 only) in mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_SOFTWARE | Force the stream to not use hardware DirectSound mixing.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_LOOP | Loop the file. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_SAMPLE_FX | Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
BASS_STREAM_PRESCAN | Pre-scan the file for accurate seek points and length reading in MP3/MP2/MP1 files and chained OGG files (has no effect on normal OGG files). This can significantly increase the time taken to create the stream, particularly with a large file and/or slow storage media. BASS_ChannelSetPosition can be used to scan the file after stream creation instead.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_DECODE | Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
BASS_ASYNCFILE | Read the file asynchronously. When enabled, the file is read and buffered in parallel with the decoding, to reduce the chances of the decoder being affected by I/O delays. This can be particularly useful with slow storage media and/or low latency output. The size of the file buffer is determined by the BASS_CONFIG_ASYNCFILE_BUFFER config option. This flag is ignored when streaming from memory (mem = TRUE).
BASS_UNICODE | file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.

Return value

If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_ILLPARAM | The length must be specified when streaming from memory.
BASS_ERROR_FILEOPEN | The file could not be opened.
BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
BASS_ERROR_NOTAUDIO | The file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODEC | The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

BASS has built-in support for MPEG, OGG, WAV and AIFF files. Support for additional formats is available through BASS_PluginLoad.

MPEG 1.0, 2.0 and 2.5 layer 3 (MP3) files are supported, layers 1 (MP1) and 2 (MP2) are also supported. Standard RIFF and RF64 WAV files are supported. All PCM formats from 8 to 32-bit are supported in WAV and AIFF files, but the output will be restricted to 16-bit unless the BASS_SAMPLE_FLOAT flag is used. 64-bit floating-point WAV and AIFF files are also supported, but they are rendered in 16-bit or 32-bit floating-point depending on the flags. The file's original resolution is available from BASS_ChannelGetInfo.

Chained OGG files containing multiple logical bitstreams are supported, but seeking within them is only fully supported if the BASS_STREAM_PRESCAN flag is used (or the BASS_CONFIG_OGG_PRESCAN option is enabled) to have them pre-scanned. Without pre-scanning, seeking will only be possible back to the start. The BASS_POS_OGG "mode" can be used with BASS_ChannelGetLength to get the number of bitstreams and with BASS_ChannelSetPosition to seek to a particular one. A BASS_SYNC_OGG_CHANGE sync can be set via BASS_ChannelSetSync to be informed of when a new bitstream begins during decoding/playback.

Multi-channel (ie. more than stereo) OGG, WAV and AIFF files are supported.

Use BASS_ChannelGetInfo to retrieve information on the file format and sample format of the stream. The playback length of the stream can be retrieved using BASS_ChannelGetLength.

If length = 0 (use all data up to the end of the file), and the file length increases after creating the stream (ie. the file is still being written), then BASS will play the extra data too, but the length returned by BASS_ChannelGetLength will not be updated until the end is reached. The BASS_StreamGetFilePosition return values will be updated during playback of the extra data though.

When streaming from memory (mem = TRUE), the memory must not be freed before the stream is freed. There may be exceptions to that with some add-ons (see the documentation).

When a plugin is used by a stream, there may be additional flags that are supported by it. Any such flags can be set after stream creation via BASS_ChannelFlags. BASS_ChannelGetInfo can be used to check which, if any, plugin is being used.

To stream a file from the internet, use BASS_StreamCreateURL. To stream from other locations, see BASS_StreamCreateFileUser.

Platform-specific

On Windows and Windows CE, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC and WMA. The BASS_CONFIG_MF_DISABLE config option can used to check whether Media Foundation is available. On iOS and OSX, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported, including support for AAC. In all cases, the OS's codecs are only tried after BASS's built-in decoders and any plugins have rejected the file. Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android/Windows CE, while they are supported via ACM and CoreAudio codecs on Windows and OSX/iOS.

On Android, file may be a String, ByteBuffer, ParcelFileDescriptor, or asset (via the Asset class) when using Java. See the BASS.JAVA file for available overloads.

Example

Create a stream from an MP3 file.
HSTREAM stream = BASS_StreamCreateFile(FALSE, "afile.mp3", 0, 0, 0);

See also

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamCreate, BASS_StreamCreateFileUser, BASS_StreamCreateURL, BASS_StreamFree, BASS_StreamGetFilePosition, BASS_CONFIG_VERIFY


BASS_StreamCreateFileUser

Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file via user callback functions.

HSTREAM BASS_StreamCreateFileUser(
    DWORD system,
    DWORD flags,
    BASS_FILEPROCS *procs,
    void *user
);

Parameters

systemFile system to use, one of the following.
STREAMFILE_NOBUFFER | Unbuffered.
STREAMFILE_BUFFER | Buffered.
STREAMFILE_BUFFERPUSH | Buffered, with the data pushed to BASS via BASS_StreamPutFileData.
flagsA combination of these flags.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONO | Decode/play the file (OGG/MP3/MP2/MP1 only) in mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_SOFTWARE | Force the stream to not use hardware DirectSound mixing.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_LOOP | Loop the file. This flag can be toggled at any time using BASS_ChannelFlags. This flag is ignored when streaming in blocks (BASS_STREAM_BLOCK).
BASS_SAMPLE_FX | Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
BASS_STREAM_PRESCAN | Pre-scan the file for accurate seek points and length reading in MP3/MP2/MP1 files and chained OGG files (has no effect on normal OGG files). This can significantly increase the time taken to create the stream, particularly with a large file and/or slow storage media. This flag only applies when using the STREAMFILE_NOBUFFER system.
BASS_STREAM_RESTRATE | Restrict the "download" rate of the file to the rate required to sustain playback. If this flag is not used, then the file will be downloaded as quickly as possible. This flag only has effect when using the STREAMFILE_BUFFER system.
BASS_STREAM_BLOCK | Download and play the file in smaller chunks. Uses a lot less memory than otherwise, but it is not possible to seek or loop the stream; once it has ended, the file must be opened again to play it again. This flag will automatically be applied when the file length is unknown. This flag also has the effect of restricting the download rate. This flag has no effect when using the STREAMFILE_NOBUFFER system.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_DECODE | Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
BASS_ASYNCFILE | Read the file asynchronously. When enabled, the file is read and buffered in parallel with the decoding, to reduce the chances of the decoder being affected by I/O delays. This can be particularly useful with slow storage media and/or low latency output. The size of the file buffer is determined by the BASS_CONFIG_ASYNCFILE_BUFFER config option. This flag only applies when using the STREAMFILE_NOBUFFER system.
procs | The user defined file functions.
user | User instance data to pass to the callback functions.

Return value

If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_ILLPARAM | system is not valid.
BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
BASS_ERROR_UNSTREAMABLE | The file cannot be streamed using the buffered file system. This could be because an MP4 file's "mdat" atom comes before its "moov" atom.
BASS_ERROR_NOTAUDIO | The file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODEC | The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The buffered file system (STREAMFILE_BUFFER) is what is used by BASS_StreamCreateURL. As the name suggests, data from the file is buffered so that it is readily available for decoding; BASS creates a thread dedicated to "downloading" the data. This is ideal for when the data is coming from a source that has high latency, like the internet. It is not possible to seek in buffered file streams, until the download has reached the requested position; it is not possible to seek at all if it is being streamed in blocks. When streaming in blocks, it may be possible to reset the stream via BASS_ChannelSetPosition with the BASS_POS_RESET flag, so that it is ready to process new data.

The push buffered file system (STREAMFILE_BUFFERPUSH) is the same, except that instead of the file data being pulled from the FILEREADPROC function in a "download" thread, the data is pushed to the stream via BASS_StreamPutFileData. A FILEREADPROC function is still required, to get the initial data used in the creation of the stream.

The unbuffered file system (STREAMFILE_NOBUFFER) is what is used by BASS_StreamCreateFile. In this system, BASS does not do any intermediate buffering; it simply requests data from the file as and when it needs it. This means that reading (FILEREADPROC) must be quick, otherwise the decoding will be delayed and playback buffer underruns (old data repeated) are a possibility. It is not so important for seeking (FILESEEKPROC) to be fast, as that is generally not required during decoding, except when looping a file.

In all cases, BASS will automatically stall playback of the stream when insufficient data is available, and resume it when enough data does become available.

A copy is made of the procs callback function table, so it does not need to persist beyond this function call.

Platform-specific

On Windows and Windows CE, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC and WMA. On iOS and OSX, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported but only for AAC/ADTS. In all cases, the OS's codecs are only tried after BASS's built-in decoders and any plugins have rejected the file. Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android/Windows CE, while they are supported via ACM and CoreAudio codecs on Windows and OSX/iOS.

See also

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamCreateFile, BASS_StreamCreateURL, BASS_StreamFree, BASS_StreamGetFilePosition, BASS_StreamPutFileData, BASS_FILEPROCS structure, BASS_CONFIG_NET_BUFFER


BASS_StreamCreateURL

Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file on the internet, optionally receiving the downloaded data in a callback function.

HSTREAM BASS_StreamCreateURL(
    char *url,
    DWORD offset,
    DWORD flags,
    DOWNLOADPROC *proc,
    void *user
);

Parameters

url | URL of the file to stream. Should begin with "http://" or "https://" or "ftp://", or another add-on supported protocol. The URL can be followed by custom HTTP request headers to be sent to the server; the URL and each header should be terminated with a carriage return and line feed ("\r\n").
offset | File position to start streaming from. This is ignored by some servers, specifically when the length is unknown/undefined.
flagsA combination of these flags.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONO | Decode/play the file (OGG/MP3/MP2/MP1 only) in mono. This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_SOFTWARE | Force the stream to not use hardware DirectSound mixing.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init, and the stream must be mono. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_LOOP | Loop the file. This flag can be toggled at any time using BASS_ChannelFlags. This flag is ignored when streaming in blocks (BASS_STREAM_BLOCK).
BASS_SAMPLE_FX | Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the stream.
BASS_STREAM_RESTRATE | Restrict the download rate of the file to the rate required to sustain playback. If this flag is not used, then the file will be downloaded as quickly as the user's internet connection allows.
BASS_STREAM_BLOCK | Download and play the file in smaller chunks, instead of downloading the entire file to memory. Uses a lot less memory than otherwise, but it is not possible to seek or loop the stream; once it has ended, the file must be opened again to play it again. This flag will automatically be applied when the file length is unknown, for example with Shout/Icecast streams. This flag also has the effect of restricting the download rate.
BASS_STREAM_STATUS | Pass status info (HTTP/ICY tags) from the server to the DOWNLOADPROC callback during connection. This can be useful to determine the reason for a failure.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_DECODE | Decode the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxx | Speaker assignment flags. These flags have no effect when the stream is more than stereo.
BASS_UNICODE | url is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.
proc | Callback function to receive the file as it is downloaded... NULL = no callback.
user | User instance data to pass to the callback function.

Return value

If successful, the new stream's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | The BASS_STREAM_AUTOFREE flag cannot be combined with the BASS_STREAM_DECODE flag.
BASS_ERROR_NONET | No internet connection could be opened. Can be caused by a bad proxy setting.
BASS_ERROR_ILLPARAM | url is not a valid URL.
BASS_ERROR_SSL | SSL/HTTPS support is not available. See BASS_CONFIG_LIBSSL.
BASS_ERROR_TIMEOUT | The server did not respond to the request within the timeout period, as set with the BASS_CONFIG_NET_TIMEOUT config option.
BASS_ERROR_FILEOPEN | The file could not be opened.
BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
BASS_ERROR_UNSTREAMABLE | The file cannot be streamed. This could be because an MP4 file's "mdat" atom comes before its "moov" atom.
BASS_ERROR_NOTAUDIO | The file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODEC | The file uses a codec that is not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Use BASS_ChannelGetInfo to retrieve information on the file format and sample format of the stream. The playback length of the stream can be retrieved using BASS_ChannelGetLength.

When playing the stream, BASS will stall the playback if there is insufficient data to continue playing. Playback will automatically be resumed when sufficient data has been downloaded. BASS_ChannelIsActive can be used to check if the playback is stalled, and the progress of the file download can be checked with BASS_StreamGetFilePosition.

When streaming in blocks (BASS_STREAM_BLOCK flag), be careful not to stop/pause the stream for too long, otherwise the connection may timeout due to there being no activity and the stream will end prematurely.

When streaming from Shoutcast servers, metadata (track titles) may be sent by the server. The data can be retrieved with BASS_ChannelGetTags. A BASS_SYNC_META sync can also be set via BASS_ChannelSetSync to be informed when metadata is received. A BASS_SYNC_OGG_CHANGE sync can be used to be informed of when a new logical bitstream begins in an Icecast/OGG stream.

When using an offset, the file length returned by BASS_StreamGetFilePosition can be used to check that it was successful by comparing it with the original file length. Another way to check is to inspect the HTTP headers retrieved with BASS_ChannelGetTags.

When a plugin is used by a stream, there may be additional flags that are supported by it. Any such flags can be set after stream creation via BASS_ChannelFlags. BASS_ChannelGetInfo can be used to check which, if any, plugin is being used.

Custom HTTP request headers may be ignored by some plugins, notably BASSWMA.

Platform-specific

On Windows and Windows CE, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC and WMA. On iOS and OSX, CoreAudio codecs are supported, including support for AAC and ALAC. Android's media codecs are also supported, including support for AAC. In all cases, the OS's codecs are only tried after BASS's built-in decoders and any plugins have rejected the file. Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android/Windows CE, while they are supported via ACM and CoreAudio codecs on Windows and OSX/iOS.

On iOS 7 and above, this function can be used to open files in the iPod Library ("ipod-library://" URLs). The offset and proc and user parameters are ignored then, as are the BASS_STREAM_RESTRATE and BASS_STREAM_BLOCK and BASS_STREAM_STATUS flags. The files are played using CoreAudio codecs and BASS does not have direct access to the files itself, so the only tags available from BASS_ChannelGetTags will be BASS_TAG_CA_CODEC tags; the MPMediaItem properties could be used to get more info.

Example

Stream an MP3 file.
HSTREAM stream = BASS_StreamCreateURL("http://www.asite.com/afile.mp3", 0, 0, NULL, 0);

Stream an MP3 file with a cookie sent to the server.

HSTREAM stream = BASS_StreamCreateURL("http://www.asite.com/afile.mp3\r\nCookie: mycookie=blah\r\n", 0, 0, NULL, 0);

See also

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_StreamCreateFile, BASS_StreamCreateFileUser, BASS_StreamFree, BASS_StreamGetFilePosition, DOWNLOADPROC callback, BASS_ATTRIB_NET_RESUME, BASS_CONFIG_NET_AGENT, BASS_CONFIG_NET_BUFFER, BASS_CONFIG_NET_PASSIVE, BASS_CONFIG_NET_PREBUF, BASS_CONFIG_NET_PROXY, BASS_CONFIG_NET_READTIMEOUT, BASS_CONFIG_NET_TIMEOUT, BASS_CONFIG_VERIFY_NET


BASS_StreamFree

Frees a sample stream's resources, including any sync/DSP/FX it has.

BOOL BASS_StreamFree(
    HSTREAM handle
);

Parameters

handle The stream handle.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.


BASS_StreamGetFilePosition

Retrieves the file position/status of a stream.

QWORD BASS_StreamGetFilePosition(
    HSTREAM handle,
    DWORD mode
);

Parameters

handle The stream handle.
modeThe file position/status to retrieve. One of the following.
BASS_FILEPOS_ASYNCBUF | The amount of data in the asynchronous file reading buffer. This requires that the BASS_ASYNCFILE flag was used at the stream's creation.
BASS_FILEPOS_BUFFER | The amount of data in the buffer of an internet file stream or "buffered" user file stream. Unless streaming in blocks, this is the same as BASS_FILEPOS_DOWNLOAD.
BASS_FILEPOS_BUFFERING | The percentage of buffering remaining before playback of an internet file stream or "buffered" user file stream can resume.
BASS_FILEPOS_CONNECTED | Internet file stream or "buffered" user file stream is still connected? 0 = no, 1 = yes.
BASS_FILEPOS_CURRENT | Position that is to be decoded for playback next. This will be a bit ahead of the position actually being heard due to buffering.
BASS_FILEPOS_DOWNLOAD | Download progress of an internet file stream or "buffered" user file stream.
BASS_FILEPOS_END | End of audio data. When streaming in blocks (the BASS_STREAM_BLOCK flag is in effect), the download buffer length is given.
BASS_FILEPOS_SIZE | Total size of the file.
BASS_FILEPOS_START | Start of audio data.
other modes may be supported by add-ons, see the documentation.

Return value

If successful, then the requested file position/status is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTFILE | The stream is not a file stream.
BASS_ERROR_NOTAVAIL | The requested file position/status is not available.

Remarks

ID3 tags (both v1 and v2) and WAVE headers, as well as any other rubbish at the start of the file, are excluded from the BASS_FILEPOS_CURRENT, BASS_FILEPOS_DOWNLOAD, and BASS_FILEPOS_END positions. The BASS_FILEPOS_START position can be added to get the actual file position.

When streaming a file from the internet or a "buffered" user file stream, the entire file is downloaded even if the audio data ends before that, in case there are tags to be read. This means that the BASS_FILEPOS_DOWNLOAD position may go beyond the BASS_FILEPOS_END position.

It is unwise to use the BASS_FILEPOS_CURRENT position for syncing purposes because it gives the position that is being decoded, not the position that is being heard. Use BASS_ChannelGetPosition and/or BASS_ChannelSetSync instead.

Platform-specific

When an Android media codec (except AAC/ADTS) is used by a stream, only the BASS_FILEPOS_SIZE mode is supported, as the file reading will not be handled by BASS.

Example

Get the percentage downloaded of an internet file stream, or the buffer level when streaming in blocks.
QWORD len = BASS_StreamGetFilePosition(stream, BASS_FILEPOS_END); // file/buffer length
QWORD buf = BASS_StreamGetFilePosition(stream, BASS_FILEPOS_BUFFER); // buffer level
float progress = 100.0 * buf / len; // percentage of buffer filled

Get the buffering progress of a stalled internet file stream.

int progress = 100 - BASS_StreamGetFilePosition(stream, BASS_FILEPOS_BUFFERING);

See also

BASS_ChannelGetPosition, BASS_ChannelGetLength


BASS_StreamPutData

Adds sample data to a "push" stream.

DWORD BASS_StreamPutData(
    HSTREAM handle,
    void *buffer,
    DWORD length
);

Parameters

handle | The stream handle.
buffer | Pointer to the sample data... NULL = allocate space in the queue buffer so that there is at least length bytes of free space.
length | The amount of data in bytes, optionally using the BASS_STREAMPROC_END flag to signify the end of the stream. 0 can be used to just check how much data is queued.

Return value

If successful, the amount of queued data is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTAVAIL | The stream is not using the push system.
BASS_ERROR_ILLPARAM | length is not valid, it must equate to a whole number of samples.
BASS_ERROR_ENDED | The stream has ended.
BASS_ERROR_MEM | There is insufficient memory.

Remarks

As much data as possible will be placed in the stream's playback buffer, and any remainder will be queued for when more space becomes available, ie. as the buffered data is played. With a decoding channel, there is no playback buffer, so all data is queued in that case. There is no limit to the amount of data that can be queued (besides available memory); the queue buffer will be automatically enlarged as required to hold the data, but it can also be enlarged in advance. The queue buffer is freed when the stream ends or is reset, eg. via BASS_ChannelPlay (with restart = TRUE) or BASS_ChannelSetPosition (with pos = 0).

DSP/FX are applied when the data reaches the playback buffer, or the BASS_ChannelGetData call in the case of a decoding channel.

Data should be provided at a rate sufficent to sustain playback. If the buffer gets exhausted, BASS will automatically stall playback of the stream, until more data is provided. BASS_ChannelGetData (BASS_DATA_AVAILABLE) can be used to check the buffer level, and BASS_ChannelIsActive can be used to check if playback has stalled. A BASS_SYNC_STALL sync can also be set via BASS_ChannelSetSync, to be triggered upon playback stalling or resuming.

See also

BASS_StreamCreate


BASS_StreamPutFileData

Adds data to a "push buffered" user file stream's buffer.

DWORD BASS_StreamPutFileData(
    HSTREAM handle,
    void *buffer,
    DWORD length
);

Parameters

handle | The stream handle.
buffer | Pointer to the file data.
length | The amount of data in bytes, or BASS_FILEDATA_END to end the file.

Return value

If successful, the number of bytes read from buffer is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTAVAIL | The stream is not using the STREAMFILE_BUFFERPUSH file system.
BASS_ERROR_ENDED | The file has ended.

Remarks

If there is not enough space in the stream's file buffer to receive all of the data, then only the amount that will fit is read from buffer. BASS_StreamGetFilePosition can be used to check the amount of space in the buffer.

File data should be provided at a rate sufficent to sustain playback. If there is insufficient file data, and the playback buffer is subsequently exhausted, BASS will automatically stall playback of the stream, until more data is available. A BASS_SYNC_STALL sync can be set via BASS_ChannelSetSync, to be triggered upon playback stalling or resuming.

See also

BASS_StreamCreateFileUser, BASS_StreamGetFilePosition


DOWNLOADPROC callback

Internet stream download callback function.

void CALLBACK DownloadProc(
    const void *buffer,
    DWORD length,
    void *user
);

Parameters

buffer | Pointer to the downloaded data... NULL = finished downloading.
length | The number of bytes in the buffer... 0 = HTTP or ICY tags.
user | The user instance data given when BASS_StreamCreateURL was called.

Remarks

The callback will be called before the BASS_StreamCreateURL call returns (if it is successful), with the initial downloaded data. So any initialization (eg. creating the file if writing to disk) needs to be done either before the call, or in the callback function.

When the BASS_STREAM_STATUS flag is specified in the BASS_StreamCreateURL call, HTTP and ICY tags may be passed to the callback during connection, before any stream data is received. The tags are given exactly as would be returned by BASS_ChannelGetTags. You can distinguish between HTTP and ICY tags by checking what the first string starts with: "HTTP" or "ICY".

A download callback function could be used in conjunction with a BASS_SYNC_META sync set via BASS_ChannelSetSync to save individual tracks to disk from a Shoutcast stream.

Example

Stream an MP3 file, and save a local copy.
FILE *file = NULL;
...
void CALLBACK MyDownloadProc(const void *buffer, DWORD length, void *user)
{
    if (!file) file = fopen("afile.mp3", "wb"); // create the file
    if (!buffer) fclose(file); // finished downloading
    else fwrite(buffer, 1, length, file);
}
...
HSTREAM stream = BASS_StreamCreateURL("http://www.asite.com/afile.mp3", 0, 0, MyDownloadProc, 0);

See also

BASS_StreamCreateURL


FILECLOSEPROC callback

User file stream close callback function.

void CALLBACK FileCloseProc(
    void *user
);

Parameters

user The user instance data given when BASS_StreamCreateFileUser was called.

Remarks

With a buffered file stream, this function is called as soon as reading reaches the end of the file. If the stream is freed before then, this function could be called while its FILEREADPROC function is in progress. If that happens, the FILEREADPROC function call should be immediately cancelled.

See also

BASS_StreamCreateFileUser, BASS_FILEPROCS structure


FILELENPROC callback

User file stream length callback function.

QWORD CALLBACK FileLenProc(
    void *user
);

Parameters

user The user instance data given when BASS_StreamCreateFileUser was called.

Return value

The length of the file in bytes. Returning 0 for a buffered file stream makes BASS stream the file in blocks and is equivalent to using the BASS_STREAM_BLOCK flag in the BASS_StreamCreateFileUser call.

Remarks

This function is called first thing, and only the once with buffered streams. With unbuffered streams, it may be called again when testing for EOF (end of file), allowing the file to grow in size.

See also

BASS_StreamCreateFileUser, BASS_FILEPROCS structure


FILEREADPROC callback

User file stream read callback function.

DWORD CALLBACK FileReadProc(
    void *buffer,
    DWORD length,
    void *user
);

Parameters

buffer | Pointer to the buffer to put the data in.
length | Maximum number of bytes to read.
user | The user instance data given when BASS_StreamCreateFileUser was called.

Return value

The number of bytes read... -1 = end of file, 0 = end of file (STREAMFILE_BUFFER file system only).

Remarks

During creation of the stream, this function should try to return the amount of data requested. After that, it can just return whatever is available up to the requested amount.

For an unbuffered file stream, this function should be as quick as possible during playback; any delays will not only affect the decoding of the current stream, but can also affect other streams and MOD musics that are playing. It is better to return less data (even none) rather than wait for more data. A buffered file stream is not affected by delays like this, as this function runs in its own thread then.

See also

BASS_StreamCreateFileUser, BASS_FILEPROCS structure


FILESEEKPROC callback

User file stream seek callback function.

BOOL CALLBACK FileSeekProc(
    QWORD offset,
    void *user
);

Parameters

offset | Position in bytes to seek to.
user | The user instance data given when BASS_StreamCreateFileUser was called.

Return value

TRUE if successful, else FALSE.

See also

BASS_StreamCreateFileUser, BASS_FILEPROCS structure


STREAMPROC callback

User stream writing callback function.

DWORD CALLBACK StreamProc(
    HSTREAM handle,
    void *buffer,
    DWORD length,
    void *user
);

Parameters

handle | The stream that needs writing.
buffer | Pointer to the buffer to write the sample data in. The data should be as follows: 8-bit samples are unsigned, 16-bit samples are signed, 32-bit floating-point samples range from -1 to +1.
length | The maximum number of bytes to write.
user | The user instance data given when BASS_StreamCreate was called.

Return value

The number of bytes written by the function, optionally using the BASS_STREAMPROC_END flag to signify that the end of the stream is reached.

Remarks

A stream writing function should be as quick as possible because other playing streams (and MOD musics) cannot be updated until it has finished (unless multiple update threads are enabled via the BASS_CONFIG_UPDATETHREADS option). It is better to return less data quickly, rather than spending a long time delivering exactly the amount requested.

Although a STREAMPROC may return less data than BASS requests, be careful not to do so by too much, too often. If the buffer gets exhausted, BASS will automatically stall playback of the stream, until more data is provided. BASS_ChannelGetData (BASS_DATA_AVAILABLE) can be used to check the buffer level, and BASS_ChannelIsActive can be used to check if playback has stalled. A BASS_SYNC_STALL sync can also be set via BASS_ChannelSetSync, to be triggered upon playback stalling or resuming. If you do return less than the requested amount of data, the number of bytes should still equate to a whole number of samples.

The BASS_ATTRIB_GRANULE attribute can be used to control the granularity of the amount of data requested.

Some functions can cause problems if called from within a stream (or DSP) function. Do not call BASS_Stop or BASS_Free from within a stream callback, and do not call BASS_ChannelStop or BASS_StreamFree with the same handle as received by the callback.

When streaming multi-channel sample data, the channel order of each sample is as follows.

3 channels | left-front, right-front, center.
4 channels | left-front, right-front, left-rear/side, right-rear/side.
5 channels | left-front, right-front, center, left-rear/side, right-rear/side.
6 channels (5.1) | left-front, right-front, center, LFE, left-rear/side, right-rear/side.
8 channels (7.1) | left-front, right-front, center, LFE, left-rear/side, right-rear/side, left-rear center, right-rear center.

Example

A callback function to stream a file, in 44100 Hz stereo 16-bit.
FILE *file;
...
// the stream writing callback
DWORD CALLBACK MyStreamProc(HSTREAM handle, void *buffer, DWORD length, void *user)
{
    DWORD c = fread(buffer, 1, length, file); // read the file into the buffer
    if (feof(file)) c |= BASS_STREAMPROC_END; // end of the file/stream
    return c;
}
...
HSTREAM stream = BASS_StreamCreate(44100, 2, 0, MyStreamProc, 0); // create the stream

See also

BASS_StreamCreate, BASS_ATTRIB_GRANULE


BASS_FILEPROCS structure

Table of callback functions used with BASS_StreamCreateFileUser.

typedef struct {
    FILECLOSEPROC *close;
    FILELENPROC *length;
    FILEREADPROC *read;
    FILESEEKPROC *seek;
} BASS_FILEPROCS;

Members

close | Callback function to close the file.
length | Callback function to get the file length.
read | Callback function to read from the file.
seek | Callback function to seek in the file. Not used by buffered file streams.

Example

Stream a file from disk via an "unbuffered" user file stream.
void CALLBACK MyFileCloseProc(void *user)
{
    fclose(user); // close the file
}

QWORD CALLBACK MyFileLenProc(void *user)
{
    struct stat s;
    fstat(fileno(user), &s);
    return s.st_size; // return the file length
}

DWORD CALLBACK MyFileReadProc(void *buffer, DWORD length, void *user)
{
    return fread(buffer, 1, length, user); // read from file
}

BOOL CALLBACK MyFileSeekProc(QWORD offset, void *user)
{
    return !fseek(user, offset, SEEK_SET); // seek to offset
}

...

BASS_FILEPROCS fileprocs = { MyFileCloseProc, MyFileLenProc, MyFileReadProc, MyFileSeekProc }; // callback table
FILE *file = fopen("a_file.mp3", "rb"); // open the file
stream = BASS_StreamCreateFileUser(STREAMFILE_NOBUFFER, 0, &fileprocs, file); // create the stream

NOTE: This is just an example. It is simpler to use BASS_StreamCreateFile to stream a file from disk.

See also

BASS_StreamCreateFileUser, FILECLOSEPROC callback, FILELENPROC callback, FILEREADPROC callback, FILESEEKPROC callback


BASS_MusicFree

Frees a MOD music's resources, including any sync/DSP/FX it has.

BOOL BASS_MusicFree(
    HMUSIC handle
);

Parameters

handle The MOD music handle.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.

See also

BASS_MusicLoad


BASS_MusicLoad

Loads a MOD music file.

HMUSIC BASS_MusicLoad(
    BOOL mem,
    void *file,
    QWORD offset,
    DWORD length,
    DWORD flags,
    DWORD freq
);

Parameters

mem | TRUE = load the MOD music from memory.
file | Filename (mem = FALSE) or a memory location (mem = TRUE).
offset | File offset to load the MOD music from (only used if mem = FALSE).
length | Data length... 0 = use all data up to the end of file (if mem = FALSE).
flagsA combination of these flags.
BASS_SAMPLE_8BITS | Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flags are specified, then the sample data will be 16-bit.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_SAMPLE_MONO | Decode/play the MOD music in mono (uses less CPU than stereo). This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init.
BASS_SAMPLE_SOFTWARE | Force the MOD music to not use hardware DirectSound mixing.
BASS_SAMPLE_3D | Enable 3D functionality. This requires that the BASS_DEVICE_3D flag was specified when calling BASS_Init. 3D channels must also be mono, so BASS_SAMPLE_MONO is automatically applied. The SPEAKER flags cannot be used together with this flag.
BASS_SAMPLE_FX | Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX to add effects to the music.
BASS_SAMPLE_LOOP | Loop the music.
BASS_MUSIC_NONINTER | Use non-interpolated sample mixing. This generally reduces the sound quality, but can be good for chip-tunes.
BASS_MUSIC_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. If neither this or the BASS_MUSIC_NONINTER flag is specified, linear interpolation is used.
BASS_MUSIC_RAMP | Use "normal" ramping (as in FastTracker 2).
BASS_MUSIC_RAMPS | Use "sensitive" ramping.
BASS_MUSIC_SURROUND | Apply XMPlay's surround sound to the music. This is ignored if the BASS_SAMPLE_MONO flag is also specified.
BASS_MUSIC_SURROUND2 | Apply XMPlay's surround sound mode 2 to the music. This is ignored if the BASS_SAMPLE_MONO flag is also specified.
BASS_MUSIC_FT2PAN | Apply FastTracker 2 panning to XM files.
BASS_MUSIC_FT2MOD | Play .MOD files as FastTracker 2 would, including applying FastTracker 2 panning.
BASS_MUSIC_PT1MOD | Play .MOD files as ProTracker 1 would.
BASS_MUSIC_POSRESET | Stop all notes when seeking (BASS_ChannelSetPosition).
BASS_MUSIC_POSRESETEX | Stop all notes and reset bpm/etc when seeking.
BASS_MUSIC_STOPBACK | Stop the music when a backward jump effect is played. This stops musics that never reach the end from going into endless loops. Some MOD musics are designed to jump all over the place, so this flag would cause those to be stopped prematurely. If this flag is used together with the BASS_SAMPLE_LOOP flag, then the music would not be stopped but any BASS_SYNC_END sync would be triggered.
BASS_MUSIC_PRESCAN | Calculate the playback length of the music, and enable seeking in bytes. This slightly increases the time taken to load the music, depending on how long it is. In the case of musics that loop, the length until the loop occurs is calculated. Use BASS_ChannelGetLength to retrieve the length.
BASS_MUSIC_NOSAMPLE | Do not load the samples. This reduces the time (and memory) taken to load the music, notably with MO3 files, which is useful if you just want to get the text and/or length of the music without playing it.
BASS_MUSIC_AUTOFREE | Automatically free the music when playback ends. Note that some musics have infinite loops, so never actually end on their own.
BASS_MUSIC_DECODE | Decode/render the sample data, without playing it. Use BASS_ChannelGetData to retrieve decoded sample data. The BASS_SAMPLE_3D, BASS_STREAM_AUTOFREE and SPEAKER flags cannot be used together with this flag. The BASS_SAMPLE_SOFTWARE and BASS_SAMPLE_FX flags are also ignored.
BASS_SPEAKER_xxx | Speaker assignment flags. The BASS_SAMPLE_MONO flag is automatically applied when using a mono speaker assignment flag.
BASS_UNICODE | file is in UTF-16 form. Otherwise it is ANSI on Windows or Windows CE, and UTF-8 on other platforms.
freq | Sample rate to render/play the MOD music at... 0 = the rate specified in the BASS_Init call, 1 = the device's current output rate (or the BASS_Init rate if that is not available).

Return value

If successful, the loaded MOD music's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_Init has not been successfully called.
BASS_ERROR_NOTAVAIL | The BASS_MUSIC_AUTOFREE flag is unavailable to decoding channels.
BASS_ERROR_FILEOPEN | The file could not be opened.
BASS_ERROR_FILEFORM | The file's format is not recognised/supported.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If using the BASS_SAMPLE_FLOAT flag, it could be that floating-point channels are not supported.
BASS_ERROR_SPEAKER | The specified SPEAKER flags are invalid. The device/drivers do not support them or 3D functionality is enabled.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_NO3D | Could not initialize 3D support.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

BASS uses the same code as XMPlay for its MOD music support, giving an accurate reproduction of the MO3 / IT / XM / S3M / MTM / MOD / UMX formats.

MO3s are treated and used in exactly the same way as normal MOD musics. The advantage of MO3s is that they can be a lot smaller with virtually identical quality. Playing a MO3 does not use any more CPU power than playing the original MOD version does. The only difference is a slightly longer load time as the samples are being decoded. MO3 files are created using the MO3 encoder available at the BASS website.

DMO effects (the same as available with BASS_ChannelSetFX) can be used in IT and XM files (and MO3 versions of them) created with Modplug Tracker. This allows effects to be added to a track without having to resort to an MP3 or OGG version, so it can remain small and still sound fancy. Of course, the effects require some CPU, so should not be used carelessly if performance is key.

"Ramping" does not take a lot of extra processing and improves the sound quality by removing clicks, by ramping/smoothing volume and pan changes. The start of a sample may also be ramped-in. That is always the case with XM files (or MOD files in FT2 mode) when using normal ramping, and possibly with all formats when using sensitive ramping; senstitive ramping will only ramp-in when necessary to avoid a click. Generally, normal ramping is recommended for XM files, and sensitive ramping for the other formats, but some XM files may also sound better using sensitive ramping.

After loading a MOD music from memory (mem = TRUE), the memory can safely be discarded.

Platform-specific

DMO effects are not supported in MOD music on Windows CE, and DirectX 8 (or above) is required on Windows. They are always available on other platforms, except for the following: Compressor, Gargle, and I3DL2Reverb. When a DMO effect is unavailable, the MOD music can still be played, but the effect will be disabled.

On Android, file may be a String, ByteBuffer, ParcelFileDescriptor, or asset (via the Asset class) when using Java. See the BASS.JAVA file for available overloads.

See also

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_MusicFree, BASS_CONFIG_MUSIC_VIRTUAL


BASS_RecordFree

Frees all resources used by the recording device.

BOOL BASS_RecordFree();

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_RecordInit has not been successfully called.

Remarks

This function should be called for all initialized recording devices before your program exits.

When using multiple recording devices, the current thread's device setting (as set with BASS_RecordSetDevice) determines which device this function call applies to.

See also

BASS_RecordInit


BASS_RecordGetDevice

Retrieves the recording device setting of the current thread.

DWORD BASS_RecordGetDevice();

Return value

If successful, the device number is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_RecordInit has not been successfully called; there are no initialized devices.

See also

BASS_ChannelGetDevice, BASS_RecordInit, BASS_RecordSetDevice


BASS_RecordGetDeviceInfo

Retrieves information on a recording device.

BOOL BASS_RecordGetDeviceInfo(
    DWORD device,
    BASS_DEVICEINFO *info
);

Parameters

device | The device to get the information of... 0 = first.
info | Pointer to a structure to receive the information.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DX | A sufficient version of DirectX is not installed.
BASS_ERROR_DEVICE | device is invalid.

Remarks

This function can be used to enumerate the available devices for a setup dialog.

Platform-specific

Recording support requires DirectX 5 (or above) on Windows.

On Linux, a "Default" device is hardcoded to device number 0, which uses the default input set in the ALSA config.

Example

Get the total number of devices currently present.
int a, count = 0;
BASS_DEVICEINFO info;
for (a = 0; BASS_RecordGetDeviceInfo(a, &info); a++)
    if (info.flags & BASS_DEVICE_ENABLED) // device is enabled
        count++; // count it

Find a microphone.

int a;
BASS_DEVICEINFO info;
for (a = 0; BASS_RecordGetDeviceInfo(a, &info); a++)
    if ((info.flags & BASS_DEVICE_ENABLED) && (info.flags & BASS_DEVICE_TYPE_MASK) == BASS_DEVICE_TYPE_MICROPHONE) { // found an enabled microphone
        // do something
    }

See also

BASS_RecordGetInfo, BASS_RecordInit, BASS_DEVICEINFO structure


BASS_RecordGetInfo

Retrieves information on the recording device being used.

BOOL BASS_RecordGetInfo(
    BASS_RECORDINFO *info
);

Parameters

info Pointer to a structure to receive the information.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT BASS_RecordInit has not been successfully called.

Example

Check if the current device can have multiple inputs enabled.
BASS_RECORDINFO info;
BASS_RecordGetInfo(&info);
if (!info.singlein) {
    // device does allow multiple inputs to be enabled
}

See also

BASS_RecordGetDeviceInfo, BASS_RECORDINFO structure


BASS_RecordGetInput

Retrieves the current settings of a recording input source.

DWORD BASS_RecordGetInput(
    int input,
    float *volume
);

Parameters

input | The input to get the settings of... 0 = first, -1 = master.
volume | Pointer to a variable to receive the volume... NULL = don't retrieve the volume.

Return value

If an error occurs, -1 is returned, use BASS_ErrorGetCode to get the error code. If successful, then the settings are returned. The BASS_INPUT_OFF flag will be set if the input is disabled, otherwise the input is enabled. The type of input is also indicated in the high 8 bits (use BASS_INPUT_TYPE_MASK to test) of the return value, and can be one of the following. If the volume is requested but not available, volume will receive -1.

BASS_INPUT_TYPE_DIGITAL | Digital input source, for example, a DAT or audio CD.
BASS_INPUT_TYPE_LINE | Line-in. On some devices, "Line-in" may be combined with other analog sources into a single BASS_INPUT_TYPE_ANALOG input.
BASS_INPUT_TYPE_MIC | Microphone.
BASS_INPUT_TYPE_SYNTH | Internal MIDI synthesizer.
BASS_INPUT_TYPE_CD | Analog audio CD.
BASS_INPUT_TYPE_PHONE | Telephone.
BASS_INPUT_TYPE_SPEAKER | PC speaker.
BASS_INPUT_TYPE_WAVE | The device's WAVE/PCM output.
BASS_INPUT_TYPE_AUX | Auxiliary. Like "Line-in", "Aux" may be combined with other analog sources into a single BASS_INPUT_TYPE_ANALOG input on some devices.
BASS_INPUT_TYPE_ANALOG | Analog, typically a mix of all analog sources.
BASS_INPUT_TYPE_UNDEF | Anything that is not covered by the other types.

Error codes

BASS_ERROR_INIT | BASS_RecordInit has not been successfully called.
BASS_ERROR_ILLPARAM | input is invalid.
BASS_ERROR_NOTAVAIL | A master input is not available.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Platform-specific

The input type information is only available on Windows. There is no "what you hear" type of input defined; if the device has one, it will typically come under BASS_INPUT_TYPE_ANALOG or BASS_INPUT_TYPE_UNDEF.

On OSX, there is no master input (-1), and only the currently enabled input has its volume setting available (if it has a volume control).

Example

List all available input sources, with their current status.
int n;
char *name;
for (n = 0; name = BASS_RecordGetInputName(n); n++) {
    float vol;
    int s = BASS_RecordGetInput(n, &vol);
    printf("%s [%s : %g]\n", name, s & BASS_INPUT_OFF ? "off" : "on", vol);
}

Find a microphone input.

int mic = -1, n, flags;
for (n = 0; (flags = BASS_RecordGetInput(n, NULL)) != -1; n++) {
    if ((flags & BASS_INPUT_TYPE_MASK) == BASS_INPUT_TYPE_MIC) { // found the mic!
        mic = n;
        break;
    }
}
if (mic != -1) printf("Found a microphone at input %d\n", mic);
else printf("No microphone found\n");

See also

BASS_RecordGetInfo, BASS_RecordGetInputName, BASS_RecordSetInput


BASS_RecordGetInputName

Retrieves the text description of a recording input source.

const char *BASS_RecordGetInputName(
    int input
);

Parameters

input The input to get the description of... 0 = first, -1 = master.

Return value

If successful, then a pointer to the description is returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_RecordInit has not been successfully called.
BASS_ERROR_ILLPARAM | input is invalid.
BASS_ERROR_NOTAVAIL | A master input is not available.

Platform-specific

The returned string is in ANSI or UTF-8 form on Windows, depending on the BASS_CONFIG_UNICODE setting. It is in UTF-16 form ("WCHAR" rather than "char") on Windows CE, and in UTF-8 form on other platforms.

There is no master input (-1) on OSX.

See also

BASS_RecordGetInfo, BASS_RecordGetInput, BASS_RecordSetInput


BASS_RecordInit

Initializes a recording device.

BOOL BASS_RecordInit(
    int device
);

Parameters

device The device to use... -1 = default device, 0 = first. BASS_RecordGetDeviceInfo can be used to enumerate the available devices.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DX | A sufficient version of DirectX (or ALSA) is not installed.
BASS_ERROR_DEVICE | device is invalid.
BASS_ERROR_ALREADY | The device has already been initialized. BASS_RecordFree must be called before it can be initialized again.
BASS_ERROR_DRIVER | There is no available device driver.

Remarks

This function must be successfully called before using the recording features.

Simultaneously using multiple devices is supported in the BASS API via a context switching system; instead of there being an extra "device" parameter in the function calls, the device to be used is set prior to calling the functions. BASS_RecordSetDevice is used to switch the current recording device. When successful, BASS_RecordInit automatically sets the current thread's device to the one that was just initialized.

When using the default device (device = -1), BASS_RecordGetDevice can be used to find out which device it was mapped to.

Platform-specific

Recording support requires DirectX 5 (or above) on Windows.

On Linux, a "Default" device is hardcoded to device number 0, which uses the default input set in the ALSA config; that could map directly to one of the other devices or it could use ALSA plugins.

See also

BASS_RecordFree, BASS_RecordGetDeviceInfo, BASS_RecordGetInfo, BASS_RecordGetInput, BASS_RecordSetDevice, BASS_RecordSetInput, BASS_RecordStart


BASS_RecordSetDevice

Sets the recording device to use for subsequent calls in the current thread.

BOOL BASS_RecordSetDevice(
    DWORD device
);

Parameters

device The device to use... 0 = first.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_DEVICE | device is invalid.
BASS_ERROR_INIT | The device has not been initialized.

Remarks

Simultaneously using multiple devices is supported in the BASS API via a context switching system; instead of there being an extra "device" parameter in the function calls, the device to be used is set prior to calling the functions. The device setting is local to the current thread, so calling functions with different devices simultaneously in multiple threads is not a problem.

The functions that use the recording device selection are the following: BASS_RecordFree, BASS_RecordGetInfo, BASS_RecordGetInput, BASS_RecordGetInputName, BASS_RecordSetInput, BASS_RecordStart.

When one of the above functions (or BASS_RecordGetDevice) is called, BASS will check the current thread's recording device setting, and if no device is selected (or the selected device is not initialized), BASS will automatically select the lowest device that is initialized. This means that when using a single device, there is no need to use this function; BASS will automatically use the device that's initialized. Even if you free the device, and initialize another, BASS will automatically switch to the one that is initialized.

Example

Start recording on device 2.
BASS_RecordSetDevice(2); // select device 2
record = BASS_RecordStart(44100, 2, 0, MyRecordProc, 0); // start recording

See also

BASS_ChannelGetDevice, BASS_RecordGetDevice, BASS_RecordInit


BASS_RecordSetInput

Adjusts the settings of a recording input source.

BOOL BASS_RecordSetInput(
    int input,
    DWORD flags,
    float volume
);

Parameters

input | The input to adjust the settings of... 0 = first, -1 = master.
flagsThe new setting... a combination of these flags.
BASS_INPUT_OFF | Disable the input. This flag cannot be used when the device supports only one input at a time.
BASS_INPUT_ON | Enable the input. If the device only allows one input at a time, then any previously enabled input will be disabled by this.
volume | The volume level... 0 (silent) to 1 (max), less than 0 = leave current.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_RecordInit has not been successfully called.
BASS_ERROR_ILLPARAM | input or volume is invalid.
BASS_ERROR_NOTAVAIL | The input does not have the necessary controls to apply the flags and/or volume. If attempting to set both at the same time, try separating them to determine which is unavailable.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

The actual volume level may not be exactly the same as requested, due to underlying precision differences. BASS_RecordGetInput can be used to confirm what the volume is.

The volume curve used by this function is always linear; the BASS_CONFIG_CURVE_VOL config option setting has no effect on this.

Changes made by this function are system-wide, ie. other software using the device will be affected by it.

Platform-specific

On OSX, there is no master input (-1), and only the currently enabled input may have its volume set (if it has a volume control).

Example

Enable the first input, and set its volume level to 50%.
BASS_RecordSetInput(0, BASS_INPUT_ON, 0.5);

See also

BASS_RecordGetInfo, BASS_RecordGetInput


BASS_RecordStart

Starts recording.

HRECORD BASS_RecordStart(
    DWORD freq,
    DWORD chans,
    DWORD flags,
    RECORDPROC *proc
    void *user
);

Parameters

freq | The sample rate to record at... 0 = device's current sample rate.
chans | The number of channels... 1 = mono, 2 = stereo, etc. 0 = device's current channel count.
flagsA combination of these flags.
BASS_SAMPLE_8BITS | Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flag are specified, then the recorded data is 16-bit.
BASS_SAMPLE_FLOAT | Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_RECORD_PAUSE | Start the recording paused.
The HIWORD - use MAKELONG(flags,period) - can be used to set the period (in milliseconds) between calls to the callback function. The minimum period is 5ms, the maximum is half the BASS_CONFIG_REC_BUFFER setting. If the period specified is outside this range, it is automatically capped. The default is 100ms.
proc | The user defined function to receive the recorded sample data... can be NULL if you do not wish to use a callback.
user | User instance data to pass to the callback function.

Return value

If successful, the new recording's handle is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT | BASS_RecordInit has not been successfully called.
BASS_ERROR_BUSY | The device is busy. An existing recording may need to be stopped before starting another one.
BASS_ERROR_NOTAVAIL | The recording device is not available. Another application may already be recording with it, or it could be a half-duplex device that is currently being used for playback.
BASS_ERROR_FORMAT | The requested format is not supported. If using the BASS_SAMPLE_FLOAT flag, it could be that floating-point recording is not supported.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Use BASS_ChannelStop to stop the recording and free its resources. BASS_ChannelPause can be used to pause the recording; it can also be started in a paused state via the BASS_RECORD_PAUSE flag, which allows DSP/FX to be set on it before any data reaches the callback function. Use BASS_ChannelPlay to resume a paused recording.

The sample data will generally arrive from the recording device in blocks rather than in a continuous stream. So when specifying a very short period between callbacks, some calls may be skipped due to there being no new data available since the last call. A loopback recording device will only deliver data while the corresponding output device is active.

When not using a callback (proc = NULL), the recorded data is instead retrieved via BASS_ChannelGetData. To keep latency at a minimum, the amount of data in the recording buffer should be monitored (also done via BASS_ChannelGetData, with the BASS_DATA_AVAILABLE flag) to check that there is not too much data; freshly recorded data will only be retrieved after the older data in the buffer is.

When freq and/or chans is set to 0 for the device's current values, BASS_ChannelGetInfo can be used afterwards to find out what values are being used by the recording.

A recording may end unexpectedly if the device fails, eg. if it is disconnected/disabled. A BASS_SYNC_DEV_FAIL sync can be set via BASS_ChannelSetSync to be informed if that happens. It will not be possible to resume the recording channel then; a new recording channel will need to be created when the device becomes available again.

Platform-specific

Multiple simultaneous recordings can be made from the same device on Windows XP and later, but generally not on older Windows. Multiple simultaneous recordings are possible on iOS and OSX, but may not always be on Linux or Windows CE.

Loopback recording is only available on Windows Vista and above. The option to use the device's current sample rate and/or channel count is only available on Windows/OSX/iOS.

On OSX and iOS, the device is instructed (when possible) to deliver data at the period set in the HIWORD of flags, even when a callback function is not used. On other platforms, it is up the the system when data arrives from the device.

Example

Start recording at 44100 Hz stereo 16-bit.
HRECORD record = BASS_RecordStart(44100, 2, 0, MyRecordProc, 0);

See also

BASS_ChannelGetData, BASS_ChannelGetLevel, BASS_ChannelPause, BASS_ChannelStop, BASS_RecordInit, RECORDPROC callback, BASS_CONFIG_REC_BUFFER


RECORDPROC callback

User defined callback function to process recorded sample data.

BOOL CALLBACK RecordProc(
    HRECORD handle,
    const void *buffer,
    DWORD length,
    void *user
);

Parameters

handle | The recording that the data is from.
buffer | Pointer to the recorded sample data. The sample data is in standard Windows PCM format, that is 8-bit samples are unsigned, 16-bit samples are signed, 32-bit floating-point samples range from -1 to +1.
length | The number of bytes in the buffer.
user | The user instance data given when BASS_RecordStart was called.

Return value

Return FALSE to stop recording, and anything else to continue recording.

Remarks

The BASS_ATTRIB_GRANULE attribute can be used to control the granularity of the amount of data received.

BASS_RecordFree should not be used to free the recording device within a recording callback function. Nor should BASS_ChannelStop be used to stop the recording; return FALSE to do that instead.

Example

A callback function to write the recorded data to disk.
BOOL CALLBACK MyRecordProc(HRECORD handle, const void *buffer, DWORD length, void *user)
{
    fwrite(buffer, 1, length, (FILE*)user); // write the buffer to the file
    return TRUE; // continue recording
}
...
HRECORD record = BASS_RecordStart(44100, 2, 0, MyRecordProc, file); // start recording

See also

BASS_RecordStart, BASS_ATTRIB_GRANULE


BASS_RECORDINFO structure

Used with BASS_RecordGetInfo to retrieve information on the current recording device.

typedef struct {
    DWORD flags;
    DWORD formats;
    DWORD inputs;
    BOOL singlein;
    DWORD freq;
} BASS_RECORDINFO;

Members

flagsThe device's capabilities... a combination of these flags.
DSCCAPS_EMULDRIVER | The device's drivers do not have DirectSound recording support, so it is being emulated.
DSCCAPS_CERTIFIED | The device driver has been certified by Microsoft.
formatsThe standard formats supported by the device... a combination of these flags.
WAVE_FORMAT_1M08 | 11025 Hz, Mono, 8-bit
WAVE_FORMAT_1S08 | 11025 Hz, Stereo, 8-bit
WAVE_FORMAT_1M16 | 11025 Hz, Mono, 16-bit
WAVE_FORMAT_1S16 | 11025 Hz, Stereo, 16-bit
WAVE_FORMAT_2M08 | 22050 Hz, Mono, 8-bit
WAVE_FORMAT_2S08 | 22050 Hz, Stereo, 8-bit
WAVE_FORMAT_2M16 | 22050 Hz, Mono, 16-bit
WAVE_FORMAT_2S16 | 22050 Hz, Stereo, 16-bit
WAVE_FORMAT_4M08 | 44100 Hz, Mono, 8-bit
WAVE_FORMAT_4S08 | 44100 Hz, Stereo, 8-bit
WAVE_FORMAT_4M16 | 44100 Hz, Mono, 16-bit
WAVE_FORMAT_4S16 | 44100 Hz, Stereo, 16-bit
The number of channels supported by the device is in the high 8 bits.
inputs | The number of input sources available to the device.
singlein | TRUE = only one input may be active at a time.
freq | The device's current sample rate. Recording at this rate will give the best quality and performance, as no resampling is required.

Platform-specific

The flags member is only used on Windows, and only prior to Vista. The formats member is only used on Windows/OSX/iOS but only for the device's channel count except on Windows prior to Vista. freq is also only available on Windows/OSX/iOS, but not on Windows prior to Vista.

See also

BASS_RecordGetInfo


What is a channel?

A "channel" can be a sample playback channel (HCHANNEL), a sample stream (HSTREAM), a MOD music (HMUSIC), or a recording (HRECORD). Each "Channel" function can be used with one or more of these channel types.

The types of channel

HCHANNEL | Returned by BASS_SampleGetChannel.
HSTREAM | Returned by BASS_StreamCreate, BASS_StreamCreateFile, BASS_StreamCreateURL, BASS_StreamCreateFileUser. Also add-on provided functions.
HMUSIC | Returned by BASS_MusicLoad.
HRECORD | Returned by BASS_RecordStart.

A sample stream (HSTREAM) or MOD music (HMUSIC) that has been created with the BASS_STREAM_DECODE or BASS_MUSIC_DECODE flag is sometimes referred to as a "decoding channel".


BASS_ChannelBytes2Seconds

Translates a byte position into time (seconds), based on a channel's format.

double BASS_ChannelBytes2Seconds(
    DWORD handle,
    QWORD pos
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD. HSAMPLE handles may also be used.
pos | The position to translate.

Return value

If successful, then the translated length is returned, else a negative value is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

The translation is based on the channel's initial sample rate, when it was created.

See also

BASS_ChannelGetInfo, BASS_ChannelGetPosition, BASS_ChannelSeconds2Bytes


BASS_ChannelFlags

Modifies and retrieves a channel's flags.

DWORD BASS_ChannelFlags(
    DWORD handle,
    DWORD flags,
    DWORD mask
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
flagsA combination of these flags.
BASS_SAMPLE_LOOP | Loop the channel.
BASS_STREAM_AUTOFREE | Automatically free the channel when playback ends. Note that the BASS_MUSIC_AUTOFREE flag is identical to this flag. (HSTREAM/HMUSIC only)
BASS_STREAM_RESTRATE | Restrict the download rate. (HSTREAM)
BASS_MUSIC_NONINTER | Use non-interpolated sample mixing. (HMUSIC)
BASS_MUSIC_SINCINTER | Use sinc interpolated sample mixing. (HMUSIC)
BASS_MUSIC_RAMP | Use "normal" ramping. (HMUSIC)
BASS_MUSIC_RAMPS | Use "sensitive" ramping. (HMUSIC)
BASS_MUSIC_SURROUND | Use surround sound. (HMUSIC)
BASS_MUSIC_SURROUND2 | Use surround sound mode 2. (HMUSIC)
BASS_MUSIC_FT2MOD | Use FastTracker 2 .MOD playback. (HMUSIC)
BASS_MUSIC_PT1MOD | Use ProTracker 1 .MOD playback. (HMUSIC)
BASS_MUSIC_POSRESET | Stop all notes when seeking. (HMUSIC)
BASS_MUSIC_POSRESETEX | Stop all notes and reset BPM/etc when seeking. (HMUSIC)
BASS_MUSIC_STOPBACK | Stop when a backward jump effect is played. (HMUSIC)
BASS_SPEAKER_xxx | Speaker assignment flags. (HSTREAM/HMUSIC)
other flags may be supported by add-ons, see the documentation.
mask | The flags (as above) to modify. Flags that are not included in this are left as they are, so it can be set to 0 in order to just retrieve the current flags. To modify the speaker flags, any of the BASS_SPEAKER_xxx flags can be used in the mask (no need to include all of them).

Return value

If successful, the channel's updated flags are returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

Some flags may not be adjustable in some circumstances, so the return value should be checked to confirm any changes. The flags listed above are just the flags that can be modified, and there may be additional flags present in the return value. See the BASS_CHANNELINFO documentation for a full list of flags.

Streams that are created by add-ons may have additional flags available. There is a limited number of possible flag values though, so some add-ons may use the same flag value for different things. This means that when using add-on specific flags with a stream created via the plugin system, it is a good idea to first confirm that the add-on is handling the stream, by checking its ctype via BASS_ChannelGetInfo.

During playback, the effects of flag changes are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

Example

Toggle looping on a channel.
if (BASS_ChannelFlags(channel, 0, 0)&BASS_SAMPLE_LOOP) { // looping is enabled, so...
    BASS_ChannelFlags(channel, 0, BASS_SAMPLE_LOOP); // remove the LOOP flag
} else { // looping is disabled, so...
    BASS_ChannelFlags(channel, BASS_SAMPLE_LOOP, BASS_SAMPLE_LOOP); // set the LOOP flag
}

See also

BASS_ChannelGetAttribute, BASS_ChannelGetInfo, BASS_ChannelSetAttribute


BASS_ChannelGet3DAttributes

Retrieves the 3D attributes of a sample, stream, or MOD music channel with 3D functionality.

BOOL BASS_ChannelGet3DAttributes(
    DWORD handle,
    DWORD *mode,
    float *min,
    float *max,
    DWORD *iangle,
    DWORD *oangle,
    float *outvol
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mode | The 3D processing mode... NULL = don't retrieve it.
min | The minimum distance... NULL = don't retrieve it.
max | The maximum distance... NULL = don't retrieve it.
iangle | The angle of the inside projection cone... NULL = don't retrieve it.
oangle | The angle of the outside projection cone... NULL = don't retrieve it.
outvol | The delta-volume outside the outer projection cone... NULL = don't retrieve it.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality.

Remarks

The iangle and oangle parameters must both be retrieved in a single call to this function; one cannot be retrieved without the other. See BASS_ChannelSet3DAttributes for an explanation of the parameters.

See also

BASS_ChannelGet3DPosition, BASS_ChannelGetAttribute, BASS_ChannelSet3DAttributes, BASS_ATTRIB_EAXMIX


BASS_ChannelGet3DPosition

Retrieves the 3D position of a sample, stream, or MOD music channel with 3D functionality.

BOOL BASS_ChannelGet3DPosition(
    DWORD handle,
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
pos | Position of the sound... NULL = don't retrieve it.
orient | Orientation of the sound... NULL = don't retrieve it.
vel | Velocity of the sound... NULL = don't retrieve it.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality.

See also

BASS_ChannelGet3DAttributes, BASS_ChannelGetAttribute, BASS_ChannelSet3DPosition, BASS_Get3DFactors, BASS_Get3DPosition, BASS_3DVECTOR structure


BASS_ChannelGetAttribute

Retrieves the value of a channel's attribute.

BOOL BASS_ChannelGetAttribute(
    DWORD handle,
    DWORD attrib,
    float *value
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
attribThe attribute to get the value of... one of the following.
BASS_ATTRIB_EAXMIX | EAX wet/dry mix. (HCHANNEL/HMUSIC/HSTREAM only)
BASS_ATTRIB_BITRATE | Average bitrate. (HSTREAM)
BASS_ATTRIB_BUFFER | Playback buffering length. (HMUSIC/HSTREAM)
BASS_ATTRIB_CPU | CPU usage. (HMUSIC/HSTREAM)
BASS_ATTRIB_FREQ | Sample rate.
BASS_ATTRIB_GRANULE | Processing granularity. (HMUSIC/HSTREAM/HRECORD)
BASS_ATTRIB_MUSIC_ACTIVE | Active channel count. (HMUSIC)
BASS_ATTRIB_MUSIC_AMPLIFY | Amplification level. (HMUSIC)
BASS_ATTRIB_MUSIC_BPM | BPM. (HMUSIC)
BASS_ATTRIB_MUSIC_PANSEP | Pan separation level. (HMUSIC)
BASS_ATTRIB_MUSIC_PSCALER | Position scaler. (HMUSIC)
BASS_ATTRIB_MUSIC_SPEED | Speed. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_CHAN | A channel volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_GLOBAL | Global volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_INST | An instrument/sample volume level. (HMUSIC)
BASS_ATTRIB_NET_RESUME | Buffer level to resume stalled playback. (HSTREAM)
BASS_ATTRIB_NOBUFFER | Playback buffering switch. (HMUSIC/HSTREAM)
BASS_ATTRIB_NORAMP | Playback ramping switch.
BASS_ATTRIB_PAN | Panning/balance position.
BASS_ATTRIB_SRC | Sample rate conversion quality.
BASS_ATTRIB_VOL | Volume level.
other attributes may be supported by add-ons, see the documentation.
value | Pointer to a variable to receive the attribute value.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOTAVAIL | The attribute is not available.
BASS_ERROR_ILLTYPE | attrib is not valid.
some attributes may have additional error codes, see the documentation.

See also

BASS_ChannelGet3DAttributes, BASS_ChannelGetAttributeEx, BASS_ChannelGetInfo, BASS_ChannelSetAttribute


BASS_ChannelGetAttributeEx

Retrieves the value of a channel's attribute.

DWORD BASS_ChannelGetAttributeEx(
    DWORD handle,
    DWORD attrib,
    void *value,
    DWORD size
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
attribThe attribute to get the value of... one of the following.
BASS_ATTRIB_SCANINFO Scanned info. (HSTREAM only)
other attributes may be supported by add-ons, see the documentation.
value | Pointer to a buffer to receive the attribute data.
size | The size of the attribute data... 0 = get the size of the attribute without getting the data.

Return value

If successful, the size of the attribute data is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOTAVAIL | The attribute is not available.
BASS_ERROR_ILLTYPE | attrib is not valid.
BASS_ERROR_ILLPARAM | size is not valid.
some attributes may have additional error codes, see the documentation.

Remarks

This function also supports the floating-point attributes supported by BASS_ChannelGetAttribute.

See also

BASS_ChannelGetAttribute, BASS_ChannelGetInfo, BASS_ChannelSetAttributeEx


BASS_ChannelGetData

Retrieves the immediate sample data (or an FFT representation of it) of a sample channel, stream, MOD music, or recording channel.

DWORD BASS_ChannelGetData(
    DWORD handle,
    void *buffer,
    DWORD length
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
buffer | Pointer to a buffer to receive the data... can be NULL when handle is a recording channel (HRECORD), to discard the requested amount of data from the recording buffer.
lengthNumber of bytes wanted (up to 268435455 or 0xFFFFFFF), and/or the following flags.
BASS_DATA_FLOAT | Return floating-point sample data.
BASS_DATA_FIXED | Return 8.24 fixed-point data.
BASS_DATA_FFT256 | 256 sample FFT (returns 128 values).
BASS_DATA_FFT512 | 512 sample FFT (returns 256 values).
BASS_DATA_FFT1024 | 1024 sample FFT (returns 512 values).
BASS_DATA_FFT2048 | 2048 sample FFT (returns 1024 values).
BASS_DATA_FFT4096 | 4096 sample FFT (returns 2048 values).
BASS_DATA_FFT8192 | 8192 sample FFT (returns 4096 values).
BASS_DATA_FFT16384 | 16384 sample FFT (returns 8192 values).
BASS_DATA_FFT32768 | 32768 sample FFT (returns 16384 values).
BASS_DATA_FFT_COMPLEX | Return the complex FFT result rather than the magnitudes. This increases the amount of data returned (as listed above) fourfold, as it returns real and imaginary parts and the full FFT result (not only the first half). The real and imaginary parts are interleaved in the returned data.
BASS_DATA_FFT_INDIVIDUAL | Perform a separate FFT for each channel, rather than a single combined FFT. The size of the data returned (as listed above) is multiplied by the number of channels.
BASS_DATA_FFT_NOWINDOW | Prevent a Hann window being applied to the sample data when performing an FFT.
BASS_DATA_FFT_NYQUIST | Return an extra value for the Nyquist frequency magnitude. The Nyquist frequency is always included in a complex FFT result.
BASS_DATA_FFT_REMOVEDC | Remove any DC bias from the sample data when performing an FFT.
BASS_DATA_AVAILABLE | Query the amount of data the channel has buffered for playback, or from recording. This flag cannot be used with decoding channels as they do not have playback buffers. buffer is ignored when using this flag.

Return value

If an error occurs, -1 is returned, use BASS_ErrorGetCode to get the error code. When requesting FFT data, the number of bytes read from the channel (to perform the FFT) is returned. When requesting sample data, the number of bytes written to buffer will be returned (not necessarily the same as the number of bytes read when using the BASS_DATA_FLOAT or BASS_DATA_FIXED flag). When using the BASS_DATA_AVAILABLE flag, the number of bytes in the channel's buffer is returned.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ENDED | The channel has reached the end.
BASS_ERROR_NOTAVAIL | The BASS_DATA_AVAILABLE flag cannot be used with a decoding channel. It is not possible to get data from final output mix streams (using STREAMPROC_DEVICE).
BASS_ERROR_BUFLOST | Should not happen... check that a valid window handle was used with BASS_Init.

Remarks

Unless the channel is a decoding channel, this function can only return as much data as has been written to the channel's playback buffer, so it may not always be possible to get the amount of data requested, especially if it is a large amount. If larger amounts are needed, the buffer length (BASS_CONFIG_BUFFER) can be increased. The BASS_DATA_AVAILABLE flag can be used to check how much data a channel's buffer contains at any time, including when stopped or stalled. BASS will retain some extra data beyond the configured buffer length to account for device latency and give the data that is currently being heard, so the amount of available data can actually exceed the configured buffer length.

When requesting data from a decoding channel, data is decoded directly from the channel's source (no playback buffer) and as much data as the channel has available can be decoded at a time.

When retrieving sample data, 8-bit samples are unsigned (0 to 255), 16-bit samples are signed (-32768 to 32767), 32-bit floating-point samples range from -1 to +1 (not clipped, so can actually be outside this range). That is unless the BASS_DATA_FLOAT flag is used, in which case the sample data will be converted to 32-bit floating-point (if it is not already), or if the BASS_DATA_FIXED flag is used, in which case the data will be coverted to 8.24 fixed-point.

Unless complex data is requested via the BASS_DATA_FFT_COMPLEX flag, the magnitudes of the first half of an FFT result are returned. For example, with a 2048 sample FFT, there will be 1024 floating-point values returned. If the BASS_DATA_FIXED flag is used, then the FFT values will be in 8.24 fixed-point form rather than floating-point. Each value, or "bin", ranges from 0 to 1 (can actually go higher if the sample data is floating-point and not clipped). The 1st bin contains the DC component, the 2nd contains the amplitude at 1/2048 of the channel's sample rate, followed by the amplitude at 2/2048, 3/2048, etc. A Hann window is applied to the sample data to reduce leakage, unless the BASS_DATA_FFT_NOWINDOW flag is used. When a window is applied, it causes the DC component to leak into the next bin, but that can be removed (reduced to 0) by using the BASS_DATA_FFT_REMOVEDC flag. Doing so slightly increases the processing required though, so it should only be done when needed, which is when a window is applied and the 2nd bin value is important.

Channels that have 2 or more sample channels (ie. stereo or above) may have FFT performed on each individual channel, using the BASS_DATA_FFT_INDIVIDUAL flag. Without this flag, all of the channels are combined, and a single mono FFT is performed. Performing the extra individual FFTs of course increases the amount of processing required. The return values are interleaved in the same order as the channel's sample data, eg. stereo = left,right,left,etc.

This function is most useful if you wish to visualize (eg. spectrum analyze) the sound.

Platform-specific

The BASS_DATA_FIXED flag is only available on Android and Windows CE.

Example

Perform a 1024 sample FFT on a channel and list the result.
float fft[512]; // fft data buffer
BASS_ChannelGetData(channel, fft, BASS_DATA_FFT1024);
for (int a = 0; a < 512; a++)
    printf("%d: %f\n", a, fft[a]);

Perform a 1024 sample FFT on a channel and list the complex result.

float fft[2048]; // fft data buffer
BASS_ChannelGetData(channel, fft, BASS_DATA_FFT1024 | BASS_DATA_FFT_COMPLEX);
for (int a = 0; a < 1024; a++)
    printf("%d: (%f, %f)\n", a, fft[a * 2], fft[a * 2 + 1]);

See also

BASS_ChannelGetLevel, BASS_ChannelIsActive


BASS_ChannelGetDevice

Retrieves the device that a channel is using.

DWORD BASS_ChannelGetDevice(
    DWORD handle
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD. HSAMPLE handles may also be used.

Return value

If successful, the device number is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

Recording devices are indicated by the HIWORD of the return value being 1, when this function is called with a HRECORD channel.

The return value may be BASS_NODEVICE, if the channel is not associated with a device.

See also

BASS_ChannelSetDevice, BASS_GetDevice, BASS_SetDevice, BASS_RecordGetDevice, BASS_RecordSetDevice


BASS_ChannelGetInfo

Retrieves information on a channel.

BOOL BASS_ChannelGetInfo(
    DWORD handle,
    BASS_CHANNELINFO *info
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
info | Pointer to structure to receive the channel information.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.

See also

BASS_ChannelFlags, BASS_ChannelGetAttribute, BASS_ChannelGetTags, BASS_CHANNELINFO structure


BASS_ChannelGetLength

Retrieves the playback length of a channel.

QWORD BASS_ChannelGetLength(
    DWORD handle,
    DWORD mode
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM. HSAMPLE handles may also be used.
modeHow to retrieve the length. One of the following.
BASS_POS_BYTE | Get the length in bytes.
BASS_POS_MUSIC_ORDER | Get the length in orders. (HMUSIC only)
BASS_POS_OGG | Get the number of bitstreams in an OGG file.
other modes may be supported by add-ons, see the documentation.

Return value

If successful, then the channel's length is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTAVAIL | The requested length is not available.

Remarks

The exact length of a stream will be returned once the whole file has been streamed, but until then it is not always possible to 100% accurately estimate the length. The length is always exact for MP3/MP2/MP1 files when the BASS_STREAM_PRESCAN flag is used in the BASS_StreamCreateFile call, otherwise it is an (usually accurate) estimation based on the file size. The length returned for OGG files will usually be exact (assuming the file is not corrupt), but when streaming from the internet (or "buffered" user file), it can be a very rough estimation until the whole file has been downloaded. It will also be an estimate for chained OGG files that are not pre-scanned.

Unless an OGG file contains a single bitstream, the number of bitstreams it contains will only be available if it was pre-scanned at the stream's creation.

Retrieving the byte length of a MOD music requires that the BASS_MUSIC_PRESCAN flag was used in the BASS_MusicLoad call.

Example

Get the duration (in seconds) of a channel.
QWORD len = BASS_ChannelGetLength(channel, BASS_POS_BYTE); // the length in bytes
double time = BASS_ChannelBytes2Seconds(channel, len); // the length in seconds

See also

BASS_ChannelBytes2Seconds, BASS_ChannelGetPosition, BASS_ChannelSetPosition, BASS_StreamGetFilePosition


BASS_ChannelGetLevel

Retrieves the level (peak amplitude) of a sample, stream, MOD music, or recording channel.

DWORD BASS_ChannelGetLevel(
    DWORD handle
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.

Return value

If an error occurs, -1 is returned, use BASS_ErrorGetCode to get the error code. If successful, the level of the left channel is returned in the low word (low 16 bits), and the level of the right channel is returned in the high word (high 16 bits). If the channel is mono, then the low word is duplicated in the high word. The level ranges linearly from 0 (silent) to 32768 (max). 0 will be returned when a channel is stalled.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOPLAY | The channel is not playing.
BASS_ERROR_ENDED | The decoding channel has reached the end.
BASS_ERROR_BUFLOST | Should not happen... check that a valid window handle was used with BASS_Init.

Remarks

This function measures the level of the channel's sample data, not its level in the final output mix, so the channel's volume (BASS_ATTRIB_VOL attribute) and panning (BASS_ATTRIB_PAN) does not affect it. The effect of any DSP/FX set on the channel is present in the measurement, except for DX8 effects when using the "With FX flag" DX8 effect implementation. DSP/FX are not present when a RECORDPROC callback function is used by a recording channel (they are only present in the data received by the RECORDPROC).

For channels that are more than stereo, the left level will include all left channels (eg. front-left, rear-left, center), and the right will include all right (front-right, rear-right, LFE). If there are an odd number of channels then the left and right levels will include all channels. If the level of each individual channel is required, that is available from BASS_ChannelGetLevelEx.

20ms of data is inspected to calculate the level. When used with a decoding channel, that means 20ms of data needs to be decoded from the channel in order to calculate the level, and that data is then gone, eg. it is not available to a subsequent BASS_ChannelGetData call.

More flexible level retrieval is available with BASS_ChannelGetLevelEx.

Example

Get the left and right levels of a stereo channel.
DWORD level, left, right;
level = BASS_ChannelGetLevel(channel);
left = LOWORD(level); // the left level
right = HIWORD(level); // the right level

See also

BASS_ChannelGetData, BASS_ChannelGetLevelEx, BASS_ChannelIsActive


BASS_ChannelGetLevelEx

Retrieves the level of a sample, stream, MOD music, or recording channel.

BOOL BASS_ChannelGetLevelEx(
    DWORD handle,
    float *levels,
    float length,
    DWORD flags
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
levels | An array to receive the levels.
length | The amount of data to inspect to calculate the level, in seconds. The maximum is 1 second. Less data than requested may be used if the full amount is not available, eg. if the channel's playback buffer is shorter.
flagsA combination of these flags.
BASS_LEVEL_MONO | Get a mono level. If neither this or the BASS_LEVEL_STEREO flag is used, then a separate level is retrieved for each channel.
BASS_LEVEL_STEREO | Get a stereo level. The left level will be from the even channels, and the right level will be from the odd channels. If there are an odd number of channels then the left and right levels will both include all channels.
BASS_LEVEL_RMS | Get the RMS level. Otherwise the peak level.
BASS_LEVEL_VOLPAN | Apply the current BASS_ATTRIB_VOL and BASS_ATTRIB_PAN values to the level reading.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLPARAM | length is not valid.
BASS_ERROR_NOPLAY | The channel is not playing.
BASS_ERROR_ENDED | The decoding channel has reached the end.
BASS_ERROR_BUFLOST | Should not happen... check that a valid window handle was used with BASS_Init.

Remarks

This function operates in the same way as BASS_ChannelGetLevel but has greater flexibility on how the level is measured. The levels are not clipped, so may exceed +/-1.0 on floating-point channels.

Example

Replicate BASS_ChannelGetLevel but with floating-point levels.
float levels[2];
BASS_ChannelGetLevelEx(handle, levels, 0.02, BASS_LEVEL_STEREO);

Get a mono RMS level reading in decibels using 50ms of data.

float level;
BASS_ChannelGetLevelEx(handle, &level, 0.05, BASS_LEVEL_MONO | BASS_LEVEL_RMS); // get the level
float dblevel = (level > 0 ? 20 * log10(level) : -1000); // translate it to dB

Get a peak level reading for each channel using 20ms of data.

BASS_CHANNELINFO ci;
BASS_ChannelGetInfo(handle, &ci);
float *levels = (float*)malloc(ci.chans * sizeof(float)); // allocate an array for each channel's level
BASS_ChannelGetLevelEx(handle, levels, 0.02, 0); // get the levels

See also

BASS_ChannelGetData, BASS_ChannelGetLevel, BASS_ChannelIsActive


BASS_ChannelGetPosition

Retrieves the playback position of a sample, stream, or MOD music. Can also be used with a recording channel.

QWORD BASS_ChannelGetPosition(
    DWORD handle,
    DWORD mode
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
modeHow to retrieve the position. One of the following, with optional flags.
BASS_POS_BYTE | Get the position in bytes.
BASS_POS_MUSIC_ORDER | Get the position in orders and rows... LOWORD = order, HIWORD = row * scaler (BASS_ATTRIB_MUSIC_PSCALER). (HMUSIC only)
BASS_POS_DECODE | Flag: Get the decoding/rendering position, which may be ahead of the playback position due to buffering. This flag is unnecessary with decoding channels because the decoding position will always be given for them anyway, as they do not have playback buffers.
other modes & flags may be supported by add-ons, see the documentation.

Return value

If successful, then the channel's position is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOTAVAIL | The requested position is not available.
BASS_ERROR_UNKNOWN | Some other mystery problem!

See also

BASS_ChannelBytes2Seconds, BASS_ChannelGetLength, BASS_ChannelIsActive, BASS_ChannelSetPosition, BASS_ChannelSetSync, BASS_StreamGetFilePosition


BASS_ChannelGetTags

Retrieves tags/headers from a channel.

const char *BASS_ChannelGetTags(
    DWORD handle,
    DWORD tags
);

Parameters

handle The channel handle... a HMUSIC or HSTREAM.
tagsThe tags/headers wanted... one of the following.
BASS_TAG_AM_MIME | Android media codec MIME type. A single string is returned.
BASS_TAG_AM_NAME | Android media codec name. A single string is returned. This in only available on Android 4.3 and above.
BASS_TAG_APE | APE (v1 or v2) tags. A pointer to a series of null-terminated UTF-8 strings is returned, the final string ending with a double null. Each string is in the form of "key=value", or "key=value1/value2/..." if there are multiple values.
BASS_TAG_APE_BINARY + tag number (0=first) | APE binary tag. A pointer to a TAG_APE_BINARY structure is returned.
BASS_TAG_CA_CODEC | CoreAudio codec information. A pointer to a TAG_CA_CODEC structure is returned.
BASS_TAG_HTTP | HTTP headers, only available when streaming from a HTTP server. A pointer to a series of null-terminated strings is returned, the final string ending with a double null.
BASS_TAG_ICY | ICY (Shoutcast) tags. A pointer to a series of null-terminated strings is returned, the final string ending with a double null.
BASS_TAG_ID3 | ID3v1 tags. A pointer to a TAG_ID3 structure is returned.
BASS_TAG_ID3V2 | ID3v2 tags. A pointer to a variable length block is returned. ID3v2 tags are supported at both the start and end of the file, and in designated RIFF/AIFF chunks. See www.id3.org for details of the block's structure.
BASS_TAG_LYRICS3 | Lyrics3v2 tag. A single string is returned, containing the Lyrics3v2 information. See www.id3.org/Lyrics3v2 for details of its format.
BASS_TAG_META | Shoutcast metadata. A single string is returned, containing the current stream title and url (usually omitted). The format of the string is: StreamTitle='xxx';StreamUrl='xxx';
BASS_TAG_MF | Media Foundation metadata. A pointer to a series of null-terminated UTF-8 strings is returned, the final string ending with a double null.
BASS_TAG_MP4 | MP4/iTunes metadata. A pointer to a series of null-terminated UTF-8 strings is returned, the final string ending with a double null.
BASS_TAG_MUSIC_AUTH | MOD music author. Only available in files created with the OpenMPT tracker.
BASS_TAG_MUSIC_INST + instrument number (0=first) | MOD instrument name. Only available with formats that have instruments, eg. IT and XM (and MO3).
BASS_TAG_MUSIC_MESSAGE | MOD message text.
BASS_TAG_MUSIC_NAME | MOD music title.
BASS_TAG_MUSIC_ORDERS | MOD music order list. A pointer to a byte array is returned, with each byte being the pattern number played at that order position. Pattern number 254 is "+++" (skip order) and 255 is "---" (end song).
BASS_TAG_MUSIC_SAMPLE + sample number (0=first) | MOD sample name.
BASS_TAG_OGG | OGG comments. A pointer to a series of null-terminated UTF-8 strings is returned, the final string ending with a double null.
BASS_TAG_RIFF_BEXT | RIFF/BWF "bext" chunk tags. A pointer to a TAG_BEXT structure is returned.
BASS_TAG_RIFF_CART | RIFF/BWF "cart" chunk tags. A pointer to a TAG_CART structure is returned.
BASS_TAG_RIFF_CUE | RIFF "cue " chunk. A pointer to a TAG_CUE structure is returned.
BASS_TAG_RIFF_DISP | RIFF "DISP" chunk text (CF_TEXT) tag. A single string is returned.
BASS_TAG_RIFF_INFO | RIFF "INFO" chunk tags. A pointer to a series of null-terminated strings is returned, the final string ending with a double null. The tags are in the form of "XXXX=text", where "XXXX" is the chunk ID.
BASS_TAG_RIFF_SMPL | RIFF "smpl" chunk. A pointer to a TAG_SMPL structure is returned.
BASS_TAG_VENDOR | OGG encoder. A single UTF-8 string is returned.
BASS_TAG_WAVEFORMAT | WAVE "fmt " chunk contents. A pointer to a WAVEFORMATEX structure is returned. As well as WAVE files, this is also provided by Media Foundation codecs.
BASS_TAG_WMA | WMA tags. A pointer to a series of null-terminated UTF-8 strings is returned, the final string ending with a double null.
other tags may be supported by add-ons, see the documentation.

Return value

If successful, the requested tags are returned, else NULL is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_NOTAVAIL | The requested tags are not available.

Remarks

Some tags (eg. ID3v1) are located at the end of the file, so when streaming a file from the internet, the tags will not be available until the download is complete. A BASS_SYNC_DOWNLOAD sync can be set via BASS_ChannelSetSync, to be informed of when the download is complete. A BASS_SYNC_META sync can be used to be informed of new Shoutcast metadata, and a BASS_SYNC_OGG_CHANGE sync for when a new logical bitstream begins in a chained OGG stream, which generally brings new OGG tags.

In a chained OGG file containing multiple bitstreams, each bitstream will have its own tags. To get the tags from a particular one, BASS_ChannelSetPosition can be first used to seek to it.

When a Media Foundation codec is in use, the BASS_TAG_WAVEFORMAT tag can be used to find out what the source format is, eg. via the WAVEFORMATEX structure's wFormatTag member. Some typical wFormatTag examples are: 0x0161 = WMA, 0x0162 = WMA pro, 0x0163 = WMA lossless, 0x1610 = AAC.

MP4 metadata can include a "Genre" tag that is either text or a number. When a number, it is an ID3v1 genre list index +1, eg. 1 = Blues, 2 = Classic Rock, etc. The full list can be found at www.id3.org.

The returned tag's memory is owned by BASS (or an add-on) and should not be modified. It should also not be accessed after the channel has been freed. If longer-term access is needed, a copy should be made.

Example

List an OGG stream's comments.
const char *comments = BASS_ChannelGetTags(channel, BASS_TAG_OGG); // get a pointer to the 1st comment
if (comments)
    while (*comments) {
        printf("%s\n", comments); // display the comment
        comments += strlen(comments) + 1; // move on to next comment
    }

List a MOD music's samples.

const char *text;
int n = 0;
while (text = BASS_ChannelGetTags(channel, BASS_TAG_MUSIC_SAMPLE + n)) {
    printf("sample %d = %s\n", n + 1, text); // display the sample text
    n++; // move on to next sample
}

See also

BASS_ChannelGetInfo, BASS_ChannelSetSync


BASS_ChannelIsActive

Checks if a sample, stream, or MOD music is active (playing) or stalled. Can also check if a recording is in progress.

DWORD BASS_ChannelIsActive(
    DWORD handle
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.

Return value

The return value is one of the following.
BASS_ACTIVE_STOPPED | The channel is not active, or handle is not a valid channel.
BASS_ACTIVE_PLAYING | The channel is playing (or recording).
BASS_ACTIVE_PAUSED | The channel is paused.
BASS_ACTIVE_PAUSED_DEVICE | The channel's device is paused.
BASS_ACTIVE_STALLED | Playback of the stream has been stalled due to a lack of sample data. Playback will automatically resume once there is sufficient data to do so.

Remarks

When using this function with a decoding channel, BASS_ACTIVE_PLAYING will be returned while there is still data to decode. Once the end has been reached, BASS_ACTIVE_STOPPED will be returned. BASS_ACTIVE_STALLED is never returned for decoding channels; you can tell a decoding channel is stalled if BASS_ChannelGetData returns less data than requested and this function still returns BASS_ACTIVE_PLAYING.

The BASS_ACTIVE_PAUSED_DEVICE state can be the result of a BASS_Pause call or of the device stopping unexpectedly (eg. a USB soundcard being disconnected). In either case, playback will be resumed by BASS_Start.

BASS_ErrorGetCode can be used to differentiate a stopped channel from an invalid channel. The error code will be BASS_OK if the channel is valid and stopped.

Syncs can be set via BASS_ChannelSetSync to be notified when a channel reaches the end (BASS_SYNC_END sync) or stalls/resumes (BASS_SYNC_STALL sync) or pauses due to device failure (BASS_SYNC_DEV_FAIL sync).

Platform-specific

When DirectSound output is used on Windows, if the device stops unexpectedly then it will need to be reinitialized with BASS_Free and BASS_Init to get it working again.

See also

BASS_ChannelGetLevel, BASS_ChannelPlay, BASS_ChannelSetSync, BASS_IsStarted, BASS_ATTRIB_NET_RESUME


BASS_ChannelIsSliding

Checks if an attribute (or any attribute) of a sample, stream, or MOD music is sliding.

BOOL BASS_ChannelIsSliding(
    DWORD handle,
    DWORD attrib
);

Parameters

handle The channel handle... a HCHANNEL, HSTREAM or HMUSIC.
attribThe attribute to check for sliding... one of the following, or 0 for any attribute.
BASS_ATTRIB_EAXMIX | EAX wet/dry mix.
BASS_ATTRIB_FREQ | Sample rate.
BASS_ATTRIB_PAN | Panning/balance position.
BASS_ATTRIB_VOL | Volume level.
BASS_ATTRIB_MUSIC_AMPLIFY | Amplification level. (HMUSIC only)
BASS_ATTRIB_MUSIC_BPM | BPM. (HMUSIC)
BASS_ATTRIB_MUSIC_PANSEP | Pan separation level. (HMUSIC)
BASS_ATTRIB_MUSIC_PSCALER | Position scaler. (HMUSIC)
BASS_ATTRIB_MUSIC_SPEED | Speed. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_CHAN | A channel volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_GLOBAL | Global volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_INST | An instrument/sample volume level. (HMUSIC)
other attributes may be supported by add-ons, see the documentation.

Return value

If the attribute is sliding, then TRUE is returned, else FALSE is returned.

See also

BASS_ChannelSlideAttribute


BASS_ChannelLock

Locks a stream, MOD music or recording channel to the current thread.

BOOL BASS_ChannelLock(
    DWORD handle,
    BOOL lock
);

Parameters

handle | The channel handle... a HMUSIC, HSTREAM or HRECORD.
lock | If FALSE, unlock the channel, else lock it.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

Locking a channel prevents other threads from performing most functions on it, including buffer updates. Other threads wanting to access a locked channel will block until it is unlocked, so a channel should only be locked very briefly. A channel must be unlocked in the same thread that it was locked.

Example

Lock a channel to ensure that 2 DSP functions start together.
BASS_ChannelLock(channel, TRUE); // lock channel
BASS_ChannelSetDSP(channel, DspProc1, NULL, 0); // set 1st DSP
BASS_ChannelSetDSP(channel, DspProc2, NULL, 0); // set 2nd DSP
BASS_ChannelLock(channel, FALSE); // unlock channel


BASS_ChannelPause

Pauses a sample, stream, MOD music, or recording.

BOOL BASS_ChannelPause(
    DWORD handle
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_NOPLAY | The channel is not playing (or handle is not a valid channel).
BASS_ERROR_DECODE | The channel is not playable; it is a "decoding channel".
BASS_ERROR_ALREADY | The channel is already paused.

Remarks

Use BASS_ChannelPlay to resume a paused channel. BASS_ChannelStop can be used to stop a paused channel.

See also

BASS_ChannelIsActive, BASS_ChannelPlay, BASS_ChannelStop


BASS_ChannelPlay

Starts (or resumes) playback of a sample, stream, MOD music, or recording.

BOOL BASS_ChannelPlay(
    DWORD handle,
    BOOL restart
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
restart | Restart playback from the beginning? If handle is a user stream (created with BASS_StreamCreate), its current buffer contents are cleared. If it is a MOD music, its BPM/etc are reset to their initial values.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_START | The output is paused/stopped, use BASS_Start to start it.
BASS_ERROR_DECODE | The channel is not playable; it is a "decoding channel".
BASS_ERROR_BUFLOST | Should not happen... check that a valid window handle was used with BASS_Init.
BASS_ERROR_NOHW | No hardware voices are available (HCHANNEL only). This only occurs if the sample was loaded/created with the BASS_SAMPLE_VAM flag and BASS_VAM_HARDWARE is set in the sample's VAM mode, and there are no hardware voices available to play it.

Remarks

When streaming in blocks (BASS_STREAM_BLOCK), the restart parameter is ignored as it is not possible to go back to the start. The restart parameter is also of no consequence with recording channels.

If other channels have been linked to the specified channel via BASS_ChannelSetLink, this function will attempt to simultaneously start playing them too but if any fail, it will be silently. The return value and error code only reflects what happened with the specified channel. BASS_ChannelIsActive can be used to confirm the status of linked channels.

See also

BASS_ChannelFlags, BASS_ChannelGetLevel, BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelSetPosition, BASS_ChannelSetSync, BASS_ChannelStop, BASS_ChannelUpdate, BASS_Start


BASS_ChannelRemoveDSP

Removes a DSP function from a stream, MOD music, or recording channel.

BOOL BASS_ChannelRemoveDSP(
    DWORD handle,
    HDSP dsp
);

Parameters

handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD.
dsp | Handle of the DSP function to remove from the channel. This can also be an HFX handle to remove an effect.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE At least one of handle and dsp is not valid.

See also

BASS_ChannelSetDSP


BASS_ChannelRemoveFX

Removes an effect on a stream, MOD music, or recording channel.

BOOL BASS_ChannelRemoveFX(
    DWORD handle,
    HFX fx
);

Parameters

handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD.
fx | Handle of the effect to remove from the channel. This can also be an HDSP handle to remove a DSP function.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE At least one of handle and fx is not valid.

Remarks

BASS_ChannelRemoveDSP can also be used to remove effects.

Platform-specific

On Windows, depending on the DX8 effect implementation being used by the channel, the channel may have to be stopped before removing a DX8 effect from it. If necessary, that is done automatically and the channel is resumed afterwards.

See also

BASS_ChannelSetFX, DX8 effect implementations


BASS_ChannelRemoveLink

Removes a links between two MOD music or stream channels.

BOOL BASS_ChannelRemoveLink(
    DWORD handle,
    DWORD chan
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
chan | The handle of the channel to have unlinked with it... a HMUSIC or HSTREAM.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ALREADY | Either chan is not a valid channel, or it is already not linked to handle.

See also

BASS_ChannelSetLink


BASS_ChannelRemoveSync

Removes a synchronizer from a MOD music, stream or recording channel.

BOOL BASS_ChannelRemoveSync(
    DWORD handle,
    HSYNC sync
);

Parameters

handle | The channel handle... a HMUSIC, HSTREAM or HRECORD.
sync | Handle of the synchronizer to remove.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE At least one of handle and sync is not valid.

See also

BASS_ChannelSetSync


BASS_ChannelSeconds2Bytes

Translates a time (seconds) position into bytes, based on a channel's format.

QWORD BASS_ChannelSeconds2Bytes(
    DWORD handle,
    double pos
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD. HSAMPLE handles may also be used.
pos | The position to translate.

Return value

If successful, then the translated length is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

The translation is based on the channel's initial sample rate, when it was created.

The return value is rounded down to the position of the nearest sample.

See also

BASS_ChannelGetInfo, BASS_ChannelSetPosition, BASS_ChannelBytes2Seconds


BASS_ChannelSet3DAttributes

Sets the 3D attributes of a sample, stream, or MOD music channel with 3D functionality.

BOOL BASS_ChannelSet3DAttributes(
    DWORD handle,
    int mode,
    float min,
    float max,
    int iangle,
    int oangle,
    float outvol
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
modeThe 3D processing mode... one of these flags, -1 = leave current.
BASS_3DMODE_NORMAL | Normal 3D processing.
BASS_3DMODE_RELATIVE | The channel's 3D position (position/velocity/orientation) is relative to the listener. When the listener's position/velocity/orientation is changed with BASS_Set3DPosition, the channel's position relative to the listener does not change.
BASS_3DMODE_OFF | Turn off 3D processing on the channel, the sound will be played in the centre.
min | The minimum distance. The channel's volume is at maximum when the listener is within this distance... 0 or less = leave current.
max | The maximum distance. The channel's volume stops decreasing when the listener is beyond this distance... 0 or less = leave current.
iangle | The angle of the inside projection cone in degrees... 0 (no cone) to 360 (sphere), -1 = leave current.
oangle | The angle of the outside projection cone in degrees... 0 (no cone) to 360 (sphere), -1 = leave current.
outvol | The delta-volume outside the outer projection cone... 0 (silent) to 1 (same as inside the cone), less than 0 = leave current.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality.
BASS_ERROR_ILLPARAM | One or more of the attribute values is invalid.

Remarks

The iangle and oangle parameters must both be set in a single call of this function; one cannot be set without the other. The iangle and oangle angles decide how wide the sound is projected around the orientation angle. Within the inside angle the volume level is the channel volume (BASS_ATTRIB_VOL attribute). Outside the outer angle, the volume changes according to the outvol value. Between the inner and outer angles, the volume gradually changes between the inner and outer volume levels. If the inner and outer angles are 360 degrees, then the sound is transmitted equally in all directions.

As with all 3D functions, use BASS_Apply3D to apply the changes made.

See also

BASS_ChannelGet3DAttributes, BASS_ChannelSet3DPosition, BASS_ChannelSetAttribute, BASS_ATTRIB_EAXMIX


BASS_ChannelSet3DPosition

Sets the 3D position of a sample, stream, or MOD music channel with 3D functionality.

BOOL BASS_ChannelSet3DPosition(
    DWORD handle,
    BASS_3DVECTOR *pos,
    BASS_3DVECTOR *orient,
    BASS_3DVECTOR *vel
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
pos | Position of the sound... NULL = leave current.
orient | Orientation of the sound... NULL = leave current. This is automatically normalized.
vel | Velocity of the sound... NULL = leave current. This is only used to calculate the doppler effect, and has no effect on the sound's position.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NO3D | The channel does not have 3D functionality.

Remarks

As with all 3D functions, BASS_Apply3D must be called to apply the changes made.

See also

BASS_Apply3D, BASS_ChannelGet3DPosition, BASS_ChannelSet3DAttributes, BASS_ChannelSetAttribute, BASS_Set3DFactors, BASS_Set3DPosition, BASS_3DVECTOR structure


BASS_ChannelSetAttribute

Sets the value of a channel's attribute.

BOOL BASS_ChannelSetAttribute(
    DWORD handle,
    DWORD attrib,
    float value
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
attribThe attribute to set the value of... one of the following.
BASS_ATTRIB_EAXMIX | EAX wet/dry mix. (HCHANNEL/HMUSIC/HSTREAM only)
BASS_ATTRIB_BUFFER | Playback buffering length. (HMUSIC/HSTREAM)
BASS_ATTRIB_FREQ | Sample rate.
BASS_ATTRIB_GRANULE | Processing granularity. (HMUSIC/HSTREAM/HRECORD)
BASS_ATTRIB_MUSIC_AMPLIFY | Amplification level. (HMUSIC)
BASS_ATTRIB_MUSIC_BPM | BPM. (HMUSIC)
BASS_ATTRIB_MUSIC_PANSEP | Pan separation level. (HMUSIC)
BASS_ATTRIB_MUSIC_PSCALER | Position scaler. (HMUSIC)
BASS_ATTRIB_MUSIC_SPEED | Speed. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_CHAN | A channel volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_GLOBAL | Global volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_INST | An instrument/sample volume level. (HMUSIC)
BASS_ATTRIB_NET_RESUME | Buffer level to resume stalled playback. (HSTREAM)
BASS_ATTRIB_NOBUFFER | Playback buffering switch. (HMUSIC/HSTREAM)
BASS_ATTRIB_NORAMP | Playback ramping switch.
BASS_ATTRIB_PAN | Panning/balance position.
BASS_ATTRIB_SRC | Sample rate conversion quality.
BASS_ATTRIB_VOL | Volume level.
other attributes may be supported by add-ons, see the documentation.
value | The new attribute value. See the attribute's documentation for details on the possible values.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLTYPE | attrib is not valid.
BASS_ERROR_ILLPARAM | value is not valid. See the attribute's documentation for the valid range of values.
some attributes may have additional error codes, see the documentation.

Remarks

The actual attribute value may not be exactly the same as requested, due to precision differences. For example, an attribute might only allow whole number values. BASS_ChannelGetAttribute can be used to confirm what the value is.

See also

BASS_ChannelFlags, BASS_ChannelGetAttribute, BASS_ChannelSetAttributeEx, BASS_ChannelSet3DAttributes, BASS_ChannelSlideAttribute


BASS_ChannelSetAttributeEx

Sets the value of a channel's attribute.

BOOL BASS_ChannelSetAttributeEx(
    DWORD handle,
    DWORD attrib,
    void *value,
    DWORD size
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.
attribThe attribute to set the value of... one of the following.
BASS_ATTRIB_SCANINFO Scanned info. (HSTREAM only)
other attributes may be supported by add-ons, see the documentation.
value | The new attribute data.
size | The size of the attribute data.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLTYPE | attrib is not valid.
BASS_ERROR_ILLPARAM | The value content or size is not valid.
some attributes may have additional error codes, see the documentation.

Remarks

This function also supports the floating-point attributes supported by BASS_ChannelGetAttribute.

See also

BASS_ChannelGetAttributeEx, BASS_ChannelSetAttribute


BASS_ChannelSetDevice

Changes the device that a stream, MOD music or sample is using.

BOOL BASS_ChannelSetDevice(
    DWORD handle,
    DWORD device
);

Parameters

handle | The channel or sample handle... a HMUSIC, HSTREAM or HSAMPLE.
device | The device to use... 0 = no sound, 1 = first real output device, BASS_NODEVICE = no device.

Return value

If successful, TRUE is returned, else FALSE is returned and the channel remains on its current device. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_DEVICE | device is invalid.
BASS_ERROR_INIT | The requested device has not been initialized.
BASS_ERROR_ALREADY | The channel is already using the requested device.
BASS_ERROR_NOTAVAIL | Only decoding channels are allowed to use the BASS_NODEVICE option. Final output mix streams (using STREAMPROC_DEVICE) cannot be moved to another device.
BASS_ERROR_FORMAT | The sample format is not supported by the device/drivers. If the channel is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_MEM | There is insufficient memory.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

All of the channel's current settings are carried over to the new device, but if the channel is using the "with FX flag" DX8 effect implementation, the internal state (eg. buffers) of the DX8 effects will be reset. When using the "without FX flag" DX8 effect implementation, the state of the DX8 effects is preserved.

When changing a sample's device, all the sample's existing channels (HCHANNELs) are freed. It is not possible to change the device of an individual sample channel.

The BASS_NODEVICE option can be used to disassociate a decoding channel from a device, so that it does not get freed when BASS_Free is called.

See also

BASS_ChannelGetDevice, BASS_Init


BASS_ChannelSetDSP

Sets up a user DSP function on a stream, MOD music, or recording channel.

HDSP BASS_ChannelSetDSP(
    DWORD handle,
    DSPPROC *proc,
    void *user,
    int priority
);

Parameters

handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD.
proc | The callback function.
user | User instance data to pass to the callback function.
priority | The priority of the new DSP, which determines its position in the DSP chain. DSPs with higher priority are called before those with lower.

Return value

If successful, then the new DSP's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

DSP functions can set and removed at any time, including mid-playback. Use BASS_ChannelRemoveDSP to remove a DSP function.

Multiple DSP functions may be used per channel, in which case the order that the functions are called is determined by their priorities. The priorities can be changed via BASS_FXSetPriority. Any DSPs that have the same priority are called in the order that they were given that priority.

DSP functions can be applied to MOD musics and streams, but not samples. If you want to apply a DSP function to a sample then you should stream it instead.

See also

BASS_ChannelLock, BASS_ChannelRemoveDSP, BASS_ChannelSetFX, BASS_FXSetPriority, BASS_CONFIG_FLOATDSP, DSPPROC callback


BASS_ChannelSetFX

Sets an effect on a stream, MOD music, or recording channel.

HFX BASS_ChannelSetFX(
    DWORD handle,
    DWORD type,
    int priority
);

Parameters

handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD.
typeOne of the following types of effect.
BASS_FX_DX8_CHORUS | DX8 Chorus. Use BASS_DX8_CHORUS structure to set/get parameters.
BASS_FX_DX8_COMPRESSOR | DX8 Compression. Use BASS_DX8_COMPRESSOR structure to set/get parameters.
BASS_FX_DX8_DISTORTION | DX8 Distortion. Use BASS_DX8_DISTORTION structure to set/get parameters.
BASS_FX_DX8_ECHO | DX8 Echo. Use BASS_DX8_ECHO structure to set/get parameters.
BASS_FX_DX8_FLANGER | DX8 Flanger. Use BASS_DX8_FLANGER structure to set/get parameters.
BASS_FX_DX8_GARGLE | DX8 Gargle. Use BASS_DX8_GARGLE structure to set/get parameters.
BASS_FX_DX8_I3DL2REVERB | DX8 I3DL2 (Interactive 3D Audio Level 2) reverb. Use BASS_DX8_I3DL2REVERB structure to set/get parameters.
BASS_FX_DX8_PARAMEQ | DX8 Parametric equalizer. Use BASS_DX8_PARAMEQ structure to set/get parameters.
BASS_FX_DX8_REVERB | DX8 Reverb. Use BASS_DX8_REVERB structure to set/get parameters.
BASS_FX_VOLUME | Volume level adjustment. Use BASS_FX_VOLUME_PARAM structure to set/get parameters.
other effects may be supported by add-ons, eg. BASS_FX.
priority | The priority of the new FX, which determines its position in the DSP chain. DSP/FX with higher priority are applied before those with lower. This parameter has no effect with DX8 effects when the "with FX flag" DX8 effect implementation is used.

Return value

If successful, then the new effect's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLTYPE | type is invalid.
BASS_ERROR_NOFX | The specified DX8 effect is unavailable.
BASS_ERROR_FORMAT | The channel's format is not supported by the effect.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Multiple effects may be used per channel. Use BASS_ChannelRemoveFX to remove an effect. Use BASS_FXSetParameters to set an effect's parameters. An effect's priority value can be changed via BASS_FXSetPriority.

Effects can be applied to MOD musics and streams, but not samples. If you want to apply an effect to a sample, you could use a stream instead.

Platform-specific

DX8 effects are a Windows feature requiring DirectX 8, or DirectX 9 for floating-point support. On other platforms, they are emulated by BASS, except for the following which are currently unsupported: COMPRESSOR, GARGLE, and I3DL2REVERB.

On Windows, depending on the DX8 effect implementation being used by the channel, the channel may have to be stopped before adding or removing DX8 effects on it. If necessary, that is done automatically and the channel is resumed afterwards.

See also

BASS_ChannelLock, BASS_ChannelRemoveFX, BASS_FXGetParameters, BASS_FXReset, BASS_FXSetParameters, BASS_FXSetPriority, BASS_ChannelSetDSP, BASS_CONFIG_FLOATDSP, DX8 effect implementations


BASS_ChannelSetLink

Links two MOD music or stream channels together.

BOOL BASS_ChannelSetLink(
    DWORD handle,
    DWORD chan
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
chan | The handle of the channel to have linked with it... a HMUSIC or HSTREAM.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | At least one of handle and chan is not a valid channel.
BASS_ERROR_DECODE | At least one of handle and chan is a "decoding channel", so cannot be linked.
BASS_ERROR_ALREADY | chan is already linked to handle.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Linked channels are started/stopped/paused/resumed together. Links are one-way; for example, channel chan will be started by channel handle, but not vice versa unless another link has been set in that direction.

If a linked channel has reached the end, it will not be restarted when a channel it is linked to is started. If you want a linked channel to be restarted, you need to have resetted its position using BASS_ChannelSetPosition beforehand.

Platform-specific

Except for when using DirectSound output on Windows, linked channels on the same device are guaranteed to start playing simultaneously. When using DirectSound output on Windows, it is possible for there to be a slight gap between them, but it will generally be shorter (and never longer) than starting them individually.

Example

Link 2 streams and play them together.
BASS_ChannelSetLink(stream1, stream2); // link stream2 to stream1
BASS_ChannelPlay(stream1, FALSE); // start both streams together

See also

BASS_ChannelRemoveLink


BASS_ChannelSetPosition

Sets the playback position of a sample, MOD music, or stream.

BOOL BASS_ChannelSetPosition(
    DWORD handle,
    QWORD pos,
    DWORD mode
);

Parameters

handle | The channel handle... a HCHANNEL, HSTREAM or HMUSIC.
pos | The position, in units determined by the mode.
modeHow to set the position. One of the following, with optional flags.
BASS_POS_BYTE | The position is in bytes, which will be rounded down to the nearest sample boundary.
BASS_POS_MUSIC_ORDER | The position is in orders and rows... use MAKELONG(order,row). (HMUSIC only)
BASS_POS_OGG | The position is a bitstream number in an OGG file... 0 = first.
BASS_POS_DECODETO | Flag: Decode/render up to the position rather than seeking to it. This is useful for streams that are unseekable or that have inexact seeking, but it is generally slower than normal seeking and the requested position cannot be behind the current decoding position. This flag can only be used with the BASS_POS_BYTE mode.
BASS_POS_INEXACT | Flag: Allow inexact seeking. For speed, seeking may stop at the beginning of a block rather than partially processing the block to reach the requested position.
BASS_POS_RELATIVE | Flag: The requested position is relative to the current position. pos is treated as signed in this case and can be negative.
BASS_POS_RESET | Flag: Reset user file buffers. This allows a user file stream with the BASS_STREAM_BLOCK flag set to be reset, so that it is ready to process new data. This flag can only be used with the BASS_POS_BYTE mode, and pos must be 0.
BASS_POS_SCAN | Flag: Scan the file to build a seek table up to the position, if it has not already been scanned. Scanning will continue from where it left off previously rather than restarting from the beginning of the file each time. This flag only applies to MP3/MP2/MP1 files and will be ignored with other file formats.
BASS_MUSIC_POSRESET | Flag: Stop all notes. This flag is applied automatically if it has been set on the channel, eg. via BASS_ChannelFlags. (HMUSIC)
BASS_MUSIC_POSRESETEX | Flag: Stop all notes and reset bpm/etc. This flag is applied automatically if it has been set on the channel, eg. via BASS_ChannelFlags. (HMUSIC)
other modes & flags may be supported by add-ons, see the documentation.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOTFILE | The stream is not a file stream.
BASS_ERROR_POSITION | The requested position is invalid, eg. it is beyond the end or the download has not yet reached it.
BASS_ERROR_NOTAVAIL | The requested mode is not available. Invalid flags are ignored and do not result in this error.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Setting the position of a MOD music in bytes (other than 0) requires that the BASS_MUSIC_PRESCAN flag was used in the BASS_MusicLoad call, or the use of the BASS_POS_DECODETO flag. When setting the position in orders and rows, the channel's byte position (as reported by BASS_ChannelGetPosition) is reset to 0. That is because it is not possible to get the byte position of an order/row position; it is possible for an order/row position to never be played in the normal course of events, or it may be played multiple times.

When setting the position of a MOD music, and the BASS_MUSIC_POSRESET flag is active, all notes that were playing before the position changed will be stopped. Otherwise, the notes will continue playing until they are stopped in the MOD music. When setting the position in bytes, the BPM, speed and global volume are updated to what they would normally be at the new position. Otherwise they are left as they were prior to the position change, unless the seek position is 0 (the start), in which case they are also reset to the starting values (with the BASS_MUSIC_POSRESET flag). When the BASS_MUSIC_POSRESETEX flag is active, the BPM, speed and global volume are reset with every seek.

For MP3/MP2/MP1 streams, unless the file is scanned via the BASS_POS_SCAN flag or the BASS_STREAM_PRESCAN flag at stream creation, seeking will be approximate but generally still quite accurate. Besides scanning, exact seeking can also be achieved with the BASS_POS_DECODETO flag.

Seeking in internet file (and "buffered" user file) streams is possible once the download has reached the requested position, so long as the file is not being streamed in blocks (BASS_STREAM_BLOCK flag).

The BASS_POS_RESET flag can be used to reset/flush a buffered user file stream, so that new data can be processed, but it may not be supported by some decoders. When it is not supported, BASS_StreamCreateFileUser can be used again instead to create a new stream for the new data.

User streams (created with BASS_StreamCreate) are not seekable, but it is possible to reset a user stream (including its buffer contents) by setting its position to byte 0.

The BASS_POS_DECODETO flag can be used to seek forwards in streams that are not normally seekable, like custom streams or internet streams that are using the BASS_STREAM_BLOCK flag, but it will only go as far as what is currently available; it will not wait for more data to be downloaded, for example.

In some cases, particularly when the BASS_POS_INEXACT flag is used, the new position may not be what was requested. BASS_ChannelGetPosition can be used to confirm what the new position actually is.

The BASS_POS_SCAN flag works the same way as the BASS_StreamCreateFile BASS_STREAM_PRESCAN flag, and can be used to delay the scanning until after the stream has been created. When a position beyond the end is requested, the call will fail (BASS_ERROR_POSITION error code) but the seek table and exact length will have been scanned. When a file has been scanned, all seeking (even without the BASS_POS_SCAN flag) within the scanned part of it will use the scanned infomation.

Example

Set the position of a channel to 1000000 bytes.
BASS_ChannelSetPosition(channel, 1000000, BASS_POS_BYTE);

Set the position of a MOD music to row 20 of order 10, and stop all currently playing notes.

BASS_ChannelSetPosition(music, MAKELONG(10, 20), BASS_POS_MUSIC_ORDER | BASS_MUSIC_POSRESET);

See also

BASS_ChannelFlags, BASS_ChannelGetLength, BASS_ChannelGetPosition, BASS_ChannelIsActive, BASS_ChannelSeconds2Bytes, BASS_ChannelUpdate


BASS_ChannelSetSync

Sets up a synchronizer on a MOD music, stream or recording channel.

HSYNC BASS_ChannelSetSync(
    DWORD handle,
    DWORD type,
    QWORD param,
    SYNCPROC *proc,
    void *user
);

Parameters

handle | The channel handle... a HMUSIC, HSTREAM or HRECORD.
typeThe type of sync (see the table below). The following flags may also be used.
BASS_SYNC_MIXTIME | Call the sync function immediately when the sync is triggered, instead of delaying the call until the sync event is actually heard. This is automatic with some sync types (see table below), and always with decoding and recording channels, as they cannot be played/heard.
BASS_SYNC_ONETIME | Call the sync only once and then remove it from the channel.
BASS_SYNC_THREAD | Call the sync asynchronously in the dedicated sync thread. This only affects mixtime syncs (except BASS_SYNC_FREE syncs) and allows the callback function to safely call BASS_StreamFree or BASS_MusicFree on the same channel handle.
param | The sync parameter. Depends on the sync type... see the table below.
proc | The callback function.
user | User instance data to pass to the callback function.

Sync types, with param and SYNCPROC data definitions.

BASS_SYNC_DEV_FAIL mixtime only | Sync when the channel's device stops unexpectedly (eg. if it is disconnected/disabled). When this happens, it will not be possible to resume a recording but it may be possible to resume playback via BASS_Start once the device becomes available again. param : not used. data : not used.
BASS_SYNC_DEV_FORMAT mixtime only | Sync when the sample format (sample rate and/or channel count) of the channel's device changes. The new format is available from BASS_GetInfo. param : not used. data : not used.
BASS_SYNC_DOWNLOAD mixtime only | Sync when downloading of an internet (or "buffered" user file) stream is done. param : not used. data : not used.
BASS_SYNC_END | Sync when a channel reaches the end, including when looping. Note that some MOD musics never reach the end; they may jump to another position first. If the BASS_MUSIC_STOPBACK flag is used with a MOD music (through BASS_MusicLoad or BASS_ChannelFlags), then this sync will also be called when a backward jump effect is played. param : not used. data : 1 = the sync is triggered by a backward jump in a MOD music, otherwise not used.
BASS_SYNC_FREE mixtime only | Sync when a channel is freed. This can be useful when you need to release some resources associated with the channel. Note that you will not be able to use any BASS functions with the channel in the callback, as the channel will no longer exist. param : not used. data : not used.
BASS_SYNC_META mixtime only | Sync when metadata is received in a Shoutcast stream. The updated metadata is available from BASS_ChannelGetTags. param : not used. data : not used.
BASS_SYNC_MUSICFX | Sync when the sync effect is used in a MOD music. The sync effect is E8x or Wxx for the XM/MTM/MOD formats, and S2x for the IT/S3M formats (where x = any value). param : 0 = the position is passed to the callback (data : LOWORD = order, HIWORD = row), 1 = the value of x is passed to the callback (data : x value).
BASS_SYNC_MUSICINST | Sync when an instrument (sample for the MOD/S3M/MTM formats) is played in a MOD music (not including retrigs). param : LOWORD = instrument (1=first), HIWORD = note (0=c0...119=b9, -1=all). data : LOWORD = note, HIWORD = volume (0-64).
BASS_SYNC_MUSICPOS | Sync when a MOD music reaches an order.row position. param : LOWORD = order (0=first, -1=all), HIWORD = row (0=first, -1=all). data : LOWORD = order, HIWORD = row.
BASS_SYNC_OGG_CHANGE | Sync when a new logical bitstream begins in a chained OGG stream. Updated tags are available from BASS_ChannelGetTags. param : not used. data : not used.
BASS_SYNC_POS | Sync when a channel reaches a position. param : position in bytes (automatically rounded down to nearest sample). data : not used.
BASS_SYNC_SETPOS | Sync when a channel's position is set, including when looping/restarting. param : not used. data : 0 = playback buffer is not flushed, 1 = playback buffer is flushed.
BASS_SYNC_SLIDE mixtime only | Sync when an attribute slide has ended. param : not used. data : the attribute that has finished sliding.
BASS_SYNC_STALL mixtime only | Sync when playback of the channel is stalled/resumed. param : not used. data : 0 = stalled, 1 = resumed.
other sync types may be supported by add-ons, see the documentation.

Return value

If successful, then the new synchronizer's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLTYPE | An illegal type was specified.
BASS_ERROR_ILLPARAM | An illegal param was specified.

Remarks

Multiple synchronizers may be used per channel, and they can be set before and while playing. Equally, synchronizers can also be removed at any time, using BASS_ChannelRemoveSync. If the BASS_SYNC_ONETIME flag is used then the sync is automatically removed after its first occurrence.

The BASS_SYNC_MIXTIME flag (without BASS_SYNC_THREAD) can be used with BASS_SYNC_END or BASS_SYNC_POS/MUSICPOS syncs to implement custom looping, by using BASS_ChannelSetPosition in the callback. A mixtime sync can also be used to make DSP/FX changes at specific points, or change a HMUSIC channel's flags or attributes. The BASS_SYNC_MIXTIME flag can also be useful with a BASS_SYNC_SETPOS sync, to reset DSP states after seeking.

Several of the sync types are triggered in the process of rendering the channel's sample data; for example, BASS_SYNC_POS and BASS_SYNC_END syncs, when the rendering reaches the sync position or the end, respectively. Those sync types should be set before starting playback or pre-buffering (ie. before any rendering), to avoid missing any early sync events.

A channel does not need to be playing for its BASS_SYNC_DEV_FAIL and BASS_SYNC_DEV_FORMAT syncs to be triggered but the device does need to be active, which means it needs to be playing other channels or the BASS_CONFIG_DEV_NONSTOP option needs to be enabled.

With recording channels, BASS_SYNC_POS syncs are triggered just before the RECORDPROC receives the block of data containing the sync position.

Platform-specific

The BASS_SYNC_DEV_FORMAT sync is only supported on Windows/OSX/iOS, but not when using DirectSound output on Windows. When using DirectSound output on Windows, it will not be possible to resume playback via BASS_Start following a BASS_SYNC_DEV_FAIL sync being triggered; the device will need to be reinitialized via BASS_Init.

Example

Do some processing until a MOD music reaches the 10th order.
BOOL order10 = FALSE; // the order 10 flag
...
// the sync callback
void CALLBACK MySyncProc(HSYNC handle, DWORD channel, DWORD data, void *user)
{
    order10 = TRUE; // set the order 10 flag
}
...
BASS_ChannelSetSync(music, BASS_SYNC_MUSICPOS | BASS_SYNC_ONETIME, MAKELONG(10, 0), MySyncProc, 0); // set the one-time order 10 sync
while (!order10) {
    // order 10 has not arrived, so do some processing
}
// order 10 has arrived!

Process metadata received from a Shoutcast stream.

char title[100] = ""; // the current stream title
...
// the sync callback
void CALLBACK MyMetaSyncProc(HSYNC handle, DWORD channel, DWORD data, void *user)
{
    const char *meta = BASS_ChannelGetTags(channel, BASS_TAG_META); // get metadata
    meta = strstr(meta, "StreamTitle='"); // look for title
    if (meta) { // found it, copy it...
        int a;
        meta += 13;
        for (a = 0; a < sizeof(title) - 1; a++) {
            if (meta[a] == ';' || !meta[a]) break;
            title[a] = meta[a];
        }
        title[a] = 0;
    }
}
...
BASS_ChannelSetSync(stream, BASS_SYNC_META, 0, MyMetaSyncProc, 0); // set the meta sync

See also

BASS_ChannelRemoveSync, SYNCPROC callback


BASS_ChannelSlideAttribute

Slides a channel's attribute from its current value to a new value.

BOOL BASS_ChannelSlideAttribute(
    DWORD handle,
    DWORD attrib,
    float value,
    DWORD time
);

Parameters

handle | The channel handle... a HCHANNEL, HSTREAM, HMUSIC, or HRECORD.
attribThe attribute to slide the value of... one of the following, with optional flags.
BASS_ATTRIB_EAXMIX | EAX wet/dry mix. (HCHANNEL/HMUSIC/HSTREAM only)
BASS_ATTRIB_FREQ | Sample rate.
BASS_ATTRIB_MUSIC_AMPLIFY | Amplification level. (HMUSIC)
BASS_ATTRIB_MUSIC_BPM | BPM. (HMUSIC)
BASS_ATTRIB_MUSIC_PANSEP | Pan separation level. (HMUSIC)
BASS_ATTRIB_MUSIC_PSCALER | Position scaler. (HMUSIC)
BASS_ATTRIB_MUSIC_SPEED | Speed. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_CHAN | A channel volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_GLOBAL | Global volume level. (HMUSIC)
BASS_ATTRIB_MUSIC_VOL_INST | An instrument/sample volume level. (HMUSIC)
BASS_ATTRIB_PAN | Panning/balance position.
BASS_ATTRIB_VOL | Volume level.
BASS_SLIDE_LOG | Flag: Slide the attribute's value logarthmically rather than linearly. This cannot be used when going from positive to negative or vice versa. An exception is when using a negative value with BASS_ATTRIB_VOL to fade-out and stop.
other attributes may be supported by add-ons, see the documentation.
value | The new attribute value. See the attribute's documentation for details on the possible values.
time | The length of time (in milliseconds) that it should take for the attribute to reach the value.

Return value

If successful, then TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_ILLTYPE | attrib is not valid.
BASS_ERROR_ILLPARAM | The attribute's value cannot go from positive to negative or vice versa when the BASS_SLIDE_LOG flag is used.
some attributes may have additional error codes, see the documentation.

Remarks

This function is similar to BASS_ChannelSetAttribute, except that the attribute is ramped to the value over the specified period of time. Another difference is that the value is not pre-checked. If it is invalid, the slide will simply end early.

If an attribute is already sliding, then the old slide is stopped and replaced by the new one.

BASS_ChannelIsSliding can be used to check if an attribute is currently sliding. A BASS_SYNC_SLIDE sync can also be set via BASS_ChannelSetSync, to be triggered at the end of a slide. The sync will not be triggered in the case of an existing slide being replaced by a new one.

Attribute slides are unaffected by whether the channel is playing, paused or stopped; they carry on regardless.

Example

Fadeout a channel's volume over a period of 1 second.
BASS_ChannelSlideAttribute(channel, BASS_ATTRIB_VOL, 0, 1000);

Fadeout a channel's volume logarithmically over a period of 2 seconds.

BASS_ChannelSlideAttribute(channel, BASS_ATTRIB_VOL | BASS_SLIDE_LOG, 0, 2000);

See also

BASS_ChannelGetAttribute, BASS_ChannelIsSliding, BASS_ChannelSetAttribute, BASS_ChannelSetSync


BASS_ChannelStop

Stops a sample, stream, MOD music, or recording.

BOOL BASS_ChannelStop(
    DWORD handle
);

Parameters

handle The channel handle... a HCHANNEL, HMUSIC, HSTREAM, or HRECORD.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not a valid channel.

Remarks

Stopping a user stream (created with BASS_StreamCreate) will clear its buffer contents, and stopping a sample channel (HCHANNEL) will result in it being freed. Use BASS_ChannelPause instead if you wish to stop a user stream or sample and then resume it from the same point.

When used with a decoding channel, this function will end the channel at its current position, so that it is not possible to decode any more data from it. Any BASS_SYNC_END syncs that have been set on the channel will not be triggered by this; they are only triggered when reaching the natural end. BASS_ChannelSetPosition can be used to reset the channel and start decoding again.

See also

BASS_ChannelIsActive, BASS_ChannelPause, BASS_ChannelPlay, BASS_RecordStart, BASS_SampleStop


BASS_ChannelUpdate

Updates the playback buffer of a stream or MOD music.

BOOL BASS_ChannelUpdate(
    DWORD handle,
    DWORD length
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
length | The amount of data to render, in milliseconds... 0 = default (2 x update period). This is capped at the space available in the buffer.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is not a valid channel.
BASS_ERROR_NOTAVAIL | Decoding channels do not have playback buffers.
BASS_ERROR_ENDED | The channel has ended.
BASS_ERROR_ALREADY | The channel is already being updated.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

When starting playback of a stream or MOD music, after creating it or changing its position, there will be a slight delay while the initial data is generated for playback. Usually the delay is not noticeable or important, but if you need playback to start instantly when you call BASS_ChannelPlay, then use this function first. The length parameter should be at least equal to the update period.

It may not always be possible to render the requested amount of data, in which case this function will still succeed. BASS_ChannelGetData (BASS_DATA_AVAILABLE) can be used to check how much data a channel has buffered for playback.

When automatic updating is disabled (BASS_CONFIG_UPDATEPERIOD = 0 or BASS_CONFIG_UPDATETHREADS = 0), this function could be used instead of BASS_Update to implement different update periods for different channels, instead of a single update period for all. Unlike BASS_Update, this function can also be used while automatic updating is enabled.

The CPU usage of this function is not included in the BASS_GetCPU reading, but is included in the channel's BASS_ATTRIB_CPU attribute value.

See also

BASS_ChannelPlay, BASS_Update


BASS_ATTRIB_EAXMIX attribute

The wet (reverb) / dry (no reverb) mix ratio of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_EAXMIX,
    float mix
);

Parameters

handle | The channel handle... a HCHANNEL, HMUSIC, HSTREAM.
mix | The wet / dry ratio... 0 (full dry) to 1 (full wet), -1 = automatically calculate the mix based on the distance (the default).

Additional error codes

BASS_ERROR_NOEAX The channel does not have EAX support. EAX only applies to 3D channels that are mixed by the hardware/drivers. BASS_ChannelGetInfo can be used to check if a channel is being mixed by the hardware.

Platform-specific

EAX is only supported on pre-Vista Windows.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_SetEAXParameters


BASS_ATTRIB_BITRATE attribute

The average bitrate of a file stream.

BASS_ChannelGetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_BITRATE,
    float *bitrate
);

Parameters

handle | The stream handle.
bitrate | The bitrate in kilobits per second (kbps).

Remarks

This attribute gives the average bitrate of the file's audio data. If the file also contains video, that is excluded from the bitrate calculation.

This attribute is read-only, so cannot be modified via BASS_ChannelSetAttribute.

See also

BASS_ChannelGetAttribute, BASS_StreamGetFilePosition


BASS_ATTRIB_BUFFER attribute

The playback buffering length.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_BUFFER,
    float buffer
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
buffer | The buffering length in seconds... 0 = no buffering. This is automatically capped to the full length of the channel's playback buffer.

Remarks

This attribute allows the amount of playback buffering to be changed without recreating the channel to get a new buffer. It limits how much data the update thread(s) or the BASS_Update function will try to keep in the playback buffer; it cannot exceed the length of the buffer, determined by the BASS_CONFIG_BUFFER setting at the time of its creation. BASS_ChannelUpdate is unaffected and can still be used to fill the entire buffer. Push streams (using STREAMPROC_PUSH) are also unaffected; they will always place as much data as possible in their playback buffers.

When this attribute is set to 0, no data will be buffered and the channel will only be asked to produce data as it is needed during the generation of the final mix. This allows the lowest latency to be achieved, but also imposes tighter timing requirements on the channel to produce its data and apply any DSP/FX (and run mixtime syncs) that are set on it; if too long is taken, there will be a break in the output, affecting all channels that are playing on the same device. The channel's data is still placed in its playback buffer, which allows BASS_ChannelGetData and BASS_ChannelGetLevel to be used, although there is likely to be less data available to them due to the buffer being less full.

This attribute can be changed mid-playback. Any excess data that is currently in the playback buffer will still be played but not replaced. Low (but not 0) settings may require the BASS_CONFIG_UPDATEPERIOD setting to be lowered too.

The default value is the channel's full playback buffer length, as determined by the BASS_CONFIG_BUFFER setting at the time of its creation.

Platform-specific

This attribute cannot be set to 0 (for no buffering) when using DirectSound output on Windows.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_CPU attribute

The CPU usage of a channel.

BASS_ChannelGetAttribute(
    DWORD handle,
    BASS_ATTRIB_CPU,
    float *cpu
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
cpu | The CPU usage.

Remarks

This attribute gives the percentage of CPU that the channel is using, including the time taken by decoding and DSP processing, and any FX that are not using the "with FX flag" DX8 effect implementation. It does not include the time taken to add the channel's data to the final output mix during playback. The processing of some add-on stream formats may also not be entirely included, if they use additional decoding threads; see the add-on documentation for details.

Like BASS_GetCPU, this function does not strictly tell the CPU usage, but rather how timely the processing is. For example, if it takes 10ms to generate 100ms of data, that would be 10%. If the reported usage exceeds 100%, that means the channel's data is taking longer to generate than to play. The duration of the data is based on the channel's current sample rate (BASS_ATTRIB_FREQ).

A channel's CPU usage is updated whenever it generates data. That could be during a playback buffer update cycle, or a BASS_Update call, or a BASS_ChannelUpdate call. For a decoding channel, it would be in a BASS_ChannelGetData or BASS_ChannelGetLevel call.

This attribute is read-only, so cannot be modified via BASS_ChannelSetAttribute.

See also

BASS_ChannelGetAttribute, BASS_GetCPU


BASS_ATTRIB_FREQ attribute

The sample rate of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_FREQ,
    float freq
);

Parameters

handle | The channel handle.
freq | The sample rate... 0 = original rate (when the channel was created).

Remarks

This attribute applies to playback of the channel, and does not affect the channel's sample data, so it has no real effect on decoding channels. It is still adjustable then though, so that it can be used by the BASSmix add-on and anything else that wants to use it.

It is not possible to change the sample rate of a channel if the "with FX flag" DX8 effect implementation enabled on it, unless DirectX 9 or above is installed.

Increasing the sample rate of a stream or MOD music increases its CPU usage, and reduces the length of its playback buffer in terms of time. If you intend to raise the sample rate above the original rate, then you may also need to increase the buffer length via the BASS_CONFIG_BUFFER config option to avoid break-ups in the sound.

When using BASS_ChannelSlideAttribute to slide this attribute, the BASS_SLIDE_LOG flag can be used to make a slide logarithmic rather than linear.

Platform-specific

When using DirectSound output on Windows, the sample rate will get rounded down to a whole number during playback.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_GetInfo


BASS_ATTRIB_GRANULE attribute

The processing granularity of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_GRANULE,
    float unit
);

Parameters

handle | The channel handle... a HMUSIC, HSTREAM, HRECORD.
unit | The processing unit size in sample frames... 0 = none.

Remarks

This attribute allows a channel's processing to be in units of a certain size, which can be helpful for some DSP processing. It does not apply to decoding channels or recording channels without a RECORDPROC; their procesing is controlled by BASS_ChannelGetData.

Each processing cycle will be on a whole number of units, not necessarily only one unit, and the number of units can vary between cycles depending on how much space there is in the channel's playback buffer (or captured data in a recording buffer). There might not be a whole number of units at the end of a file or when a stream stalls.

When granularity is enabled (non-0), it can change the timing of any DSP/FX changes that are made in mixtime sync callbacks. That is because the DSP/FX processing is done on the entire block of data at the end of the processing cycle then (rather than splitting it at the sync positions), to maintain the specified granularity, resulting in the changes effectively being applied at the start of the processing cycle.

The default value is 0 (none). Changes take immediate effect.

Example

Request a processing unit of 512 samples.
BASS_ChannelSetAttribute(stream, BASS_ATTRIB_GRANULE, 512);

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_MUSIC_ACTIVE attribute

The number of active channels in a MOD music.

BASS_ChannelGetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_ACTIVE,
    float *active
);

Parameters

handle | The MOD music handle.
active | The number of channels.

Remarks

This attribute gives the number of channels (including virtual) that are currently active in the decoder, which may not match what is being heard during playback due to buffering. This time difference can be reduced via the BASS_ATTRIB_BUFFER attribute.

This attribute is read-only, so cannot be modified via BASS_ChannelSetAttribute.

See also

BASS_ChannelGetAttribute, BASS_CONFIG_MUSIC_VIRTUAL


BASS_ATTRIB_MUSIC_AMPLIFY attribute

The amplification level of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_AMPLIFY,
    float amp
);

Parameters

handle | The MOD music handle.
amp | Amplification level... 0 (min) to 100 (max). This will be rounded down to a whole number.

Remarks

As the amplification level get's higher, the sample data's range increases, and therefore, the resolution increases. But if the level is set too high, then clipping can occur, which can result in distortion of the sound.

You can check the current level of a MOD music at any time by using BASS_ChannelGetLevel. By doing so, you can decide if a MOD music's amplification level needs adjusting.

The default amplification level is 50.

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute


BASS_ATTRIB_MUSIC_BPM attribute

The BPM of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_BPM,
    float bpm
);

Parameters

handle | The MOD music handle.
bpm | The BPM... 1 (min) to 255 (max). This will be rounded down to a whole number.

Remarks

This attribute is a direct mapping of the MOD's BPM, so the value can be changed via effects in the MOD itself.

Note that by changing this attribute, you are changing the playback length.

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_ATTRIB_MUSIC_SPEED


BASS_ATTRIB_MUSIC_PANSEP attribute

The pan separation level of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_PANSEP,
    float pansep
);

Parameters

handle | The MOD music handle.
pansep | Pan separation... 0 (min) to 100 (max), 50 = linear. This will be rounded down to a whole number.

Remarks

By default BASS uses a linear panning "curve". If you want to use the panning of FT2, use a pan separation setting of around 35. To use the Amiga panning (ie. full left and right) set it to 100.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute


BASS_ATTRIB_MUSIC_PSCALER attribute

The position scaler of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_PSCALER,
    float scale
);

Parameters

handle | The MOD music handle.
scale | The scaler... 1 (min) to 256 (max). This will be rounded down to a whole number.

Remarks

When getting the order position via BASS_ChannelGetPosition, the row will be scaled by this value. By using a higher scaler, you can get a more precise position indication.

The default position scaler is 1.

Example

Get the position of a MOD music accurate to within a 10th of a row.
DWORD pos, order, row, row10th;
BASS_ChannelSetAttribute(music, BASS_ATTRIB_MUSIC_PSCALER, 10); // set the scaler
pos = ChannelGetPosition(music, BASS_POS_MUSIC_ORDER);
order = LOWORD(pos); // the order
row = HIWORD(pos) / 10; // the row
row10th = HIWORD(pos) % 10; // the 10th of a row

See also

BASS_ChannelGetAttribute, BASS_ChannelGetPosition, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute


BASS_ATTRIB_MUSIC_SPEED attribute

The speed of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_SPEED,
    float speed
);

Parameters

handle | The MOD music handle.
speed | The speed... 0 (min) to 255 (max). This will be rounded down to a whole number.

Remarks

This attribute is a direct mapping of the MOD's speed, so the value can be changed via effects in the MOD itself.

The "speed" is the number of ticks per row. Setting it to 0, stops and ends the music. Note that by changing this attribute, you are changing the playback length.

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_ATTRIB_MUSIC_BPM


BASS_ATTRIB_MUSIC_VOL_CHAN attribute

The volume level of a channel in a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_VOL_CHAN + channel,
    float volume
);

Parameters

handle | The MOD music handle.
channel | The channel to set the volume of... 0 = 1st channel.
volume | The volume level... 0 (silent) to 1 (full).

Remarks

The volume curve used by this attribute is always linear, eg. 0.5 = 50%. The BASS_CONFIG_CURVE_VOL config option setting has no effect on this. The volume level of all channels is initially 1 (full).

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

This attribute can also be used to count the number of channels in a MOD Music.

Example

Count the number of channels in a MOD music.
int channels = 0;
float dummy;
while (BASS_ChannelGetAttribute(music, BASS_ATTRIB_MUSIC_VOL_CHAN + channels, &dummy))
    channels++;

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_ATTRIB_MUSIC_VOL_INST


BASS_ATTRIB_MUSIC_VOL_GLOBAL attribute

The global volume level of a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_VOL_GLOBAL,
    float volume
);

Parameters

handle | The MOD music handle.
volume | The global volume level... 0 (min) to 64 (max, 128 for IT format). This will be rounded down to a whole number.

Remarks

This attribute is a direct mapping of the MOD's global volume, so the value can be changed via effects in the MOD itself.

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_ATTRIB_MUSIC_AMPLIFY


BASS_ATTRIB_MUSIC_VOL_INST attribute

The volume level of an instrument in a MOD music.

BASS_ChannelSetAttribute(
    HMUSIC handle,
    BASS_ATTRIB_MUSIC_VOL_INST + inst,
    float volume
);

Parameters

handle | The MOD music handle.
inst | The instrument to set the volume of... 0 = 1st instrument.
volume | The volume level... 0 (silent) to 1 (full).

Remarks

The volume curve used by this attribute is always linear, eg. 0.5 = 50%. The BASS_CONFIG_CURVE_VOL config option setting has no effect on this. The volume level of all instruments is initially 1 (full). For MOD formats that do not use instruments, read "sample" for "instrument".

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. This latency can be reduced via the BASS_ATTRIB_BUFFER attribute.

This attribute can also be used to count the number of instruments in a MOD music.

Example

Count the number of instruments in a MOD music.
int instruments = 0;
float dummy;
while (BASS_ChannelGetAttribute(music, BASS_ATTRIB_MUSIC_VOL_INST + instruments, &dummy))
    instruments++;

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_ATTRIB_MUSIC_VOL_CHAN


BASS_ATTRIB_NET_RESUME attribute

The download buffer level required to resume stalled playback.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_NET_RESUME,
    float resume
);

Parameters

handle | The stream handle.
resume | The resumption level in percent... 0 - 100.

Remarks

This attribute determines what percentage of the download buffer (BASS_CONFIG_NET_BUFFER) needs to be filled before playback of a stalled internet stream will resume. It also applies to "buffered" user file streams created with BASS_StreamCreateFileUser. The buffering progress can be monitored with BASS_StreamGetFilePosition (BASS_FILEPOS_BUFFERING).

The default is 50%.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_CONFIG_NET_BUFFER


BASS_ATTRIB_NOBUFFER attribute

Disable playback buffering?

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_NOBUFFER,
    float nobuffer
);

Parameters

handle | The channel handle... a HMUSIC or HSTREAM.
nobuffer | Disable playback buffering... 0 = no, else yes.

Remarks

This sets the BASS_ATTRIB_BUFFER attribute to 0 (playback buffering disabled) or the full playback buffer length (playback buffering enabled).

Platform-specific

This attribute is not available when using DirectSound output on Windows, as BASS does not generate the final mix.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ATTRIB_BUFFER


BASS_ATTRIB_NORAMP attribute

Disable playback ramping?

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_NORAMP,
    float noramp
);

Parameters

handle | The channel handle.
noramp | Disable playback ramping... 0 = no, else yes.

Remarks

By default, a channel will be ramped-in when starting playback and ramped-out when stopping/pausing playback, to avoid sudden level changes that could result in a click sound each time. That ramping can be disabled by enabling this option. Volume (BASS_ATTRIB_VOL) and panning (BASS_ATTRIB_PAN) changes are always ramped regardless of this option setting. Ramping only applies during normal playback and does not affect decoding channels; it will not be present in the data delivered by BASS_ChannelGetData.

Ramping-in is skipped when a channel's sample data begins at a low level (so will not produce a click sound). Ramping-out requires data in the channel's playback buffer, so it generally does not apply when buffering has been disabled via the BASS_ATTRIB_BUFFER option unless the channel is a "push" stream or BASS_ChannelUpdate is used to pre-buffer some data.

Platform-specific

This attribute is not available when using DirectSound output on Windows, as BASS does not generate the final mix.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_PAN attribute

The panning/balance position of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_PAN,
    float pan
);

Parameters

handle | The channel handle.
pan | The pan position... -1 (full left) to +1 (full right), 0 = centre.

Remarks

This attribute applies to playback of the channel, and does not affect the channel's sample data, so it has no real effect on decoding channels. It is still adjustable then though, so that it can be used by the BASSmix add-on and anything else that wants to use it.

It is not possible to set the pan position of a 3D channel.

Platform-specific

When using DirectSound output on Windows, this attribute has no effect when speaker assignment is used, except on Windows Vista and newer with the BASS_CONFIG_VISTA_SPEAKERS config option enabled. Balance control could be implemented via a DSP function instead.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_CONFIG_CURVE_PAN


BASS_ATTRIB_SCANINFO attribute

The scanned info of a channel.

BASS_ChannelSetAttributeEx(
    DWORD handle,
    BASS_ATTRIB_SCANINFO,
    void *scaninfo,
    DWORD size
);

Parameters

handle | The channel handle.
scaninfo | The scanned info.
size | The size of the scanned info.

Remarks

This attribute is the information that is scanned from a file when the BASS_STREAM_PRESCAN flag is used in a BASS_StreamCreateFile call or when the BASS_POS_SCAN flag is used with BASS_ChannelSetPosition. It is supported on MP3/MP2/MP1 files and chained OGG files. It may be supported by add-ons too; see the documentation.

The structure of the scanned info may change in future versions, so if the data is stored, be prepared for BASS_ChannelSetAttributeEx to fail when trying to apply it; the file can be scanned again if that happens.

Example

Transfer scanned info from one stream to another stream of the same file.
DWORD size = BASS_ChannelGetAttributeEx(stream1, BASS_ATTRIB_SCANINFO, NULL, 0); // get the size
void *scaninfo = malloc(size); // allocate a buffer for the data
BASS_ChannelGetAttributeEx(stream1, BASS_ATTRIB_SCANINFO, scaninfo, size); // get the data
BASS_ChannelSetAttributeEx(stream2, BASS_ATTRIB_SCANINFO, scaninfo, size); // apply it to the other stream
free(scaninfo);

See also

BASS_ChannelGetAttributeEx, BASS_ChannelSetAttributeEx


BASS_ATTRIB_SRC attribute

The sample rate conversion quality of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_SRC,
    float quality
);

Parameters

handle | The channel handle.
quality | The sample rate conversion quality... 0 = linear interpolation, 1 = 8 point sinc interpolation, 2 = 16 point sinc interpolation, 3 = 32 point sinc interpolation, 4 = 64 point sinc interpolation. Other values are also accepted but will be interpreted as 0 or 4, depending on whether they are lower or higher.

Remarks

When a channel has a different sample rate to what the output device is using, the channel's sample data will need to be converted to match the output device's rate during playback. This attribute determines how that is done. The linear interpolation option uses less CPU, but the sinc interpolation gives better sound quality (less aliasing), with the quality and CPU usage increasing with the number of points. A good compromise for lower spec systems could be to use sinc interpolation for music playback and linear interpolation for sound effects.

Whenever possible, a channel's sample rate should match the output device's rate to avoid the need for any sample rate conversion. The device's sample rate could be used in BASS_StreamCreate or BASS_MusicLoad or MIDI stream creation calls, for example.

The sample rate conversion occurs (when required) during playback, after the sample data has left the channel's playback buffer, so it does not affect the data delivered by BASS_ChannelGetData. Although this attribute has no direct effect on decoding channels, it is still available so that it can be used by the BASSmix add-on and anything else that wants to use it.

This attribute can be set at any time, and changes take immediate effect. A channel's initial setting is determined by the BASS_CONFIG_SRC config option, or BASS_CONFIG_SRC_SAMPLE in the case of a sample channel.

Platform-specific

When using DirectSound output on Windows, sample rate conversion is handled by DirectSound or the output device/driver rather than BASS, so this setting has no effect on playback then.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_CONFIG_SRC, BASS_CONFIG_SRC_SAMPLE


BASS_ATTRIB_VOL attribute

The volume level of a channel.

BASS_ChannelSetAttribute(
    DWORD handle,
    BASS_ATTRIB_VOL,
    float volume
);

Parameters

handle | The channel handle.
volume | The volume level... 0 = silent, 1.0 = normal, above 1.0 = amplification.

Remarks

This attribute applies to playback of the channel and does not affect the channel's sample data, so has no direct effect on decoding channels. It is still adjustable then though, so that it can be used by the BASSmix add-on and anything else that wants to use it. The BASS_FX_VOLUME effect can be used via BASS_ChannelSetFX to change the level of a channel's sample data.

When using BASS_ChannelSlideAttribute to slide this attribute, a negative volume value can be used to fade-out and then stop the channel. When the linear volume curve is in use, the BASS_SLIDE_LOG flag can also be used to make a slide logarithmic rather than linear.

Platform-specific

When using DirectSound output on Windows, amplification is not supported so this attribute will be limited to 1.0. On platforms/architectures without floating-point support (see BASS_CONFIG_FLOAT), amplification is limited to 16x.

See also

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute, BASS_CONFIG_CURVE_VOL


DSPPROC callback

User defined DSP callback function.

void CALLBACK DSPProc(
    HDSP handle,
    DWORD channel,
    void *buffer,
    DWORD length,
    void *user
);

Parameters

handle | The DSP handle.
channel | Channel that the DSP is being applied to.
buffer | Pointer to the sample data to apply the DSP to. The data is as follows: 8-bit samples are unsigned, 16-bit samples are signed, 32-bit floating-point samples range from -1 to +1 (not clipped, so can actually be outside this range).
length | The number of bytes to process.
user | The user instance data given when BASS_ChannelSetDSP was called.

Remarks

The format of the sample data is as stated by BASS_ChannelGetInfo, except that it will always be floating-point if the BASS_CONFIG_FLOATDSP config option is enabled.

If the DSP processing requires a particular amount of data, the BASS_ATTRIB_GRANULE attribute can be used to specify that.

A DSP function should be as quick as possible, as any lengthy delays can result in stuttering playback. Some functions can cause problems if called from within a DSP function. Do not call BASS_Stop or BASS_Free from within a DSP callback, and do not call BASS_ChannelStop, BASS_MusicFree or BASS_StreamFree with the same channel handle as received by the callback.

Example

A DSP function to swap the left/right channels of a stereo 16-bit channel.
void CALLBACK SwapDSP(HDSP handle, DWORD channel, void *buffer, DWORD length, void *user)
{
    short *s = (short*)buffer;
    for (; length; length -= 4, s += 2) {
        short temp = s[0];
        s[0] = s[1];
        s[1] = temp;
    }
}

A panning/balance DSP function for a stereo 16-bit channel.

float pan; // panning position, set as you would the BASS_ATTRIB_PAN attribute

void CALLBACK PanDSP(HDSP handle, DWORD channel, void *buffer, DWORD length, void *user)
{
    short *s = (short*)buffer;
    if (!pan) return; // no processing neeeded for centre panning
    for (; length; length -= 4, s += 2) {
        if (pan < 0) s[1] = s[1] * (1 + pan); // pan left = reduce right
        else s[0] = s[0] * (1 - pan); // vice versa
    }
}

See also

BASS_ChannelSetDSP, BASS_ATTRIB_GRANULE, BASS_CONFIG_FLOATDSP


SYNCPROC callback

User defined synchronizer callback function.

void CALLBACK SyncProc(
    HSYNC handle,
    DWORD channel,
    DWORD data,
    void *user
);

Parameters

handle | The sync that has occurred.
channel | The channel that the sync occurred on.
data | Additional data associated with the sync's occurrence.
user | The user instance data given when BASS_ChannelSetSync was called.

Remarks

BASS creates a single thread dedicated to executing sync callback functions, so a callback function should be quick as other syncs cannot be processed until it has finished. Attribute slides (initiated with BASS_ChannelSlideAttribute) are also performed by the sync thread, so are also affected if a sync callback takes a long time.

"Mixtime" syncs are usually not executed in the sync thread (unless the BASS_SYNC_THREAD flag is used) but rather immediately in whichever thread triggers them. In most cases that will be an update thread, and so the same restrictions that apply to stream callbacks (STREAMPROC) also apply here, except that BASS_ChannelStop can be used in a BASS_SYNC_POS sync's callback to stop a channel at a particular position. Other exceptions are that the channel can be freed in a BASS_SYNC_DEV_FAIL or BASS_SYNC_DEV_FORMAT or BASS_SYNC_SLIDE sync's callback.

BASS_ChannelSetPosition can be used in a mixtime sync (without BASS_SYNC_THREAD set) to implement custom looping, eg. set a BASS_SYNC_POS sync at the loop end position and seek to the loop start position in the callback.

See also

BASS_ChannelSetSync


BASS_CHANNELINFO structure

Used with BASS_ChannelGetInfo to retrieve information on a channel.

typedef struct {
    DWORD freq;
    DWORD chans;
    DWORD flags;
    DWORD ctype;
    DWORD origres;
    HPLUGIN plugin;
    HSAMPLE sample;
    char *filename;
} BASS_CHANNELINFO;

Members

freq | Default playback rate.
chans | Number of channels... 1=mono, 2=stereo, etc.
flagsA combination of these flags.
BASS_SAMPLE_8BITS | The channel's resolution is 8-bit. If neither this or the BASS_SAMPLE_FLOAT flags are present, then the channel's resolution is 16-bit.
BASS_SAMPLE_FLOAT | The channel's resolution is 32-bit floating-point.
BASS_SAMPLE_LOOP | The channel is looped.
BASS_SAMPLE_3D | The channel has 3D functionality enabled.
BASS_SAMPLE_SOFTWARE | The channel is not using hardware DirectSound mixing.
BASS_SAMPLE_VAM | The channel is using the DX7 voice allocation and management features. (HCHANNEL only)
BASS_SAMPLE_MUTEMAX | The channel is muted when at (or beyond) its max distance.
BASS_SAMPLE_FX | The channel has the "with FX flag" DX8 effect implementation enabled. (HSTREAM/HMUSIC)
BASS_STREAM_RESTRATE | The internet file download rate is restricted. (HSTREAM)
BASS_STREAM_BLOCK | The internet file (or "buffered" user file) is streamed in small blocks. (HSTREAM)
BASS_STREAM_AUTOFREE | The channel will automatically be freed when it ends. (HSTREAM/HMUSIC)
BASS_STREAM_DECODE | The channel is a "decoding channel". (HSTREAM/HMUSIC/HRECORD)
BASS_MUSIC_RAMP | The MOD music is using "normal" ramping. (HMUSIC)
BASS_MUSIC_RAMPS | The MOD music is using "sensitive" ramping. (HMUSIC)
BASS_MUSIC_SURROUND | The MOD music is using surround sound. (HMUSIC)
BASS_MUSIC_SURROUND2 | The MOD music is using surround sound mode 2. (HMUSIC)
BASS_MUSIC_NONINTER | The MOD music is using non-interpolated mixing. (HMUSIC)
BASS_MUSIC_FT2MOD | The MOD music is using FastTracker 2 .MOD playback. (HMUSIC)
BASS_MUSIC_PT1MOD | The MOD music is using ProTracker 1 .MOD playback. (HMUSIC)
BASS_MUSIC_STOPBACK | The MOD music will be stopped when a backward jump effect is played. (HMUSIC)
BASS_SPEAKER_xxx | Speaker assignment flags. (HSTREAM/HMUSIC)
BASS_ASYNCFILE | The file is read asynchronously. (HSTREAM)
BASS_UNICODE | filename is in UTF-16 form.
other flags may be supported by add-ons, see the documentation.
ctypeThe type of channel it is, which can be one of the following.
BASS_CTYPE_SAMPLE | Sample channel. (HCHANNEL)
BASS_CTYPE_STREAM | User sample stream. This can also be used as a flag to test if the channel is any kind of HSTREAM.
BASS_CTYPE_STREAM_DUMMY | "dummy" stream (using STREAMPROC_DUMMY).
BASS_CTYPE_STREAM_DEVICE | "dummy" stream for device final output mix (using STREAMPROC_DEVICE).
BASS_CTYPE_STREAM_VORBIS | Ogg Vorbis format stream.
BASS_CTYPE_STREAM_MP1 | MPEG layer 1 format stream.
BASS_CTYPE_STREAM_MP2 | MPEG layer 2 format stream.
BASS_CTYPE_STREAM_MP3 | MPEG layer 3 format stream.
BASS_CTYPE_STREAM_AIFF | Audio IFF format stream.
BASS_CTYPE_STREAM_AM | Android media codec stream. Additional format information is avaliable from BASS_ChannelGetTags (BASS_TAG_AM_MIME).
BASS_CTYPE_STREAM_CA | CoreAudio codec stream. Additional format information is avaliable from BASS_ChannelGetTags (BASS_TAG_CA_CODEC).
BASS_CTYPE_STREAM_MF | Media Foundation codec stream. Additional format information is avaliable from BASS_ChannelGetTags (BASS_TAG_WAVEFORMAT).
BASS_CTYPE_STREAM_WAV_PCM | Integer PCM WAVE format stream.
BASS_CTYPE_STREAM_WAV_FLOAT | Floating-point PCM WAVE format stream.
BASS_CTYPE_STREAM_WAV | WAVE format flag. This can be used to test if the channel is any kind of WAVE format. The codec (the file's "wFormatTag") is specified in the LOWORD. Additional information is also avaliable from BASS_ChannelGetTags (BASS_TAG_WAVEFORMAT).
BASS_CTYPE_MUSIC_MOD | Generic MOD format music. This can also be used as a flag to test if the channel is any kind of HMUSIC.
BASS_CTYPE_MUSIC_MTM | MultiTracker format music.
BASS_CTYPE_MUSIC_S3M | ScreamTracker 3 format music.
BASS_CTYPE_MUSIC_XM | FastTracker 2 format music.
BASS_CTYPE_MUSIC_IT | Impulse Tracker format music.
BASS_CTYPE_MUSIC_MO3 | MO3 format flag, used in combination with one of the BASS_CTYPE_MUSIC types.
BASS_CTYPE_RECORD | Recording channel. (HRECORD)
other channel types may be supported by add-ons, see the documentation.
origres | The original resolution (bits per sample)... 0 = undefined. If the original sample format is floating-point, then the BASS_ORIGRES_FLOAT flag will be set and the number of bits will be in the LOWORD.
plugin | The plugin that is handling the channel... 0 = not using a plugin. Note this is only available with streams created using the plugin system via the standard BASS stream creation functions, not those created by add-on functions. Information on the plugin can be retrieved via BASS_PluginGetInfo.
sample | The sample that is playing on the channel. (HCHANNEL only)
filename | The filename associated with the channel. (HSTREAM only)

Remarks

The BASS_SAMPLE_SOFTWARE flag indicates whether or not the channel's sample data is being mixed into the final output by the hardware. It does not indicate whether the processing required to generate the sample data is being done by the hardware.

With a recording channel, the BASS_STREAM_DECODE flag indicates that it is not using a RECORDPROC callback function.

BASS supports 8/16/32-bit sample data, so if a WAV file, for example, uses another sample resolution, it will have to be converted by BASS. The origres member can be used to check what the resolution originally was.

Platform-specific

On Linux/OSX/iOS/Android, the BASS_UNICODE flag may not be present even if it was used in the stream's creation, as BASS will have translated the filename to the native UTF-8 form. On Windows CE, the opposite is true: the BASS_UNICODE flag may be present even if it was not used in the stream's creation, as BASS will have translated the filename to the native UTF-16 form.

Example

Check if a channel is an MP3 stream.
BASS_CHANNELINFO info;
BASS_ChannelGetInfo(channel, &info); // get info
if (info.ctype == BASS_CTYPE_STREAM_MP3) {
    // it's an MP3!
}

See also

BASS_ChannelGetInfo


TAG_APE_BINARY structure

APEv2 binary tag structure.

typedef struct {
    char *key;
    void *data;
    DWORD length;
} TAG_APE_BINARY;

Members

key | The name of the tag.
data | The tag data.
length | The size of data in bytes.

See also

BASS_ChannelGetTags


TAG_BEXT structure

BWF "bext" tag structure.

typedef struct {
    char Description[256];
    char Originator[32];
    char OriginatorReference[32];
    char OriginationDate[10];
    char OriginationTime[8];
    QWORD TimeReference;
    WORD Version;
    BYTE UMID[64];
    BYTE Reserved[190];
    char CodingHistory[];
} TAG_BEXT;

Members

Description | A free description of the sequence. To help applications which only display a short description, it is recommended that a summary of the description is contained in the first 64 characters, and the last 192 characters are used for details.
Originator | The name of the originator/producer of the audio file.
OriginatorReference | A non ambiguous reference allocated by the originating organization.
OriginationDate | The date of creation of the audio sequence, in the form of "yyyy-mm-dd" (year-month-day).
OriginationTime | The time of creation of the audio sequence, in the form of "hh-mm-ss" (hours-minutes-seconds).
TimeReference | The timecode of the sequence. The first sample count since midnight.
Version | The BWF version.
UMID | 64 bytes containing a UMID (Unique Material Identifier) to the SPMTE 330M standard. If only a 32 byte "basic UMID" is used, the last 32 bytes should be set to zero.
Reserved | Reserved for extensions.
CodingHistory | A series of CR/LF terminated strings, each containing a description of a coding process applied to the audio data.

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the TimeReference and Version members will need to be reversed on big-endian platforms. The UMID member is only available with BWF version 1 (and above).

See the BWF specification for further details.

See also

BASS_ChannelGetTags, TAG_CART structure


TAG_CART structure

BWF "cart" tag structure.

typedef struct {
    char Version[4];
    char Title[64];
    char Artist[64];
    char CutID[64];
    char ClientID[64];
    char Category[64];
    char Classification[64];
    char OutCue[64];
    char StartDate[10];
    char StartTime[8];
    char EndDate[10];
    char EndTime[8];
    char ProducerAppID[64];
    char ProducerAppVersion[64];
    char UserDef[64];
    DWORD dwLevelReference;
    TAG_CART_TIMER PostTimer[8];
    char Reserved[276];
    char URL[1024];
    char TagText[];
} TAG_CART;

Members

Version | Version of the data structure.
Title | Title of cart audio sequence.
Artist | Artist or creator name.
CutID | Cut number identification.
ClientID | Client identification.
Category | Category ID, PSA, NEWS, etc.
Classification | Classification or auxiliary key.
OutCue | Out cue text.
StartDate | Start date, in the form of "yyyy-mm-dd" (year-month-day).
StartTime | Start time, in the form of "hh-mm-ss" (hours-minutes-seconds).
EndDate | End date, in the form of "yyyy-mm-dd" (year-month-day).
EndTime | End time, in the form of "hh-mm-ss" (hours-minutes-seconds).
ProducerAppID | Name of vendor or application.
ProducerAppVersion | Version of producer application.
UserDef | User defined text.
dwLevelReference | Sample value for 0 dB reference.
PostTimer | 8 time markers after head.
Reserved | Reserved for extensions.
URL | Uniform resource locator.
TagText | Free form text for scripts or tags.

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the dwLevelReference and PostTimer members will need to be reversed on big-endian platforms.

See the "CartChunk" specification for further details.

See also

BASS_ChannelGetTags, TAG_BEXT structure, TAG_CART_TIMER structure


TAG_CART_TIMER structure

BWF "cart" tag timer structure.

typedef struct {
    DWORD dwUsage;
    DWORD dwValue;
} TAG_CART_TIMER;

Members

dwUsage | FOURCC timer usage ID.
dwValue | Timer value in samples from head.

See also

TAG_CART structure


TAG_CA_CODEC structure

CoreAudio codec information structure.

typedef struct {
    DWORD ftype;
    DWORD atype;
    char *name;
} TAG_CA_CODEC;

Members

ftype | File format identifier.
atype | Audio data format identifier.
name | Description of the audio file format.

Remarks

A list of file and audio data format identifiers is available from Apple, here. Additional formats may be available via third-party codecs.

See also

BASS_ChannelGetTags


TAG_CUE structure

RIFF "cue " tag structure.

typedef struct {
    DWORD dwCuePoints;
    TAG_CUE_POINT CuePoints[];
} TAG_CUE;

Members

dwCuePoints | Count of cue points
CuePoints | Cue point table.

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the members will need to be reversed on big-endian platforms.

See also

BASS_ChannelGetTags, TAG_CUE_POINT structure


TAG_CUE_POINT structure

RIFF "cue " tag cue point structure.

typedef struct {
    DWORD dwName;
    DWORD dwPosition;
    DWORD fccChunk;
    DWORD dwChunkStart;
    DWORD dwBlockStart;
    DWORD dwSampleOffset;
} TAG_CUE_POINT;

Members

dwName | Specifies the cue point name. Each record must have a unique dwName field.
dwPosition | Specifies the sample position of the cue point. This is the sequential sample number within the play order.
fccChunk | Specifies the name or chunk ID of the chunk containing the cue point.
dwChunkStart | Specifies the position of the start of the data chunk containing the cue point. This should be zero if there is only one chunk containing data (as is currently always the case).
dwBlockStart | Specifies the position of the start of the block containing the position. This is the byte offset from the start of the data section of the chunk, not the chunk’s FOURCC.
dwSampleOffset | Specifies the sample offset of the cue point relative to the start of the block.

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the members will need to be reversed on big-endian platforms.

See also

TAG_CUE structure


TAG_ID3 structure

ID3v1 tag structure.

typedef struct {
    char id[3];
    char title[30];
    char artist[30];
    char album[30];
    char year[4];
    char comment[30];
    BYTE genre;
} TAG_ID3;

Members

id | ID3v1 tag identifier... "TAG".
title | Song title.
artist | Artist name.
album | Album title.
year | Year.
comment | Comment. If the 30th character is non-null whilst the 29th character is null, then the 30th character is the track number and the comment is limited to the first 28 characters.
genre | Genre number. The number can be translated to a genre, using the list at www.id3.org.

Remarks

See www.id3.org/ID3v1 for further details.

Example

Display the title from a channel's ID3v1 tag.
const TAG_ID3 *id3 = (const TAG_ID3*)BASS_ChannelGetTags(channel, BASS_TAG_ID3); // get the ID3 tags
if (id3) printf("title = %.30s\n", id3->title); // display the title

See also

BASS_ChannelGetTags


TAG_SMPL structure

RIFF "smpl" tag structure.

typedef struct {
    DWORD dwManufacturer;
    DWORD dwProduct;
    DWORD dwSamplePeriod;
    DWORD dwMIDIUnityNote;
    DWORD dwMIDIPitchFraction;
    DWORD dwSMPTEFormat;
    DWORD dwSMPTEOffset;
    DWORD cSampleLoops;
    DWORD cbSamplerData;
    TAG_SMPL_LOOP SampleLoops[];
} TAG_SMPL;

Members

dwManufacturer | Specifies the MMA Manufacturer code for the intended target device. The high byte indicates the number of low order bytes (1 or 3) that are valid for the manufacturer code. For example, this value will be 0x01000013 for Digidesign (the MMA Manufacturer code is one byte, 0x13); whereas 0x03000041 identifies Microsoft (the MMA Manufacturer code is three bytes, 0x00 0x00 0x41). If the sample is not intended for a specific manufacturer, then this field should be set to zero.
dwProduct | Specifies the Product code of the intended target device for the dwManufacturer. If the sample is not intended for a specific manufacturer’s product, then this field should be set to zero.
dwSamplePeriod | Specifies the period of one sample in nanoseconds (normally 1/nSamplesPerSec from the WAVEFORMAT structure for the RIFF WAVE file--however, this field allows fine tuning). For example, 44.1 kHz would be specified as 22675 (0x00005893).
dwMIDIUnityNote | Specifies the MIDI note which will replay the sample at original pitch. This value ranges from 0 to 127 (a value of 60 represents Middle C as defined by the MMA).
dwMIDIPitchFraction | Specifies the fraction of a semitone up from the specified dwMIDIUnityNote. A value of 0x80000000 is 1/2 semitone (50 cents); a value of 0x00000000 represents no fine tuning between semitones.
dwSMPTEFormat | Specifies the SMPTE time format used in the dwSMPTEOffset field. Possible values are (unrecognized formats should be ignored): 0 - specifies no SMPTE offset (dwSMPTEOffset should also be zero), 24 - specifies 24 frames per second, 25 - specifies 25 frames per second, 29 - specifies 30 frames per second with frame dropping ("30 drop"), 30 - specifies 30 frames per second
dwSMPTEOffset | Specifies a time offset for the sample if it is to be syncronized or calibrated according to a start time other than 0. The format of this value is 0xhhmmssff. hh is a signed Hours value [-23..23]. mm is an unsigned Minutes value [0..59]. ss is unsigned Seconds value [0..59]. ff is an unsigned value [0..(dwSMPTEFormat - 1)].
cSampleLoops | Specifies the number (count) of TAG_SMPL_LOOP records that are contained in SampleLoops.
cbSamplerData | Specifies the size in bytes of the optional sampler-specific data. Sampler specific data is stored imediately following the SampleLoops records. The cbSamplerData field will be zero if no extended sampler specific information is stored in the chunk.
SampleLoops | Specifies the sample loop(s).

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the members will need to be reversed on big-endian platforms.

See also

BASS_ChannelGetTags, TAG_SMPL_LOOP structure


TAG_SMPL_LOOP structure

RIFF "smpl" tag sample loop structure.

typedef struct {
    DWORD dwIdentifier;
    DWORD dwType;
    DWORD dwStart;
    DWORD dwEnd;
    DWORD dwFraction;
    DWORD dwPlayCount;
} TAG_SMPL_LOOP;

Members

dwIdentifier | Identifies the unique ’name’ of the loop. This field may correspond with a name stored in a cue points ("cue ") chunk. The name data is stored in an associated data list ("adtl") chunk.
dwType | Specifies the loop type: 0 - Loop forward (normal), 1 - Alternating loop (forward/backward), 2 - Loop backward, 3-31 - reserved for future standard types, 32-? - sampler specific types (manufacturer defined)
dwStart | Specifies the startpoint of the loop in samples.
dwEnd | Specifies the endpoint of the loop in samples (this sample will also be played).
dwFraction | Allows fine-tuning for loop fractional areas between samples. Values range from 0x00000000 to 0xFFFFFFFF. A value of 0x80000000 represents 1/2 of a sample length.
dwPlayCount | Specifies the number of times.

Remarks

The structure is given by BASS_ChannelGetTags as it is in the RIFF file, which is little-endian, so the members will need to be reversed on big-endian platforms.

See also

TAG_SMPL structure


DX8 effect implementations

DX8 effects are otherwise known as DirectX Media Object (DMO) effects, and as the name suggests, requires DirectX 8 (or above) to be installed. BASS provides 2 different implementations of DX8 effects, each with its advantages. The method used by a channel depends on whether the BASS_SAMPLE_FX flag is used in its creation.

With the BASS_SAMPLE_FX flag

This is the standard way of using DX8 effects. The main advantage of this method is that effect parameter changes are audible instantaneously. The main disadvantages are that the channel's sample rate cannot be changed (can with DX9), and it cannot be used with decoding channels or speaker assignment.

Without the BASS_SAMPLE_FX flag

The advantages/disadvantages of this method are basically the opposite of the other method; the channel's sample rate can be changed, but there's a delay in effect parameter changes being audible. The reason being that, using this method, the effects are applied at the same stage as user DSP functions. There are also other advantages to this method, as shown in the table below.

 | With FX flag | Without FX flag
Adding & removing | Channel needs to be stopped when adding or removing an effect. | Can add and remove effects without stopping playback.
Decoding channels | Not possible. | Automatically used for decoding channels.
Speaker assignment | Not possible. | Can be used with speaker assignment.
Recording | Not possible. | Automatically used for recording channels.
Parameter changes | Audible instantaneously. | Delayed by the length of the channel's buffer; using a smaller buffer means less delay.
Channel sample rate | Can only be changed when using DirectX 9. | Can be changed.
Effected sample data | Not available. DSP functions, BASS_ChannelGetData and BASS_ChannelGetLevel receive the original data (without the effects applied). | The effected data is available to BASS functions.
Effect chain ordering | Not possible. | The effects can be applied in any order you want, and can be intermingled with DSP functions.
Channel buffer length | Must be at least 150ms. | No restriction.
CPU usage | CPU use is not included in BASS_GetCPU. | CPU use is included in BASS_GetCPU. Also slightly lower CPU usage.

In both cases, DX8 effects are not supported on channels that are more than stereo, and floating-point support requires DirectX 9.

Platform-specific

The "With FX flag" system is only available when using DirectSound output on Windows. Away from Windows, the DX8 effects are emulated by BASS, floating-point is supported, and the PARAMEQ effect also supports more than stereo.

See also

BASS_ChannelSetFX, BASS_MusicLoad, BASS_StreamCreate, BASS_StreamCreateFile, BASS_StreamCreateURL


BASS_FXGetParameters

Retrieves the parameters of an effect.

BOOL BASS_FXGetParameters(
    HFX handle,
    void *params
);

Parameters

handle | The effect handle.
params | Pointer to the parameters structure to fill. The structure used depends on the effect type.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is invalid.

See also

BASS_ChannelSetFX, BASS_FXSetParameters


BASS_FXReset

Resets the state of an effect or all effects on a channel.

BOOL BASS_FXReset(
    DWORD handle
);

Parameters

handle The effect or channel handle... a HFX, HSTREAM, HMUSIC, or HRECORD.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is invalid.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

This function flushes the internal buffers of the effect(s). Effects are automatically reset by BASS_ChannelSetPosition, except when called from a "mixtime" SYNCPROC.

See also

BASS_ChannelSetFX


BASS_FXSetParameters

Sets the parameters of an effect.

BOOL BASS_FXSetParameters(
    HFX handle,
    void *params
);

Parameters

handle | The effect handle.
params | Pointer to the parameters structure. The structure used depends on the effect type.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is invalid.
BASS_ERROR_ILLPARAM | One or more of the parameters are invalid, make sure all the values are within the valid ranges.
BASS_ERROR_UNKNOWN | Some other mystery problem!

See also

BASS_ChannelSetFX, BASS_FXGetParameters


BASS_FXSetPriority

Sets the priority of an effect or DSP function, which determines its position in the DSP chain.

BOOL BASS_FXSetPriority(
    DWORD handle,
    int priority
);

Parameters

handle | The DSP/FX handle... a HDSP or HFX.
priority | The new priority of the DSP/FX.

Return value

If successful, TRUE is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE | handle is invalid.
BASS_ERROR_NOTAVAIL | Priority is not supported on DX8 effects when the "with FX flag" DX8 effect implementation is used.

Remarks

If there are multiple DSP/FX with the same priority value, they will be applied in the order in which they were given that priority.

See also

BASS_ChannelSetDSP, BASS_ChannelSetFX


BASS_DX8_CHORUS structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 chorus effect.

typedef struct {
    float fWetDryMix;
    float fDepth;
    float fFeedback;
    float fFrequency;
    DWORD lWaveform;
    float fDelay;
    DWORD lPhase;
} BASS_DX8_CHORUS;

Members

fWetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet). The default value is 50.
fDepth | Percentage by which the delay time is modulated by the low-frequency oscillator (LFO). Must be in the range from 0 through 100. The default value is 10.
fFeedback | Percentage of output signal to feed back into the effect's input, in the range from -99 to 99. The default value is 25.
fFrequency | Frequency of the LFO, in the range from 0 to 10. The default value is 1.1.
lWaveform | Waveform of the LFO... 0 = triangle, 1 = sine. By default, the waveform is sine.
fDelay | Number of milliseconds the input is delayed before it is played back, in the range from 0 to 20. The default value is 16 ms.
lPhase | Phase differential between left and right LFOs, one of BASS_DX8_PHASE_NEG_180, BASS_DX8_PHASE_NEG_90, BASS_DX8_PHASE_ZERO, BASS_DX8_PHASE_90 and BASS_DX8_PHASE_180. The default value is BASS_DX8_PHASE_90.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_COMPRESSOR structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 compression effect.

typedef struct {
    float fGain;
    float fAttack;
    float fRelease;
    float fThreshold;
    float fRatio;
    float fPredelay;
} BASS_DX8_COMPRESSOR;

Members

fGain | Output gain of signal after compression, in the range from -60 to 60. The default value is 0 dB.
fAttack | Time before compression reaches its full value, in the range from 0.01 to 500. The default value is 10 ms.
fRelease | Speed at which compression is stopped after input drops below fThreshold, in the range from 50 to 3000. The default value is 200 ms.
fThreshold | Point at which compression begins, in decibels, in the range from -60 to 0. The default value is -20 dB.
fRatio | Compression ratio, in the range from 1 to 100. The default value is 3, which means 3:1 compression.
fPredelay | Time after fThreshold is reached before attack phase is started, in milliseconds, in the range from 0 to 4. The default value is 4 ms.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_DISTORTION structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 distortion effect.

typedef struct {
    float fGain;
    float fEdge;
    float fPostEQCenterFrequency;
    float fPostEQBandwidth;
    float fPreLowpassCutoff;
} BASS_DX8_DISTORTION;

Members

fGain | Amount of signal change after distortion, in the range from -60 through 0. The default value is -18 dB.
fEdge | Percentage of distortion intensity, in the range in the range from 0 through 100. The default value is 15 percent.
fPostEQCenterFrequency | Center frequency of harmonic content addition, in the range from 100 through 8000. The default value is 2400 Hz.
fPostEQBandwidth | Width of frequency band that determines range of harmonic content addition, in the range from 100 through 8000. The default value is 2400 Hz.
fPreLowpassCutoff | Filter cutoff for high-frequency harmonics attenuation, in the range from 100 through 8000. The default value is 8000 Hz.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_ECHO structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 echo effect.

typedef struct {
    float fWetDryMix;
    float fFeedback;
    float fLeftDelay;
    float fRightDelay;
    BOOL lPanDelay;
} BASS_DX8_ECHO;

Members

fWetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet). The default value is 50.
fFeedback | Percentage of output fed back into input, in the range from 0 through 100. The default value is 50.
fLeftDelay | Delay for left channel, in milliseconds, in the range from 1 through 2000. The default value is 500 ms.
fRightDelay | Delay for right channel, in milliseconds, in the range from 1 through 2000. The default value is 500 ms.
lPanDelay | Value that specifies whether to swap left and right delays with each successive echo. The default value is FALSE, meaning no swap.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_FLANGER structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 flanger effect.

typedef struct {
    float fWetDryMix;
    float fDepth;
    float fFeedback;
    float fFrequency;
    DWORD lWaveform;
    float fDelay;
    DWORD lPhase;
} BASS_DX8_FLANGER;

Members

fWetDryMix | Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from 0 through 100 (all wet). The default value is 50.
fDepth | Percentage by which the delay time is modulated by the low-frequency oscillator (LFO). Must be in the range from 0 through 100. The default value is 100.
fFeedback | Percentage of output signal to feed back into the effect's input, in the range from -99 to 99. The default value is -50.
fFrequency | Frequency of the LFO, in the range from 0 to 10. The default value is 0.25.
lWaveform | Waveform of the LFO... 0 = triangle, 1 = sine. By default, the waveform is sine.
fDelay | Number of milliseconds the input is delayed before it is played back, in the range from 0 to 4. The default value is 2 ms.
lPhase | Phase differential between left and right LFOs, one of BASS_DX8_PHASE_NEG_180, BASS_DX8_PHASE_NEG_90, BASS_DX8_PHASE_ZERO, BASS_DX8_PHASE_90 and BASS_DX8_PHASE_180. The default value is BASS_DX8_PHASE_ZERO.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_GARGLE structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a gargle DX8 (amplitude modulation) effect.

typedef struct {
    DWORD dwRateHz;
    DWORD dwWaveShape;
} BASS_DX8_GARGLE;

Members

dwRateHz | Rate of modulation, in Hertz. Must be in the range from 1 through 1000. The default value is 20.
dwWaveShape | Shape of the modulation waveform... 0 = triangle, 1 = square. By default, the waveform is triangle.

See also

BASS_ChannelSetFX, BASS_FXGetParameters,


BASS_DX8_I3DL2REVERB structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 I3DL2 (Interactive 3D Audio Level 2) reverberation effect.

typedef struct {
    int lRoom;
    int lRoomHF;
    float flRoomRolloffFactor;
    float flDecayTime;
    float flDecayHFRatio;
    int lReflections;
    float flReflectionsDelay;
    int lReverb;
    float flReverbDelay;
    float flDiffusion;
    float flDensity;
    float flHFReference;
} BASS_DX8_I3DL2REVERB;

Members

lRoom | Attenuation of the room effect, in millibels (mB), in the range from -10000 to 0. The default value is -1000 mB.
lRoomHF | Attenuation of the room high-frequency effect, in mB, in the range from -10000 to 0. The default value is -100 mB.
flRoomRolloffFactor | Rolloff factor for the reflected signals, in the range from 0 to 10. The default value is 0.0.
flDecayTime | Decay time, in seconds, in the range from 0.1 to 20. The default value is 1.49 seconds.
flDecayHFRatio | Ratio of the decay time at high frequencies to the decay time at low frequencies, in the range from 0.1 to 2. The default value is 0.83.
lReflections | Attenuation of early reflections relative to lRoom, in mB, in the range from -10000 to 1000. The default value is -2602 mB.
flReflectionsDelay | Delay time of the first reflection relative to the direct path, in seconds, in the range from 0 to 0.3. The default value is 0.007 seconds.
lReverb | Attenuation of late reverberation relative to lRoom, in mB, in the range from -10000 to 2000. The default value is 200 mB.
flReverbDelay | Time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds, in the range from 0 to 0.1. The default value is 0.011 seconds.
flDiffusion | Echo density in the late reverberation decay, in percent, in the range from 0 to 100. The default value is 100.0 percent.
flDensity | Modal density in the late reverberation decay, in percent, in the range from 0 to 100. The default value is 100.0 percent.
flHFReference | Reference high frequency, in hertz, in the range from 20 to 20000. The default value is 5000.0 Hz.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_PARAMEQ structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 parametric equalizer effect.

typedef struct {
    float fCenter;
    float fBandwidth;
    float fGain;
} BASS_DX8_PARAMEQ;

Members

fCenter | Center frequency, in hertz.
fBandwidth | Bandwidth, in semitones, in the range from 1 to 36. The default value is 12.
fGain | Gain, in the range from -15 to 15. The default value is 0 dB.

Platform-specific

On Windows, fCenter must be in the range of 80 to 16000, and not exceed one-third of the channel's sample rate. On other platforms, the range is above 0 and below half the channel's sample rate.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_DX8_REVERB structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a DX8 reverb effect.

typedef struct {
    float fInGain;
    float fReverbMix;
    float fReverbTime;
    float fHighFreqRTRatio;
} BASS_DX8_REVERB;

Members

fInGain | Input gain of signal, in decibels (dB), in the range from -96 through 0. The default value is 0 dB.
fReverbMix | Reverb mix, in dB, in the range from -96 through 0. The default value is 0 dB.
fReverbTime | Reverb time, in milliseconds, in the range from 0.001 through 3000. The default value is 1000.
fHighFreqRTRatio | High-frequency reverb time ratio, in the range from 0.001 through 0.999. The default value is 0.001.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters


BASS_FX_VOLUME_PARAM structure

Used with BASS_FXGetParameters and BASS_FXSetParameters to retrieve and set the parameters of a volume level effect.

typedef struct {
    float fTarget;
    float fCurrent;
    float fTime;
    DWORD lCurve;
} BASS_FX_VOLUME_PARAM;

Members

fTarget | The new volume level... 0 = silent, 1.0 = normal, above 1.0 = amplification. The default value is 1.
fCurrent | The current volume level... -1 = leave existing current level when setting parameters. The default value is 1.
fTime | The time to take to transition from the current level to the new level, in seconds. The default value is 0.
lCurve | The curve to use in the transition... 0 = linear, 1 = logarithmic. The default value is 0.

Remarks

The fTime value is based on the channel's original sample rate. If the playback rate is changed via the BASS_ATTRIB_FREQ attribute, then the transition time that is heard will be affected accordingly.

When retrieving parameters, the returned fCurrent value is the level that is currently being applied, not necessarily the level that was last set via BASS_FXSetParameters. During playback, it may not be the value that is currently being heard, due to buffering.

Unlike the BASS_ATTRIB_VOL attribute, this effect modifies the channel's sample data, so it can be used to change the level of decoding channels and recording channels. The BASS_CONFIG_CURVE_VOL setting does not affect this effect; the fTarget and fCurrent values are always linear.

See also

BASS_ChannelSetFX, BASS_FXGetParameters, BASS_FXSetParameters, BASS_ATTRIB_VOL


Floating-point channels

Channels can be made to use 32-bit floating-point sample data. When a channel uses floating-point sample data, BASS takes full advantage of the extra resolution when generating the decoded sample data; it does not simply convert 16-bit data to floating-point.

The main advantage of floating-point channels, aside from the increased resolution/quality, is that they are not clipped until output. This makes them particularly good for DSP/FX, because the quality is not degraded as the data passes through a chain of DSP/FX. So even if the output device is not capable of outputting the channel in its full quality, the quality is still improved.

Floating-point sample data ranges from -1 to +1, but as mentioned above, it is not clipped to this range until output, so it is possible that DSPPROC callback functions or BASS_ChannelGetData calls could receive data outside of this range.

When a floating-point channel is played, it is converted to whatever resolution the output device supports in the final mix.

Platform-specific

Floating-point channels are not supported when using VxD drivers (on Windows 98/95), except for "decoding channels". Windows Vista (and later) audio is natively floating-point, so for optimum performance (not to mention quality), BASS channels should also be floating-point. That particularly applies to formats that are decoded in floating-point anyway, ie. lossy formats like MP3 and OGG. It also applies to other platforms/architectures that support floating-point channels; the BASS_CONFIG_FLOAT option can be used to check that.

Example

Check for 32-bit floating-point channel support.
DWORD floatable; // floating-point channel support? 0 = no, else yes
...
if (BASS_GetConfig(BASS_CONFIG_FLOAT)) {
    floatable = BASS_StreamCreate(44100, 1, BASS_SAMPLE_FLOAT, NULL, NULL); // try creating a floating-point stream
    if (floatable) BASS_StreamFree(floatable); // floating-point channels are supported (free the test stream)
} else
    floatable = 0;

See also

BASS_MusicLoad, BASS_StreamCreate, BASS_StreamCreateFile, BASS_StreamCreateURL


Speaker assignment flags

Most soundcards these days are capable of more than plain stereo output. To take advantage of this, HSTREAM and HMUSIC channels can be assigned to specific speakers. For example, channels can be played on the front or rear speakers to effectively have 2 separate stereo outputs from the one device. A 3rd stereo output is available on 5.1 cards, and a 4th on 7.1 cards. The speakers member of the BASS_INFO structure can be used to check how many speakers are available.

Stereo speaker assignment flags

BASS_SPEAKER_FRONT | The front speakers.
BASS_SPEAKER_REAR | The rear/side speakers.
BASS_SPEAKER_CENLFE | The center and LFE (subwoofer) speakers in a 5.1 setup.
BASS_SPEAKER_REAR2 | The rear center speakers in a 7.1 setup.

Mono speaker assignment flags

BASS_SPEAKER_FRONTLEFT | The left-front speaker.
BASS_SPEAKER_FRONTRIGHT | The right-front speaker.
BASS_SPEAKER_REARLEFT | The left-rear/side speaker.
BASS_SPEAKER_REARRIGHT | The right-rear/side speaker.
BASS_SPEAKER_CENTER | The center speaker in a 5.1 speaker setup.
BASS_SPEAKER_LFE | The LFE (subwoofer) speaker in a 5.1 setup.
BASS_SPEAKER_REAR2LEFT | The left-rear center speaker in a 7.1 setup.
BASS_SPEAKER_REAR2RIGHT | The right-rear center speaker in a 7.1 setup.

As well as these defined speaker location flags, there is the BASS_SPEAKER_N(n) macro that can be used to access the extra speakers of soundcards that have more than 8 speakers, where n is the n'th pair of speakers (up to a maximum of 15). For example, BASS_SPEAKER_N(1) is equivalent to BASS_SPEAKER_FRONT. To use a speaker in mono, add the BASS_SPEAKER_LEFT or BASS_SPEAKER_RIGHT flags.

The stereo speaker assignment flags can also be used with mono channels, so that, for example, a mono channel can be played on both the front speakers. But mono speaker assignment flags cannot be used with stereo channels, so, for example, it is not possible to play a stereo channel on just the center speaker.

See also

BASS_ChannelFlags, BASS_MusicLoad, BASS_StreamCreate, BASS_StreamCreateFile, BASS_StreamCreateURL, Multi-channel streams


Multi-channel streams

Most soundcards these days are capable of more than plain stereo output. To take advantage of this, as well as the speaker assignment flags, BASS has support for multi-channel user streams, and also has built-in support for multi-channel OGG, WAV and AIFF files. Add-ons provide support for other multi-channel formats.

When a stream having more channels than there are speakers is played, the extra channels will generally not be heard, but may be heard on other speakers instead in some cases when using DirectSound output on Windows. The chans member of the BASS_CHANNELINFO structure can be used to check how many channels a stream has, and the speakers member of the BASS_INFO structure can be used to check how many speakers there are.

Platform-specific

On Windows prior to Vista, multi-channel streams require the output device to have WDM drivers installed.

See also

BASS_StreamCreate, STREAMPROC callback


BASSALAC

BASSALAC enables the decoding and playing of ALAC (Apple Lossless Audio Codec) encoded files. It can be downloaded from the BASS website: www.un4seen.com

The BASSALAC.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSALAC documentation from within this BASS documentation.


BASSCD

BASSCD enables digital streaming and ripping of audio CD tracks, and also includes analog playback support. It can be downloaded from the BASS website: www.un4seen.com

The BASSCD.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSCD documentation from within this BASS documentation.


BASSDSD

BASSDSD enables the decoding and playing of DSD (Direct Stream Digital) files and streams, including support for raw DSD and DSD-over-PCM output. It can be downloaded from the BASS website: www.un4seen.com

The BASSDSD.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSDSD documentation from within this BASS documentation.


BASSFLAC

BASSFLAC enables the decoding and playing of FLAC (Free Lossless Audio Codec) encoded files and streams. It can be downloaded from the BASS website: www.un4seen.com

The BASSFLAC.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSFLAC documentation from within this BASS documentation.


BASSHLS

BASSHLS enables the decoding and playing of HLS (HTTP Live Streaming) streams. It can be downloaded from the BASS website: www.un4seen.com

The BASSHLS.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSHLS documentation from within this BASS documentation.


BASSMIDI

BASSMIDI enables the playback of MIDI files and custom event sequences, using SF2 and SFZ soundfonts to provide the sounds. It also includes support for MIDI input. It can be downloaded from the BASS website: www.un4seen.com

The BASSMIDI.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSMIDI documentation from within this BASS documentation.


BASSOPUS

BASSOPUS enables the decoding and playing of Opus encoded files and streams. It can be downloaded from the BASS website: www.un4seen.com

The BASSOPUS.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSOPUS documentation from within this BASS documentation.


BASSWEBM

BASSWEBM enables the decoding and playing of WebM and Matroska files and streams. It can be downloaded from the BASS website: www.un4seen.com

The BASSWEBM.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSWEBM documentation from within this BASS documentation.


BASSWMA

BASSWMA enables the decoding and playing of WMA encoded files and streams. It also includes support for WMA encoding and broadcasting. It can be downloaded from the BASS website: www.un4seen.com

The BASSWMA.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSWMA documentation from within this BASS documentation.


BASSWV

BASSWV enables the decoding and playing of WavPack encoded files. It can be downloaded from the BASS website: www.un4seen.com

The BASSWV.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSWV documentation from within this BASS documentation.


BASSenc

BASSenc allows BASS channels to be encoded using command-line encoders with STDIN support (LAME/OGGENC/etc), or ACM codecs (on Windows) or CoreAudio codecs (on OSX/iOS) or user-provided encoders. As well as writing to file, it can serve the encoded data to clients via Shoutcast and Icecast servers or directly. It can also write plain PCM/WAV files. BASSenc itself also has add-ons available for FLAC / MP3 / Ogg Vorbis / OPUS encoding. They can be downloaded from the BASS website: www.un4seen.com

The BASSENC.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSenc documentation from within this BASS documentation.


BASSmix

BASSmix provides the ability to mix together multiple BASS channels, with resampling and matrix mixing features. It also provides the ability to split a BASS channel into multiple separate channels. It can be downloaded from the BASS website: www.un4seen.com

The BASSMIX.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSmix documentation from within this BASS documentation.


BASSWASAPI

BASSWASAPI adds the ability to use exclusive mode WASAPI input and output on Windows Vista and above. It can be downloaded from the BASS website: www.un4seen.com

The BASSWASAPI.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASSWASAPI documentation from within this BASS documentation.


BASS_FX

BASS_FX provides several effects, including tempo & pitch control. It can be downloaded from the BASS website: www.un4seen.com

The BASS_FX.CHM file should be copied into the same directory as this file (BASS.CHM), to be able to conveniently access the BASS_FX documentation from within this BASS documentation.