BASSMIDI 2.4
Copyright (c) 2006-2014 Un4seen Developments Ltd. All rights reserved.

Files that you should have found in the BASSMIDI package
========================================================
Win32 version
-------------
BASSMIDI.TXT    This file
BASSMIDI.DLL    BASSMIDI module
BASSMIDI.CHM    BASSMIDI documentation
X64\
  BASSMIDI.DLL    64-bit BASSMIDI module
C\              C/C++ API and examples...
  BASSMIDI.H      BASSMIDI C/C++ header file
  BASSMIDI.LIB    BASSMIDI import library
  BASSMIDI.DSW    Visual C++ 6 workspace for examples
  BASSMIDI.SLN    Visual C++ 2005 (and above) solution for examples
  MAKEFILE        Makefile for all examples
  MAKEFILE.IN     Makefile helper macros
  X64\
    BASSMIDI.LIB    64-bit BASSMIDI import library
  MIDITEST\       MIDI playback example
    MIDITEST.C
    MIDITEST.RC
    MIDITEST.DSP
    MIDITEST.VCPROJ
    MAKEFILE
  SF2PACK\        Soundfont packer
    SF2PACK.C
    SF2PACK.DSP
    SF2PACK.VCPROJ
    MAKEFILE
  SYNTH\          Real-time MIDI example
    SYNTH.C
    SYNTH.RC
    SYNTH.DSP
    SYNTH.VCPROJ
    MAKEFILE
  BIN\            Precompiled examples
    MIDITEST.EXE
    SF2PACK.EXE
    SYNTH.EXE
VB\             Visual Basic API and examples...
  BASSMIDI.BAS    BASSMIDI Visual Basic module
  MIDITEST\       MIDI playback example
    PRJMIDITEST.VBP
    FRMMIDITEST.FRM
    MODMIDITEST.BAS
DELPHI\         Delphi API and examples...
  BASSMIDI.PAS    BASSMIDI Delphi unit
  MIDITEST\       MIDI playback example
    MIDITEST.DPR
    UNIT1.PAS
    UNIT1.DFM
  SYNTH\          Real-time MIDI example
    SYNTH.DPR
    MAIN.PAS
    MAIN.DFM

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

NOTE: To build the examples, you will need to copy the BASS API into the
      same directory as the BASSMIDI API.

MacOSX version
--------------
BASSMIDI.TXT    This file
LIBBASSMIDI.DYLIB  BASSMIDI module
BASSMIDI.CHM    BASSMIDI documentation
BASSMIDI.H      BASSMIDI C/C++ header file
MAKEFILE        Makefile for all examples
MAKEFILE.IN     Makefile helper macros
BASSMIDI.XCODEPROJ  Xcode project for examples
MIDITEST\       MIDI playback example
  MIDITEST.C
  MIDITEST.NIB
  MAKEFILE
SF2PACK\        Soundfont packer
  SF2PACK.C
  MAKEFILE
SYNTH\          Real-time MIDI example
  SYNTH.C
  SYNTH.NIB
  MAKEFILE

NOTE: To build the examples, you will need to copy the BASS API into the
      same directory as the BASSMIDI API.

Linux version
-------------
BASSMIDI.TXT    This file
LIBBASSMIDI.SO  BASSMIDI module
BASSMIDI.CHM    BASSMIDI documentation
BASSMIDI.H      BASSMIDI C/C++ header file
MAKEFILE        Makefile for all examples
MAKEFILE.IN     Makefile helper macros
X64\
  LIBBASSMIDI.SO  64-bit BASSMIDI module
MIDITEST\       MIDI playback example
  MIDITEST.C
  MIDITEST.GLADE
  MAKEFILE
SF2PACK\        Soundfont packer
  SF2PACK.C
  MAKEFILE
SYNTH\          Real-time MIDI example
  SYNTH.C
  SYNTH.GLADE
  MAKEFILE

NOTE: To build the examples, you will need to copy the BASS API into the
      same directory as the BASSMIDI API.

What's the point?
=================
BASSMIDI is an extension to the BASS audio library, enabling the playing of
MIDI files and custom event sequences, using SF2 and/or SFZ soundfonts to
provide the sounds. MIDI input is also supported.

Requirements
============
BASS 2.4 is required.

Using BASSMIDI
==============
The MIDI format is used in very much the same way as any of the built-in BASS
stream formats; simply call the MIDI stream creation function instead of the
BASS built-in functions. The BASS plugin system (see BASS_PluginLoad) is also
supported.

SF2 soundfonts are used to provide the sounds. There are several soundfonts
available on the internet. One example (Chorium) is available from the BASS
webpage. On Windows, the Creative 28MB (28MBGM.SF2), 8MB (CT8MGM.SF2), 4MB
(CT4MGM.SF2), or 2MB (CT2MGM.SF2) soundfont will be used by default when
present in the Windows system directory. SFZ soundfonts are also supported.

The usage information in the BASS.TXT file (from the BASS package) is also
applicable to BASSMIDI and other add-ons.

TIP: The BASSMIDI.CHM file should be put in the same directory as the BASS.CHM
     file, so that the BASSMIDI documentation can be accessed from within the
     BASS documentation.

Latest Version
==============
The latest versions of BASSMIDI & BASS can be found at the BASS website:

    www.un4seen.com

Licence
=======
BASSMIDI is free to use with BASS.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, BASSMIDI 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 BASSMIDI. YOU USE
BASSMIDI ENTIRELY AT YOUR OWN RISK.

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

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

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 BASSMIDI interface are listed.

2.4.9 - 4/12/2014
-----------------
* SFZ soundfont support
    BASS_MIDI_FontInit/Ex
* Support for XG drums in bank 127 of SF2 soundfonts
    BASS_MIDI_FONT_XGDRUMS (BASS_MIDI_FontInit/Ex flag)
* Key pressure/aftertouch support
    MIDI_EVENT_KEYPRES (BASS_MIDI_StreamEvent/s)
    MIDI_EVENT_KEYPRES_VIBRATO/PITCH/FILTER/VOLUME (BASS_MIDI_StreamEvent/s)
* 3rd effect path for custom processing
    BASS_MIDI_CHAN_USERFX (BASS_MIDI_StreamGetChannel option)
    MIDI_EVENT_USERFX (BASS_MIDI_StreamEvent/s)
    MIDI_EVENT_USERFX_LEVEL (BASS_MIDI_StreamEvent/s)
    MIDI_EVENT_USERFX_REVERB (BASS_MIDI_StreamEvent/s)
    MIDI_EVENT_USERFX_CHORUS (BASS_MIDI_StreamEvent/s)
* Custom reverb/chorus effect processing
    BASS_MIDI_CHAN_CHORUS/REVERB (BASS_MIDI_StreamGetChannel options)
* Custom channel processing output routed to reverb/chorus/custom effects
    BASS_MIDI_StreamGetChannel
* Default drum reverb/chorus levels set to XG spec in XG mode (GS/GM modes too)
    MIDI_EVENT_DRUM_REVERB/CHORUS (BASS_MIDI_StreamEvent/s)
* Decay time event
    MIDI_EVENT_DECAY (BASS_MIDI_StreamEvent/s)
* Support for up to 65536 presets per bank
    BASS_MIDI_StreamSetFonts
    MIDI_EVENT_PROGRAM (BASS_MIDI_StreamEvent/s)
* Input ports to receive MIDI data from other software on Linux
    BASS_MIDI_InInit
    BASS_CONFIG_MIDI_IN_PORTS (BASS_SetConfig option)
    SYNTH example updated
* Single note releasing when there are overlapping instances of the same note
    BASS_MIDI_NOTEOFF1 (BASS_MIDI_StreamCreateFile/User/URL flag)
* Ignoring of system resets with unchanged mode
    BASS_MIDI_NOSYSRESET (BASS_MIDI_StreamCreateFile/User/URL flag)
    MIDI_EVENT_SYSTEM (BASS_MIDI_StreamEvent/s)
* Disabling of running status
    BASS_MIDI_EVENTS_NORSTATUS (BASS_MIDI_StreamEvents flag)
* Maximum voice limit increased to 1000
    BASS_CONFIG_MIDI_VOICES (BASS_SetConfig option)
    BASS_ATTRIB_MIDI_VOICES (BASS_ChannelSetAttribute option)
* Reduction of 24-bit data to 16-bit when packing soundfont samples
    BASS_MIDI_PACK_16BIT (BASS_MIDI_FontPack flag)
* Support for remaining SF2 generators: fixed key, fixed velocity, key to vol/mod envelope hold/decay
* Fix for multi-track custom event sequence stream creation
    BASS_MIDI_StreamCreateEvents

2.4.8 - 2/5/2013
----------------
* User file soundfont loading
    BASS_MIDI_FontInitUser
* Retrieval of all of a soundfont's preset numbers
    BASS_MIDI_FontGetPresets
* More flexible soundfont preset mapping
    BASS_MIDI_FONT_EX (BASS_MIDI_StreamSetFonts/GetFonts flag)
    BASS_MIDI_FONTEX structure
* Bank LSB controller support
    MIDI_EVENT_BANK_LSB (BASS_MIDI_StreamEvent/s)
    BASS_MIDI_FONTEX structure
* Modulation depth range control
    MIDI_EVENT_MODRANGE (BASS_MIDI_StreamEvent/s)
* Channel pressure destination control
    MIDI_EVENT_CHANPRES_VIBRATO/PITCH/FILTER/VOLUME (BASS_MIDI_StreamEvent/s)
* Unhandled controller event
    MIDI_EVENT_CONTROL (BASS_MIDI_StreamEvent/s)
* Reverb send level default changed to 40 (was 0)
    MIDI_EVENT_REVERB (BASS_MIDI_StreamEvent/s)
* Retrieval of events from all tracks at once
    BASS_MIDI_StreamGetEvents
* Copyright/instrument/track name markers
    BASS_MIDI_MARK_COPY (BASS_MIDI_StreamGetMark type)
    BASS_MIDI_MARK_INST (BASS_MIDI_StreamGetMark type)
    BASS_MIDI_MARK_TRACK (BASS_MIDI_StreamGetMark type)
* Retrieval of all markers at once
    BASS_MIDI_StreamGetMarks
* New sync type that supports all marker types
    BASS_SYNC_MIDI_MARK (BASS_ChannelSetSync type)
* Non-removal of empty space at the end of a MIDI file
    BASS_MIDI_NOCROP (BASS_MIDI_StreamCreateFile/User/URL flag)
* Omission of a WAVE header when packing soundfont samples
    BASS_MIDI_PACK_NOHEAD (BASS_MIDI_FontPack flag)
* Streams created via the plugin system use the output device's sample rate
    BASS_StreamCreateFile/etc
* Automatic BASS_UNICODE flag use in C++ and Delphi
    BASS_MIDI_StreamCreateFile/URL
    BASS_MIDI_FontInit/Pack/Unpack

2.4.7 - 29/6/2012
-----------------
* Custom event sequence streams
    BASS_MIDI_StreamCreateEvents
* Sinc interpolated sample mixing
    BASS_MIDI_SINCINTER (BASS_MIDI_StreamCreate/Events/File/User/URL flag)
* Asynchronous sample loading
    BASS_ATTRIB_MIDI_CPU
* Preset unloading
    BASS_MIDI_FontUnload
* Note stopping without sustain/decay
    BASS_EVENT_NOTE (BASS_MIDI_StreamEvent/s)
* Syncing on all event types
    BASS_SYNC_MIDI_EVENT (BASS_ChannelSetSync type)
* Marker tick position retrieval
    BASS_MIDI_MARK_TICK (BASS_MIDI_StreamGetMark flag)
* Maximum voice limit increased to 500
    BASS_CONFIG_MIDI_VOICES (BASS_SetConfig option)
    BASS_ATTRIB_MIDI_VOICES (BASS_ChannelSetAttribute option)
* Default voice limit raised to 40 on Android/iOS
    BASS_CONFIG_MIDI_VOICES (BASS_SetConfig option)
* Active voice count retrieval
    BASS_ATTRIB_MIDI_VOICES_ACTIVE (BASS_ChannelGetAttribute option)
* Use of the device's current output rate
    BASS_MIDI_StreamCreate/Events/File/User/URL
* Memory-mapped soundfont loading
    BASS_MIDI_FONT_MMAP (BASS_MIDI_FontInit flag)
* Fix for applying multiple events in BASS_MIDI_EVENTS_STRUCT mode
    BASS_MIDI_StreamEvents
* Marker sync compatibility (with mixer/splitter/tempo/reverse streams) fix
    BASS_SYNC_MIDI_MARKER/CUE/LYRIC (BASS_ChannelSetSync types)
* MIDI sysex input compatibility fix for some drivers on Windows
    MIDIINPROC

2.4.6 - 30/3/2011
-----------------
* MIDI input device support
    BASS_MIDI_InGetDeviceInfo
    BASS_MIDI_InInit
    BASS_MIDI_InFree
    BASS_MIDI_InStart
    BASS_MIDI_InStop
    MIDIINPROC
    SYNTH example updated
* Multiple event processing including support for raw MIDI data
    BASS_MIDI_StreamEvents
* CPU usage limiting
    BASS_ATTRIB_MIDI_CPU (BASS_ChannelSetAttribute option)
* Scale/octave tuning
    MIDI_EVENT_SCALETUNING (BASS_MIDI_StreamEvent/s)
* Soft pedal event
    MIDI_EVENT_SOFT (BASS_MIDI_StreamEvent/s)
* Random panning
    MIDI_EVENT_PAN (BASS_MIDI_StreamEvent/s)
* System reset event
    MIDI_EVENT_SYSTEM/EX (BASS_MIDI_StreamEvent/s)
* Resetting of overridden drum key pan/reverb/chorus back to normal
    MIDI_EVENT_DRUM_PAN/REVERB/CHORUS (BASS_MIDI_StreamEvent)
* Retrieval of drum key event values
    BASS_MIDI_StreamGetEvent
* All events initialized to a MIDI file's 1st tick values
    BASS_MIDI_StreamGetEvent
* Adjustable MIDI channel count
    BASS_ATTRIB_MIDI_CHANS (BASS_ChannelSetAttribute option)
* Adjustable voice limit
    BASS_ATTRIB_MIDI_VOICES (BASS_ChannelSetAttribute option)
* Preloaded presets are not automatically compacted
    BASS_MIDI_FontLoad
    BASS_CONFIG_MIDI_COMPACT (BASS_SetConfig option)
* Multiple instances of a soundfont
    BASS_MIDI_FontInit
* Xcode examples project added for OSX

2.4.5 - 8/2/2010
----------------
* Key signature retrieval
    BASS_MIDI_MARK_KEYSIG (BASS_MIDI_StreamGetMark type)
    BASS_SYNC_MIDI_KEYSIG (BASS_ChannelSetSync type)
* Tempo event initialized to MIDI file's 1st tick value
    MIDI_EVENT_TEMPO (BASS_MIDI_StreamGetEvent)
* UTF-16 support on OSX
    BASS_UNICODE (BASS_MIDI_StreamCreateFile/BASS_MIDI_FontInit/Pack/Unpack flag)

2.4.4 - 24/8/2009
-----------------
* Attack & release time events
    MIDI_EVENT_ATTACK/RELEASE (BASS_MIDI_StreamEvent)
* Drum key level NRPN event
    MIDI_EVENT_DRUM_LEVEL (BASS_MIDI_StreamEvent)
* MIDI file event retrieval
    BASS_MIDI_StreamGetEvents
* Time signature retrieval
    BASS_MIDI_MARK_TIMESIG (BASS_MIDI_StreamGetMark type)
    BASS_SYNC_MIDI_TIMESIG (BASS_ChannelSetSync type)
* Default soundfont configuration
    BASS_CONFIG_MIDI_DEFFONT (BASS_SetConfig option)

2.4.3 - 19/3/2009
-----------------
* Possibility of applying DSP/FX to individual MIDI channels
    BASS_MIDI_StreamGetChannel
* Per-track volume control
    BASS_ATTRIB_MIDI_TRACK_VOL (BASS_ChannelSetAttribute option)
* Support for all tracks in format 2 MIDI files
    BASS_MIDI_StreamCreateFile/User/URL

2.4.2 - 28/10/2008
------------------
* Decaying of old sound when seeking
    BASS_MIDI_DECAYSEEK (BASS_MIDI_StreamCreateFile/User/URL flag)
    MIDITEST example updated (C version)
* End decaying now also applies when looping
    BASS_MIDI_DECAYEND (BASS_MIDI_StreamCreateFile/User/URL flag)
* Support for 28MBGM.SF2 and CT8MGM.SF2 as default soundfonts

2.4.1 - 9/7/2008
----------------
* Ticks-per-beat retrieval
    BASS_ATTRIB_MIDI_PPQN (BASS_ChannelGetAttribute option)

2.4 - 2/4/2008
--------------
* Tick-based positioning
    BASS_POS_MIDI_TICK (BASS_ChannelGetLength/GetPosition/SetPosition mode)
    BASS_SYNC_MIDI_TICK (BASS_ChannelSetSync type)
* Preset name retrieval
    BASS_MIDI_FontGetPreset
* Text markers
    BASS_MIDI_MARK_TEXT (BASS_MIDI_StreamGetMark type)
    BASS_SYNC_MIDI_TEXT (BASS_ChannelSetSync type)
* Individual marker retrieval
    BASS_MIDI_StreamGetMark
    BASS_MIDI_StreamGetMarks *removed*
* Marker index passed to marker sync callbacks
    BASS_SYNC_MIDI_MARKER/CUE/LYRIC
* Use of BASS_Init sample rate
    BASS_MIDI_StreamCreate/File/User/URL
* Support for updated user file stream system
    BASS_MIDI_StreamCreateFileUser
* 64-bit file positioning
    BASS_MIDI_StreamCreateFile
* Callback "user" parameters changed to pointers
    BASS_MIDI_StreamCreateURL
    BASS_MIDI_StreamCreateFileUser

2.3.0.3 - 10/7/2007
-------------------
* Syncing on events
    BASS_SYNC_MIDI_EVENT (BASS_ChannelSetSync type)

2.3.0.2 - 26/2/2007
-------------------
* Reverb and chorus
    MIDI_EVENT_REVERB/CHORUS (BASS_MIDI_StreamEvent)
    MIDI_EVENT_REVERB_TIME/DELAY/LOCUTOFF/HICUTOFF/LEVEL (BASS_MIDI_StreamEvent)
    MIDI_EVENT_CHORUS_DELAY/DEPTH/RATE/FEEDBACK/LEVEL/REVERB (BASS_MIDI_StreamEvent)
    BASS_MIDI_NOFX (BASS_MIDI_StreamCreate/File/User/URL flag)
* Resonant low-pass filters
    MIDI_EVENT_CUTOFF/RESONANCE (BASS_MIDI_StreamEvent)
* Portamento
    MIDI_EVENT_PORTAMENTO/TIME/NOTE (BASS_MIDI_StreamEvent)
* Fine-tuning
    MIDI_EVENT_FINETUNE/COARSETUNE (BASS_MIDI_StreamEvent)
* Drum key specific parameters
    MIDI_EVENT_DRUM_FINETUNE/COARSETUNE/PAN/REVERB/CHORUS/CUTOFF/RESONANCE (BASS_MIDI_StreamEvent)
* Support for mono channel mode
    MIDI_EVENT_MODE (BASS_MIDI_StreamEvent)
* Support for master volume
    MIDI_EVENT_MASTERVOL (BASS_MIDI_StreamEvent)
* Channel level control
    MIDI_EVENT_MIXLEVEL (BASS_MIDI_StreamEvent)
* Channel transposing
    MIDI_EVENT_TRANSPOSE (BASS_MIDI_StreamEvent)
* Retrieval of current event values
    BASS_MIDI_StreamGetEvent
* Soundfont volume control
    BASS_MIDI_FontSetVolume/GetVolume
* Track number added to markers and syncs
    BASS_MIDI_MARK (track member)
    BASS_SYNC_MIDI_MARKER/CUE/LYRIC

2.3.0.1 - 1/12/2006
-------------------
* Optionally apply matching soundfonts to all banks
    BASS_CONFIG_MIDI_AUTOFONT (BASS_SetConfig option)
* Support for 0 length notes

2.3 - 14/11/2006
----------------
* First release

Bug reports, Suggestions, Comments, Enquiries, etc...
=====================================================
If you have any of the aforementioned please visit the BASS forum at
the website.


BASS_CONFIG_MIDI_AUTOFONT config option

Automatically load matching soundfonts?

BASS_SetConfig(
    BASS_CONFIG_MIDI_AUTOFONT,
    DWORD autofont
);

Parameters

autofont If set to 1, BASSMIDI will try to load a soundfont matching the MIDI file. If set to 2, the matching soundfont will also be used on all banks.

Remarks

When enabled, BASSMIDI will check for a matching soundfont when loading a MIDI file. For example, if the MIDI file is "afile.mid", then it will look for a soundfont named "afile.sf2" or "afile.mid.sf2". If found, this soundfont will take precedence over any other soundfonts applied via BASS_MIDI_StreamSetFonts.

When the soundfont is used on all banks (autofont=2), BASSMIDI will first check for the specific bank and preset in the soundfont, but if it does not find that, it will just look for a preset match on any bank.

This option only applies to local MIDI files, loaded using BASS_MIDI_StreamCreateFile (or BASS_StreamCreateFile via the plugin system). BASSMIDI will not look for matching soundfonts for MIDI files loaded from the internet.

By default, this option is set to 1.

See also

BASS_MIDI_StreamCreateFile

BASS_GetConfig, BASS_SetConfig


BASS_CONFIG_MIDI_COMPACT config option

Automatically compact all soundfonts following a configuration change?

BASS_SetConfig(
    BASS_CONFIG_MIDI_COMPACT,
    BOOL compact
);

Parameters

compact If TRUE, all soundfonts are compacted following a MIDI stream being freed, or a BASS_MIDI_StreamSetFonts call.

Remarks

The compacting is not performed immediately upon a MIDI stream being freed or BASS_MIDI_StreamSetFonts being called, but rather 2 seconds later (in another thread), so that if another MIDI stream immediately starts using the soundfonts, they are not needlessly closed and reopened.

Samples that have been preloaded by BASS_MIDI_FontLoad are not affected by automatic compacting. Other samples that have been preloaded by BASS_MIDI_StreamLoadSamples are affected though, so it is probably wise to disable this option when using that function.

By default, this option is enabled.

See also

BASS_MIDI_FontCompact

BASS_GetConfig, BASS_SetConfig


BASS_CONFIG_MIDI_DEFFONT config option

The default soundfont.

BASS_SetConfigPtr(
    BASS_CONFIG_MIDI_DEFFONT,
    char *filename
);

Parameters

filename Filename of the soundfont... NULL = no default soundfont.

Remarks

When setting the default soundfont, a copy is made of the filename, so it does not need to persist beyond the BASS_SetConfigPtr call. If the specified soundfont cannot be loaded, the default soundfont setting will remain as it is. BASS_GetConfigPtr can be used to confirm what that is.

Platform-specific

On Windows, the default is to use one of the Creative soundfonts (28MBGM.SF2 or CT8MGM.SF2 or CT4MGM.SF2 or CT2MGM.SF2), if present in the Windows system directory.

See also

BASS_MIDI_StreamCreateFile

BASS_GetConfigPtr, BASS_SetConfigPtr


BASS_CONFIG_MIDI_IN_PORTS config option

The number of MIDI input ports to make available.

BASS_SetConfig(
    BASS_CONFIG_MIDI_IN_PORTS,
    DWORD ports
);

Parameters

ports Number of input ports... 0 (min) - 10 (max).

Remarks

MIDI input ports allow MIDI data to be received from other software, not only MIDI devices. Once a port has been initialized via BASS_MIDI_InInit, the ALSA client and port IDs can be retrieved from BASS_MIDI_InGetDeviceInfo, which other software can use to connect to the port and send data to it. Prior to initialization, an input port will have a client ID of 0.

The default is for 1 input port to be available.

Platform-specific

This option is only available on Linux.

See also

BASS_MIDI_InGetDeviceInfo, BASS_MIDI_InInit

BASS_GetConfig, BASS_SetConfig


BASS_CONFIG_MIDI_VOICES config option

The maximum number of samples to play at a time.

BASS_SetConfig(
    BASS_CONFIG_MIDI_VOICES,
    DWORD voices
);

Parameters

voices Maximum number of samples to play at a time... 1 (min) - 1000 (max).

Remarks

This setting determines the maximum number of samples that can play together in a single MIDI stream. This is not necessarily the same thing as the maximum number of notes, due to presets possibly containing multiple layered samples, ie. multiple samples may be played for a single note. When the voice limit is hit, the voice with the lowest volume level will be killed, which will usually be one that is already fading out following a note release.

The more voices that are used, the more CPU that is required. So this option can be used to restrict that, for example on a lower spec system. The BASS_ATTRIB_MIDI_CPU attribute can also be used to limit CPU usage.

Changing this setting only affects subsequently created MIDI streams, not any that already exist. The voice limit of an existing MIDI stream can be changed via the BASS_ATTRIB_MIDI_VOICES attribute.

Platform-specific

The default setting is 100, except on iOS and Android where it is 40.

See also

BASS_MIDI_StreamCreateFile, BASS_ATTRIB_MIDI_CPU, BASS_ATTRIB_MIDI_VOICES

BASS_GetConfig, BASS_SetConfig


BASS_MIDI_StreamCreate

Creates a sample stream to render real-time MIDI events.

HSTREAM BASS_MIDI_StreamCreate(
    DWORD channels,
    DWORD flags,
    DWORD freq
);

Parameters

channels | The number of MIDI channels... 1 (min) - 128 (max). The number of channels can subsequently be changed via the BASS_ATTRIB_MIDI_CHANS attribute.
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 more info.
BASS_SAMPLE_MONO | Decode/play the MIDI 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 stream to not use hardware 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 stream.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_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_MIDI_NOFX | Disable reverb and chorus processing, saving some CPU time. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOSYSRESET | Ignore system reset events (MIDI_EVENT_SYSTEM) when the system mode is unchanged. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOTEOFF1 | Only release the oldest instance upon a note off event (MIDI_EVENT_NOTE with velocity=0) when there are overlapping instances of the note. Otherwise all instances are released. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. Otherwise linear interpolation is used. This flag can be toggled at any time using BASS_ChannelFlags.
freq | Sample rate to render/play the MIDI 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 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 | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_ILLPARAM | channels is not valid.
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 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

This function creates a stream solely for real-time MIDI events. As it is not based on any file, the stream has no predetermined length and is never-ending. Seeking is not possible, but it is possible to reset everything, including playback buffer, by calling BASS_ChannelPlay (restart = TRUE) or BASS_ChannelSetPosition (pos = 0).

MIDI events are applied using the BASS_MIDI_StreamEvent and BASS_MIDI_StreamEvents functions. If the stream is being played (it is not a decoding channel), then there will be some delay in the effect of the events being heard. This latency can be reduced by making use of the BASS_CONFIG_BUFFER and BASS_CONFIG_UPDATEPERIOD config options.

If a stream has 16 MIDI channels, then channel 10 defaults to percussion/drums and the rest melodic, otherwise they are all melodic. That can be changed using BASS_MIDI_StreamEvent and the MIDI_EVENT_DRUMS event.

Soundfonts provide the sounds that are used to render a MIDI stream. A default soundfont configuration is applied initially to the new MIDI stream, which can subsequently be overridden using BASS_MIDI_StreamSetFonts.

To play a MIDI file, use BASS_MIDI_StreamCreateFile.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored. On Android and iOS, sinc interpolation requires a NEON-supporting CPU; the BASS_MIDI_SINCINTER flag will otherwise be ignored. Sinc interpolation is not available on Windows CE.

See also

BASS_MIDI_StreamCreateEvents, BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamEvent, BASS_MIDI_StreamEvents, BASS_MIDI_StreamGetChannel, BASS_MIDI_StreamSetFonts, BASS_ATTRIB_MIDI_CPU, BASS_CONFIG_MIDI_DEFFONT, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetInfo, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamFree


BASS_MIDI_StreamCreateEvents

Creates a sample stream from a sequence of MIDI events.

HSTREAM BASS_MIDI_StreamCreateEvents(
    BASS_MIDI_EVENT *events,
    DWORD ppqn,
    DWORD flags,
    DWORD freq
);

Parameters

events | Pointer to an array containing the event sequence to play.
ppqn | The Pulses Per Quarter Note, or ticks per beat.
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 more info.
BASS_SAMPLE_MONO | Decode/play the MIDI 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 stream to not use hardware 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 stream.
BASS_STREAM_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_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_MIDI_NOFX | Disable reverb and chorus processing, saving some CPU time. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOSYSRESET | Ignore system reset events (MIDI_EVENT_SYSTEM) when the system mode is unchanged. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOTEOFF1 | Only release the oldest instance upon a note off event (MIDI_EVENT_NOTE with velocity=0) when there are overlapping instances of the note. Otherwise all instances are released. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. Otherwise linear interpolation is used. This flag can be toggled at any time using BASS_ChannelFlags.
freq | Sample rate to render/play the MIDI 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 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 | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_ILLPARAM | ppqn cannot be 0.
BASS_ERROR_POSITION | The events must be in chronological order (within each track).
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 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

This function creates a 16 channel MIDI stream to play a predefined sequence of MIDI events. Any of the standard MIDI events listed in the BASS_MIDI_StreamEvent section can be used, but the MIDI_EVENT_MIXLEVEL, MIDI_EVENT_TRANSPOSE, and MIDI_EVENT_SYSTEMEX events are not available and will be ignored. The sequence should end with a MIDI_EVENT_END event. Multiple tracks are possible via the MIDI_EVENT_END_TRACK event, which signals the end of a track; the next event will be in a new track.

The event sequence is copied, so the events array does not need to persist beyond the function call.

Soundfonts provide the sounds that are used to render a MIDI stream. A default soundfont configuration is applied initially to the new MIDI stream, which can subsequently be overridden using BASS_MIDI_StreamSetFonts.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored. On Android and iOS, sinc interpolation requires a NEON-supporting CPU; the BASS_MIDI_SINCINTER flag will otherwise be ignored. Sinc interpolation is not available on Windows CE.

Example

Play a middle C note (key 60) on a violin every 2 seconds.
BASS_MIDI_EVENT events[]={
    {MIDI_EVENT_TEMPO, 500000, 0, 0}, // set the tempo to 0.5 seconds per quarter note
    {MIDI_EVENT_PROGRAM, 40, 0, 0}, // select the violin preset
    {MIDI_EVENT_NOTE, MAKEWORD(60, 100), 0, 0}, // press the key
    {MIDI_EVENT_NOTE, 60, 0, 200}, // release the key after 200 ticks
    {MIDI_EVENT_END, 0, 0, 400} // end after 400 ticks
};
HSTREAM stream=BASS_MIDI_StreamCreateEvents(events, 100, BASS_SAMPLE_LOOP, 0); // create a looping stream from the events
BASS_ChannelPlay(stream, 0); // start playing it

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamGetChannel, BASS_MIDI_StreamLoadSamples, BASS_MIDI_StreamSetFonts, BASS_ATTRIB_MIDI_CPU, BASS_CONFIG_MIDI_DEFFONT, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetInfo, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamFree


BASS_MIDI_StreamCreateFile

Creates a sample stream from a MIDI file.

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

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_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 more info.
BASS_SAMPLE_MONO | Decode/play the MIDI 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 stream to not use hardware 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_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_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_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_MIDI_DECAYEND | Let the sound decay naturally (including reverb) instead of stopping it abruptly at the end of the file. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_DECAYSEEK | Let the old sound decay naturally (including reverb) when changing the position, including looping. This flag can be toggled at any time using BASS_ChannelFlags, and can also be used in BASS_ChannelSetPosition calls to have it apply to particular position changes.
BASS_MIDI_NOCROP | Do not remove empty space (containing no events) from the end of the file.
BASS_MIDI_NOFX | Disable reverb and chorus processing, saving some CPU time. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOSYSRESET | Ignore system reset events (MIDI_EVENT_SYSTEM) when the system mode is unchanged. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOTEOFF1 | Only release the oldest instance upon a note off event (MIDI_EVENT_NOTE with velocity=0) when there are overlapping instances of the note. Otherwise all instances are released. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. Otherwise linear interpolation is used. This flag can be toggled at any time using BASS_ChannelFlags.
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 MIDI 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 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 | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
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_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 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

BASSMIDI supports standard MIDI format 0/1/2 files. In the case of format 2, the tracks are rendered/played one after another. RIFF MIDI (RMID) files are also supported. The General MIDI standard events are supported, as are several Roland GS and Yamaha XG NRPN and SysEx events. A full list of supported MIDI events can be found in the BASS_MIDI_StreamEvent documentation.

Soundfonts provide the sounds that are used to render a MIDI stream. A default soundfont configuration is applied initially to the new MIDI stream, which can subsequently be overridden using BASS_MIDI_StreamSetFonts. By default, with the BASS_CONFIG_MIDI_AUTOFONT config option enabled, BASSMIDI will also check for a soundfont of the same name as the MIDI file. Note that a MIDI stream can have multiple soundfonts stacked, each providing different presets, for example.

As well as the standard byte/time-based positioning, MIDI tick-based positioning is also supported. The BASS_POS_MIDI_TICK "mode" can be used with BASS_ChannelGetLength, BASS_ChannelGetPosition and BASS_ChannelSetPosition to deal in ticks. The BASS_ATTRIB_MIDI_PPQN attribute can be used to translate the position to beats.

Marker, instrument name, cue, text, and lyric events can be retrieved via the BASS_MIDI_StreamGetMark function. Syncs can also be used to be notified of their occurrence.

Other texts of each track (eg. track name) are available via the BASS_TAG_MIDI_TRACK+<track> tag, where track=0 is the first track. A pointer to a series of null-terminated strings is given, the final string ending with a double null. The first text in the first track is generally the title of the MIDI file. RIFF MIDI tags are also available via the standard BASS_TAG_RIFF_INFO tag.

Alongside the events played from the MIDI file, custom MIDI events can be applied via the BASS_MIDI_StreamEvent and BASS_MIDI_StreamEvents functions. The events can be played on the same MIDI channels that are used by the MIDI file, or they can be played on additional channels allocated via the BASS_ATTRIB_MIDI_CHANS attribute.

Unlike with most stream formats, the entire MIDI file is loaded to memory. This means the file can be deleted or moved after calling this function, or the memory can be discarded (mem = TRUE).

To play a MIDI file from the internet, use BASS_MIDI_StreamCreateURL. To play a custom sequence of MIDI events, BASS_MIDI_StreamCreateEvents can be used.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored. On Android and iOS, sinc interpolation requires a NEON-supporting CPU; the BASS_MIDI_SINCINTER flag will otherwise be ignored. Sinc interpolation is not available on Windows CE.

Example

Create a stream of a MIDI file, with a sample rate of 44100hz.
HSTREAM stream=BASS_MIDI_StreamCreateFile(FALSE, "afile.mid", 0, 0, 0, 44100);

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamCreateEvents, BASS_MIDI_StreamCreateFileUser, BASS_MIDI_StreamCreateURL, BASS_MIDI_StreamGetChannel, BASS_MIDI_StreamGetEvents, BASS_MIDI_StreamGetMark, BASS_MIDI_StreamLoadSamples, BASS_MIDI_StreamSetFonts, BASS_ATTRIB_MIDI_CPU, BASS_CONFIG_MIDI_AUTOFONT, BASS_CONFIG_MIDI_DEFFONT, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamFree


BASS_MIDI_StreamCreateFileUser

Creates a sample stream from a MIDI file via user callback functions.

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

Parameters

system | File system to use, which must be STREAMFILE_NOBUFFER, as the entire MIDI file is preloaded.
flagsAny 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 more info.
BASS_SAMPLE_MONO | Decode/play the MIDI 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 stream to not use hardware 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_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_AUTOFREE | Automatically free the stream when playback ends.
BASS_STREAM_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_MIDI_DECAYEND | Let the sound decay naturally (including reverb) instead of stopping it abruptly at the end of the file. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_DECAYSEEK | Let the old sound decay naturally (including reverb) when changing the position, including looping. This flag can be toggled at any time using BASS_ChannelFlags, and can also be used in BASS_ChannelSetPosition calls to have it apply to particular position changes.
BASS_MIDI_NOCROP | Do not remove empty space (containing no events) from the end of the file.
BASS_MIDI_NOFX | Disable reverb and chorus processing, saving some CPU time. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOSYSRESET | Ignore system reset events (MIDI_EVENT_SYSTEM) when the system mode is unchanged. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOTEOFF1 | Only release the oldest instance upon a note off event (MIDI_EVENT_NOTE with velocity=0) when there are overlapping instances of the note. Otherwise all instances are released. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. Otherwise linear interpolation is used. This flag can be toggled at any time using BASS_ChannelFlags.
procs | The user defined file functions.
user | User instance data to pass to the callback functions.
freq | Sample rate to render/play the MIDI 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 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 | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_ILLPARAM | system is not valid.
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 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 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

As there is no file associated with a user file stream, it is not possible for BASSMIDI to look for a soundfont with the same name as the MIDI file. If there is a matching soundfont, it can be applied using BASS_MIDI_StreamSetFonts.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored. On Android and iOS, sinc interpolation requires a NEON-supporting CPU; the BASS_MIDI_SINCINTER flag will otherwise be ignored. Sinc interpolation is not available on Windows CE.

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamCreateEvents, BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamCreateURL, BASS_MIDI_StreamGetChannel, BASS_MIDI_StreamGetMark, BASS_MIDI_StreamLoadSamples, BASS_MIDI_StreamSetFonts, BASS_CONFIG_MIDI_DEFFONT, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamFree, BASS_FILEPROCS structure


BASS_MIDI_StreamCreateURL

Creates a sample stream from an MIDI file on the internet, optionally receiving the downloaded data in a callback.

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

Parameters

url | URL of the file to stream. Should begin with "http://" or "ftp://".
offset | File position to start streaming from. This is ignored by some servers, specifically when the file length is unknown.
flagsAny 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 more info.
BASS_SAMPLE_MONO | Decode/play the MIDI 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 stream to not use hardware 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_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_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/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_MIDI_DECAYEND | Let the sound decay naturally (including reverb) instead of stopping it abruptly at the end of the file. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_DECAYSEEK | Let the old sound decay naturally (including reverb) when changing the position, including looping. This flag can be toggled at any time using BASS_ChannelFlags, and can also be used in BASS_ChannelSetPosition calls to have it apply to particular position changes.
BASS_MIDI_NOCROP | Do not remove empty space (containing no events) from the end of the file.
BASS_MIDI_NOFX | Disable reverb and chorus processing, saving some CPU time. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOSYSRESET | Ignore system reset events (MIDI_EVENT_SYSTEM) when the system mode is unchanged. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_NOTEOFF1 | Only release the oldest instance upon a note off event (MIDI_EVENT_NOTE with velocity=0) when there are overlapping instances of the note. Otherwise all instances are released. This flag can be toggled at any time using BASS_ChannelFlags.
BASS_MIDI_SINCINTER | Use sinc interpolated sample mixing. This increases the sound quality, but also requires more CPU. Otherwise linear interpolation is used. This flag can be toggled at any time using BASS_ChannelFlags.
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 downloaded file... NULL = no callback.
user | User instance data to pass to the callback function.
freq | Sample rate to render/play the MIDI 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 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 | Only decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_NONET | No internet connection could be opened.
BASS_ERROR_ILLPARAM | url is not a valid URL.
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_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 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 entire MIDI file is preloaded, so the standard BASS_STREAM_BLOCK and BASS_STREAM_RESTRATE flags have no effect here.

Regardless of the BASS_CONFIG_MIDI_AUTOFONT setting, a matching soundfont is not looked for when opening a MIDI file from a URL.

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored. On Android and iOS, sinc interpolation requires a NEON-supporting CPU; the BASS_MIDI_SINCINTER flag will otherwise be ignored. Sinc interpolation is not available on Windows CE.

See also

BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamCreateFileUser, BASS_MIDI_StreamGetChannel, BASS_MIDI_StreamGetMark, BASS_MIDI_StreamLoadSamples, BASS_MIDI_StreamSetFonts, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetInfo, BASS_ChannelGetLength, BASS_ChannelGetTags, BASS_ChannelPlay, BASS_ChannelSetAttribute, BASS_ChannelSetDSP, BASS_ChannelSetFX, BASS_ChannelSetLink, BASS_StreamFree, DOWNLOADPROC callback, BASS_CONFIG_NET_AGENT, BASS_CONFIG_NET_PROXY, BASS_CONFIG_NET_TIMEOUT


BASS_MIDI_StreamEvent

Applies an event to a channel in a MIDI stream.

BOOL BASS_MIDI_StreamEvent(
    HSTREAM handle,
    DWORD chan,
    DWORD event,
    DWORD param
);

Parameters

handle | The MIDI stream to apply the event to.
chan | The MIDI channel to apply the event to... 0 = channel 1.
event | The event to apply, see the table below.
param | The event parameter.

Event types, with param definitions.

MIDI_EVENT_NOTEPress or release a key, or stop without sustain/decay.
param : LOBYTE = key number (0-127, 60=middle C), HIBYTE = velocity (0=release, 1-127=press, 255=stop).
MIDI_EVENT_PROGRAMSelect the preset/instrument to use. Standard soundfont presets follow the General MIDI standard, and generally also include Roland GS variations in other banks (accessible via the MIDI_EVENT_BANK event).
param : preset number (0-65535).
MIDI_EVENT_CHANPRESSet the channel pressure.
param : pressure level (0-127).
MIDI_EVENT_KEYPRESSet a key's pressure/aftertouch.
param : LOBYTE = key number (0-127), HIBYTE = pressure level (0-127).
MIDI_EVENT_PITCHSet the pitch wheel position.
param : pitch wheel position (0-16383, 8192=normal/middle).
MIDI_EVENT_BANKSelect the bank to use (MIDI controller 0).
param : bank number MSB (0-127).
MIDI_EVENT_MODULATIONSet the modulation (MIDI controller 1)
param : modulation level (0-127).
MIDI_EVENT_PORTATIMESet the portamento time (MIDI controller 5).
param : portamento time (0-127).
MIDI_EVENT_VOLUMESet the volume (MIDI controller 7).
param : volume level (0-127).
MIDI_EVENT_PANSet the pan position (MIDI controller 10).
param : pan position (0-128, 0=left, 64=middle, 127=right, 128=random).
MIDI_EVENT_EXPRESSIONSet the expression (MIDI controller 11).
param : expression level (0-127).
MIDI_EVENT_BANK_LSBSelect the bank LSB to use (MIDI controller 32).
param : bank number LSB (0-127).
MIDI_EVENT_SUSTAINSet the sustain pedal/switch (MIDI controller 64).
param : sustain is on? (0-63=no, 64-127=yes).
MIDI_EVENT_PORTAMENTOSet the portamento switch (MIDI controller 65).
param : portamento is on? (0-63=no, 64-127=yes).
MIDI_EVENT_SOFTSet the soft pedal/switch (MIDI controller 67).
param : soft is on? (0-63=no, 64-127=yes).
MIDI_EVENT_RESONANCESet the low-pass filter resonance (MIDI controller 71, NRPN 121h)
param : resonance level (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_RELEASESet the release time (MIDI controller 72, NRPN 166h)
param : release time (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_ATTACKSet the attack time (MIDI controller 73, NRPN 163h)
param : attack time (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_CUTOFFSet the low-pass filter cutoff (MIDI controller 74, NRPN 120h)
param : cutoff level (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_DECAYSet the decay time (MIDI controller 75, NRPN 164h)
param : decay time (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_PORTANOTESet the portamento start key; the next note starts at this key (MIDI controller 84).
param : key number (1-127, 60=middle C).
MIDI_EVENT_REVERBSet the reverb send level (MIDI controller 91)
param : reverb level (0-127).
MIDI_EVENT_CHORUSSet the chorus send level (MIDI controller 93)
param : chorus level (0-127).
MIDI_EVENT_USERFXSet the user effect send level (MIDI controller 94). This will have no audible effect unless custom processing is applied to the user effect mix via BASS_MIDI_StreamGetChannel.
param : user effect level (0-127).
MIDI_EVENT_SOUNDOFFStop all sounds (MIDI controller 120).
param : not used.
MIDI_EVENT_RESETReset controllers (MIDI controller 121), that is modulation=0, expression=127, sustain=0, portamento=0, release time=64, attack time=64, pitch wheel=8192, channel pressure=0.
param : not used.
MIDI_EVENT_NOTESOFFRelease all keys (MIDI controller 123).
param : not used.
MIDI_EVENT_MODESet poly/mono mode (MIDI controllers 126 & 127).
param : mode (0=poly, 1=mono).
MIDI_EVENT_CONTROLUnhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with a BASS_SYNC_MIDI_EVENT sync.
param : LOBYTE = controller number, HIBYTE = controller value.
MIDI_EVENT_PITCHRANGESet pitch wheel range (MIDI RPN 0).
param : range in semitones.
MIDI_EVENT_FINETUNESet the fine tuning (MIDI RPN 1).
param : finetune in cents (0-16383, 0=-100, 8192=normal, 16383=+100).
MIDI_EVENT_COARSETUNESet the coarse tuning (MIDI RPN 2).
param : finetune in semitones (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_MODRANGESet the modulation/vibrato depth range (MIDI RPN 5).
param : vibrato depth in cents (128=100, 256=200, etc).
MIDI_EVENT_DRUMSSet the percussion/drums channel switch. The bank and program are reset to 0 when this changes.
param : use drums? (0=no, 1=yes).
MIDI_EVENT_DRUM_CUTOFFSet the low-pass filter cutoff of a drum key (MIDI NRPN 14knh)
param : LOBYTE = key number (0-127), HIBYTE = cutoff level (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_DRUM_RESONANCESet the low-pass filter resonance of a drum key (MIDI NRPN 15knh)
param : LOBYTE = key number (0-127), HIBYTE = resonance level (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_DRUM_COARSETUNESet the coarse tuning of a drum key (MIDI NRPN 18knh).
param : LOBYTE = key number (0-127), HIBYTE = finetune in semitones (0-127, 0=-64, 64=normal, 127=+63).
MIDI_EVENT_DRUM_FINETUNESet the fine tuning of a drum key (MIDI NRPN 19knh).
param : LOBYTE = key number (0-127), HIBYTE = finetune in cents (0-127, 0=-100, 64=normal, 127=+100).
MIDI_EVENT_DRUM_LEVELSet the level of a drum key (MIDI NRPN 1Aknh)
param : LOBYTE = key number (0-127), HIBYTE = level (0-127, 127=normal/full).
MIDI_EVENT_DRUM_PANSet the pan position of a drum key (MIDI NRPN 1Cknh).
param : LOBYTE = key number (0-127), HIBYTE = pan position (0-128, 0=random, 1=left, 64=middle, 127=right, 128=normal).
MIDI_EVENT_DRUM_REVERBSet the reverb send level of a drum key (MIDI NRPN 1Dknh)
param : LOBYTE = key number (0-127), HIBYTE = reverb level (0-127, 127=normal/full).
MIDI_EVENT_DRUM_CHORUSSet the chorus send level of a drum key (MIDI NRPN 1Eknh)
param : LOBYTE = key number (0-127), HIBYTE = chorus level (0-127, 127=normal/full).
MIDI_EVENT_DRUM_USERFXSet the user effect send level of a drum key (MIDI NRPN 1Fknh)
param : LOBYTE = key number (0-127), HIBYTE = user effect level (0-127, 127=normal/full).
MIDI_EVENT_SCALETUNINGSet the tuning of a note in every octave.
param : LOWORD = tuning change in cents (0-16383, 0=-100, 8192=normal, 16383=+100), HIWORD = note (0-11, 0=C).
MIDI_EVENT_CHANPRES_FILTERSet the maximum effect of channel pressure on filter cutoff.
param : filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600).
MIDI_EVENT_CHANPRES_PITCHSet the maximum effect of channel pressure on pitch.
param : pitch effect in semitones (0=-24, 24=none, 48=+24).
MIDI_EVENT_CHANPRES_VIBRATOSet the maximum effect of channel pressure on vibrato depth.
param : vibrato depth effect in cents (0=none, 128=100, 256=200, etc).
MIDI_EVENT_CHANPRES_VOLUMESet the maximum effect of channel pressure on volume.
param : volume effect percentage (0=-100, 100=none, 200=+100).
MIDI_EVENT_KEYPRES_FILTERSet the maximum effect of key pressure/aftertouch on filter cutoff.
param : filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600).
MIDI_EVENT_KEYPRES_PITCHSet the maximum effect of key pressure/aftertouch on pitch.
param : pitch effect in semitones (0=-24, 24=none, 48=+24).
MIDI_EVENT_KEYPRES_VIBRATOSet the maximum effect of key pressure/aftertouch on vibrato depth.
param : vibrato depth effect in cents (0=none, 128=100, 256=200, etc).
MIDI_EVENT_KEYPRES_VOLUMESet the maximum effect of key pressure/aftertouch on volume.
param : volume effect percentage (0=-100, 100=none, 200=+100).

Global events.

MIDI_EVENT_SYSTEM,
MIDI_EVENT_SYSTEMEX		Set the system mode, resetting everything to the system's defaults. MIDI_SYSTEM_DEFAULT is identical to MIDI_SYSTEM_GS, except that channel 10 is melodic if there are not 16 channels. MIDI_EVENT_SYSTEM does not reset things in any additional channels allocated to a MIDI file stream via the BASS_ATTRIB_MIDI_CHANS attribute, while MIDI_EVENT_SYSTEMEX does. If the system mode is unchanged and the BASS_MIDI_NOSYSRESET flag is set on the MIDI stream, then MIDI_EVENT_SYSTEM has no effect (MIDI_EVENT_SYSTEMEX still does).
param : system mode (MIDI_SYSTEM_DEFAULT, MIDI_SYSTEM_GM1, MIDI_SYSTEM_GM2, MIDI_SYSTEM_GS, MIDI_SYSTEM_XG).
MIDI_EVENT_TEMPOSet the tempo (MIDI meta event 81). Changing the tempo affects the stream length, and the BASS_ChannelGetLength byte value will no longer be valid.
param : tempo in microseconds per quarter note.
MIDI_EVENT_MASTERVOLSet the master volume.
param : volume level (0-16383, 0=silent, 16383=normal/full).
MIDI_EVENT_REVERB_TIMESet the reverb time.
param : reverb time in milliseconds.
MIDI_EVENT_REVERB_DELAYSet the reverb delay.
param : reverb delay in 10ths of a millisecond.
MIDI_EVENT_REVERB_LOCUTOFFSet the reverb low-pass cutoff
param : reverb low-pass cutoff in hertz (0=off).
MIDI_EVENT_REVERB_HICUTOFFSet the reverb high-pass cutoff
param : reverb high-pass cutoff in hertz (0=off).
MIDI_EVENT_REVERB_LEVELSet the reverb level
param : reverb level (0=off, 100=0dB, 200=+6dB).
MIDI_EVENT_CHORUS_DELAYSet the chorus delay.
param : chorus delay in 10ths of a millisecond.
MIDI_EVENT_CHORUS_DEPTHSet the chorus depth.
param : chorus depth in 10ths of a millisecond.
MIDI_EVENT_CHORUS_RATESet the chorus rate.
param : chorus rate in 100ths of a hertz.
MIDI_EVENT_CHORUS_FEEDBACKSet the chorus feedback level.
param : chorus feedback level (0=-100%, 100=off, 200=+100%).
MIDI_EVENT_CHORUS_LEVELSet the chorus level.
param : chorus level (0=off, 100=0dB, 200=+6dB).
MIDI_EVENT_CHORUS_REVERBSet the chorus send to reverb level.
param : chorus send to reverb level (0=off, 100=0dB, 200=+6dB).
MIDI_EVENT_USERFX_LEVELSet the user effect level.
param : user effect level (0=off, 100=0dB, 200=+6dB).
MIDI_EVENT_USERFX_CHORUSSet the user effect send to chorus level.
param : user effect send to chorus level (0=off, 100=0dB, 200=+6dB).
MIDI_EVENT_USERFX_REVERBSet the user effect send to reverb level.
param : user effect send to reverb level (0=off, 100=0dB, 200=+6dB).

Other (non-MIDI) events.

MIDI_EVENT_MIXLEVELSet the level.
param : the level (0=silent, 100=0dB, 200=+6dB).
MIDI_EVENT_TRANSPOSETranspose all notes. Changes take effect from the next note played, and affect melodic channels only (not drum channels).
param : transposition amount in semitones (0=-100, 100=normal, 200=+100).

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_ILLPARAM | One of the other parameters is invalid.
BASS_ERROR_NOTAVAIL | Tempo only applies to MIDI file streams.

Remarks

Apart from the "global" events, all events apply only to the specified MIDI channel.

Except for the "non-MIDI" events, events applied to a MIDI file stream can subsequently be overridden by events in the file itself, and will also be overridden when seeking or looping. That can be avoided by using additional channels, allocated via the BASS_ATTRIB_MIDI_CHANS attribute.

BASS_SYNC_MIDI_EVENT syncs are not triggered by this function. If sync triggering is wanted, BASS_MIDI_StreamEvents can be used instead.

If the MIDI stream is being played (it is not a decoding channel), then there will be some delay in the effect of the event being heard. This latency can be reduced by making use of the BASS_CONFIG_BUFFER and BASS_CONFIG_UPDATEPERIOD config options when creating the stream.

If multiple events need to be applied at the same time, BASS_MIDI_StreamEvents can be used instead of this function.

Example

Play the middle C note (key 60) with a velocity of 100, on channel 1 for 2 seconds.
BASS_MIDI_StreamEvent(handle, 0, MIDI_EVENT_NOTE, MAKEWORD(60, 100)); // press the key
Sleep(2000); // wait 2 seconds
BASS_MIDI_StreamEvent(handle, 0, MIDI_EVENT_NOTE, 60); // release the key

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamEvents, BASS_MIDI_StreamGetEvent


BASS_MIDI_StreamEvents

Applies any number of events to a MIDI stream.

DWORD BASS_MIDI_StreamEvents(
    HSTREAM handle,
    DWORD mode,
    void *events,
    DWORD length
);

Parameters

handle | The MIDI stream to apply the events to.
modeThe type of event data to apply. One of the following, with optional flags.
BASS_MIDI_EVENTS_RAW | Raw MIDI event data, as would be sent to a MIDI device. To overcome the 16 channel limit, the event data's channel information can optionally be overridden by adding the new channel number to this parameter, where +1 = the 1st channel.
BASS_MIDI_EVENTS_STRUCT | An array of BASS_MIDI_EVENT structures.
BASS_MIDI_EVENTS_NORSTATUS | Flag: Disable running status, meaning each event must include a status byte. Only applicable with BASS_MIDI_EVENTS_RAW.
BASS_MIDI_EVENTS_SYNC | Flag: Trigger BASS_SYNC_MIDI_EVENT syncs for the processed events.
events | The event data.
length | The length of the event data. The number of bytes or BASS_MIDI_EVENT structures, depending on the type of event data.

Return value

If successful, the number of events processed 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_ILLPARAM | mode is not valid.

Remarks

Events applied to a MIDI file stream can subsequently be overridden by events in the file itself, and will also be overridden when seeking or looping. That can be avoided by using additional channels, allocated via the BASS_ATTRIB_MIDI_CHANS attribute.

If the MIDI stream is being played (it is not a decoding channel), then there will be some delay in the effect of the event being heard. This latency can be reduced by making use of the BASS_CONFIG_BUFFER and BASS_CONFIG_UPDATEPERIOD config options when creating the stream.

Example

Play a C major chord with a velocity of 100, on channel 1 for 2 seconds.
BASS_MIDI_EVENT events[3];
events[0].event=MIDI_EVENT_NOTE;
events[0].param=MAKEWORD(60, 100); // C
events[0].chan=0;
events[1].event=MIDI_EVENT_NOTE;
events[1].param=MAKEWORD(64, 100); // E
events[1].chan=0;
events[2].event=MIDI_EVENT_NOTE;
events[2].param=MAKEWORD(67, 100); // G
events[2].chan=0;
BASS_MIDI_StreamEvents(handle, BASS_MIDI_EVENTS_STRUCT, events, 3); // process the events
Sleep(2000); // wait 2 seconds
// modify the event data to release the keys
events[0].param=60; // release C
events[1].param=64; // release E
events[2].param=67; // release G
BASS_MIDI_StreamEvents(handle, BASS_MIDI_EVENTS_STRUCT, events, 3); // process the events

The same thing using raw MIDI event data.

BYTE events[7]={0x90, 60, 100, 64, 100, 67, 100}; // the event data
BASS_MIDI_StreamEvents(handle, BASS_MIDI_EVENTS_RAW, events, 7); // process the events
Sleep(2000); // wait 2 seconds
// modify the event data to release the keys
events[2]=0; // release C
events[4]=0; // release E
events[6]=0; // release G
BASS_MIDI_StreamEvents(handle, BASS_MIDI_EVENTS_RAW, events, 7); // process the events

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamEvent, BASS_MIDI_StreamGetEvent


BASS_MIDI_StreamGetChannel

Retrieves a MIDI channel's stream handle, which can be used to set DSP/FX on it. Can also replace the default reverb and chorus processing.

HSTREAM BASS_MIDI_StreamGetChannel(
    HSTREAM handle,
    DWORD chan
);

Parameters

handle The MIDI stream.
chanThe MIDI channel... 0 = channel 1. Or one of the following special channels.
BASS_MIDI_CHAN_CHORUS | Chorus mix channel. The default chorus processing is replaced by the stream's processing.
BASS_MIDI_CHAN_REVERB | Reverb mix channel. The default reverb processing is replaced by the stream's processing.
BASS_MIDI_CHAN_USERFX | User effect mix channel.

Return value

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

Error codes

BASS_ERROR_HANDLE | handle is not valid.
BASS_ERROR_ILLPARAM | chan is not valid.

Remarks

By default, MIDI channels do not have streams assigned to them; a MIDI channel only gets a stream when this function is called, which it then keeps until the MIDI stream is freed. MIDI channel streams can also be freed before then via BASS_StreamFree. Each MIDI channel stream increases the CPU usage slightly, even if there are no DSP/FX set on them, so for optimal performance they should not be activated unnecessarily.

A MIDI channel stream receives the channel's dry mix, and its output is then sent through the normal reverb/chorus/userfx processing, but drum key reverb/chorus/userfx settings get ignored as it is impossible to apply different reverb/chorus/userfx levels to individual keys in this case (they have already been mixed).

MIDI channel streams can only be used to set DSP/FX on the channels. They cannot be used with BASS_ChannelGetData or BASS_ChannelGetLevel to visualise the channels, for example, but that could be achieved with a DSP function instead.

Platform-specific

This function is not available on Android.

Example

Apply some DX8 distortion to channel 1 of a MIDI stream.
HSTREAM chan1=BASS_MIDI_StreamGetChannel(midi, 0); // get a stream for MIDI channel 1
HFX fx=BASS_ChannelSetFX(chan1, BASS_FX_DX8_DISTORTION, 0); // set the DX8 distortion effect on it

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamCreateFile

BASS_ChannelSetDSP, BASS_ChannelSetFX


BASS_MIDI_StreamGetEvent

Retrieves the current value of an event in a MIDI stream channel.

DWORD BASS_MIDI_StreamGetEvent(
    HSTREAM handle,
    DWORD chan,
    DWORD event
);

Parameters

handle | The MIDI stream to get the event value from.
chan | The MIDI channel to get the event value from... 0 = channel 1.
event | The event value to retrieve. See BASS_MIDI_StreamEvent for details on the available event types and their values. With the drum key events (MIDI_EVENT_DRUM_CUTOFF/etc) and the MIDI_EVENT_KEYPRES and MIDI_EVENT_SCALETUNING events, the HIWORD - use MAKELONG(event,key) - can be used to specify which key/note to get the value from.

Return value

If successful, the event value 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_ILLPARAM | One of the other parameters is invalid.

Remarks

Syncs can be used to be informed of when event values change.

See also

BASS_MIDI_StreamEvent, BASS_MIDI_StreamGetEvents


BASS_MIDI_StreamGetEvents

Retrieves the events in a MIDI file stream.

DWORD BASS_MIDI_StreamGetEvents(
    HSTREAM handle,
    int track,
    DWORD filter,
    BASS_MIDI_EVENT *events
);

Parameters

handle | The MIDI stream to get the events from.
track | The track to get the events from... 0 = 1st track, -1 = all tracks.
filter | The type of events to retrieve... 0 = all events. See BASS_MIDI_StreamEvent for a list of possible event types.
events | Pointer to an array to receive the events... NULL = get the number of events without getting the events themselves.

Return value

If successful, the number of events 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 for real-time events only, so does not have an event sequence.
BASS_ERROR_ILLPARAM | track is not valid.

Remarks

This function should first be called with events = NULL to get the number of events, before allocating an array of the required size and retrieving the events. The events are ordered chronologically, and by track number (lowest first) if multiple events have the same position.

Example

Retrieve all events in the 1st track.
DWORD eventc=BASS_MIDI_StreamGetEvents(handle, 0, 0, NULL); // get number of events in 1st track
BASS_MIDI_EVENT *events=(BASS_MIDI_EVENT*)malloc(eventc*sizeof(BASS_MIDI_EVENT)); // allocate event array
BASS_MIDI_StreamGetEvents(handle, 0, 0, events); // get the events

Retrieve all note events in the 2nd track.

DWORD eventc=BASS_MIDI_StreamGetEvents(handle, 1, MIDI_EVENT_NOTE, NULL); // get number of note events in 2nd track
BASS_MIDI_EVENT *events=(BASS_MIDI_EVENT*)malloc(eventc*sizeof(BASS_MIDI_EVENT)); // allocate event array
BASS_MIDI_StreamGetEvents(handle, 1, MIDI_EVENT_NOTE, events); // get the events

See also

BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamGetEvent, BASS_MIDI_EVENT structure


BASS_MIDI_StreamGetFonts

Retrieves the soundfont configuration of a MIDI stream, or the default soundfont configuration.

DWORD BASS_MIDI_StreamGetFonts(
    HSTREAM handle,
    void *fonts,
    DWORD count
);

Parameters

handle | The MIDI stream to retrieve the soundfont configuration of... 0 = get default soundfont configuration.
fonts | An array of BASS_MIDI_FONT or BASS_MIDI_FONTEX to retrieve the soundfont configuration.
count | The maximum number of elements to retrieve in the fonts array. The BASS_MIDI_FONT_EX flag may also be used to specify that fonts is an array of BASS_MIDI_FONTEX rather than BASS_MIDI_FONT. This and fonts can be 0, to get the number of elements in the soundfont configuration.

Return value

If successful, the number of soundfonts in the configuration (which can be higher than count) is returned, else -1 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE handle is not valid.

Remarks

When a soundfont matching the MIDI file is loaded, it will be the first element in the returned configuration.

Platform-specific

Depending on the programming language used, the BASS_MIDI_FONT_EX flag may be automatically applied when the BASS_MIDI_FONTEX structure is used, through overloading in the BASSMIDI header. That is true for C++ and Delphi.

See also

BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamSetFonts, BASS_MIDI_FONT structure, BASS_MIDI_FONTEX structure


BASS_MIDI_StreamGetMark

Retrieves a marker from a MIDI file stream.

BOOL BASS_MIDI_StreamGetMark(
    HSTREAM handle,
    DWORD type,
    DWORD index,
    BASS_MIDI_MARK *mark
);

Parameters

handle | The MIDI stream to retrieve the marker from.
typeThe type of marker to retrieve, one of the following.
BASS_MIDI_MARK_COPY | Copyright notice events (MIDI meta event 2).
BASS_MIDI_MARK_CUE | Cue events (MIDI meta event 7).
BASS_MIDI_MARK_INST | Instrument name events (MIDI meta event 4).
BASS_MIDI_MARK_KEYSIG | Key signature events (MIDI meta event 89). The marker text is in the form of "a b", where a is the number of sharps (if positive) or flats (if negative), and b signifies major (if 0) or minor (if 1).
BASS_MIDI_MARK_LYRIC | Lyric events (MIDI meta event 5).
BASS_MIDI_MARK_MARKER | Marker events (MIDI meta event 6).
BASS_MIDI_MARK_TEXT | Text events (MIDI meta event 1).
BASS_MIDI_MARK_TIMESIG | Time signature events (MIDI meta event 88). The marker text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse, and d is the number of 32nd notes per MIDI quarter-note.
BASS_MIDI_MARK_TRACK | Track name events (MIDI meta event 3).
BASS_MIDI_MARK_TICK | Flag: Get the marker's position in ticks rather than bytes.
index | The marker to retrieve... 0 = the first.
mark | Pointer to a structure to receive the marker details.

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_ILLTYPE | type in not valid.
BASS_ERROR_ILLPARAM | index in not valid.

Remarks

The markers are ordered chronologically, and by track number (lowest first) if multiple markers have the same position.

Syncs can be used to be informed of when markers are encountered during playback.

If a lyric marker text begins with a / (slash) character, that means a new line should be started. If the text begins with a \ (backslash) character, the display should be cleared. Lyrics can sometimes be found in BASS_MIDI_MARK_TEXT instead of BASS_MIDI_MARK_LYRIC markers.

Example

List a MIDI stream's markers.
BASS_MIDI_MARK mark;
int a;
for (a=0; BASS_MIDI_StreamGetMark(handle, BASS_MIDI_MARK_MARKER, a, &mark); a++)
    printf("marker @ %d = %s\n", mark.pos, mark.text); // display marker position and text

See also

BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamGetMarks, BASS_MIDI_MARK structure


BASS_MIDI_StreamGetMarks

Retrieves the markers in a MIDI file stream.

DWORD BASS_MIDI_StreamGetMarks(
    HSTREAM handle,
    int track,
    DWORD type,
    BASS_MIDI_MARK *marks
);

Parameters

handle | The MIDI stream to retrieve the markers from.
track | The track to get the markers from... 0 = 1st track, -1 = all tracks.
typeThe type of marker to retrieve, one of the following.
BASS_MIDI_MARK_COPY | Copyright notice events (MIDI meta event 2).
BASS_MIDI_MARK_CUE | Cue events (MIDI meta event 7).
BASS_MIDI_MARK_INST | Instrument name events (MIDI meta event 4).
BASS_MIDI_MARK_KEYSIG | Key signature events (MIDI meta event 89). The marker text is in the form of "a b", where a is the number of sharps (if positive) or flats (if negative), and b signifies major (if 0) or minor (if 1).
BASS_MIDI_MARK_LYRIC | Lyric events (MIDI meta event 5).
BASS_MIDI_MARK_MARKER | Marker events (MIDI meta event 6).
BASS_MIDI_MARK_TEXT | Text events (MIDI meta event 1).
BASS_MIDI_MARK_TIMESIG | Time signature events (MIDI meta event 88). The marker text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse, and d is the number of 32nd notes per MIDI quarter-note.
BASS_MIDI_MARK_TRACK | Track name events (MIDI meta event 3).
BASS_MIDI_MARK_TICK | Flag: Get the marker's position in ticks rather than bytes.
marks | Pointer to an array to receive the marker details... NULL = get the number of markers without getting the markers themselves.

Return value

If successful, the number of markers 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_ILLTYPE | type is not valid.
BASS_ERROR_ILLPARAM | track is not valid.

Remarks

This function should first be called with marks = NULL to get the number of markers, before allocating an array of the required size and retrieving the markers. The markers are ordered chronologically, and by track number (lowest first) if multiple markers have the same position.

Syncs can be used to be informed of when markers are encountered during playback.

If a lyric marker text begins with a / (slash) character, that means a new line should be started. If the text begins with a \ (backslash) character, the display should be cleared. Lyrics can sometimes be found in BASS_MIDI_MARK_TEXT instead of BASS_MIDI_MARK_LYRIC markers.

Example

Retrieve the markers from all tracks in a MIDI stream.
DWORD markc=BASS_MIDI_StreamGetMarks(handle, -1, BASS_MIDI_MARK_MARKER, NULL); // get number of markers
BASS_MIDI_MARK *marks=(BASS_MIDI_MARK*)malloc(markc*sizeof(BASS_MIDI_MARK)); // allocate marker array
BASS_MIDI_StreamGetMarks(handle, -1, BASS_MIDI_MARK_MARKER, marks); // get the markers

See also

BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamGetMark, BASS_MIDI_MARK structure


BASS_MIDI_StreamLoadSamples

Preloads the samples required by a MIDI file stream.

BOOL BASS_MIDI_StreamLoadSamples(
    HSTREAM handle
);

Parameters

handle The MIDI 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_ERROR_NOTAVAIL | The stream is for real-time events only, so it is not possible to know what presets are going to be used. Use BASS_MIDI_FontLoad instead.

Remarks

Samples are normally loaded as they are needed while rendering a MIDI stream, which can result in CPU spikes, particularly with packed soundfonts. That generally will not cause any problems, but when smooth/constant performance is critical this function can be used to preload the samples before rendering, so avoiding the need to load them while rendering.

The samples loaded by this function are subject to automatic compacting via the BASS_CONFIG_MIDI_COMPACT option, so it is probably wise to disable that option when using this function, to avoid any chance of the loaded samples subsequently being automatically unloaded.

This function should not be used while the MIDI stream is being rendered, as it could delay the rendering.

See also

BASS_MIDI_FontLoad, BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamSetFonts, BASS_CONFIG_MIDI_COMPACT


BASS_MIDI_StreamSetFonts

Applies a soundfont configuration to a MIDI stream, or sets the default soundfont configuration.

BOOL BASS_MIDI_StreamSetFonts(
    HSTREAM handle,
    void *fonts,
    DWORD count
);

Parameters

handle | The MIDI stream to apply the soundfonts to... 0 = set default soundfont configuration.
fonts | An array of BASS_MIDI_FONT or BASS_MIDI_FONTEX containing the soundfonts to apply.
count | The number of elements in the fonts array. The BASS_MIDI_FONT_EX flag may also be used to specify that fonts is an array of BASS_MIDI_FONTEX rather than BASS_MIDI_FONT.

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_ILLPARAM | Something in the fonts array is invalid, check the soundfont handles.

Remarks

Multiple soundfonts can be stacked, each providing different presets, for example. When a preset is present in multiple soundfonts, the earlier soundfont in the array has priority. When a soundfont matching the MIDI file is loaded, that remains loaded when calling this function, and has priority over all other soundfonts. When a preset is not available on a non-0 bank in any soundfont, BASSMIDI will try to fall back to bank 0; first the LSB and then the MSB if still unsuccessful.

Changing the default configuration only affects subsequently created MIDI streams. Existing streams that are using the previous default configuration will continue to use that previous configuration.

Platform-specific

Depending on the programming language used, the BASS_MIDI_FONT_EX flag may be automatically applied when the BASS_MIDI_FONTEX structure is used, through overloading in the BASSMIDI header. That is true for C++ and Delphi.

Example

Set a MIDI stream to use one soundfont for program 10 on bank 0, and all available presets from another soundfont.
BASS_MIDI_FONT fonts[2];
fonts[0].font=font1;
fonts[0].preset=10; // preset 10
fonts[0].bank=0; // bank 0
fonts[1].font=font2;
fonts[1].preset=-1; // all presets
fonts[1].bank=0; // default banks
BASS_MIDI_StreamSetFonts(handle, fonts, 2); // apply it to the stream

Set a MIDI stream to use preset 20 from one soundfont for program 10 on bank 0, and all available presets from another soundfont.

BASS_MIDI_FONTEX fonts[2];
fonts[0].font=font1;
fonts[0].spreset=10; // soundfont preset 20
fonts[0].sbank=0; // soundfont bank 0
fonts[0].dpreset=10; // destination preset 10
fonts[0].dbank=0; // destination bank 0
fonts[0].dbanklsb=0; // destination bank LSB 0
fonts[1].font=font2;
fonts[1].spreset=-1; // all presets
fonts[1].sbank=-1; // all banks
fonts[1].dpreset=-1; // all presets
fonts[1].dbank=0; // default banks
fonts[1].dbanklsb=0; // destination bank LSB 0
BASS_MIDI_StreamSetFonts(handle, fonts, 2|BASS_MIDI_FONT_EX); // apply it to the stream

See also

BASS_MIDI_FontInit, BASS_MIDI_StreamCreateFile, BASS_MIDI_StreamGetFonts, BASS_MIDI_StreamLoadSamples, BASS_MIDI_FONT structure, BASS_MIDI_FONTEX structure, BASS_CONFIG_MIDI_AUTOFONT, BASS_CONFIG_MIDI_DEFFONT


MIDI syncs - BASS_ChannelSetSync

Syncs are set on MIDI streams in exactly the same way as on any other stream, using BASS_ChannelSetSync. The following is a list of the types of sync supported on MIDI streams.

Sync types, with param and SYNCPROC data definitions.

BASS_SYNC_MIDI_EVENT | Sync when a type of event is processed. param : event type (0 = all types). data : LOWORD = event parameter, HIWORD = channel (high 8 bits contain the event type when syncing on all types). See BASS_MIDI_StreamEvent for a list of event types and their parameters.
BASS_SYNC_MIDI_MARK | Sync when a marker is encountered. param : marker type. data : the marker index, which can be used in a BASS_MIDI_StreamGetMark call.
BASS_SYNC_MIDI_TICK | Sync when reaching a tick position. param : tick position. data : not used.

The BASS_SYNC_POS, BASS_SYNC_END, BASS_SYNC_SLIDE, BASS_SYNC_STALL and BASS_SYNC_FREE sync types are also supported on MIDI streams, as described in the BASS_ChannelSetSync documentation.


Plugin system

As well as providing dedicated stream creation functions, BASSMIDI supports the BASS plugin system, adding MIDI file support to the standard BASS stream creation functions: BASS_StreamCreateFile, BASS_StreamCreateURL, and BASS_StreamCreateFileUser. This is enabled using the BASS_PluginLoad function.

MIDI streams created via the plugin system use the device's sample rate, equivalent to using freq=1 in a BASS_MIDI_StreamCreateFile call.


BASS_MIDI_EVENT structure

Used with BASS_MIDI_StreamEvents to apply events and BASS_MIDI_StreamGetEvents to retrieve events, and BASS_MIDI_StreamCreateEvents to play event sequences.

typedef struct {
    DWORD event;
    DWORD param;
    DWORD chan;
    DWORD tick;
    DWORD pos;
} BASS_MIDI_EVENT;

Members

event | The event type.
param | The event parameter.
chan | The MIDI channel of the event... 0 = channel 1.
tick | The position of the event, in ticks.
pos | The position of the event, in bytes.

Remarks

The tick and pos members are ignored by BASS_MIDI_StreamEvents. pos is also ignored by BASS_MIDI_StreamCreateEvents.

See also

BASS_MIDI_StreamEvents, BASS_MIDI_StreamGetEvents


BASS_MIDI_FONT structure

Used with BASS_MIDI_StreamSetFonts and BASS_MIDI_StreamGetFonts to set and retrieve soundfont configurations.

typedef struct {
    HSOUNDFONT font;
    int preset;
    int bank;
} BASS_MIDI_FONT;

Members

font | Soundfont handle, previously initialized with BASS_MIDI_FontInit.
preset | Preset number... 0-65535, -1 = use all presets in the soundfont. This determines what MIDI_EVENT_PROGRAM event value(s) the soundfont is used for.
bank | Base bank number, or the bank number of the individual preset. This determines what MIDI_EVENT_BANK event value(s) the soundfont is used for.

Remarks

When using an individual preset from a soundfont, BASSMIDI will first look for the exact preset and bank match, but if that is not present, the first preset from the soundfont will be used. This is useful for single preset soundfonts. Individual presets can be assigned to program numbers beyond the standard 127 limit, up to 65535, which can then be accessed via BASS_MIDI_StreamEvent.

When using all presets in a soundfont, the bank member is a base number that is added to the soundfont's banks. For example, if bank=1 then the soundfont's bank 0 becomes bank 1, etc. Negative base numbers are allowed.

For more flexible mapping of soundfont presets to MIDI programs, see the BASS_MIDI_FONTEX structure.

See also

BASS_MIDI_FontInit, BASS_MIDI_StreamGetFonts, BASS_MIDI_StreamSetFonts


BASS_MIDI_FONTEX structure

Used with BASS_MIDI_StreamSetFonts and BASS_MIDI_StreamGetFonts to set and retrieve soundfont configurations.

typedef struct {
    HSOUNDFONT font;
    int spreset;
    int sbank;
    int dpreset;
    int dbank;
    int dbanklsb;
} BASS_MIDI_FONTEX;

Members

font | Soundfont handle, previously initialized with BASS_MIDI_FontInit.
spreset | Soundfont preset number... 0-127, -1 = use all presets.
sbank | Soundfont bank number... 0-128, -1 = use all banks.
dpreset | Destination preset/program number... 0-65535, -1 = all presets. This determines what MIDI_EVENT_PROGRAM event value(s) the soundfont is used for.
dbank | Destination bank number, or a base bank number when using all presets from all banks. This determines what MIDI_EVENT_BANK event value(s) the soundfont is used for.
dbanklsb | Destination bank number LSB. This is the MIDI_EVENT_BANK_LSB event value that the soundfont is used for.

Remarks

This is an extended version of the BASS_MIDI_FONT structure that allows more flexible mapping of soundfont presets to MIDI programs, including access to the bank LSB (eg. MIDI controller 32).

When using an individual preset from a soundfont, BASSMIDI will first look for the exact spreset and sbank match, but if that is not present, the first preset from the soundfont will be used. This is useful for single preset soundfonts. Individual presets can be assigned to program numbers beyond the standard 127 limit, up to 65535, which can then be accessed via BASS_MIDI_StreamEvent.

When using all presets from all banks in a soundfont, the dbank member is a base number that is added to the soundfont's banks. For example, if dbank = 1 then the soundfont's bank 0 becomes bank 1, etc. Negative base numbers are allowed, to lower a soundfont's bank numbers.

The bank LSB raises the maximum number of melodic banks from 128 to 16384 (128 x 128), but the SF2 soundfont format only supports 128 banks, so a soundfont that is set to be used on all banks (dpreset and dbank are -1) will still only apply to the single bank LSB specified by dbanklsb.

See also

BASS_MIDI_FontInit, BASS_MIDI_StreamGetFonts, BASS_MIDI_StreamSetFonts


BASS_MIDI_MARK structure

Used with BASS_MIDI_StreamGetMark and BASS_MIDI_StreamGetMarks to retrieve markers.

typedef struct {
    DWORD track;
    DWORD pos;
    char *text;
} BASS_MIDI_MARK;

Members

track | The MIDI track containing the marker... 0 = first.
pos | The position of the marker. This may be in bytes or ticks, depending on whether the BASS_MIDI_MARK_TICK flag was used in the BASS_MIDI_StreamGetMark or BASS_MIDI_StreamGetMarks call.
text | The marker text.

Remarks

If a lyric marker's text begins with a / (slash) character, a new line should be started. If it begins with a \ (backslash) character, the display should be cleared.

See also

BASS_MIDI_StreamGetMark


BASS_ATTRIB_MIDI_CHANS attribute

The number of MIDI channels in a MIDI stream.

BASS_ChannelSetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_CHANS,
    float channels
);

Parameters

handle | The MIDI stream handle.
channels | The number of MIDI channels... 1 (min) - 128 (max). For a MIDI file stream, the minimum is 16.

Remarks

New channels are melodic by default. Any notes playing on a removed channel are immediately stopped.

See also

BASS_MIDI_StreamCreate, BASS_MIDI_StreamCreateFile

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_MIDI_CPU attribute

The maximum percentage of CPU time that a MIDI stream can use.

BASS_ChannelSetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_CPU,
    float limit
);

Parameters

handle | The MIDI stream handle.
limit | The CPU usage limit... 0 to 100, 0 = no limit.

Remarks

It is not strictly the CPU usage that is measured, but rather how timely the stream is able to render data. For example, a limit of 50% would mean that the rendering would need to be at least 2x real-time speed. When the limit is exceeded, BASSMIDI will begin killing voices, starting with the most quiet.

When the CPU usage is limited, the stream's samples are loaded asynchronously so that any loading delays (eg. due to slow disk) do not hold up the stream for too long. If a sample cannot be loaded in time, then it will be silenced until it is available and the stream will continue playing other samples as normal in the meantime. This does not affect sample loading via BASS_MIDI_StreamLoadSamples, which always operates synchronously.

By default, a MIDI stream will have no CPU limit.

See also

BASS_ATTRIB_MIDI_VOICES

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_MIDI_PPQN attribute

The Pulses Per Quarter Note (or ticks per beat) value of a MIDI stream.

BASS_ChannelGetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_PPQN,
    float *ppqn
);

Parameters

handle | The MIDI stream handle.
ppqn | The PPQN value.

Remarks

This attribute is the number of ticks per beat as defined by the MIDI file; it will be 0 for MIDI streams created via BASS_MIDI_StreamCreate. It is also read-only, so cannot be modified via BASS_ChannelSetAttribute.

Example

Get the currnet position of a MIDI stream in beats.
float ppqn;
BASS_ChannelGetAttribute(handle, BASS_ATTRIB_MIDI_PPQN, &ppqn); // get PPQN value
QWORD tick=BASS_ChannelGetPosition(handle, BASS_POS_MIDI_TICK); // get tick position
DWORD beat=tick/ppqn; // translate it to beats

See also

BASS_ChannelGetAttribute


BASS_ATTRIB_MIDI_TRACK_VOL attribute

The volume level of a track in a MIDI file stream.

BASS_ChannelSetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_TRACK_VOL + track,
    float volume
);

Parameters

handle | The MIDI stream handle.
track | The track to set the volume of... 0 = first track.
volume | The volume level... 0 = silent, 1.0 = normal/default.

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.

During playback, the effect of changes to this attribute are not heard instantaneously, due to buffering. To reduce the delay, use the BASS_CONFIG_BUFFER config option to reduce the buffer length.

This attribute can also be used to count the number of tracks in a MIDI file stream. MIDI streams created via BASS_MIDI_StreamCreate do not have any tracks.

Example

Count the number of tracks in a MIDI stream.
int tracks=0;
float dummy;
while (BASS_ChannelGetAttribute(handle, BASS_ATTRIB_MIDI_TRACK_VOL+tracks, &dummy))
    tracks++;

See also

BASS_MIDI_StreamEvent

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute, BASS_ChannelSlideAttribute


BASS_ATTRIB_MIDI_VOICES attribute

The maximum number of samples to play at a time in a MIDI stream.

BASS_ChannelSetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_VOICES,
    float voices
);

Parameters

handle | The MIDI stream handle.
voices | The number of voices... 1 (min) - 1000 (max).

Remarks

If there are currently more voices active than the new limit, then some voices will be killed to meet the limit. The number of voices currently active is available via the BASS_ATTRIB_MIDI_VOICES_ACTIVE attribute.

A MIDI stream will initially have a default number of voices as determined by the BASS_CONFIG_MIDI_VOICES config option.

See also

BASS_ATTRIB_MIDI_CHANS, BASS_ATTRIB_MIDI_CPU, BASS_ATTRIB_MIDI_VOICES_ACTIVE, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_ATTRIB_MIDI_VOICES_ACTIVE attribute

The number of samples currently playing in a MIDI stream.

BASS_ChannelGetAttribute(
    HSTREAM handle,
    BASS_ATTRIB_MIDI_VOICES_ACTIVE,
    float *voices
);

Parameters

handle | The MIDI stream handle.
voices | The number of voices.

Remarks

This attribute is read-only, so cannot be modified via BASS_ChannelSetAttribute.

See also

BASS_ATTRIB_MIDI_CPU, BASS_ATTRIB_MIDI_VOICES, BASS_CONFIG_MIDI_VOICES

BASS_ChannelGetAttribute, BASS_ChannelSetAttribute


BASS_MIDI_FontCompact

Compacts a soundfont's memory usage.

BOOL BASS_MIDI_FontCompact(
    HSOUNDFONT handle
);

Parameters

handle The soundfont handle... 0 = all soundfonts.

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

Compacting involves freeing any samples that are currently loaded but unused by any MIDI streams. The amount of sample data currently loaded can be retrieved using BASS_MIDI_FontGetInfo.

See also

BASS_MIDI_FontFree, BASS_MIDI_FontGetInfo, BASS_MIDI_FontUnload, BASS_CONFIG_MIDI_COMPACT


BASS_MIDI_FontFree

Frees a soundfont.

BOOL BASS_MIDI_FontFree(
    HSOUNDFONT handle
);

Parameters

handle The soundfont 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.

Remarks

When a soundfont is freed, it is automatically removed from any MIDI streams that are using it.

See also

BASS_MIDI_FontCompact, BASS_MIDI_FontInit


BASS_MIDI_FontGetInfo

Retrieves information on a soundfont.

BOOL BASS_MIDI_FontGetInfo(
    HSOUNDFONT handle,
    BASS_MIDI_FONTINFO *info
);

Parameters

handle | The soundfont to get info on.
info | Pointer to a structure to receive the info.

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_MIDI_FontGetPreset, BASS_MIDI_FontGetPresets, BASS_MIDI_FONTINFO structure


BASS_MIDI_FontGetPreset

Retrieves the name of a preset in a soundfont.

char *BASS_MIDI_FontGetPreset(
    HSOUNDFONT handle,
    int preset,
    int bank
);

Parameters

handle | The soundfont to get the preset name from.
preset | Preset number... -1 = any preset (the first encountered).
bank | Bank number... -1 = any bank (the first encountered).

Return value

If successful, the requested preset name is 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 soundfont does not contain the requested preset.

Remarks

A list of all presets in a soundfont is available from BASS_MIDI_FontGetPresets.

Drum kits are located in bank 128, and possibly bank 127 in the case of XG drum kits.

See also

BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPresets, BASS_MIDI_FontInit


BASS_MIDI_FontGetPresets

Retrieves the presets in a soundfont.

BOOL BASS_MIDI_FontGetPresets(
    HSOUNDFONT handle,
    DWORD *presets
);

Parameters

handle | The soundfont to get the presets from.
presets | A pointer to an array to receive the presets.

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

Before using this function to retrieve the presets, BASS_MIDI_FontGetInfo should be used to get the number of presets in the soundfont. The presets are delivered with the preset number in the LOWORD and the bank number in the HIWORD, and in numerically ascending order.

Example

List all presets in a soundfont, with their names.
int a;
BASS_MIDI_FONTINFO info;
BASS_MIDI_FontGetInfo(handle, &info); // get soundfont info for preset count
DWORD *presets=(DWORD*)malloc(info.presets*sizeof(DWORD)); // allocate array for presets
BASS_MIDI_FontGetPresets(handle, presets); // get the presets
for (a=0; a<info.presets; a++) {
    DWORD preset=LOWORD(presets[a]), bank=HIWORD(presets[a]); // extract preset and bank number
    const char *name=BASS_MIDI_FontGetPreset(handle, preset, bank); // get the preset's name
    printf("%d.%d: %s\n", bank, preset, name);
}
free(presets);

See also

BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPreset


BASS_MIDI_FontGetVolume

Retrieves a soundfont's volume level.

float BASS_MIDI_FontGetVolume(
    HSOUNDFONT handle
);

Parameters

handle The soundfont to get the volume of.

Return value

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

Error codes

BASS_ERROR_HANDLE handle is not valid.

See also

BASS_MIDI_FontSetVolume


BASS_MIDI_FontInit

Initializes a soundfont.

HSOUNDFONT BASS_MIDI_FontInit(
    void *file,
    DWORD flags
);

Parameters

file The soundfont filename.
flagsAny combination of these flags.
BASS_MIDI_FONT_MMAP | Map the file into memory. This flag is ignored if the soundfont is packed as the sample data cannot be played directly from a mapping; it needs to be decoded. This flag is also ignored if the file is too large to be mapped into memory.
BASS_MIDI_FONT_XGDRUMS | Use bank 127 in the soundfont for XG drum kits. When an XG drum kit is needed, bank 127 in soundfonts that have this flag set will be checked first, before falling back to bank 128 (the standard SF2 drum kit bank) if it is not available there.
BASS_UNICODE | file is in UTF-16 form. Otherwise it is ANSI on Windows, and UTF-8 on other platforms.

Return value

If successful, the soundfont'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's format is not recognised/supported.

Remarks

BASSMIDI uses SF2 and/or SFZ soundfonts to provide the sounds to use in the rendering of MIDI files. Several soundfonts can be found on the internet, including a couple on the BASS website.

A soundfont needs to be initialized before it can be used to render MIDI streams. Once initialized, a soundfont can be assigned to MIDI streams via the BASS_MIDI_StreamSetFonts function. A single soundfont can be shared by multiple MIDI streams. If a soundfont is initialized multiple times, each instance will have its own handle but share the same sample data. Information on the initialized soundfont can be retrieved using BASS_MIDI_FontGetInfo.

Soundfonts use PCM sample data as standard, but BASSMIDI can accept any format that is supported by BASS or its add-ons. The BASS_MIDI_FontPack function can be used to compress the sample data in SF2 files. SFZ samples are in separate files and can be compressed using standard encoding tools.

Using soundfonts that are located somewhere other than the file system is possible via BASS_MIDI_FontInitUser.

SFZ support

The following SFZ opcodes are supported: ampeg_attack, ampeg_decay, ampeg_delay, ampeg_hold, ampeg_release, ampeg_sustain, ampeg_vel2attack, ampeg_vel2decay, amplfo_delay/fillfo_delay/pitchlfo_delay, amplfo_depth, amplfo_freq/fillfo_freq/pitchlfo_freq, amp_veltrack, cutoff, effect1, effect2, end, fileg_attack/pitcheg_attack, fileg_decay/pitcheg_decay, fileg_delay/pitcheg_delay, fileg_depth, fileg_hold/pitcheg_hold, fileg_release/pitcheg_release, fileg_sustain/pitcheg_sustain, fileg_vel2depth, fillfo_depth, fil_veltrack, group, hikey, hivel, key, lokey, loop_end, loop_mode, loop_start, lovel, offset, off_by, pan, pitcheg_depth, pitchlfo_depth, pitch_keycenter, pitch_keytrack, pitch_veltrack, resonance, sample, seq_length, seq_position, transpose, tune, volume. The fil_type opcode is also supported, but only to confirm that a low pass filter is wanted (the filter will be disabled otherwise). The combined EG and LFO entries in the opcode list reflect that there is a shared EG for pitch/filter and a shared LFO for amplitude/pitch/filter, as is the case in SF2. Information on these (and other) SFZ opcodes can be found at www.sfzformat.com.

Samples can also be loaded from memory by setting the "sample" opcode to "mem:<address>:<length>", where address and length are both in hexadecimal. The memory should remain valid until the font is freed via BASS_MIDI_FontFree.

SFZ files don't have a defined preset or bank number, so they are nominally assigned to preset 0 in bank 0 when loaded, but can be assigned to other presets/banks via BASS_MIDI_StreamSetFonts.

Platform-specific

The BASS_MIDI_FONT_MMAP option is not available on big-endian systems (eg. PowerPC) as a soundfont's little-endian sample data cannot be played directly from a mapping; its byte order needs to be reversed.

Example

Initialize a soundfont.
HSOUNDFONT sfont=BASS_MIDI_FontInit("afile.sf2", 0);

See also

BASS_MIDI_FontFree, BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPresets, BASS_MIDI_FontInitUser, BASS_MIDI_FontPack, BASS_MIDI_FontLoad, BASS_MIDI_FontSetVolume, BASS_MIDI_StreamSetFonts, BASS_CONFIG_MIDI_COMPACT


BASS_MIDI_FontInitUser

Initializes a soundfont via user callback functions.

HSOUNDFONT BASS_MIDI_FontInitUser(
    BASS_FILEPROCS *procs,
    void *user,
    DWORD flags
);

Parameters

procs | The user defined file functions.
user | User instance data to pass to the callback functions.
flags | Unused.

Return value

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

Error codes

BASS_ERROR_FILEFORM The file's format is not recognised/supported.

Remarks

The unbuffered file system (STREAMFILE_NOBUFFER) is always used by this function.

See also

BASS_MIDI_FontFree, BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPresets, BASS_MIDI_FontInit, BASS_MIDI_FontPack, BASS_MIDI_FontLoad, BASS_MIDI_FontSetVolume, BASS_MIDI_StreamSetFonts, BASS_CONFIG_MIDI_COMPACT


BASS_MIDI_FontLoad

Preloads presets from a soundfont.

BOOL BASS_MIDI_FontLoad(
    HSOUNDFONT handle,
    int preset,
    int bank
);

Parameters

handle | The soundfont handle.
preset | Preset number to load... -1 = all presets.
bank | Bank number to load... -1 = all banks.

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_CODEC | The appropriate add-on to decode the samples is not loaded.
BASS_ERROR_NOTAVAIL | The soundfont does not contain the requested preset.

Remarks

Samples are normally loaded as they are needed while rendering a MIDI stream, which can result in CPU spikes, particularly with packed soundfonts. That generally will not cause any problems, but when smooth/constant performance is critical this function can be used to preload the samples before rendering, so avoiding the need to load them while rendering.

When preloading samples to render a particular MIDI stream, it is more efficient to use BASS_MIDI_StreamLoadSamples to preload the specific samples that the MIDI stream will use, rather than preloading the entire soundfont.

Samples that are preloaded by this function are not affected by automatic compacting via the BASS_CONFIG_MIDI_COMPACT option, but can be compacted/unloaded manually with BASS_MIDI_FontCompact and BASS_MIDI_FontUnload.

A soundfont should not be preloaded while it is being used to render any MIDI streams, as that could delay the rendering.

See also

BASS_MIDI_FontCompact, BASS_MIDI_FontGetInfo, BASS_MIDI_FontGetPreset, BASS_MIDI_FontInit, BASS_MIDI_FontUnload, BASS_MIDI_StreamLoadSamples


BASS_MIDI_FontPack

Produces a compressed version of a soundfont.

BOOL BASS_MIDI_FontPack(
    HSOUNDFONT handle,
    void *outfile,
    void *encoder,
    DWORD flags
);

Parameters

handle | The soundfont to pack.
outfile | Filename for the packed soundfont.
encoder | Encoder command-line.
flagsAny combination of these flags.
BASS_MIDI_PACK_NOHEAD | Don't send a WAVE header to the encoder. If this flag is used then the sample format (mono 16-bit) must be passed to the encoder some other way, eg. via the command-line.
BASS_MIDI_PACK_16BIT | Reduce 24-bit sample data to 16-bit before encoding.
BASS_UNICODE | outfile and encoder are in UTF-16 form. Otherwise they are ANSI on Windows, and UTF-8 on other platforms.

Return value

If successful, the 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_FILEOPEN | Could not start the encoder. Check that the executable exists.
BASS_ERROR_CREATE | Could not create the output file, outfile.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

Standard soundfonts use PCM samples, so they can be quite large, which can be a problem if they are to be distributed. To reduce the size, BASSMIDI can compress the samples using any command-line encoder with STDIN and STDOUT support. Packed soundfonts can be used for rendering by BASSMIDI just like normal soundfonts. They can also be unpacked using BASS_MIDI_FontUnpack.

Although any command-line encoder can be used, it is best to use a lossless format like FLAC or WavPack, rather than a lossy one like OGG or MP3. Using a lossless encoder, the packed soundfont will produce exactly the same results as the original soundfont, and will be identical to the original when unpacked. As a compromise between quality and size, the WavPack hybrid/lossy mode also produces good sounding results.

The encoder must be told (via the command-line) to expect input from STDIN and to send its output to STDOUT.

Before using a packed soundfont, the appropriate BASS add-on needs to be loaded via BASS_PluginLoad. For example, if the samples are FLAC encoded, BASSFLAC would need to be loaded. During rendering, the samples are unpacked as they are needed, which could result in CPU spikes. Where smooth performance is critical, it may be wise to preload the samples using BASS_MIDI_FontLoad or BASS_MIDI_StreamLoadSamples.

A soundfont should not be packed while it is being used to render any MIDI streams, as that could delay the rendering.

This function only applies to SF2 soundfonts. SFZ samples can be compressed using standard encoding tools.

Platform-specific

This function is not available on iOS or Android.

Example

Create a FLAC encoded version of a soundfont.
HSOUNDFONT handle=BASS_MIDI_FontInit("afile.sf2", 0); // open original soundfont
BASS_MIDI_FontPack(handle, "afile.sf2pack", "flac --best -", 0); // produce packed version

See also

BASS_MIDI_FontInit, BASS_MIDI_FontLoad, BASS_MIDI_FontUnpack


BASS_MIDI_FontSetVolume

Sets a soundfont's volume level.

BOOL BASS_MIDI_FontSetVolume(
    HSOUNDFONT handle,
    float volume
);

Parameters

handle | The soundfont to set the volume of.
volume | The volume level... 0 = silent, 1.0 = normal/default.

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

By default, some soundfonts may be louder than others, which could be a problem when mixing multiple soundfonts. This function can be used to compensate for any differences, by raising the level of the quieter soundfonts or lowering the louder ones.

Changes take immediate effect in any MIDI streams that are using the soundfont.

See also

BASS_MIDI_FontGetVolume


BASS_MIDI_FontUnload

Unloads presets from a soundfont.

BOOL BASS_MIDI_FontUnload(
    HSOUNDFONT handle,
    int preset,
    int bank
);

Parameters

handle | The soundfont handle.
preset | Preset number to unload... -1 = all presets.
bank | Bank number to unload... -1 = all banks.

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_NOTAVAIL | The soundfont does not contain the specified preset, or the soundfont is memory mapped.

Remarks

An unloaded preset will be loaded again when needed by a MIDI stream. Any samples that are currently being used by a MIDI stream will not be unloaded.

See also

BASS_MIDI_FontCompact, BASS_MIDI_FontLoad


BASS_MIDI_FontUnpack

Produces a decompressed version of a packed soundfont.

BOOL BASS_MIDI_FontUnpack(
    HSOUNDFONT handle,
    void *outfile,
    DWORD flags
);

Parameters

handle | The soundfont to unpack.
outfile | Filename for the unpacked soundfont.
flagsAny combination of these flags.
BASS_UNICODE outfile is in UTF-16 form. Otherwise it is ANSI on Windows, and UTF-8 on other platforms.

Return value

If successful, the 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_NOTAVAIL | The soundfont is not packed.
BASS_ERROR_INIT | BASS_Init has not been successfully called - it needs to be to decode the samples.
BASS_ERROR_CODEC | The appropriate add-on to decode the samples is not loaded.
BASS_ERROR_CREATE | Could not create the output file, outfile.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Remarks

To unpack a soundfont, the appropriate BASS add-on needs to be loaded (via BASS_PluginLoad) to decode the samples. For example, if the samples are FLAC encoded, BASSFLAC would need to be loaded. BASS also needs to have been initialized, using BASS_Init. For just unpacking a soundfont, the "no sound" device could be used.

A soundfont should not be unpacked while it is being used to render any MIDI streams, as that could delay the rendering.

BASS_MIDI_FontGetInfo can be used to check if a soundfont is packed.

Example

Unpack a FLAC encoded soundfont.
BASS_PluginLoad("bassflac.dll", 0); // load FLAC plugin
HSOUNDFONT handle=BASS_MIDI_FontInit("afile.sf2pack", 0); // open soundfont
BASS_MIDI_FontUnpack(handle, "afile.sf2", 0); // produce unpacked version

See also

BASS_MIDI_FontInit, BASS_MIDI_FontPack


BASS_MIDI_FONTINFO structure

Used with BASS_MIDI_FontGetInfo to retrieve information on a soundfont.

typedef struct {
    char *name;
    char *copyright;
    char *comment;
    DWORD presets;
    DWORD samsize;
    DWORD samload;
    DWORD samtype;
} BASS_MIDI_FONTINFO;

Members

name | Name of the soundfont.
copyright | Copyright notice.
comment | Any comments.
presets | The number of presets/instruments in the soundfont.
samsize | The total size (in bytes) of the sample data in the soundfont.
samload | The amount of sample data currently loaded... -1 = the soundfont is memory mapped.
samtype | The BASS_CTYPE_STREAM_xxx format of the sample data if it is packed... -1 = unknown format (appropriate BASS add-on not loaded), 0 = not packed.

Remarks

The name, copyright and comment information might not be included in some SF2 files. Only the presets, samload and samtype members are available with SFZ files, with the samtype value reflecting the most recently loaded encoded sample (it is possible for different samples to use different encoding).

See also

BASS_MIDI_FontGetInfo


BASS_MIDI_InFree

Frees a MIDI input device.

BOOL BASS_MIDI_InFree(
    DWORD device
);

Parameters

device The device to 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_DEVICE | device is invalid.
BASS_ERROR_INIT | The device has not been initialized.

See also

BASS_MIDI_InInit


BASS_MIDI_InGetDeviceInfo

Retrieves information on a MIDI input device.

BOOL BASS_MIDI_InGetDeviceInfo(
    DWORD device,
    BASS_MIDI_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.

Platform-specific

MIDI input is not available on Android.

See also

BASS_MIDI_InInit


BASS_MIDI_InInit

Initializes a MIDI input device.

BOOL BASS_MIDI_InInit(
    DWORD device,
    MIDIINPROC *proc,
    void *user
);

Parameters

device | The device to use... 0 = first. BASS_MIDI_InGetDeviceInfo can be used to enumerate the available devices.
proc | Callback function to receive MIDI data from the device.
user | User instance data to pass to the callback function.

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_DEVICE | device is invalid.
BASS_ERROR_ALREADY | The device has already been initialized. BASS_MIDI_InFree must be called before it can be initialized again.
BASS_ERROR_NOTAVAIL | The device not available.
BASS_ERROR_UNKNOWN | Some other mystery problem!

Platform-specific

MIDI input is not available on Android.

See also

BASS_MIDI_InFree, BASS_MIDI_InGetDeviceInfo, BASS_MIDI_InStart, BASS_CONFIG_MIDI_IN_PORTS


BASS_MIDI_InStart

Starts a MIDI input device.

BOOL BASS_MIDI_InStart(
    DWORD device
);

Parameters

device The device to 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_DEVICE | device is invalid.
BASS_ERROR_INIT | The device has not been initialized.
BASS_ERROR_UNKNOWN | Some other mystery problem!

See also

BASS_MIDI_InStop


BASS_MIDI_InStop

Stops a MIDI input device.

BOOL BASS_MIDI_InStop(
    DWORD device
);

Parameters

device The device to 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_DEVICE | device is invalid.
BASS_ERROR_INIT | The device has not been initialized.
BASS_ERROR_UNKNOWN | Some other mystery problem!

See also

BASS_MIDI_InFree, BASS_MIDI_InStart


MIDIINPROC callback

User defined callback function to receive MIDI data.

void CALLBACK MidiInProc(
    DWORD device,
    double time,
    const BYTE *buffer,
    DWORD length,
    void *user
);

Parameters

device | The MIDI input device that the data is from.
time | Timestamp, in seconds since BASS_MIDI_InStart was called.
buffer | Pointer to the MIDI data.
length | The amount of data in bytes.
user | The user instance data given when BASS_MIDI_InInit was called.

Example

A callback function that forwards the received data to a MIDI stream.
stream=BASS_MIDI_StreamCreate(16, 0, 0); // create a MIDI stream to play the MIDI data

...

void CALLBACK MidiInProc(DWORD device, double time, const BYTE *buffer, DWORD length, void *user)
{
    BASS_MIDI_StreamEvents(stream, BASS_MIDI_EVENTS_RAW, buffer, length); // forward the data to the MIDI stream
}

See also

BASS_MIDI_InInit


BASS_MIDI_DEVICEINFO structure

Used with BASS_MIDI_InGetDeviceInfo to retrieve information on a MIDI input device.

typedef struct {
    char *name;
    DWORD id;
    DWORD flags;
} BASS_MIDI_DEVICEINFO;

Members

name | Description of the device.
id | An identification number.
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_INIT | The device is initialized, ie. BASS_MIDI_InInit has been called.

Platform-specific

On Windows, id consists of a manufacturer identifier in the LOWORD and a product identifier in the HIWORD. This will not uniquely identify a particular device, ie. multiple devices may have the same value. A list of identifiers is available from Microsoft, here. On OSX, id is the device's "kMIDIPropertyUniqueID" property value, which is unique to the device. On Linux, id contains the device's ALSA client ID in the LOWORD and port ID in the HIWORD.

See also

BASS_MIDI_InGetDeviceInfo