BASS.NET API for the Un4seen BASS Audio Library

WaveForm Class

BASS.NET API for the Un4seen BASS Audio Library
Provides general methods to generate a stereo or mono channel waveform graphic for an audio file or a decoding stream handle.

The WaveForm will be drawn as two independent stereo envelopes, a combined dual mono envelope or a mono envelope.

Requires: bass.dll - available @ www.un4seen.com

Inheritance Hierarchy

SystemObject
  Un4seen.Bass.MiscWaveForm

Namespace:  Un4seen.Bass.Misc
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

[SerializableAttribute]
public sealed class WaveForm

The WaveForm type exposes the following members.

Constructors

  NameDescription
Public methodWaveForm
Default constructor creating a new instance of the WaveForm class.
Public methodWaveForm(String)
Creates a new instance of the WaveForm class, initializing the file name.
Public methodWaveForm(String, WAVEFORMPROC, Control)
Creates a new instance of the WaveForm class, initializing the file name and a notification handler.
Top
Properties

  NameDescription
Public propertyBeatLength
Gets or Sets the length of the beat position line to be drawn in percentage of the total height (default is 0.05 = 5%).
Public propertyBeatWidth
Gets or Sets the width in pixel of the beat position line to be drawn (default is 1px).
Public propertyCallbackFrequency
Gets or Sets the frequency in FrameResolution frames - how often the WAVEFORMPROC callback should be invoked (default=250, every 5sec. - if the FrameResolution is set to 20ms).

Specify 0, if you want to invoke the callback only at the end of the rendering process.

Example: Specify 50, if you want the callback to be called for every second of the deconding stream (slow - if the FrameResolution is set to 20ms). Or specify 500 to invoke the callback for every 10 seconds (if the FrameResolution is set to 20ms) rendered. Default is 250 = every 5sec. (if the FrameResolution is set to 20ms default).

Public propertyColorBackground
Gets or Sets the background color to be used when drawing the wave form image (Default = SystemColors.Control).
Public propertyColorBeat
Gets or Sets the color to be used when drawing beat position marker (Default = Color.CornflowerBlue).
Public propertyColorLeft
Gets or Sets the base color (left channel) to be used when drawing the wave form image (Default = Color.Gainsboro).
Public propertyColorLeft2
Gets or Sets the gradient color (left channel) to be used when drawing the wave form image (Default = Color.Gainsboro).
Public propertyColorLeftEnvelope
Gets or Sets the envelope color (left channel) to be used when drawing the wave form image (Default = Color.Gray).
Public propertyColorMarker
Gets or Sets the color to be used when drawing a marker (Default = Color.DarkBlue).
Public propertyColorMiddleLeft
Gets or Sets the center line color (left channel) to be used when drawing the wave form image (Default = Color.Empty).
Public propertyColorMiddleRight
Gets or Sets the center line color (right channel) to be used when drawing the wave form image (Default = Color.Empty).
Public propertyColorRight
Gets or Sets the base color (right channel) to be used when drawing the wave form image (Default = Color.LightGray).
Public propertyColorRight2
Gets or Sets the gradient color (right channel) to be used when drawing the wave form image (Default = Color.White).
Public propertyColorRightEnvelope
Gets or Sets the envelope color (right channel) to be used when drawing the wave form image (Default = Color.DimGray).
Public propertyColorVolume
Gets or Sets the color to be used when drawing volume curve (Default = Color.IndianRed).
Public propertyDetectBeats
Gets or Sets, if the beat positions should also be detected during the rendering process.
Public propertyDrawBeat
Gets or Sets if and how beat position should be drawn in the WaveForm (Default = None).
Public propertyDrawCenterLine
Gets or Sets a flag if the center line should be drawn in the wave form image (Default = ).
Public propertyDrawEnvelope
Gets or Sets a flag if the envelope should be drawn in the wave form image (Default = ).
Public propertyDrawGradient
Gets or Sets a flag if the wave form should be drawn in gradient mode (Default = ).
Public propertyDrawMarker
Gets or Sets if and how markers should be drawn in the WaveForm (Default = None).
Public propertyDrawVolume
Gets or Sets if and how a volume curve should be drawn in the WaveForm (Default = None).
Public propertyDrawWaveForm
Gets or Sets how the wave form should be drawn (Default = Stereo).
Public propertyFileName
Gets or Sets the file name to render. Needs to be set before calling the RenderFile method.
Public propertyFrameResolution
Gets or Sets the rendering resolution in seconds. The resolution defines the length of one frame which is the smallest unit to display.

The minimum is 0.001 (1ms) and the maximum is 5.0 (5000ms, 5sec.). Default is 0.01 = 10ms.

Public propertyFramesRendered
Gets how many frames have been rendered (one frame = FrameResolution ms).

When rendering has finished this should be equal to FramesToRender.

Public propertyFramesToRender
Gets how many frames have to be rendered in total (one frame = FrameResolution ms).
Public propertyGainFactor
Gets or Sets a gain factor which should be used when creating the WaveForm image to amplify the amplitude (default is 1.0 = no amplification).
Public propertyIsRendered
Gets, if the wave form has already been rendered.
Public propertyIsRenderingInProgress
Gets, if the wave form rendering process is still in progress.
Public propertyMarkerFont
Gets or Sets the font to be used when drawing a marker (Default = Arial, 7.5, regular).
Public propertyMarkerLength
Gets or Sets the length of the marker line to be drawn in percentage of the total height (default is 0.1 = 10%).
Public propertyNotifyHandler
Gets or Sets the WAVEFORMPROC callback delegete which should be invoked during the rendering progress started with RenderStart(Int32, Boolean).
Public propertyPixelFormat
Gets or Sets the pixel format to use for drawing a bitmap (Default = Format32bppArgb).
Public propertyPreScan
Gets or Sets, if the PRESCAN flag should be added by default when rendering the WaveForm.
Public propertySyncFactor
Gets the current sync factor between rendering and playback.
Public propertyTempoFactor
Gets or Sets the tempo adjustment factor in percent (e.g. 0.05 for +5% or -0.1 for -10%, default is 0).
Public propertyUseSimpleScan
Gets or Sets, if a faster simple scan algo should be used.
Public propertyVolumeCurveZeroLevel
Gets or Sets if the initial level when drawing a volume curve should be silent (default is ).
Public propertyWave
Gets or Sets the rendered wave buffer instance, ie. lets you access the peak levels scanned.
Public propertyWinControl
Gets or Sets the application window control (use null for console applications).

This window control will be used to invoke the WAVEFORMPROC (if set), so that the callback will be executed in the 'correct' GUI thread, if the background option was set during RenderStart(Int32, Boolean).

Top
Methods

  NameDescription
Public methodCode exampleAddMarker(String, Double)
Add or replace a marker to the WaveForm.
Public methodCode exampleAddMarker(String, Int64)
Add or replace a marker to the WaveForm.
Public methodAddVolumePoint(Double, Single)
Add or replace a volume point to the WaveForm.
Public methodAddVolumePoint(Int64, Single)
Add or replace a volume point to the WaveForm.
Public methodClearAllMarker
Removes all markers from the WaveForm.
Public methodClearAllVolumePoints
Removes all volume points from the WaveForm.
Public methodClone
Returns a new WaveForm instance which is a clone of the current one.
Public methodCreateBitmap(Graphics, Rectangle, Int32, Int32, Boolean)
Draws the rendered wave form directly on the provided GDI+ graphics.
Public methodCode exampleCreateBitmap(Int32, Int32, Int32, Int32, Boolean)
Creates a bitmap from a rendered wave form.
Public methodDetectNextLevel(Double, Double, Boolean, Boolean)
Finds the next position with a certain volume level.
Public methodDetectNextLevel(Int64, Double, Boolean, Boolean)
Finds the next position with a certain volume level.
Public methodFindNextZeroCrossing
Finds the next zero crossing position related to the given position (forward seeking).
Public methodFindPreviousZeroCrossing
Finds the previous zero crossing position related to the given position (backward seeking).
Public methodFrame2Bytes
Converts a given frame to the position (in bytes).
Public methodFrame2Seconds
Converts a given frame to the position (in seconds).
Public methodCode exampleGetBytePositionFromX
Translates a X coordinate of a drawn WaveForm graphic to the related byte position within the rendered stream.
Public methodCode exampleGetCuePoints(Double, Double, Double)
Determines silence positions at the beginning and end of a rendered wave form.
Public methodCode exampleGetCuePoints(Int64, Int64, Double)
Determines silence positions at the beginning and end of a rendered wave form.
Public methodCode exampleGetCuePoints(Double, Double, Double, Double)
Determines silence positions at the beginning and end of a rendered wave form.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Double)
Determines silence positions at the beginning and end of a rendered wave form.
Public methodCode exampleGetCuePoints(Double, Double, Double, Double, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Double, Double, Double, Int32, Int32)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Double, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Int32, Int32)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Double, Double, Double, Double, Int32, Int32)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Double, Double, Double, Int32, Int32, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Double, Int32, Int32)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Int32, Int32, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Double, Double, Double, Double, Int32, Int32, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetCuePoints(Int64, Int64, Double, Double, Int32, Int32, Boolean)
Determines silence positions of a rendered wave form within a given range.
Public methodCode exampleGetMarker
Returns a given marker position.
Public methodGetMarkerCount
Returns the number of markers within the wave form.
Public methodGetMarkers
Returns an array of strings containing all marker names.
Public methodCode exampleGetMarkerSec
Returns a given marker position.
Public methodGetNormalizationGain
Determines a gain factor (normalization), so that the maximum peak level of the sample data will be at 0 dB.
Public methodGetVolumeLevel(Double, Boolean, Double, Single)
Returns the volume level at the given position of the volume curve.
Public methodGetVolumeLevel(Int64, Boolean, Int64, Single)
Returns the volume level at the given position of the volume curve.
Public methodGetVolumePoint(Double)
Returns the level of a given volume point.
Public methodGetVolumePoint(Int32)
Returns a certain volume point at the given index.
Public methodGetVolumePoint(Int64)
Returns the level of a given volume point.
Public methodGetVolumePointCount
Returns the number of volume points within the wave form.
Public methodIsZeroCrossingFrame
Detects, if the two given positions reflect a zero crossing.
Public methodPeakLevelOfFrame
Returns the peak level (between 0 and 32767) of a given frame position.
Public methodPosition2Frames(Double)
Converts a given position (in seconds) to the frame number.
Public methodPosition2Frames(Int64)
Converts a given position (in bytes) to the frame number.
Public methodPosition2Playback(Double)
Converts a given rendering position to the playback position according to the SyncFactor.
Public methodPosition2Playback(Int64)
Converts a given rendering position to the playback position according to the SyncFactor.
Public methodPosition2Rendering(Double)
Converts a given playback position to the rendering position according to the SyncFactor.
Public methodPosition2Rendering(Int64)
Converts a given playback position to the rendering position according to the SyncFactor.
Public methodCode exampleRemoveMarker
Removes an existing marker from the WaveForm.
Public methodRemoveVolumePoint(Double)
Removes an existing volume point from the WaveForm.
Public methodRemoveVolumePoint(Int64)
Removes an existing volume point from the WaveForm.
Public methodRemoveVolumePointsBetween(Double, Double)
Removes all volume points between the two given points exclusive.
Public methodRemoveVolumePointsBetween(Int64, Int64)
Removes all volume points between the two given points exclusive.
Public methodCode exampleRenderRecording
Renders live recorded data and generates the WaveForm data for it.
Public methodCode exampleRenderRecording(IntPtr, Int32)
Renders live recorded data and generates the WaveForm data for it.
Public methodRenderStart(Boolean, BASSFlag)
Start the rendering process for the FileName given (peak levels will be scanned).
Public methodRenderStart(Int32, Boolean)
Start the rendering process for the specified decoding stream (peak levels will be scanned).
Public methodRenderStart(Boolean, ThreadPriority, BASSFlag)
Start the rendering process for the FileName given (peak levels will be scanned).
Public methodRenderStart(Int32, Boolean, Boolean)
Start the rendering process for the specified decoding stream (peak levels will be scanned).
Public methodRenderStart(Boolean, BASSFlag, IntPtr, Int64)
Start the rendering process for audio data located at the memory position (peak levels will be scanned). Note: The FileName will be ignored.
Public methodRenderStart(Int32, Boolean, ThreadPriority, Boolean)
Start the rendering process for the specified decoding stream (peak levels will be scanned).
Public methodRenderStartRecording(Int32, Int32, Int32)
Start a live recording rendering process for the specified non-decoding handle (peak levels will not be scanned at this point).
Public methodRenderStartRecording(Int32, Single, Single)
Start a live recording rendering process for the specified stream handle (peak levels will not be scanned at this point).
Public methodRenderStop
Stops a currently running rendering process.
Public methodRenderStopRecording
Stops live recording rendering.
Public methodReset
Resets the wave form.
Public methodCode exampleSearchVolumePoint(Double)
Searches for a certain volume point.
Public methodCode exampleSearchVolumePoint(Int64)
Searches for a certain volume point.
Public methodSearchVolumePoint(Double, WaveFormVolumePoint, WaveFormVolumePoint)
Searches for a certain volume point.
Public methodSearchVolumePoint(Int64, WaveFormVolumePoint, WaveFormVolumePoint)
Searches for a certain volume point.
Public methodSyncPlayback
Sets a playback channel to synchronize the wave form positions.
Public methodWaveFormLoadFromFile(String)
Loads a rendered WaveForm from a file.
Public methodWaveFormLoadFromFile(String, Boolean)
Loads a rendered WaveForm from a file.
Public methodCode exampleWaveFormLoadFromMemory(Byte)
Loads a rendered WaveForm from a byte array.
Public methodCode exampleWaveFormLoadFromMemory(Byte, Boolean)
Loads a rendered WaveForm from a byte array.
Public methodWaveFormSaveToFile(String)
Saves a rendered WaveForm to a file (uncompressed).
Public methodWaveFormSaveToFile(String, Boolean)
Saves a rendered WaveForm to a file.
Public methodCode exampleWaveFormSaveToMemory
Saves a rendered WaveForm to a byte array.
Public methodCode exampleWaveFormSaveToMemory(Boolean)
Saves a rendered WaveForm to a byte array.
Top
Remarks

The WaveForm class is an internal implementation of the BASS.NET API and does not require any additional extension or add-on to the BASS audio library, meaning only bass.dll is required.

However, BASS_Init(Int32, Int32, BASSInit, IntPtr, IntPtr) must have been called before using any method within this class!

NOTE: When using the WaveForm class with an already existing decoding channel (created with the BASS_STREAM_DECODE flag) the data will be retrieved from that channel, meaning the data will be 'stolen'. In such a case you must reset the position to the beginning of the stream afterwards, e.g. use BASS_ChannelGetPosition(Int32, BASSMode) before rendering the WaveForm and call BASS_ChannelSetPosition(Int32, Int64, BASSMode) when rendering of the WaveForm has been completed.

The typical use of this class is as followed:

a) create an instance of this class (e.g. together with the filename)

b) call RenderStart(Int32, Boolean) to scan all peak levels

c) call CreateBitmap(Int32, Int32, Int32, Int32, Boolean) to generate a wave form image

You might also use WaveFormSaveToFile(String) and WaveFormLoadFromFile(String) to save or load a rendered wave form.

The methods AddMarker(String, Int64) and RemoveMarker(String) lets you manage named position markers within the WaveForm to be displayed, use the DrawMarker property to specify how and if markers should be displayed.

When the image of the rendered wave form or a zoomed window of it is created via CreateBitmap(Int32, Int32, Int32, Int32, Boolean) the global properties ColorBackground, ColorRight and ColorLeft as well as ColorMarkerare used.

You might also access the scanned peak levels directly via the Wave property.

See Also

Reference